mcp-vk-ads: Instructions file for Claude Code

CLAUDE.md — mcp-vk-ads

MCP server for the VK Ads (VK Реклама) API (TypeScript, stdio). Tools wrap the REST endpoints; 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 VK_ADS_TOKEN)

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

Architecture

• src/client.ts — HTTP client over https://ads.vk.com/api (override with VK_ADS_API_BASE): Bearer auth resolved per request from TokenStore (so a login mid-session takes effect at once) with one silent refresh+replay on 401, AbortController timeout (covers reading the body), SSRF guard (buildUrl refuses a path resolving off the API origin), retry/backoff (honors Retry-After) — 429 for any method, but 5xx and network errors ONLY for idempotent GET (a retried POST could duplicate a create), getAll offset/count pagination, VkAdsError(status, body). No sandbox, no quota header, no async report polling.
• src/tools/*.ts — one file per area (auth, account, adPlans, adGroups, banners, statistics, raw), each exports register<Name>Tools(server, client).
• src/oauth.ts / src/auth.ts / src/credentials.ts — the in-chat login. oauth.ts talks to v2/oauth2/token.json (mint + refresh, VK's error codes turned into advice); TokenStore resolves the token per request (env VK_ADS_TOKEN wins, else the stored login) and refreshes it; credentials.ts is the 0600 file under ~/.config/mcp-vk-ads/. finish_login stores the client_secret on purpose — VK refuses a refresh_token grant without it.
• 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). A server without a token no longer dies, so it pings unconfigured_start instead of startup_failed — keep them apart, or server_start stops meaning "a usable install started". reason is a closed vocabulary (missing_token, invalid_api_base, …) — never a variable's name or value.
• src/config.ts — env → config. A missing token is not an error: the server starts anyway so the user can connect from the chat (it used to exit before the MCP handshake, leaving a red cross and nothing to read). A malformed value still throws ConfigError (with a reason code), which index.ts carries into the session instead of exiting.