mcp-yango-delivery: Instructions file for Claude Code

CLAUDE.md — mcp-yango-delivery

MCP server for the Yango Delivery B2B API (TypeScript, stdio) — the international brand of Yandex Delivery. A write API: tools create, accept and cancel real deliveries. Only the express (claims) contour exists in the international docs: b2b.taxi.yandex.net, POST/GET /b2b/cargo/integration/v2/*. Auth is Authorization: Bearer <YANGO_DELIVERY_TOKEN> from the delivery cabinet (Integration tab → "Get token"). The Russia-only offers/calculate method and the platform (NDD / pickup-point) contour are deliberately excluded. raw_request is the escape hatch for 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 YANGO_DELIVERY_TOKEN)

Architecture

• src/config.ts — env → config. A missing YANGO_DELIVERY_TOKEN is NOT an error: the field stays undefined, the server starts degraded and the client raises CredentialsError (lives in types.ts) 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: YANGO_DELIVERY_BASE_URL, YANGO_DELIVERY_LANG (default en), YANGO_DELIVERY_TIMEOUT_MS, YANGO_DELIVERY_MAX_RETRIES.
• src/client.ts — all HTTP. request(method, path, {query, body, idempotent}) first rejects a missing token 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 builds the query string, sends Authorization: Bearer + 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/claims.ts — the seven claim-lifecycle tools; src/tools/tracking.ts — the five tracking/contact tools; src/tools/raw.ts — raw_request (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 starts the server even on a config problem; without a token the initialize instructions open with the unconfigured prefix (set YANGO_DELIVERY_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.