mcp-google-docs CLAUDE.md

CLAUDE.md — mcp-google-docs

MCP server for the Google Docs API v1 (TypeScript, stdio). Mixed read/write: tools cover document creation (incl. from Markdown), reading as text/structure/ Markdown, index-based text editing, character/paragraph styles, lists, tables, breaks, images, Drive-backed comments and export; raw_request is the escape hatch. The server talks to https://docs.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_DOCS_ACCESS_TOKEN, mostly for testing). Export, Markdown conversion and comments have no Docs API endpoints — the client calls Drive API v3 on https://www.googleapis.com as an internal dependency; no general-purpose Drive tool is exposed.

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 check: read-only by default; GOOGLE_DOCS_SMOKE_LIVE_WRITE=1
                   # runs create→edit→export→delete on a disposable doc (cleanup in finally)

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_DOCS_CLIENT_ID + GOOGLE_DOCS_CLIENT_SECRET + GOOGLE_DOCS_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_DOCS_ACCESS_TOKEN; optional GOOGLE_DOCS_API_BASE, GOOGLE_DOCS_DRIVE_API_BASE, GOOGLE_DOCS_TIMEOUT_MS, GOOGLE_DOCS_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 for BOTH hosts. Token lifecycle (cache until ~60s before expiry, dedupe concurrent refreshes, one forced re-mint + replay on 401); the private send() core resolves the path against the given base and rejects foreign origins (SSRF guard), enforces an AbortController timeout that also covers reading the body (bytes, because exports are binary), retries 429 always but 5xx/network errors only for GET — replaying a write after an ambiguous failure would duplicate it — and throws GoogleDocsError(status, body). Typed per-endpoint methods build the batchUpdate requests and computed fields masks; pure exported helpers (buildTextStyle, buildParagraphStyle, mapBulletPreset, hexToRgbColor, extractBlocks, extractDocumentText, extractTabTree) carry the normalized→wire vocabulary and the text extraction. Drive methods (exportDocument, importMarkdown, createDocumentFromMarkdown, comments, deleteFile for smoke cleanup) use the same core with the Drive base; request() (raw_request surface) is pinned to the Docs base.
• src/tools/documents.ts — create_document, get_document, read_document_text, list_tabs, export_document, import_markdown. src/tools/text.ts — insert_text, replace_range, replace_all_text, delete_range. src/tools/styles.ts — style_text, style_paragraph, set_paragraph_bullets. src/tools/tables.ts — insert_table, edit_table. src/tools/structure.ts — insert_break. src/tools/images.ts — insert_image, replace_image. src/tools/comments.ts — list_comments, manage_comment. src/tools/raw.ts — raw_request (GET/POST, Docs host only). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE) and shared zod schema factories (documentIdSchema, indexSchema, tabIdSchema, segmentIdSchema, hexColorSchema).
• 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.