mcp-yandex-audience: Instructions file for Claude Code

CLAUDE.md — mcp-yandex-audience

MCP server for the Yandex Audience API (TypeScript, stdio). Write-capable: tools wrap segment management (file/CRM uploads with two-phase confirm, lookalike, pixel-based), pixels and access grants; raw_request is the escape hatch. The server talks to the Yandex Audience Management API (api-audience.yandex.ru, /v1/management/*); auth is a Yandex OAuth token sent as Authorization: OAuth <token> on every request — either from YANDEX_AUDIENCE_TOKEN or minted by the in-chat login (start_login / finish_login).

Commands

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

Architecture

• src/config.ts — env → config. A missing YANDEX_AUDIENCE_TOKEN is NOT an error: the field stays undefined, the server starts and the token is resolved per request by the TokenStore. ConfigError (with a reason code) is reserved for malformed values, caught by loadConfigOrDegraded in index.ts (no such checks exist today). Optional YANDEX_AUDIENCE_API_HOST (default https://api-audience.yandex.ru), YANDEX_AUDIENCE_TIMEOUT_MS, YANDEX_AUDIENCE_MAX_RETRIES.
• src/oauth.ts — the OAuth flow: PKCE pair (S256), authorize URL with the https://oauth.yandex.ru/verification_code redirect, code exchange and refresh. No client_secret — this is a public client, and a secret inside an npm package would protect nothing. Scope is pinned to audience:read audience:write. The pending verifier lives in one module-level slot (one stdio server = one user); a second start_login replaces it. Own app via YANDEX_AUDIENCE_OAUTH_CLIENT_ID.
• src/credentials.ts — ~/.config/mcp-yandex-audience/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 in the chat, or YANDEX_AUDIENCE_TOKEN + restart). It replaced the old CredentialsError.
• src/client.ts — one typed method per endpoint (listSegments, confirmSegment, createLookalikeSegment, createPixel, addSegmentGrant, …): OAuth header, path/query/body assembly ({segment: …} / {pixel: …} / {grant: …} envelopes, compact() drops undefined), upload() for multipart file uploads (no explicit Content-Type — fetch sets the boundary). The token comes from the TokenStore on EVERY attempt (never cached on the instance); a missing token raises AuthRequiredError while the auth header is built — rethrown before the retry/backoff branch and before fetch. A 401 (or 403 naming invalid_token) on a stored token triggers one silent refresh + replay. request() resolves the path against the base and rejects any path that escapes to a foreign origin (SSRF guard), enforces an AbortController timeout that also covers reading the body, and throws AudienceError(status, body) parsing the API's {errors: [{error_type, message, location}], code, message} format. Retries: 429 for any method; 5xx/network only for GET — repeating a committed write would duplicate it.
• src/tools/auth.ts — auth_status, start_login, finish_login, logout: the in-chat login. finish_login stores the token and proves it with a live listSegments read; logout deletes only the stored file, never the env token. src/tools/segments.ts — list_segments, upload_segment_file, upload_segment_csv_file, confirm_segment, rename_segment, delete_segment, create_lookalike_segment, create_pixel_segment. Upload tools accept file_path XOR content (checked in the handler — cross-field rules can't live in a plain-object inputSchema). src/tools/pixels.ts — list_pixels, create_pixel, update_pixel, delete_pixel. src/tools/grants.ts — list_segment_grants, add_segment_grant, delete_segment_grant. src/tools/raw.ts — raw_request (GET/POST/PUT/DELETE, defaults to GET). src/tools/util.ts — ok/fail, the annotation constants (READ_ONLY/WRITE/WRITE_IDEMPOTENT/DESTRUCTIVE/RAW) and shared zod field factories.
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded starts the server even on a config problem; connected = tokens.hasToken() is resolved once, only to pick the instructions text — without a token they open with the unconfigured prefix (connect via start_login right in the chat, or set YANDEX_AUDIENCE_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; no such checks exist today), also fire-and-forget.