gdocs-mcp: Instructions file for Claude Code

CLAUDE.md — working conventions for this repo

Guidance for AI agents (and humans) working on gdocs-mcp. Read before adding or changing tools.

What this is

An MCP server that lets an agent treat a Google Doc like a local file: read as markdown, string-anchored edits, styling, suggestions, comments, tables, images, sharing, tabs, multi-account. Architecture and rationale live in DESIGN.md; the canonical tool list is the table in README.md; known API dead-ends are in docs/limitations.md.

Build / test

• npm run typecheck · npm run build (tsc) · npm test (vitest).
• Tests are sandboxed: test/setup.ts points GDOCS_MCP_CONFIG_DIR at a temp dir, so nothing touches a real ~/.config. Keep it that way — never let a module perform filesystem side effects at import time (see src/config.ts).

Tool-surface discipline (READ BEFORE ADDING A TOOL)

The tool count is a budget, not a free-for-all — every tool's schema costs context on every call and enlarges the model's selection space, which measurably lowers accuracy. We deliberately keep the surface small (19 tools). Before adding one, do this review and record the trade-off in the PR/commit:

1. Default to enhancing an existing tool. Can this be a new parameter or a target/op variant on a tool that already exists? Prefer that. Examples we chose: headers and footers became a segment param on every content tool, not a family of their own; a tab became a step in the document path, not a tab param or a family of tab tools (DESIGN.md §3d).
2. Merge symmetric verbs. CRUD verbs that share a target and param shape should be one parametric tool: write_doc (create when the path names nothing, replace when it names something), drive mv (rename and move, for files and tabs), add_comment({replyTo?}), share_doc (person vs. link), apply_suggestions (1+ ids).
3. A new tool is justified only when the vocabulary or return shape genuinely differs. set_page_setup earns its place because page geometry (margins/ size/orientation via updateDocumentStyle) shares nothing with text styling. Same test gates get_page_setup as its read counterpart.
4. Keep destructive verbs as distinct, named tools. Do NOT hide unshare_doc or a replacing write_doc behind a generic op enum or inside drive — their confirmation guards (confirmLoss, expectQuote, expectRole) must stay legible at the call site, and a user who allowlists a safe tool must not be allowlisting a destructive one with it (#47). No tool deletes a doc, folder or tab. A guard must be a fact the caller had to fetch, not one they supplied. confirmLoss comes from write_doc's own refusal, expectQuotedText from list_comments, expectContext/expectTitle from list_suggestions, expectRole from list_permissions — echoing one back proves the caller looked, and that the thing hasn't changed since. A guard over something they typed proves nothing: unshare_doc takes expectRole and NOT expectEmail, because the email is the selector (#43). A guard is named expect plus the name of the field it echoes: role is checked as expectRole, quotedText as expectQuotedText. A parameter that places something by a read's field takes that field's name as it is: add_comment(quotedText).
5. Uniform-vocabulary targets can merge; target-dependent style can't. A tool is clearest to the model when its style/param fields don't change based on the target. Paragraph, run and table style go through edit_doc as CSS because they share one vocabulary (DESIGN.md §2a, §2d); page geometry does NOT (margins and page size have no element to sit on), so set_page_setup stays its own tool.
6. Pair reads with writes. Every write must be visible to a read. For paragraph, run and table style that read is read_doc itself — the CSS it emits is the CSS edit_doc accepts, so no getter is needed. Anything markdown can't carry gets a getter: get_page_setup/set_page_setup. Shipping without one is a deliberate choice you state in the commit, not a default — this rule used to say "consider", which is how a table style setter shipped with no reader at all, leaving column widths and shading settable but invisible (#33).