mcp-google-merchants: Instructions file for Claude Code

CLAUDE.md — mcp-google-merchants

MCP server for Google Merchant Center via the Merchant API v1 (TypeScript, stdio). Single host https://merchantapi.googleapis.com with per-sub-API path prefixes (accounts/v1, products/v1, datasources/v1, promotions/v1, reports/v1, issueresolution/v1, quota/v1). Auth is Google OAuth 2.0 (scope https://www.googleapis.com/auth/content): the client exchanges a refresh token at https://oauth2.googleapis.com/token and caches the access token, or uses a static GOOGLE_MERCHANTS_ACCESS_TOKEN. This is a write-capable server: products and promotions can be created and deleted. Do NOT copy paths or product-ID formats from Content API for Shopping (content/v2.1, sunset 2026-08-18) or v1beta (shut down 2026-02-28) — v1 product IDs are contentLanguage~feedLabel~offerId, no channel.

Commands

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

Architecture

• src/config.ts — env → config. Credentials: the OAuth trio (GOOGLE_MERCHANTS_CLIENT_ID/_CLIENT_SECRET/_REFRESH_TOKEN — all three or ConfigError incomplete_oauth, whose message lists the missing variables) or GOOGLE_MERCHANTS_ACCESS_TOKEN; optional GOOGLE_MERCHANTS_ACCOUNT_ID, _API_BASE, _TOKEN_URL, _TIMEOUT_MS, _MAX_RETRIES. No credentials at all is NOT an error: the fields stay undefined (empty string = absent) and the server starts degraded. Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (opens with the historical startup error verbatim, then names the variables and the restart) and hasCredentials().
• src/client.ts — all HTTP and all wire mapping: token refresh (cached, shared across concurrent calls, one automatic retry on 401), accountPath() fallback to the configured default account, data-source name expansion, per-endpoint methods with camelCase wire bodies, query-param building. request() resolves the path against the base and rejects any path that escapes to a foreign origin (SSRF guard), retries 429 on any method but 5xx/network errors on GET only, honors Retry-After, enforces an AbortController timeout that also covers reading the body, and throws MerchantsError(status, body) (decodes the Google error envelope).
• src/tools/*.ts — one register fn per domain (accounts, products, datasources, promotions, reports, issues, quota) + raw.ts (raw_request, full method enum, DESTRUCTIVE annotations). util.ts — ok/fail, the READ_ONLY/WRITE/DESTRUCTIVE annotation constants 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 credentials"; 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"; unconfigured_start is a degraded start and startup_failed a malformed config caught at load — both carry a reason from a closed vocabulary (missing_credentials, incomplete_oauth) — never a variable's name or value.