intervalsicu-mcp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

The MCP server in a self-hosted, multi-tenant "Intervals.icu MCP" system running on Kubernetes (Flux GitOps) behind a single host, https://intervalsicu.farhoodlabs.com. This is a fork of the upstream single-tenant project (github.com/mvilanova/intervals-mcp-server) that has been reworked for remote, OAuth-authenticated, per-user operation.

It exposes the Intervals.icu REST API (activities, events, wellness, power curves, gear, custom items) as MCP tools over streamable-HTTP at /mcp. Python 3.12+, built on FastMCP (from mcp[cli]) + httpx, with SQLAlchemy/asyncpg + Alembic for the user store and PyJWT for token verification. Managed with uv.

Three services share one CloudNativePG Postgres database on that host:

• intervalsicu-mcp (this repo) — the MCP server at /mcp.
• intervalsicu-mcp-ui — a portal at /portal where users sign in (Google via Better Auth) and set their Intervals.icu credentials, and admins approve accounts.
• intervalsicu-mcp-auth — a TypeScript Better Auth OAuth 2.1 server at /api/auth (DCR per RFC 7591, PKCE, EdDSA-signed JWT access tokens + JWKS, Google login). Claude's connector self-registers here.

Runtime auth flow: Claude connector → dynamic client registration at the auth server → Google login → JWT access token (audience = the /mcp resource URL) → this server verifies the JWT against the auth server's JWKS and resolves the caller's stored Intervals.icu credentials by the token subject. If the user has no approved-and-populated credentials, tools return a friendly "account isn't ready" message.

Commands

uv venv --python 3.12 && source .venv/bin/activate
uv sync --all-extras            # install incl. dev extras

uv run pytest                   # run all tests (enforces a >=90% coverage gate; see pyproject)
uv run pytest tests/test_server.py::test_name   # single test
ruff check .                    # lint
mypy src tests                  # type check

ruff check ., mypy src tests, and pytest must all pass before committing. Gitea CI (.gitea/workflows/build.yaml) installs with pip install -e ".[dev]", runs pytest (which enforces the coverage gate), then builds and pushes the image to git.farh.net/farhoodlabs/intervalsicu-mcp; Flux deploys it. If you change dependencies, run uv lock and commit pyproject.toml + uv.lock together. For code-only changes leave uv.lock untouched.

Architecture

