ohmywind

# OhMyWind ⛵

> **Talk to your LLM. Cast off with confidence.**
>
> OhMyWind turns any MCP-capable assistant (Claude, Le Chat, Cursor, Goose,
> Zed, Continue) into a sailing planner. Ask in plain language, anywhere in
> the world: get a per-leg ETA, a 1‑5 complexity score, and a deep-link to
> the full plan. On the French Atlantic coast it goes further, swapping the
> global current model for the SHOM Atlas C2D and MARC PREVIMER atlases.
> Free, keyless, open source.

[![CI](https://github.com/qdonnars/ohmywind/actions/workflows/ci.yml/badge.svg)](https://github.com/qdonnars/ohmywind/actions/workflows/ci.yml)

[**ohmywind.fr**](https://ohmywind.fr) · [MCP endpoint](https://mcp.ohmywind.fr/mcp) · [Changelog](CHANGELOG.en.md) · [AGPL-3.0](LICENSE) + [trademark](TRADEMARK.md)

> [!WARNING]
> **Decision-support tool, not a navigation instrument.** OhMyWind does not
> replace the official marine forecast from your national weather service,
> up-to-date charts, or the skipper's judgement. Forecast models are sometimes
> wrong: you remain responsible for your passage.

![OhMyWind passage plan rendered in the web app](docs/screenshots/plan.png)

---

## Try it in 30 seconds

**1.** Open your MCP client and add the endpoint:

```
https://mcp.ohmywind.fr/mcp
```

**2.** Ask, in your own words:

> *"Demain matin, Marseille → Porquerolles, sur un Sun Odyssey 36. Bonne
> idée ? Combien de temps et c'est tendu comment ?"*

**3.** Your assistant calls the OhMyWind tools and answers in plain language.
On hosts that support the [MCP Apps spec](https://modelcontextprotocol.io/extensions/client-matrix)
(Claude, Claude Desktop, ChatGPT, VS Code Copilot, Goose, Postman, MCPJam) you
also get a live, interactive widget: the [ohmywind.fr](https://ohmywind.fr)
plan view rendered inline. On hosts that don't (Cursor, Le Chat, terminal),
the assistant hands you the same plan as an [ohmywind.fr](https://ohmywind.fr)
deep-link. No account. No API key. No credit card.

> **First time with MCP?** It takes 2 minutes. Pick your client on
> [modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients),
> then follow the
> [remote-server quickstart](https://modelcontextprotocol.io/docs/develop/connect-remote-servers).
> Claude Desktop users can start with the
> [user quickstart](https://modelcontextprotocol.io/quickstart/user). In Le Chat,
> add it under **Connectors → Add connector → Custom MCP connector** and paste
> the endpoint above.

### If your client only speaks stdio

Some hosts cannot reach a remote MCP server directly yet. Bridge it with
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which runs locally
and forwards to the endpoint:

```json
{
  "mcpServers": {
    "ohmywind": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.ohmywind.fr/mcp"]
    }
  }
}
```

Nothing else to configure: **no account, no API key, no OAuth, no credit
card.** A client that asks you for credentials is guessing rather than reading
the server, and you can leave those fields empty.

### Ask it something real

Three prompts, each exercising a different tool:

- *"Quels bateaux tu connais ? J'ai un First 27."* maps your boat to a polar
  archetype. The assistant chooses from the descriptions; there is no
  server-side lookup table.
- *"Le vent au cap Sicié samedi après-midi ?"* returns wind and sea at one
  point, AROME first, in knots.
- *"Meilleur créneau cette semaine pour Marseille → Porquerolles ?"* walks
  every hourly departure up to 14 days out and compares them in one call.

## Why OhMyWind

|                              |                                                                                              |
|------------------------------|----------------------------------------------------------------------------------------------|
| 🆓 **Free, keyless**         | Wind & sea via [Open-Meteo](https://open-meteo.com) (CC BY 4.0). No account, no API key.     |
| 🌍 **Works anywhere**        | Global models (ECMWF, GFS) cover any coast. Over France, AROME 1.3 km takes over and catches thermals, mistral, tramontane. |
| ⛵ **Boat-aware**             | Eight archetypes from a 16 ft sail-and-oar dinghy and 20 ft trailer-cruisers to bluewater 50-footers, real polars, an `efficiency` parameter for trim and crew level. |
| 🗓️ **Window-aware**           | One call sweeps a 14-day departure range and lets your LLM pick the calmest weekend slot, no math by hand. |
| 🔌 **Client-agnostic**        | One HTTP MCP endpoint. Works in Claude Desktop, Le Chat, Cursor, Goose, Zed, Continue, …     |
| 🖼️ **Rich on supporting hosts** | On Claude / ChatGPT / VS Code Copilot / Goose, an interactive widget renders inline via [MCP Apps](https://modelcontextprotocol.io/extensions/client-matrix). Other hosts fall back to a clean text summary + deep-link. |
| 🛠️ **Open source, AGPL**      | Self-host on Fly, Modal, or your own VPS: `mcp-core` is deployment-agnostic. The HF Space is one wrapper among many. Fork it under your own name and icons, see [TRADEMARK.md](TRADEMARK.md). |

## What the LLM sees

Four MCP tools, all async, all keyless:

| Tool                      | What it does                                                              |
|---------------------------|---------------------------------------------------------------------------|
| `list_boat_archetypes`    | Eight descriptive archetypes; the LLM maps "Sun Odyssey 36" → `cruiser_30ft` itself. |
| `get_marine_forecast`     | Wind + sea around a point/window, multi-model.                            |
| `plan_passage`            | End-to-end: per-leg timing + 1‑5 complexity + ohmywind.fr deep-link, in one call. Pass `latest_departure` to compare every hourly window up to 14 days out, and the LLM picks the calmest slot. |
| `read_me`                 | Returns OhMyWind's calculation methodology. Call it when the user asks how things are computed. |

`plan_passage` declares an MCP Apps UI resource (`ui://openwind/plan-passage`)
on its `_meta`. Hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/client-matrix)
render the live `ohmywind.fr/plan?…` view in a sandboxed iframe automatically,
with no host-specific CSS and no vendor lock-in. Hosts without MCP Apps support
silently get the structured payload + the `openwind_url` deep-link.

## Architecture

```
packages/
├── data-adapters/   # pure domain logic (forecast adapters, polars, routing, complexity)
├── api/             # REST API as a Starlette app: create_app(settings, mcp_app=None)
├── mcp-core/        # FastMCP server (cloud-agnostic, no Gradio, no HF deps)
├── hf-space/        # Docker wrapper for Hugging Face Spaces (~100 lines + Dockerfile)
└── web/             # React 19 + Vite app deployed to Cloudflare Pages (ohmywind.fr)
```

`api` and `mcp-core` both stay deployment-agnostic, and neither depends on the
other: the API serves without an MCP server behind it, and the MCP tools run
over stdio with no HTTP at all. Re-deploying on Fly, Modal, or a VPS is a
different `Dockerfile` and an entry point that calls `create_app()` and
`build_server()`. See [docs/architecture.md](docs/architecture.md).

## Run locally

```bash
# Tests + lint (data-adapters & mcp-core, Python via uv)
cd packages/mcp-core
uv sync --all-extras
uv run pytest -x -q
uv run ruff check .

# Local HTTP MCP smoke
cd packages/hf-space
uv run python app.py   # serves :7860, point any MCP client at /mcp

# Web app (ohmywind.fr)
cd packages/web
npm install
npm run dev            # vite dev server
npm run build          # outputs packages/web/dist
```

## V1 scope

Wind, sea (`Hs` max), per-leg ETA, 1–5 complexity. Tides and currents ignored
on the Med (negligible). No automatic routing optimisation: the LLM and the
human stay in the loop. Roadmap and scope decisions live in a `plan/` directory kept
local to the working copy, not published here.

## Calculation method

Defaults below are what the MCP server uses unless overridden by tool parameters.
Implementation: [`packages/data-adapters/src/openwind_data/routing/passage.py`](packages/data-adapters/src/openwind_data/routing/passage.py).

### Polar speed model

- 8 archetypes (`cruiser_20ft`, `cruiser_25ft`, `cruiser_30ft`, `cruiser_40ft`, `cruiser_50ft`, `racer_cruiser`, `catamaran_40ft`, `voile_aviron_16ft`), each with an ORC-style polar in [`packages/data-adapters/src/openwind_data/routing/polars/`](packages/data-adapters/src/openwind_data/routing/polars/).
- Lookup is **bilinear interpolation** in (TWS, TWA), clamped at grid edges.
- TWA is symmetric `[0°, 180°]` only, no port/starboard distinction.

### Boat speed adjustments

- **Efficiency factor (default 0.75).** ORC polars are theoretical maxima. Real cruising loses ~25% (sail trim, comfort margins, helmsman, untracked currents). Override per call: `0.85` racing, `0.75` cruising, `0.65` loaded family cruising, `0.55` heavy seas / fouled hull.
- **VMG / tacking correction.** When the route's TWA is below the boat's optimal upwind angle (typically ~42-48°), the simulator assumes the sailor tacks. Effective speed toward destination is `polar(optimal_TWA) × cos(optimal_TWA − route_TWA)`. At dead upwind this reduces to `polar(opt) × cos(opt) ≈ polar / √2`; at TWA=20° with opt=45° the reduction is only `cos(25°) ≈ 0.91`.
- **Wave derate (opt-in).** `max(0.5, 1 − 0.05 × Hs^1.75 × cos²(TWA/2))`. Disabled by default; sea state feeds the warning bar rather than slowing the boat.
- **Minimum boat speed.** 0.5 kn floor, prevents division blow-up in extreme stalls.

### Timing

- **Single-pass approximation.** A 6 kn heuristic estimates segment mid-times, then real polar speeds are computed at each mid-time's actual wind. No convergence iteration. Bias is bounded by the Mediterranean's multi-hour wind correlation length.
- Routes are split into ~10 nm sub-segments by default for per-segment weather sampling. Drop to 5 nm for tight coastal work; raise to 20 nm for long offshore legs.

### Compare-windows mode

`plan_passag