guru

Windguru CLI + MCP + Python library for kiters and agents — free named spots, WINDGURU DEFAULT top models, gear advice. No HTML scraping. No PRO.

Free only — named spots + WINDGURU DEFAULT Tune top-3. No PRO lat/lon click-forecast.

Humans: paste this repo URL into Cursor, Claude, Codex, or ChatGPT and ask “set this up and tell me where I can kite.” The agent instructions below are written for that.

For AI agents (mandatory protocol)

If the user pasted https://github.com/berendgort/guru (or this README), you must follow this section exactly. Do not invent a Windguru scrape, browser walkthrough, or multi-question onboarding.

Goal

Onboard the rider on the first message, then answer kite questions with gear advice using the windguru package (guru CLI and/or guru-mcp tools). Speak to the human like a kiter, not like a JSON dump.

Bootstrap (do this first)

1. Prefer PyPI, and upgrade every session before briefing:

   pipx upgrade windguru || pipx install 'windguru[mcp]'
   # or: pip install -U 'windguru[mcp]'   (activate venv first)
   

   Check guru doctor --json → upgrade.update_available, or guru instruct --json → data.upgrade.
2. Confirm: guru doctor and guru instruct --json.
3. Immediately check the profile. If first_pass / ready=false / range_ready=false, your first reply to the human must be the intake prompt (include level). Do not run weekend/best yet.
4. Wire tools for the host you are in:
   • Cursor / Claude Desktop / local Codex with MCP → ensure MCP server guru runs guru-mcp (full path from which guru-mcp if needed). Then prefer MCP tools over shell.
   • Shell-capable agent (Cursor Agent, Codex, Claude with bash) → run guru … --json if MCP is not configured yet.
   • Claude Cowork / claude.ai → local STDIO MCP will not work. Either run CLI in a local terminal the user controls, or start guru-mcp-http and help them add a public HTTPS URL under Customize → Connectors. Do not pretend localhost is reachable from Anthropic’s cloud.
   • ChatGPT cloud → same as Cowork for MCP (needs public HTTP), otherwise guide install + have the user paste guru … --json output, or use whatever shell/Code Interpreter the product gives you.

MCP config (Cursor / Claude Desktop):

{
  "mcpServers": {
    "guru": {
      "command": "guru-mcp"
    }
  }
}

Operating loop (every kite question)

First pass (mandatory on the first kite message when ready=false or range_ready=false / first_pass=true):

1. Your first message to the human must show exactly data.intake.prompt_to_user (or the template below). Collect sport, weight, level (required — changes GO wind and sizing), quiver, wetsuits, home range — one message.
2. Wait for one reply (key=value paste). Do not ask sport, then weight, then kites separately. Do not skip intake.
3. Run:

   guru setup --intake '<their paste>' --json
   

   or MCP setup_profile with the same fields (including level).
4. Only then continue with weekend / best.

Template to show if you cannot read prompt_to_user yet:

sport=kitefoil weight=78 level=intermediate kites=7,9,12 wetsuits=3/2,4/3 session=3 home=41.39,2.17 drive_km=200 range=Trabucador → Leucate

How to talk to the human

After tools return, narrate for a rider:

• Verdict: GO / MARGINAL / NO-GO
• Week plan from schedule (Tue / Wed / Thu…) — do not wait for “what about Thursday?”
• Best spot + rough drive distance
• Window in local-friendly terms if you can, else UTC
• Wind + gusts; model_agree; size for gusts
• Kite size from quiver; wetsuit for session hours
• Short checklist: watch beach 5 min, side-shore preference, don’t long-drive for marginal

Do not dump raw model tables unless they ask.

Hard rules

• Use preset WINDGURU_DEFAULT only (guru best / best_forecast). Do not default to raw GFS.
• Never scrape windguru.cz HTML, Tune UI, or MapLibre.
• Never require PRO or invent lat/lon click-forecasts.
• On error_type: ambiguous, pick from candidates — never silent first-match.
• Respect retryable on errors; don’t hammer rate limits.
• Profile lives at ~/.config/guru/profile.json (override with GURU_CONFIG_DIR).

MCP tool map

More: docs/mcp.md · skill copy: skills/guru/SKILL.md

Install

pipx install windguru          # CLI: guru …
pipx install 'windguru[mcp]'   # + MCP: guru-mcp / guru-mcp-http
guru --help

Or with pip: pip install windguru / pip install 'windguru[mcp]'.

PyPI: windguru · commands: guru, guru-mcp, guru-mcp-http

Host cheat sheet

guru-mcp-http listens at http://127.0.0.1:8000/mcp/ — Cowork/claude.ai need that URL exposed publicly; there is no hosted Windguru MCP in this repo.

CLI

Ambiguous names fail with error_type: ambiguous + candidates (pass numeric id or --pick).

Library

from guru import get_best_forecast, search_spots
from guru.rider.advice import advise_forecast, drive_km_from_home
from guru.rider.profile_store import load_profile

spots = search_spots("castelldefels")
best = get_best_forecast(201, top=3, hours=24)
profile = load_profile()
advice = advise_forecast(
    best.forecasts[0], profile, drive_km=drive_km_from_home(profile, best.spot)
)
print(advice.verdict, advice.summary)

Develop

git clone https://github.com/berendgort/guru.git
cd guru
pipx install -e ".[dev,mcp]"
# or: python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev,mcp]"
pytest -q
ruff check .

Read AGENTS.md before extending. Capture Network → fixtures → tests.

Engineering standards (kept in-repo):

• docs/code_quality.md — Korotkevich / Tourist bar
• docs/data_engineering_standards.md — Gray / Stonebraker bar

Disclaimer

Unofficial. Not affiliated with Windguru. Personal / research use; respect ToS and rate limits.

License

MIT