mcp-yandex-direct: Instructions file for Claude Code

CLAUDE.md — mcp-yandex-direct

MCP server for the Yandex Direct API v5 (TypeScript, stdio). Tools wrap the JSON services; 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 calls (needs YANDEX_DIRECT_TOKEN)

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

Architecture

• src/client.ts — HTTP client: timeout, retry/backoff, Units quota, getAll cursor pagination, report polling. Every request path (call/callV4/report) resolves the token through the TokenStore per request; a missing token raises AuthRequiredError before building the request, the retries and fetch. An authorization error (code 53) on a stored token triggers one silent refresh + replay per request.
• 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-direct/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, and it names both fixes (start_login, env variable).
• src/tools/*.ts — one file per service, each exports register<Name>Tools(server, client); src/tools/auth.ts (auth_status, start_login, finish_login, logout) additionally takes the TokenStore.
• src/tools/util.ts — shared helpers (see conventions below).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded starts the server even on a config problem; without a token the initialize instructions open with the unconfigured prefix (connect via start_login, or set YANDEX_DIRECT_TOKEN and restart).
• 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). server_start means "a usable install started"; an install without a token sends unconfigured_start instead. The reason is a closed vocabulary (missing_token, …) — never a variable's name or value. startup_failed remains for a config unusable at load time (malformed values), also fire-and-forget.
• src/config.ts — env → config. A missing YANDEX_DIRECT_TOKEN is NOT an error: the field stays undefined, the token is resolved per request (env → stored credentials) and the client raises AuthRequiredError at call time. ConfigError (with a reason code) is reserved for malformed values, caught by loadConfigOrDegraded in index.ts (no such checks exist today — the optional variables fall back to defaults on junk).