mcp-google-contacts: Instructions file for Claude Code

CLAUDE.md — mcp-google-contacts

MCP server for the Google People API v1 — the API behind Google Contacts — (TypeScript, stdio). Mixed read/write: tools cover contact list/search/read, contact CRUD, contact groups and membership, batch mutations and read-only "Other contacts"; raw_request is the escape hatch. The server talks to https://people.googleapis.com with a Bearer token; the token is minted from an OAuth2 refresh token via https://oauth2.googleapis.com/token (or a static GOOGLE_CONTACTS_ACCESS_TOKEN, mostly for testing).

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 check (refresh-flow creds; optional resource argv/GOOGLE_CONTACTS_SMOKE_RESOURCE)
npm run smoke -- --live  # opt-in live WRITE scenario on disposable resources, cleanup in finally

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_CONTACTS_CLIENT_ID + GOOGLE_CONTACTS_CLIENT_SECRET + GOOGLE_CONTACTS_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_CONTACTS_ACCESS_TOKEN; optional GOOGLE_CONTACTS_API_BASE, GOOGLE_CONTACTS_TIMEOUT_MS, GOOGLE_CONTACTS_MAX_RETRIES. 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 and all wire mapping. Token lifecycle (cache until ~60s before expiry, dedupe concurrent refreshes, one forced re-mint + replay on 401); request() resolves the path against the base and rejects foreign origins (SSRF guard), enforces an AbortController timeout that also covers reading the body, retries 429 always but 5xx/network errors only for GET — replaying a write after an ambiguous failure would apply it twice — and throws GoogleContactsError(status, body). Array query values become repeated params (resourceNames=a&resourceNames=b for people:batchGet). buildPerson() maps the normalized contact vocabulary (given_name/emails/phones/... in ContactFields) to the wire Person and returns the touched field groups — that list IS the computed updatePersonFields mask. Etag handling lives here too: updateContact / updateContactGroup / batchUpdateContacts fetch the current etag when the caller has none (one extra read; batch uses a single batchGet). searchContacts / searchOtherContacts send the documented warmup request (empty query) once per endpoint per session — never retried, failures swallowed — before the first real query, not before every search.
• src/tools/contacts.ts — list_contacts, search_contacts, get_contact, batch_get_contacts, create_contact, update_contact, delete_contact. src/tools/groups.ts — list_contact_groups, get_contact_group, create_contact_group, update_contact_group, delete_contact_group, modify_group_members. src/tools/batch.ts — batch_create_contacts, batch_update_contacts, batch_delete_contacts. src/tools/other.ts — list_other_contacts (list or, with query, search), copy_other_contact. src/tools/raw.ts — raw_request (GET/POST/PATCH/PUT/DELETE). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE), shared zod schema factories (personResourceNameSchema, personFieldsSchema, ...), the contactFieldsShape() input factory and toContactFields() (snake_case → normalized, no wire knowledge).
• 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_config) — never a variable's name or value.