mcp-yandex-dostavka: Instructions file for Claude Code

CLAUDE.md — mcp-yandex-dostavka

MCP server for the Yandex Delivery B2B API (TypeScript, stdio). A write API: tools create, accept and cancel real deliveries. Two independent contours behind one server: express (same-day claims — b2b.taxi.yandex.net, POST/GET /b2b/cargo/integration/v2/*) and platform (NDD / pickup points — b2b-authproxy.taxi.yandex.net, /api/b2b/platform/*). Auth on both is Authorization: Bearer <token> from the dostavka.yandex.ru cabinet; the shared YANDEX_DELIVERY_TOKEN can be overridden per contour. raw_request is the escape hatch for the ~30 endpoints without a dedicated tool.

Commands

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

Architecture

• src/config.ts — env → config. Tokens: YANDEX_DELIVERY_TOKEN fills both contours, YANDEX_DELIVERY_EXPRESS_TOKEN / YANDEX_DELIVERY_PLATFORM_TOKEN override it. A missing token is NOT an error: the field stays undefined (an empty string reads as absent), the server starts degraded and the client raises CredentialsError (lives in types.ts) when a call needs that contour. ConfigError (with a reason code) is reserved for malformed values, caught by loadConfigOrDegraded in index.ts (no such checks exist today). Optional: *_BASE_URL per contour (platform test contour: b2b.taxi.tst.yandex.net), YANDEX_DELIVERY_LANG, YANDEX_DELIVERY_TIMEOUT_MS, YANDEX_DELIVERY_MAX_RETRIES.
• src/client.ts — all HTTP. request(contour, method, path, {query, body, idempotent}) picks the base + Bearer token by contour (a bare contour throws CredentialsError right there — before the request is built, retried or sent; the message opens with the historical startup text verbatim and ends with the env-and-restart fix), builds the query string, sends Accept-Language, rejects paths that resolve to a foreign origin (SSRF guard), enforces an AbortController timeout that also covers reading the body, retries with backoff (honors Retry-After) and throws DeliveryError(status, body). One typed method per endpoint; claims/create mints a UUID request_id (query param) when the caller omits one.
• src/tools/express.ts — the nine express_* tools; src/tools/platform.ts — the six platform_* tools; src/tools/raw.ts — raw_request (contour + path + query + body). src/tools/util.ts — ok/fail, the READ_ONLY/WRITE/DESTRUCTIVE annotation presets and shared zod schema factories.
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no tokens"; a start with a missing token prepends the per-contour unconfigured prefix — plus Проблема конфигурации: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a fully configured install or unconfigured_start otherwise (reason in the old check order: with both contours bare it is missing_token, never a contour-specific code).
• 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 missing a token sends unconfigured_start instead, and startup_failed remains for a config unusable at load time (malformed values). Every reason is a closed vocabulary (missing_token, missing_express_token, missing_platform_token) — never a variable's name or value.