mcp-google-business: Instructions file for Claude Code

CLAUDE.md — mcp-google-business

MCP server for Google Business Profile (TypeScript, stdio). Read/write: tools wrap accounts, locations (Business Information), performance metrics, reviews and local posts; raw_request is the escape hatch. GBP is served by four hosts under one OAuth scope (https://www.googleapis.com/auth/business.manage): Account Management, Business Information and Performance (v1) plus the legacy v4 mybusiness.googleapis.com — reviews and local posts were never migrated to v1 and only exist there. Auth is an OAuth2 refresh flow (client id + secret + refresh token → Bearer), or a static access token for quick tests.

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + dist stdio 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. Accepts either the OAuth trio (GOOGLE_BUSINESS_CLIENT_ID/_CLIENT_SECRET/_REFRESH_TOKEN; a partial trio without an access token throws ConfigError incomplete_oauth_credentials) or GOOGLE_BUSINESS_ACCESS_TOKEN; optional timeout/retries and four per-service base overrides. DEFAULT_BASES (the host map) lives here. No credentials at all is NOT an error: the fields stay undefined 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: the ApiService → host routing (accounts/businessinfo/performance/v4), the OAuth2 token refresh with caching and in-flight dedupe, resource-name building (bareAccountId/bareLocationId accept bare ids and full names), the default readMask injection, flattened dailyRange.*/monthlyRange.* query params, retries (429/quota-403 always; 5xx/network only for non-POST), the AbortController timeout that also covers reading the body, the SSRF origin guard and GoogleBusinessError(status, body) with the quota-0 hint.
• src/tools/*.ts — one module per API group: accounts (1 tool), locations (7), performance (3), reviews (4), posts (4), raw (1) = 20 tools. src/tools/util.ts — ok/fail, the five annotation constants (READ_ONLY/WRITE/CREATE/DESTRUCTIVE/RAW) and the isoDate/isoMonth 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_credentials) — never a variable's name or value.