verified-googledocs-mcp

An MCP server for Google Docs whose writes carry proof. Every mutating tool re-reads the affected content from the document after it writes and returns evidence of what actually changed: before/after excerpts, the match count, and the document revision before and after. A tool never reports success for an edit that did not land.

Status: all 20 tools are implemented, covered by an offline unit suite, and exercised against the real Google Docs and Drive APIs by the live test suite. The original fourteen passed the formal live acceptance gate; the gate is rerun before each release. Install with uvx verified-googledocs-mcp. See Status.

The problem

Driving Google Docs from an agent through a general Workspace MCP server tends to fail in quiet, expensive ways:

• A findAndReplace meant for one tab silently edits every tab in the document.
• A search returns "0 matches" because the document has curly quotes or a non-breaking space the query doesn't, with no hint why.
• A replace meant for one occurrence hits a repeated sentence and collapses both.
• A "resolve comment" call returns success while the comment stays open.
• Listing comments misses suggested edits entirely.
• A markdown merge injects garbled text that a human only catches days later.

Each of these has a procedural workaround: tell the agent to scope to a tab, retry with normalized quotes, re-read after every write, never trust a resolve result. Those instructions work until someone forgets one. This server moves the discipline into the protocol, where it is deterministic.

The verified-write contract

Every mutating tool runs the same pipeline: read the tab, locate the target, apply the edit under a revision precondition, read the tab again, and return evidence built from the second read. The return value is a claim about the document's state after the call, backed by a server-side re-read, not an echo of the API response.

// replace_text(doc_id, tab_id, find="teh", replace="the", expected_matches=1)
{
  "applied": true,
  "match_count": 1,
  "rung": "exact",                 // which normalization rung matched
  "before": "...±200 chars around the edit, pre-write...",
  "after":  "...the same span, re-read after the write...",
  "revision_before": "ALm37BX...",
  "revision_after":  "ALm37Cy...",
  "audit_logged": true
}

When something is wrong, the tool fails loud and diagnosed, with a typed error the agent can act on in one round trip rather than guessing:

{
  "error_code": "MATCH_COUNT_MISMATCH",
  "message": "expected 1 match(es) but found 3 at rung 'exact'",
  "diagnostics": { "expected": 1, "actual": 3, "spans": [ /* every location */ ] },
  "retryable": false
}

What backs the guarantee

• Tab-scoped by default. Editing tools require an explicit tab_id. There is no whole-document replace, so a one-tab edit can never leak into a cover letter or an appendix tab.
• Normalization ladder. A search tries exact match, then curly/straight quote equivalence, then non-breaking-space and whitespace-run equivalence, then soft-hyphen stripping, and reports which rung matched. A zero-match result includes the nearest near-miss span it found.
• Match-count guard. expected_matches defaults to 1. If the real count differs, the tool makes no edit and returns every match location.
• Revision preconditions. Writes carry writeControl.requiredRevisionId from the pre-read, so a document that changed underneath the operation is rejected by the API rather than edited blind. Section ranges from find_sections are stamped with the revision they were computed at and refuse to apply once stale.
• UTF-16 correct. Match spans are mapped to the UTF-16 code units the Docs API indexes by, so emoji, combining marks, and other astral characters don't shift an edit onto the wrong text.
• Audit trail. Every mutation appends a line to a local JSONL log. The append is best-effort: it never fails a write, and if it can't be written the evidence says so (audit_logged: false).

Evidence by family

The guarantee is not one universal payload — it is a per-family invariant. Each family re-reads the document after the write and proves the property that family is responsible for. Every mutating tool also carries revision_before, revision_after, and audit_logged.

The read and sync tools (read_document, list_tabs, find_sections, list_open_items, get_comment_thread, diff_tab_vs_file, list_tables, get_table) make no changes and carry no applied/evidence payload. export_pdf is also a read/export tool in this sense — it returns file facts (bytes_written, sha256, page_count) rather than an applied key, since nothing in the document changes.

Dry run

Eight mutating tools (replace_text, format_text, replace_range_markdown, replace_tab_markdown, append_markdown, insert_image, replace_table_row, insert_table) accept dry_run=true. No API write is issued; the response carries applied: false, an empty revision_after (no write, so no new revision), audit_logged: false, and — for replace_text — a predicted after excerpt computed by splicing the replacement into the pre-read, or — for format_text — a predicted runs_after computed by overlaying the requested style onto the pre-read runs. format_text additionally never issues a write at all when the matched text already carries every requested style value, dry run or not — that's the tool's normal idempotent no-op path, not specific to dry_run. For replace_table_row and insert_table, dry_run is authoritative for index validity: the same assembled request list is index-simulated whether dry_run is true or false, so a passing dry run always means the real write will pass too. Use it to confirm a locate resolves to the right span before committing the edit.

For the three markdown tools, dry_run is also authoritative for structure prediction (issue #65): before any batchUpdate, the compiled requests' own predicted block structure — nesting, ordered-vs-unordered, headings, tables — is compared against the parsed input markdown, identically in dry_run and the real write. A mismatch refuses with STRUCTURE_PREDICTION_FAILED before the document is touched, rather than mutating it and only then discovering post-write verification would have failed. Every response from these three tools — dry run, refused, or written — carries write_status, one of not_written (dry run, or a pre-flight refusal: INDEX_SIMULATION_FAILED, STRUCTURE_PREDICTION_FAILED, or the structural-loss guardrail), written_unverified (a batchUpdate was sent and accepted, but the post-write re-read did not confirm it matched — VERIFICATION_FAILED), or written_verified (confirmed) — plus a retry_safe boolean (false only for written_unverified, since a caller that retries a call whose mutation status is unconfirmed risks a second mutation on top of an unconfirmed first one; there is no automatic rollback — Docs has no revision-restore endpoint, and a compensating markdown rewrite would itself be lossy, so needs_manual_restore: true still means restoring from Docs version history). write_status/retry_safe are additive: the pre-existing applied field keeps its documented meaning unchanged.