strava-mcp AGENTS.md

Strava MCP Server

Remote MCP server for connecting AI tools to your Strava data.

Documentation

Reference docs live in docs/. Read the relevant one before working in its area; this file holds only the invariants that apply to every change.

Doc	Read before
docs/architecture.md	Changing server internals (transport, HTTP layer, cache, errors, analysis math, tool metadata)
docs/mcp-apps.md	Adding or changing an MCP App package, packages/ui, or packages/data
docs/tools.md	Adding, renaming, or describing tools/prompts — it is the single catalog; keep it current
docs/operations.md	Configuring or debugging a deployed instance
docs/development.md	Turborepo, coverage gates, Storybook gates, Docker image build
docs/releasing.md	Shipping — PR titles are Conventional Commits; release automation does the rest
docs/project.md	Filing/triaging issues, editing the project board

Architecture invariants

One line each; full rationale in docs/architecture.md. These exist because breaking them has shipped bugs — do not work around them locally.

• Dual-era serving shares one factory. mcpEndpoint.ts serves the 2026-07-28 revision statelessly per request and routes 2025-era clients through the SDK's legacy fallback; one createServer backs both legs so the eras cannot drift. No sessions (Mcp-Session-Id is gone; GET/DELETE answer 405). The endpoint parses every POST body itself with parseJsonWithLargeInts → SDK parsedBody; that seam keeps 64-bit ids intact.
• Rate limits and retries live in fetchClient.ts, never per-tool. Parses X-RateLimit-*/Retry-After into a snapshot; bounded retries honour Retry-After; transient 5xx/network faults retry GET/HEAD only, never writes.
• Error types survive translation. handleApiError rethrows RateLimitError intact (context prefixed onto message, bare window detail kept) and wraps everything else in StravaApiError extends HttpError. Flattening to plain Error silently kills callers' instanceof/status checks — degrade only on a type or status that is still there.
• Caching policy lives in stravaCacheTtl (path-keyed TTLs; key is full URL, TTL matches query-stripped path). Writes invalidate descendants AND ancestors; skipCache: true guards append reads; handlers floor after/before bounds to the minute (quantizedEpochAfter/Before) so a pair's two calls share one cache key.
• Stream reads go through the stravaClient.ts wrappers (shared fetchStreamSet: shape validation, 401 refresh-retry, structured 429). Only genuine 404/empty throws StreamsUnavailableError — the one error a caller may degrade on. Catching more misreports failures as absences.
• Derived numbers have exactly one home. GAP: hillAnalysis.ts (gapFactor, computeGrades) — splitAnalysis.ts imports, never re-derives. Time-free segment/route profiles: gradientProfile.ts (+ shared prose in tools/_profileText.ts). CTL/ATL/TSB and any projection/taper math: fitnessTrend.ts. Route elevation resolves once via loadRouteProfile (genuine 404 → GPX <ele> fallback). Text tool and app reading different copies is the failure mode these prevent.
• Telemetry: dispatchToolCall emits one JSON line per call; timer starts before token resolution (not-connected calls count); a returned isError counts as an error; recordToolCall can never fail the call it describes.
• Progress: every handler gets a ReportProgress closure (third arg, always present). Tick counter without total (spec demands monotonic increase; multi-phase calls can't carry two denominators); time-based throttle with important: true bypass; fire-and-forget.
• Tokens come from getStravaToken(), passed to handlers as argument 2 — never read process.env.STRAVA_ACCESS_TOKEN in a tool. NoTokenError / TokenRevokedError map to one not-connected message naming /auth/start. OAuth POSTs go through postOAuthToken, which retries 5xx only — a timeout may have rotated the refresh token server-side.
• Ids go through stravaIdInput (tools/_ids.ts). Advertised schema is string-only (stravaIdJsonSchemaOverride) because ids above 2^53 are rounded by hosts' JSON.parse unrecoverably; safe-int numbers accepted at runtime, normalised to digit strings; handlers pass strings through without parsing back.
• Tools returning data publish outputSchema + matching structuredContent from tools/outputs.ts (schemas grouped, not per file). Text tools reuse the apps' mappers rather than re-deriving — e.g. get-activity-zones calls mapActivityZones from activityZones.ts. Empty results emit a valid payload (count: 0). warnOnSchemaDrift keeps dev honest.
• Exports choose delivery via _exportOutput.ts: omitting output picks file when ROUTE_EXPORT_PATH is set, content otherwise. Content mode caps bytes and says outright that a truncated GPX will not open.
• sportType is an enum: SPORT_TYPES (utils/activityWrite.ts) backs both the advertised schema and the runtime check; rejections name the near miss (Weightlifting → WeightTraining).
• Annotations come from the four _annotations.ts constants, never inline objects — they decide whether hosts grant reads durably or re-prompt forever. READ_ONLY states destructiveHint: false explicitly (its documented default is true). Nothing may set _meta["anthropic/requiresUserInteraction"]. server.annotations.test.ts holds an exhaustive read/write classification table — a new tool must be added to it.
• Tool identity is a published contract. tool-surface.lock.json fingerprints name + annotations + inputSchema + outputSchema + _meta; toolSurface.test.ts fails on drift. Regenerate deliberately (UPDATE_TOOL_SURFACE_LOCK=1 bunx vitest run src/toolSurface.test.ts) and say so in the PR — users pay a round of re-prompting.
• Protocol-surface tests go over the wire in both eras (server.integration.test.ts under describe.each(ERAS) via mcpTestClient.ts): capabilities, object inputSchemas (no $ref), string ids, structuredContent, isError not JSON-RPC errors, app resources, prompts. Extend the shared client, never a new bootstrap copy.
• Tool error text has one home: toolErrorText (tools/_errors.ts). It branches on RateLimitError / HttpError.status (404, 402), never on message text; every isError text starts with ❌. Catch blocks and the dispatcher's final catch call it for the text and write the { content, isError: true } literal themselves. Tests reject with the __fixtures__/errors.ts shapes (handledRateLimit, handledNotFound, handledSubscriptionRequired), never a plain Error("404 Not Found").
• The response cache never shares references and coalesces in-flight GETs. Every value FetchClient hands out (hit, populating miss, coalesced awaiter) is a structuredClone; concurrent identical cacheable GETs share one upstream promise (failures never cached, write invalidation drops in-flight entries, skipCache bypasses both). Never return a cached object by reference or add a per-tool in-flight map.
• Token status is served from memory. getTokenStatus reads cachedTokens before disk and never caches "no tokens": authed /health and /auth/status polls cost no filesystem read and no repeated "Loaded tokens" lines; a tokens.json replaced by hand needs a restart, exactly as it does for tool calls.
• Auth pages escape at the sink. authRoutes.ts entity-encodes every reflected string inside errorPage/successPage, never at call sites: /auth/callback is public and its error branch runs before the state gate, so a new page helper must escape too.
• The Bun version has one home: root packageManager. CI reads it via bun-version-file; dockerRuntime.test.ts pins the Dockerfile's FROM oven/bun:<tag> lines to the same x.y.z, because Dependabot bumps the base image but never packageManager, and the lockfile must be resolved and installed by the same Bun.