a1-yandex-kit-skills: Instructions file for Claude Code

CLAUDE.md — a1-yandex-kit-skills

npm-workspaces monorepo: typed client, MCP server (stdio) and Claude agent skills for the Yandex KIT e-commerce API, all driven by the bundled OpenAPI spec (specs/kit-swagger.openapi.json — 166 operations, 24 tag groups, the single source of truth).

Commands

npm ci
npm run typecheck   # builds core first, then checks every workspace
npm run build       # core + mcp -> dist/
npm test            # unit tests, no network
npm run gen         # regenerate registry/types/TOOLS.md/skills (deterministic)
npm run validate:agent-plugin # validate root Agent Plugins manifest, MCP config and skills
npm run spec:fetch  # refresh specs/ from Yandex + diff report
npm run smoke       # live READ-ONLY calls (needs YANDEX_KIT_TOKEN)
npm run e2e         # live WRITE calls — TEST store only (needs YANDEX_KIT_E2E_WRITE=1)

Verify like CI does (node 20/22/24 matrix):

npm run typecheck && npm run build && npm test
npm run gen
git add -N -- packages/core/src/generated docs/TOOLS.md skills   # register untracked generated files
git diff --exit-code -- packages/core/src/generated docs/TOOLS.md skills
npx @modelcontextprotocol/inspector@2 --cli node packages/mcp/dist/index.js --method tools/list -e YANDEX_KIT_TOKEN=dummy

More detail in docs/DEVELOPMENT.md. Tool list: docs/TOOLS.md.

Repo map

• packages/core — yandex-kit-core: KitClient (Bearer auth, timeout, token-bucket rate limiter at 3 rps, backoff retries on network/5xx/429 (the live limiter answers 429 with a plain-text limited body, no Retry-After) and LIMIT_EXCEEDED which arrives with HTTP 400 — GET only: mutations always make exactly one network attempt (no idempotency contract from the API, a repeated write could duplicate the change), auto-pagination via listAll, per-operation content type: merge-patch and multipart where the spec says so), KitApiError, ajv-based validateRequestBody/resolveOperationSchema, and src/generated/{registry.json,types.ts}.
• packages/mcp — mcp-yandex-kit: stdio MCP server with 88 tools; src/tools/*.ts is one file per domain; meta.ts hosts the trio (search_operations, get_operation_schema, kit_request) that covers all 166 operations (92 have curated tools). telemetry.ts — anonymous usage pings to usage.gistrec.cloud (ids/names/versions only, never data or arguments; fire-and-forget, must never block or throw; opt-out YANDEX_KIT_TELEMETRY=0). startup_failed is the exception: sendBlocking awaits it, because the caller exits right after and a fire-and-forget ping would die in flight. Its reason is a closed vocabulary (missing_token, invalid_config) — never a variable's name or value.
• packages/codegen — private generators run via tsx: gen-registry, gen-types, gen-docs, gen-skills, fetch-spec, plus the offline Agent Plugins validator.
• skills/ — 6 generated API skills plus setup and the manually maintained operator, catalog-doctor, promo-launcher and launch-check scenarios. Each manual scenario skill records its editing invariants in skills/<name>/AGENTS.md.
• plugin.json + mcp.json — portable Agent Plugins package; mcp.json deliberately contains no store token.
• .codex-plugin/, .cursor-plugin/, .claude-plugin/, .agents/ and .mcp.json — client-specific or compatibility artifacts retained alongside the portable core.