Registration is import-side-effect driven. There is no central registry call. mcp_instance.py creates the single shared FastMCP instance; every tool module decorates its functions with @mcp.tool(), so a tool only exists once its module is imported. server.py imports all tool modules at module load (the # noqa: E402 imports near the bottom) purely to trigger those decorators. If you add a new tool module, you must import it in server.py or its tools silently won't register. register_tools() in tools/__init__.py is a no-op kept for API compatibility.

Import layering avoids cycles. Tool modules import mcp from mcp_instance.py, never from server.py. mcp_instance.py imports the lifespan (setup_api_client) from api/client.py and the auth builder from auth.py. Keep this direction: server.py → tools → mcp_instance → api/client.

All HTTP to Intervals.icu goes through one function. api/client.py::make_intervals_request(url, api_key, params, method, data) is the only path out. It uses HTTP Basic auth (username literally "API_KEY", password = the per-user key), a shared lazily-created httpx.AsyncClient, 30s timeout, and returns either parsed JSON or an error dict {"error": True, "status_code": int, "message": str}. Tools must check for that error shape before formatting. The shared client is closed by the FastMCP lifespan (setup_api_client), which also handles test monkeypatching via server.httpx_client.

Tools return formatted strings, not raw JSON. Each @mcp.tool() is an async def -> str. The per-tool pattern: resolve the caller's (athlete_id, api_key) via credentials.resolve_caller_credentials() (catching CredentialError and returning its message), validate inputs, call make_intervals_request, error-check, then render human-readable text via helpers in utils/formatting.py. Because the return type is str, FastMCP auto-generates an outputSchema wrapping the result — this is expected.

Multi-tenancy: how a caller's credentials are resolved

• credentials.py::resolve_caller_credentials() is what tools call. It reads the OAuth access token from the request context (get_access_token()); if there is a subject, it looks up that user's active credentials in the store. With no auth context (stdio / local dev / tests) it falls back to the API_KEY / ATHLETE_ID env config, so single-user local runs still work. On failure it raises CredentialError, whose message is safe to show the user ("account isn't ready", or "not authenticated").
• store.py — async data access over the User model. get_active_credentials(sub) returns (athlete_id, api_key) only for an enabled user that actually has credentials, decrypting the key on the way out. Also has the admin/UI write helpers (upsert_login, set_credentials, set_enabled, etc.). Plaintext API keys are never persisted.
• crypto.py — AES-256-GCM authenticated encryption of the stored API key. Key comes from INTERVALS_ENC_KEY (base64 32 bytes, mounted from a k8s secret, shared with the UI so both read/write the same ciphertext). Layout: nonce(12) || ciphertext+tag; reversible (the server needs the key to call Intervals), not a hash.
• db/models.py — the users table (sub PK = OAuth subject, email, name, optional athlete_id + encrypted api_key_enc, enabled gate defaulting to false, timestamps). has_credentials property.
• db/session.py — lazily-created async engine/sessionmaker from DATABASE_URL (postgresql+asyncpg://…). Lazy so importing never requires a database (tests/stdio don't connect); configure()/reset() let tests point at aiosqlite.
• Schema is managed by Alembic (alembic/, alembic.ini); the deployment runs alembic upgrade head in an initContainer (Alembic is copied into the image for this).

Auth: JWT verification

auth.py holds the verifier. build_auth() returns (AuthSettings, TokenVerifier) only when MCP_ISSUER, MCP_RESOURCE, and MCP_JWKS_URI are all set; otherwise (None, None) and the server runs unauthenticated (stdio / dev / tests). AuthentikTokenVerifier validates the Bearer JWT against the JWKS (PyJWKClient), accepting algorithms EdDSA, RS256, ES256 (Better Auth signs EdDSA). It verifies signature + issuer + exp/iat strictly, but the audience check is soft (logged, not rejected) because this is a single-resource server behind a dedicated auth server with dynamic (DCR-issued) client ids. Env:

• MCP_ISSUER — expected token issuer (the auth server).
• MCP_RESOURCE — the /mcp resource URL; drives path-scoped RFC 9728 protected-resource metadata and the accepted audiences (both trailing-slash forms, plus optional MCP_CLIENT_ID).
• MCP_JWKS_URI — JWKS endpoint. In-cluster this is an internal URL so verification bypasses Cloudflare.

Transport

mcp_instance.py builds the FastMCP instance from env; server_setup.py starts it.

• MCP_TRANSPORT — stdio (default), sse, or http/streamable-http (deployment uses HTTP).
• MCP_STATELESS_HTTP / MCP_JSON_RESPONSE — HTTP tuning (defaults false = stateful + SSE, which is what a single Claude Desktop session wants). The Kubernetes deployment sets both true (stateless + JSON): the distributed Claude connector can hit any replica and can't rely on Mcp-Session-Id session affinity, so stateful/SSE breaks it.
• FASTMCP_HOST / FASTMCP_PORT — bind address for HTTP/SSE.
• server_setup.py adds CORS middleware to the streamable-http app so browser-based connector setup can reach /mcp: CORSMiddleware answers the OPTIONS preflight directly (200) instead of the auth layer rejecting it (401). Bearer-token auth with no cookies, so a wildcard origin is safe; it exposes Mcp-Session-Id and WWW-Authenticate.

Config

config.py::get_config() reads API_KEY, ATHLETE_ID, INTERVALS_API_BASE_URL from env (.env auto-loaded) — this is only the local/dev fallback identity, not the multi-tenant path. ATHLETE_ID must match r"i?\d+" (see utils/validation.py), validated at server startup, not import.

Layout

• mcp_instance.py — the shared FastMCP instance; wires transport tuning + auth from env.
• server.py — entry point; wires config, imports tools to register them, starts transport.
• server_setup.py — reads MCP_TRANSPORT, starts the chosen transport, adds CORS for streamable-http.
• auth.py — JWT/JWKS verification and AuthSettings construction.
• credentials.py / store.py / crypto.py / db/ — the multi-tenant credential store.
• tools/ — one module per domain: activities, events, custom_items, power_curves, gear, wellness.
• api/client.py — Intervals.icu HTTP client, Basic auth, error mapping, lifespan.
• utils/ — formatting.py, validation.py, dates.py, types.py (enums incl. TransportAliases, and workout Value/step dataclasses used by event tools).

Deployment / connecting

This is a remote OAuth MCP connector, not a local stdio server. To use it, add a custom remote connector in Claude pointing at https://intervalsicu.farhoodlabs.com/mcp. Name the connector without a dot (use intervals, not intervals.icu) — Claude Desktop/mobile won't load the tools if the name contains a dot. Claude then runs DCR against the auth server and Google login; the user must have been approved in the portal and have set their Intervals.icu credentials.

Testing conventions

Tests never hit the real API or a real database. Async tools use @pytest.mark.asyncio; Intervals HTTP is stubbed with pytest-mock (patch httpx.AsyncClient or monkeypatch server.httpx_client); the store is tested against aiosqlite via db/session.py::configure. Shared fixtures/mock payloads live in tests/sample_data.py. Cover both the success path and the {"error": True, ...} / CredentialError paths. pytest enforces a 90% coverage gate.

Note on stale docs

.cursor/rules/*.mdc and AGENTS.md predate the multi-tenant refactor (they describe the upstream single-tenant stdio server and claim all tools live in server.py). Trust this file and the code.