mcp-google-multi: Instructions file for Claude Code

Working on mcp-google-multi

Conventions for AI assistants modifying this codebase. v6 is user-OAuth only: stdio by default, optional Streamable HTTP (MCP_TRANSPORT=http|both) behind a built-in OAuth 2.1 authorization server; one owner identity context per transport, with seams (hint provider, boot gates, tenant purge) a multi-tenant host can fill. User-facing rationale for the big mechanisms (discover-first, fan-out, trimming, write-control, escape hatch) lives in docs/features.md; implementation rationale too long for a code comment (Windows rename retry, GET/HEAD body stripping, admin-scope gating) lives in docs/internals.md. Keep both in sync when behavior changes — comments stay one-line and point there.

Project shape

• src/index.ts — entry. main() dispatches the CLI commands (auth, migrate-tokens, migrate-config, doctor, reset, metrics, write-client-config, account export|import, config check), else resolves the transport (src/http-config.ts), the master key and usage metrics, then builds one McpServer + identity context + registry per transport: stdio, and/or HTTP (forces curated mode, mounts the OAuth AS, refuses to boot without MCP_OWNER_EMAILS unless multi-tenant boot gates are installed). Each registry's installListHandler() runs before connect.
• src/compose.ts — buildRegistry(server, ctx, mode?, metrics?) registers every enabled service (the curated SERVICES table plus GENERATED_SERVICES, gates in src/services.ts, all filtered by GOOGLE_TOOLSETS), fails fast if registry.services() is empty (BEFORE meta tools register — escape tools would mask an empty service set), then registerDiscoverTools() + registerEscapeTools() + registerAccountTools() + registerDiagnoseTool(), plus registerAccountWizardTools() for the owner context only. requestHooksFor() builds the per-request arg-normalization / unknown-arg / validation-envelope hooks both transports share. No import-time side effects.
• src/registry.ts — ToolRegistry wraps the MCP server: records a ToolEntry per tool (name, service, cud, description, inputShape, annotations, clientMeta?, meta, generated, irreversible, requiredScopes?), derives cud (read/create/update/delete) from the tool name via inferCud, enforces write-control by wrapping every CUD handler, injects computed annotations (readOnlyHint/destructiveHint; anthropic/requiresUserInteraction on IRREVERSIBLE_TOOLS), and owns discover-first visibility: all tools register eagerly (always callable — graceful dispatch), but the custom tools/list handler advertises per GOOGLE_DISCOVERY mode (lazy default = meta + reveal()ed services; curated = + all curated; eager = everything; generated provenance on ToolEntry from the explicit-cud marker; tools no catalog bundle can authorize are never advertised). discover_all/discover_reset metas toggle a runtime lazy→curated overlay (expand()/collapse(), both fire tools/list_changed; collapse also clears reveals — a client mishandling a shrinking list degrades collapse to a session no-op, zero correctness impact). hideServices(services) keeps whole services out of tools/list whatever the mode or a later reveal (hidden, not unregistered: still callable by name and listed by {service}_discover; meta tools never hidden; each call replaces the earlier set) for a host that serves one registry per identity. The httpConfirm field (HttpConfirm, see src/http-confirm.ts) decides how an escape-hatch write is confirmed over HTTP. installListHandler() must run after registration, before connect. Service files call server.registerTool(...) — server is a ToolRegistry.
• src/discover.ts — registerDiscoverTools(): one eager {service}_discover meta-tool per service; returns the catalog (registry.catalog), reveals the service, triggers tools/list_changed. Never emit tool_reference content blocks or top-level defer_loading fields — strict SDK clients reject/strip them (a client-side constraint, independent of the server SDK version).
• src/toolsets.ts — GOOGLE_TOOLSETS parsing (all | CSV of service names).
• src/discovery-client.ts — runtime Google API Discovery: loadMethodIndex(api) fetches https://www.googleapis.com/discovery/v1/apis/{id}/{version}/rest on demand, disk-caches 7 days (DISCOVERY_CACHE_PATH), stale-if-offline; cudFromMethod (HTTP verb → cud, POST read-verbs like batchGet → read), expandPath ({param} + {+param} templates), searchMethods. Deps injectable for tests — never hit the network in unit tests.
• src/tools/google-api.ts — registerEscapeTools(): eager google_api_search + google_api_call. The call tool enforces write-control ITSELF (its registry cud is read, so the wrapper doesn't gate it) via isAllowed on the method's derived cud — keep that check when touching this file.
• src/fanout.ts — cross-account fan-out: parseAccountSelector ("*" | CSV | single), runFanout (bounded 5, per-account isolation, merged {results, partial} envelope with parsed payloads; never embed raw JSON strings), fanoutAccountField (union schema: a live *-or-alias check | CSV regex; the set is read at parse time). Wired in registry.ts: read tools only, never meta (google_api_call infers cud=read but executes writes), never FANOUT_EXCLUDE (read tools that write local files). Fan-out wraps the raw handler INNERMOST so compaction runs once on the merged envelope.
• src/tools/accounts-tool.ts — eager account_list meta tool + deriveAccountHealth (pure, deps-injectable). Reads the context's token store through accountHealthDepsFor(ctx.tokenStore) — NEVER getClient (would attach refresh listeners). readToken throws on decrypt failure (only returns null when missing) — keep the per-account try/catch. Never output token values.
• src/trim.ts — response trimming: compactResult (registry re-serializes every JSON text output compactly; GOOGLE_TRIM=off opts out — compaction only, never the caps), capText (paging caps with truncated/totalChars), sliceClean (permanent caps — drops a trailing lone surrogate). Fat readers own their caps: drive_read maxChars/offset, gmail reads 50k body cap + full param, calendar_list_events AND calendar_list_instances list-mode formatEvent(e, {full:false}). New fat-payload tools should reuse these helpers.
• src/write-control.ts — resolvePolicy() (env → policy) + isAllowed() (deny-by-default verdict) + denyReason()/writeDisabledResult() + describePolicy() (config check rendering) + IRREVERSIBLE_TOOLS. src/outbound-allowlist.ts — opt-in GOOGLE_OUTBOUND_ALLOWLIST recipient gate (Gmail recipients, Calendar attendees, Drive grantees, escape-hatch bodies); off when unset.
• src/token-store.ts — encrypted token store (AES-256-GCM, key from resolveMasterKey()); readToken/writeToken/updateToken/hasToken over the owner dir, createTokenStore(dir, {tenantId?}) for any other. The migrate-tokens CLI lives in src/migrate-tokens.ts. src/master-key.ts — MASTER_KEY and MCP_JWT_KEY resolution (see Auth / tokens).
• src/auth.ts — OAuth flow + per-account scope resolution: each account's scopeProfile (from the AccountSet) selects bundles from the catalog; getOptionalBundles() returns the UNION across accounts (drives service registration), authz stays per-account; legacy GOOGLE_OPTIONAL_SCOPES acts as an implicit global profile (warns). src/scope-catalog.ts — the ONE bundle catalog (scopes + description + risk + workspaceOnly; keys are frozen public API, renames via BUNDLE_ALIASES only); unknown bundle names fail E_UNKNOWN_BUNDLE with a did-you-mean hint.
• src/client.ts — makeGetClient(contextKey, deps) builds a context's client factory; getClient is the owner's. Fresh OAuth2Client per call from the encrypted token (concurrent calls for one alias share the in-flight build); its tokens listener re-encrypts on refresh (updateToken). CuratedToolDeps (getClientFn, localFiles) is the injection surface for curated tool files.
• src/accounts.ts — resolveAccounts() builds the AccountSet (registry): whole-registry env override via GOOGLE_ACCOUNTS, else config.json; getAccountSet() is the live accessor (dispatch-time readers use it, never a captured snapshot); invalidateAccountSet()/isAccountSetStale() back the reload path. Token dir defaults to ~/.config/mcp-google-multi/tokens (override TOKEN_STORE_PATH).
• src/config-file.ts — config.json zod-strict schema (secrets-shaped keys fail), version gate, mutateConfigFile read-latest-under-lock writer. src/fs-atomic.ts — path-keyed hardlink lock + atomic write (generalized from the token store; token writes delegate to it).
• src/identity.ts — buildIdentityContext(env, {transport}): the frozen forward-compat seam {subject, accounts, policy, getClient, tokenStore} (subject is 'owner' in the free core); buildRegistry(server, ctx) consumes it. index.ts builds one owner context per transport; isOwnerContext() gates host-disk tools and the account wizard.
• src/migrate-config.ts — migrate-config CLI: env -> config.json accounts (idempotent, never edits env).
• src/tools/_errors.ts — mapGoogleError typed taxonomy + handleGoogleApiError result wrapper; each service file defines its own handle<Service>Error shim over it (optionally with a service-specific 403 hint).
• src/tools/_coerce.ts — coerceArray/coerceJson/coerceBoolean for string-encoded client args.
• src/scope-observability.ts — the #114 three-state classifier (callable / requestable_not_granted / not_requestable{add_bundle|account_type|unknown_scope}): joins a method's required scopes (escape hatch: runtime Discovery; generated tools: baked+interned at gen time on ApiMethodRef.scopes) against the account's GRANTED token scopes, enriches insufficient_scope hints with copy-pasteable remediation and an honest retriable. account_list's scopes block is the compact profile∪granted report; the registered-tool universe is doctor's. Also exports accountScopeSets (granted and profile scope sets for one account; ScopeSetDeps reads a custom token store) and summarizeToolScopes (how many registered tools an account can call and which bundle unlocks the rest), behind the Scopes line of doctor and config check.
• src/executor.ts — executeApiMethod: the shared REST executor for generated tools and google_api_call (100k-char response cap).
• src/arg-normalize.ts / src/arg-strict.ts — transport-level argument handling: snake_case→camelCase key rename (GOOGLE_ARG_NORMALIZE, on by default), unknown-argument screening (GOOGLE_ARG_UNKNOWN=reject|warn|off, default reject), and withValidationEnvelope (SDK schema-validation prose → JSON error envelope).
• src/http-config.ts — MCP_TRANSPORT (stdio default | http | both), MCP_HTTP_HOST/MCP_HTTP_PORT (127.0.0.1:4243), MCP_PUBLIC_URL, MCP_ALLOWED_ORIGINS; canonicalizes the advertised resource URI exactly once. src/http-transport.ts — HttpTransportHost: node:http server, Host/Origin guard, stateless per-request /mcp dispatch, mounted AS routes. Stateless HTTP cannot push tools/list_changed, so it forces curated mode.
• src/http-confirm.ts: HttpConfirm (the registry's httpConfirm field): how an escape-hatch write that needs a human is confirmed over stateless HTTP, where the server cannot ask mid-call. 2026-07-28 revision: an SDK inputRequired result (elicit key confirm, signed requestState bound to the call hash and the subject), served by the second server a lane builds through ServerTarget.modern; the client repeats the call with its answer. 2025 revision, only with MCP_HTTP_CONFIRM_TOKEN (or ServerTarget.confirmToken): refusal confirmation_required with a summary and a single-use confirmToken (ConfirmTokens, signed with MCP_CONFIRM_KEY, expiry MCP_CONFIRM_TTL_SECONDS); the repeat call carries it outside the tool schema, and a changed, reused or expired token is confirmation_invalid. stdio keeps live elicitation. User doc: docs/configuration.md; rationale: docs/internals.md.
• src/oauth-as.ts — buildAuthServer(): built-in OAuth 2.1 authorization + resource server. Mints its own audience-bound HS256 token for the MCP client, gates on an owner Google login (MCP_OWNER_EMAILS; those Google tokens are discarded), keeps per-alias Google tokens separate, and issues signed alias_reauth links. src/mcp-token.ts — JWT/state/code signing, replay guard, rotated refresh store, keyed by MCP_JWT_KEY. src/cimd-cache.ts + src/ssrf-guard.ts — client-ID metadata document fetch (HTTPS only, private ranges blocked, capped, cached). src/oauth-consent.ts — loopback consent on an ephemeral port, shared by auth --account and the wizard. src/reauth-hint.ts — re-auth hint: the CLI command over stdio, a signed link over HTTP.
• src/hint-provider.ts — optional process-global remediation-hint provider (setHintProvider/hints()), keyed by HintCase facts. A single-owner process never installs one, so every call site keeps its literal. src/boot-gates.ts / src/tenant-purge.ts — multi-tenant boot gates and token-purge primitives; the free core never installs or calls them.
• src/doctor.ts — runDiagnostics(): one engine, two skins (doctor CLI, diagnose tool); also the reset CLI. src/api-probe.ts — doctor's live per-service API-enablement probe.
• src/tools/account-wizard.ts — elicitation-driven account_add / account_reauth / account_write_config (cud=read via CUD_OVERRIDES, gated by anthropic/requiresUserInteraction); owner context only. src/client-config.ts — MCP-client detection + idempotent config entry (write-client-config CLI); never inlines secrets. src/setup-prompt.ts — the setup MCP prompt (Google Cloud Console walkthrough).
• src/usage-metrics.ts / src/metrics-tap.ts / src/metrics-cli.ts — local usage metrics, off by default (GOOGLE_USAGE_METRICS, USAGE_METRICS_PATH); zero egress (import set allowlisted in tests/usage-metrics.test.ts), no identity dimensions (it counts protocol revisions as proto and clients as [email protected] as clients, nothing else about a caller); metrics CLI reads the local files. User doc: docs/usage-metrics.md.
• src/registry-transfer.ts — account export / account import: passphrase-encrypted bundle of config + still-encrypted token files (never MASTER_KEY or the client secret); refuses a tenant-namespaced store.
• src/env-load.ts (.env loading, real env wins), src/net-tuning.ts (raises Node's happy-eyeballs connect timeout), src/open-url.ts (best-effort browser launch).
• Public API: the exports map in package.json is the supported surface for hosts that embed the core (MIGRATION-v6.md lists each subpath); tests/exports-map.test.ts pins it. A module a host needs must be declared there, and a deep import into dist/ outside the map is unsupported.