mcp-yandex-wordstat: Instructions file for Claude Code

CLAUDE.md — mcp-yandex-wordstat

MCP server for the Yandex Wordstat API (TypeScript, stdio). Read-only: tools wrap the search-demand reports (top/related queries, dynamics, regional distribution); raw_request is the escape hatch. The server talks to the Yandex Cloud Search API v2 (searchapi.api.cloud.yandex.net, POST /v2/wordstat/*); auth is an Api-Key and every request body carries a folderId. (The legacy standalone oauth flavor — api.wordstat.yandex.net, Bearer, v1/* — was removed in 2.0.0; Yandex folded that functionality into the Search API.)

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 WORDSTAT_API_KEY + WORDSTAT_FOLDER_ID)

Architecture

• src/config.ts — env → config. Missing WORDSTAT_API_KEY / WORDSTAT_FOLDER_ID is NOT an error: the fields stay undefined, the server starts degraded and the client raises CredentialsError at call time. ConfigError (with a reason code) is reserved for malformed values, caught by loadConfigOrDegraded in index.ts (no such checks exist today). Optional WORDSTAT_LANG, WORDSTAT_API_BASE, WORDSTAT_TIMEOUT_MS, WORDSTAT_MAX_RETRIES.
• src/client.ts — maps each logical call (topRequests/dynamics/regions/regionsTree) to a v2/wordstat/* path: Api-Key auth, all POST, folderId injected into every body, regions as strings, DEVICE_* / PERIOD_* / REGION_* enums. request() first rejects a missing credential with CredentialsError (before building the request, the retries and fetch — the message is the product: it names the env variable to set and the needed restart), then resolves the path against the base and rejects any path that escapes to a foreign origin (SSRF guard), retries 429 / 5xx / network errors with backoff (honors Retry-After), enforces an AbortController timeout that also covers reading the body, and throws WordstatError(status, body).
• src/tools/wordstat.ts — top_requests, dynamics, regions, list_regions. Inputs are normalized (regionIds, devices, period, regionMode); the client does the wire mapping. src/tools/raw.ts — raw_request (POST only). src/tools/util.ts — ok/fail, the READ_ONLY annotation and shared zod schema factories (deviceEnum, rfc3339Date).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded starts the server even on a config problem; without credentials the initialize instructions open with the unconfigured prefix (set WORDSTAT_API_KEY / WORDSTAT_FOLDER_ID 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 credentials sends unconfigured_start instead. The reason is a closed vocabulary (missing_token, missing_folder_id) — never a variable's name or value. startup_failed remains for a config unusable at load time (malformed values), also fire-and-forget.