mcp-google-tagmanager: Instructions file for Claude Code

CLAUDE.md

MCP server (stdio) for the Google Tag Manager API v2 (tagmanager.googleapis.com/tagmanager/v2). Auth is Google OAuth 2.0: a refresh-token trio exchanged at oauth2.googleapis.com/token (cached until 60 s before expiry) or a direct access token. TypeScript, ESM, @modelcontextprotocol/sdk + zod, Node >= 20.

Commands

• npm run typecheck — tsc over src including tests (tsconfig.check.json)
• npm run build — compile to dist/ (tests and smoke excluded)
• npm test — unit suite (tsx loader) + dist smoke (real stdio handshake)
• npm run smoke — live read-only check (needs real credentials)
• npm run dev — tsx watch

Architecture

• src/index.ts — wiring only: telemetry → config → client → McpServer → register tools → stdio. 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/config.ts — env → TagManagerConfig; never exits. No credentials at all (empty string = missing) is NOT an error: the fields stay undefined and the server starts degraded. A partial setup still throws ConfigError(message, reason) with the historical per-variable checks; the reason codes (missing_client_id, missing_client_secret, missing_refresh_token) are pinned by config.test.ts. Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (opens with the historical startup error verbatim, then says to set the variables and restart) and hasCredentials().
• src/auth.ts — TokenProvider: refresh-token → access-token exchange, promise-shared, cached until expiry − 60 s; direct access token passes through. Token calls bypass the rate limiter (different quota). With no credentials at all it throws CredentialsError BEFORE any fetch — a degraded start must never reach the token endpoint or the retry loop.
• src/client.ts — ALL HTTP: URL building under /tagmanager/v2/, Bearer auth, SSRF guard, timeout covering body reads, the rate limiter and the retry policy. One typed method per endpoint; tools never build URLs.
• src/builtin-variable-types.ts — generated from the discovery doc; do not hand-edit.
• src/tools/*.ts — register<Domain>Tools(server, client); handlers are always try { ok(await client...) } catch (e) { fail(e) }.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never the OAuth credentials, account/container ids 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 the ConfigError code vocabulary (missing_client_id, missing_client_secret, missing_refresh_token) — never a variable's value.