mcp-shopify-admin CLAUDE.md

CLAUDE.md — mcp-shopify-admin

MCP server for the Shopify Admin API (GraphQL — the store admin, not the Storefront API), TypeScript over stdio. One endpoint https://{store}.myshopify.com/admin/api/{version}/graphql.json; every request is signed with an X-Shopify-Access-Token, and that token comes from one of two paths. SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET of a Dev Dashboard app is the recommended one: the client runs the client_credentials grant itself against https://{store}.myshopify.com/admin/oauth/access_token and keeps the token (24 hours) fresh — the only path open to a store set up today, since admin-created custom apps stopped being issuable on 2026-01-01. A ready-made SHOPIFY_ACCESS_TOKEN is still accepted, used as-is and never refreshed, for stores that already hold such a token; it wins when both are set. The store host comes from SHOPIFY_STORE_DOMAIN, the version from SHOPIFY_API_VERSION (default pinned in config.ts). The API is metered by a GraphQL cost bucket (per-query cost, restoreRate points restored per second) reported in extensions.cost of every response.

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + a dist smoke probe, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live READ-ONLY calls (needs the store domain + credentials)

Architecture

• src/config.ts — env → config. Missing SHOPIFY_STORE_DOMAIN / credentials (empty string = absent) is NOT an error: the fields stay undefined, the server starts degraded and the client raises CredentialsError (lives in types.ts) at call time. hasCredentials(config) is satisfied by either auth path — a ready-made SHOPIFY_ACCESS_TOKEN or the SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET pair the client can mint one with — and authMode(config) names which one is in play (token / client_credentials / none) for the startup line and telemetry, since the two behave differently when a token goes stale. ConfigError (with a reason code) is reserved for malformed values — invalid_store_domain (only *.myshopify.com hosts: silently sending the token to a foreign host is how tokens leak; a bare handle or pasted URL normalizes cleanly), invalid_api_version and invalid_api_base (must parse as an http/https URL) — and is caught by loadConfigOrDegraded in index.ts, which keeps the message as configProblem on the degraded config. describeTarget(config) is the only shape of the target that may be printed: the store domain, else the endpoint reduced to origin + path, so nothing a URL may carry (a user:password@, a token in the path) reaches stderr. Optional SHOPIFY_API_VERSION, SHOPIFY_TIMEOUT_MS, SHOPIFY_MAX_RETRIES, SHOPIFY_TOKEN_LEEWAY_SECONDS (how early a minted token is replaced, default 300), SHOPIFY_API_BASE (full endpoint override; also satisfies hasCredentials without a domain, for mocks).
• src/types.ts — config, CostInfo (flattened extensions.cost), ApiResponse<T> = {data, cost}, ConnectionPage<T> ({count, items, hasNextPage, endCursor}), the enum tuples (PRODUCT_STATUSES, ORDER_CANCEL_REASONS, INVENTORY_REASONS, GID_TYPES) the tools build zod enums from, ShopifyAdminError, MutationError, ValidationError, CredentialsError.
• src/client.ts — the GraphQL documents (compact selections: the consumer is an LLM) and one transport. The --- Auth --- section owns the token: authToken() returns a ready-made SHOPIFY_ACCESS_TOKEN untouched, otherwise the cached minted one while it is still more than the leeway away from expiry, otherwise the in-flight mint — the promise is stored, so a burst of parallel tool calls shares one exchange and a failed mint is never cached. fetchToken() posts the client_credentials grant to /admin/oauth/access_token (derived from the endpoint's origin, which keeps a mock self-consistent) and caches {value, expiresAt} in memory only, never on disk; it never retries, because its characteristic failure — shop_not_permitted, the app and the store sitting in different Shopify organizations — is not transient (tools/util.ts turns it into exactly that hint). forgetToken() drops the cache so the next attempt mints afresh; send() fetches the token per attempt, since a long retry ladder can outlive one. send() first rejects a missing credential with CredentialsError (before retries and fetch — the message is the product: it names the variables and the needed restart, or, when configProblem is set, the malformed variable instead of the credentials), then POSTs with an AbortController timeout that also covers reading the body, retries with backoff, lifts extensions.cost into the envelope and turns GraphQL errors — and a 200 that carries no data object — into ShopifyAdminError. request() also forwards an optional operationName. mutate() additionally turns a non-empty userErrors into MutationError (with errorsKey for renames: orderCancel → orderCancelUserErrors) and drops the empty field from clean results. Also holds the pre-flight validators: toGid (builds gids, refuses cross-type ones), isMutationDocument (retry safety for graphql_request, over firstOperationKind — a walk that skips comments, strings and (…) to find the first executable operation past any fragment definitions; unparseable counts as a mutation), throttleWaitSeconds (bucket math), normalizePageSize (clamp into 1..250).
• src/tools/*.ts — shop, products, orders, customers, inventory, discounts, raw; each exports one register*Tools(server, client). tools/util.ts — ok/fail, the annotation presets and the shared zod schema factories. tools/harness.ts — the fake server/client pair the tool tests share (excluded from the build in tsconfig.json).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no credentials" with no endpoint at all; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Проблема конфигурации: <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). Reasons are a closed vocabulary (missing_store_domain, missing_credentials, invalid_store_domain, invalid_api_version, invalid_api_base) — never a variable's name or value.