feat: @searoute-ts/mcp — first-party MCP server for AI agents

[mayurrawte]

What does this PR do?

Adds a first-party Model Context Protocol server so AI agents (Claude Desktop, the claude CLI, etc.) can compute real shortest sea routes directly — answering "how far is Shanghai to Rotterdam by sea, avoiding Suez?" by calling the library instead of guessing. This is the TypeScript analog of the community searoute_mcp Python wrapper referenced in #13.

claude mcp add searoute -- npx -y @searoute-ts/mcp

Tools (thin wrappers over the existing public API — no new routing logic):

• sea_route(origin, destination, options) → distance, optional duration, canals/straits traversed, detour ratio, and route GeoJSON.
• sea_route_alternatives(origin, destination, k) → up to k distinct routes by canal permutation (baseline / no-Suez / no-Panama …), sorted by distance.

Both accept UN/LOCODE port codes ('CNSHA') as well as [lon, lat] coordinates — the server imports searoute-ts/ports so codes work out of the box (pairs with #7, as the issue suggested). sea_route also exposes restrictions, allowArctic, speedKnots, vesselDraftMeters, maxSnapDistanceKm, and an includeGeometry toggle.

Packaging — kept out of the core

Shipped as its own package (@searoute-ts/mcp) under examples/mcp-server/ (the issue offered "its own package or a subpath"). This keeps the MCP SDK — which pulls in ~90 transitive packages — entirely out of searoute-ts, so the core stays dependency-lean (it depends on the published searoute-ts@^2.2.0). The core package is untouched by this PR apart from a README section, so the root build/lint/test are unaffected.

Structure

• src/tools.ts — zod input schemas + pure, testable handlers (runSeaRoute, runSeaRouteAlternatives) returning the MCP result shape; maps library errors (UnknownPortError, NoRouteError, SnapFailedError) to isError results.
• src/server.ts — createServer() registers the two tools on the SDK's McpServer.
• src/index.ts — stdio entry point (bin: searoute-ts-mcp).
• README.md — tool reference + claude mcp add / client-config snippets; root README gains a "Use from an AI agent (MCP)" section.

Checklist

• Thin wrapper over the public API — no new routing logic
• New behavior is covered by tests
• Core package (and its CI) left untouched apart from a README section

Validation

Sub-package (examples/mcp-server):

• npm install
• npm run build ✅ (tsc clean)
• npm test ✅ (8 vitest tests: port-code & coordinate routing, passages includes suez, restrictions: ['suez','babelmandeb'] yields a longer Suez-free route, speedKnots → durationHours, includeGeometry:false drops the GeoJSON, unknown-code → isError, and k distinct alternatives sorted ascending)

Also verified end-to-end over stdio with a real MCP client (initialize → tools/list → tools/call): both tools list; sea_route('CNSHA','NLRTM') = 19,752.85 km via Suez; sea_route_alternatives returns 3 sorted distinct routes (baseline 19,753 / no-malacca 20,759 / no-suez 25,315 km); an unknown code returns isError: true with UnknownPortError.

Root package (unchanged behavior, confirmed still green from a clean tree): npm ci · npm run lint ✅ · npm run format:check ✅ · npm run build ✅ · npm test ✅ (67 tests).

Closes #13

---

Generated by Claude Code