mcp-yandex-merchants: Instructions file for Claude Code

CLAUDE.md — mcp-yandex-merchants

MCP server for the Yandex Merchants (Яндекс Товары) partner API (TypeScript, stdio). This is a write API: tools wrap the 4 documented endpoints — feeds info (GET /feeds-info), price updates (POST /offer-prices/updates), hiding (POST /hidden-offers) and unhiding (DELETE /hidden-offers); raw_request is the escape hatch. The server talks to https://yandex.ru/products/api/ext/partner; auth is a Yandex OAuth token with the products:partner-api scope, sent as Authorization: OAuth <token> — the token must belong to the login that uploaded the YML feed. The token comes from the in-chat login (start_login/finish_login, stored on disk) or from YANDEX_MERCHANTS_OAUTH_TOKEN (which wins).

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 YANDEX_MERCHANTS_OAUTH_TOKEN)

Architecture

• src/config.ts — env → config. A missing YANDEX_MERCHANTS_OAUTH_TOKEN is NOT an error: the field stays undefined, the server starts anyway and the token is resolved per request (env → stored login); with neither source the client raises AuthRequiredError 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 YANDEX_MERCHANTS_BASE_URL, YANDEX_MERCHANTS_TIMEOUT_MS, YANDEX_MERCHANTS_MAX_RETRIES.
• src/oauth.ts — the OAuth flow: PKCE pair (S256), authorize URL against https://oauth.yandex.ru/verification_code, code exchange and refresh, explicit scope=products:partner-api + force_confirm=yes. No client_secret — this is a public client («Яндекс Товары — A1-x-Tech MCP», overridable via YANDEX_MERCHANTS_OAUTH_CLIENT_ID), and a secret inside an npm package would protect nothing. The pending verifier lives in one module-level slot (one stdio server = one user); a second start_login replaces it.
• src/credentials.ts — ~/.config/mcp-yandex-merchants/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 the env var + restart). It replaced the former CredentialsError.
• src/client.ts — maps each logical call (feedsInfo/updateOfferPrices/hideOffers/ showOffers) to its endpoint: OAuth auth resolved per request via TokenStore, the price wire shape ({ feed: { id }, id, price: { currencyId: "RUR", value, discountBase?, payBy? } }), hiddenOffers with ttlInHours stamped onto every element. request() rethrows AuthRequiredError before the retries and before fetch (a missing setup is not transport trouble), resolves the path against the base and rejects any path that escapes to a foreign origin (SSRF guard), retries 429 always but 5xx/network only for GET (a 502 after a write commits could duplicate it), re-mints a stored token once on 401 (403 stays out: here it means a wrong login or unconfirmed Webmaster rights, which a fresh token cannot fix), enforces an AbortController timeout that also covers reading the body, and throws MerchantsError(status, body).
• src/tools/auth.ts — auth_status, start_login, finish_login (verifies the new token with a live feeds-info call and warns when it sees zero feeds — a wrong-login token), logout. src/tools/feeds.ts — list_feeds, check_access (diagnostics: failures come back as { ok: false, error } data, not isError). src/tools/prices.ts — set_offer_price, update_offer_prices, set_offer_discount (validates the 5–95% window before the request). src/tools/hidden.ts — hide_offer, hide_offers, show_offers. src/tools/raw.ts — raw_request (GET/POST/DELETE, not read-only). src/tools/util.ts — ok/fail/errorMessage, the READ_ONLY/WRITE/ WRITE_IDEMPOTENT/WRITE_DELETE annotations and shared zod schema factories (feedId, offerId, price, ttlInHours, payByCondition).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded starts the server even on a config problem; connected = tokens.hasToken() is read once, only to pick the instructions text — without a token the initialize instructions open with the unconfigured prefix (log in via start_login, or set YANDEX_MERCHANTS_OAUTH_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.