mcp-yango-retail: Instructions file for Claude Code

CLAUDE.md — mcp-yango-retail

MCP server for the Yango Tech Retail (grocery platform) B2B API (TypeScript, stdio). A write API: tools create orders and overwrite prices, discounts and stock levels. Backend: https://api.retailtech.yango.com, every endpoint under /b2b/v1/*, every call is a POST with a JSON body — including reads. Auth is Authorization: Bearer <token> on every request (YANGO_RETAIL_TOKEN). There is no public docs portal: the official Python client (yango-tech/yango-tech-grocery-client) is the de-facto spec. raw_request is the escape hatch for the ~15 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 (stores/get; needs YANGO_RETAIL_TOKEN)

Architecture

• src/config.ts — env → config. A missing YANGO_RETAIL_TOKEN (alias YANGO_AUTH_TOKEN) is NOT an error: the field stays undefined, the server starts degraded and the client raises CredentialsError at call time (telemetry reason: missing_token). Also home to CredentialsError / MISSING_TOKEN_MESSAGE (opens with the historical startup error verbatim, then names the variables and the restart). ConfigError (with a reason code) is reserved for malformed values, caught by loadConfigOrDegraded in index.ts (no such checks exist today). Optional: YANGO_RETAIL_API_BASE_URL (aliases YANGO_API_BASE_URL, YANGO_DOMAIN), YANGO_RETAIL_TIMEOUT_MS, YANGO_RETAIL_MAX_RETRIES.
• src/client.ts — all HTTP. request(path, 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 POSTs JSON with the Bearer header, 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 YangoRetailError(status, body, {traceId, requestId}) with the x-yatraceid/x-yarequestid headers. One typed method per endpoint; page-size defaults (products 300, others 100), the price_per_quantity default and the stocks update_mode mapping live here.
• src/tools/orders.ts — six order/receipt tools; src/tools/catalog.ts — stores + products; src/tools/pricing.ts — price lists, prices, discounts; src/tools/stocks.ts — stock feed + update; src/tools/raw.ts — raw_request. 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 token"; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Configuration problem: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a configured install or unconfigured_start (with the reason) otherwise.
• 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.