mcp-yandex-metrica: Instructions file for Claude Code

CLAUDE.md — mcp-yandex-metrica

MCP server for the Yandex Metrica API (TypeScript, stdio). Read-only MVP: tools wrap the Management and Reporting APIs; raw_request is the escape hatch for everything without a dedicated tool.

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live READ-ONLY call (needs YANDEX_METRIKA_TOKEN)

More detail in docs/DEVELOPMENT.md. Tool list: docs/TOOLS.md.

Architecture

• src/client.ts — HTTP client over https://api-metrika.yandex.net (override with YANDEX_METRIKA_API_BASE): OAuth auth header, AbortController timeout, retry/backoff on 429 + 5xx (honors Retry-After), getAllStat limit/offset pagination of the Stat API, YandexMetrikaError(status, body). The client targets a full path ("management/v1/..." or "stat/v1/data") — Metrica has two API surfaces on one host.
• src/oauth.ts — the OAuth flow: PKCE pair (S256), authorize URL against https://oauth.yandex.ru/verification_code, code exchange and refresh. No client_secret — this is a public client, and a secret inside an npm package would protect nothing. The pending verifier lives in one module-level slot (one stdio server = one user); a second start_login replaces it.
• src/credentials.ts — ~/.config/mcp-yandex-metrica/credentials.json, mode 0600. An unparsable file reads as "not connected", never as an empty token.
• src/auth.ts — TokenStore: resolves the token per request (env wins over stored), refreshes on expiry, and raises AuthRequiredError whose message is the product — it is the only text the user ever sees about a missing token.
• src/tools/*.ts — auth (auth_status, start_login, finish_login, logout), counters (list_counters, list_goals), statistics (get_statistics), raw (raw_request); each exports register<Name>Tools(server, client).
• src/tools/util.ts — shared helpers (see conventions below).
• src/index.ts — wires every register* into the McpServer.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never data or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0). startup_failed is the exception: sendBlocking awaits it, because the caller exits right after and a fire-and-forget ping would die in flight. Its reason is a closed vocabulary (missing_token, …) — never a variable's name or value.
• src/config.ts — env → config; throws ConfigError (with a reason code) instead of exiting, so index.ts can report the drop-off before dying.