io.github.michaelrobertsutton/verified-googledocs-mcp

Add a comment to a document, validated against a quoted passage. Use this tool when you need to create a comment on specific text in a document tab. The quote must exist in the tab — the tool locates it via the same normalization ladder as replace_text and returns QUOTE_NOT_FOUND with nearest candidate anchors if the quote is absent. NOTE: The Drive API may render the created comment as document-level even when quotedFileContent is supplied. This behaviour is pending confirmation from a live anchoring spike; for now the comment is created with the quote embedded in its content and the tool returns comment-state evidence. Returns comment-state evidence: applied, comment_id, resolved, reply_count, content, quoted_text, audit_logged. Errors: QUOTE_NOT_FOUND – quote not found in the tab; nearest candidates listed INVALID_INPUT – empty body or quote TAB_NOT_FOUND – tab_id not in document

Append compiled markdown at the end of a document tab. Use this tool when you need to add new content at the end of a tab without disturbing existing content. Inserts before the final trailing newline. Set dry_run=true to validate and preview without writing. Errors: UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct TAB_NOT_FOUND – tab_id not in document REVISION_CONFLICT – document changed mid-call; re-read and retry

Export a document tab as markdown and diff against a local file. Use this tool when you need to compare a Google Doc tab against a local markdown file. The server reads the file directly (it runs locally). Returns a structured diff with tagged hunks (equal/insert/delete/replace) and a unified diff string. This is a read-only tool — it makes no changes to the document or file. Returns: doc_id, tab_id, file_path, revision_id, identical (bool), hunks (list of tagged diff blocks), unified_diff (unified diff string) Errors: TAB_NOT_FOUND – tab_id not in document INVALID_INPUT – file not found at file_path

Find headings in a document tab and return their document ranges. Use this tool when you need to locate a section by its heading text before performing a targeted edit on that section. The returned ranges carry a computed_at_revision stamp; range-editing tools in later milestones will refuse stale ranges (ranges computed against an older document revision). Call find_sections immediately before editing — do not cache returned ranges across separate edits. Matching is case-insensitive and substring-based: a query of "intro" will match a heading "Introduction".

Retrieve the full reply chain for a comment. Use this tool when you need to read a comment thread in full before deciding on a response or resolution. Returns the comment content, all replies, quoted text, resolved status, and author. Requires both the doc_id (the Google Doc's file ID) and the comment_id from the Drive API.

Insert an inline image after the paragraph containing anchor text. Use this tool when you need to add an image to a specific location in a document tab. The anchor resolves via the same normalization ladder as replace_text (exact → curly/straight quotes → NBSP/whitespace → soft-hyphen). The image is inserted as an inline object in a new paragraph immediately after the paragraph containing the resolved anchor. source must be a publicly fetchable URL (http/https). Local file paths are rejected with IMAGE_SOURCE_UNSUPPORTED — the Docs API fetches the image from the URL directly and cannot access local files. Set dry_run=true to preview the resolved anchor position without writing. Returns structural evidence: applied, revision_before/after, inline_object_confirmed (whether the post-read confirms an inline object near the anchor paragraph), audit_logged. Errors: QUOTE_NOT_FOUND – anchor not found; nearest candidates listed IMAGE_SOURCE_UNSUPPORTED – source is a local path, not a URL TAB_NOT_FOUND – tab_id not in document REVISION_CONFLICT – document changed mid-call; re-read and retry

List all open comments and pending suggested edits on a document. Use this tool when you need a single unified view of all open review items on a document. Returns both Drive-level comments (labeled scope='document') and per-tab suggested edits in one response. Comments come from the Drive API and cannot be attributed to a specific tab — Drive comment anchors are opaque. If tab_id is provided it filters the suggestions returned to that tab only; if omitted all tabs are included. Comments are always returned document-wide regardless of tab_id. Suggestions are extracted from the raw Docs JSON (suggestedInsertionIds / suggestedDeletionIds / suggestedTextStyleChanges) and are per-tab. The document is fetched with suggestionsViewMode=SUGGESTIONS_INLINE so that suggestion fields are populated.

List the tabs in a Google Doc. Use this tool first when you need to read or edit a document but do not yet know its tab structure. Returns tab IDs, titles, nesting level, and index. Required before calling read_document or find_sections because every tool in this server requires an explicit tab_id. For documents created before Google's tabbed-docs feature, returns a single synthetic tab with id "_body" that covers the whole document.

Read the content of a specific tab in a Google Doc. Use this tool when you need to read the text, headings, tables, or structure of a document tab. Call list_tabs first to get the tab_id. format="markdown" (default): returns markdown text. Out-of-subset elements (images, smart chips, footnotes) appear as stable placeholder tokens and are listed in lossy_elements. format="structured": returns paragraph positions and style runs from the raw Docs JSON, suitable for computing exact edit ranges. Drive's files.export cannot scope to a single tab, which is why this server uses its own Docs JSON converter for markdown output.

Replace a document range with compiled markdown. Use this tool when you need to replace a section of a document with new markdown content. Obtain start_index, end_index, and computed_at_revision from find_sections. The range stamp is validated against the current document revision — a stale stamp raises STALE_RANGE ("re-run find_sections"). The structural guardrail inventories tables, images, chips, and footnotes inside the target range before writing. If the replacement markdown does not account for them the write is refused unless allow_structural_loss=true. A blast-radius check compares structural element counts outside the edited range pre/post; any change there is a hard failure. Set dry_run=true to validate and preview without writing. Errors: STALE_RANGE – range stamp is outdated; re-run find_sections UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct INVALID_INPUT – structural guardrail refused or blast-radius violation TAB_NOT_FOUND – tab_id not in document REVISION_CONFLICT – document changed mid-call; re-read and retry

Replace the entire content of a document tab with compiled markdown. Use this tool when you need to completely replace a tab's content with new markdown. tab_id is required and must identify an existing tab. The structural guardrail refuses writes that would silently lose tables, images, chips, or footnotes unless allow_structural_loss=true. Set dry_run=true to validate and preview without writing. Errors: UNSUPPORTED_MARKDOWN – markdown contains an unsupported construct INVALID_INPUT – structural guardrail refused TAB_NOT_FOUND – tab_id missing or not in document REVISION_CONFLICT – document changed mid-call; re-read and retry

Replace occurrences of a text string in a Google Doc tab. Use this tool when you need to make an exact-text substitution in a document tab. Call list_tabs first to get the tab_id, then read_document to confirm the text you want to replace is present as-is. The tool locates every occurrence of ``find`` using a normalization ladder (exact → curly/straight quote equivalence → NBSP/whitespace collapse → soft-hyphen strip) and refuses the write if the match count does not equal ``expected_matches``. This prevents accidental multi-replacement and duplicate-sentence collapse. Set ``dry_run=True`` to preview the operation without writing; the response carries ``applied: false`` and the matched span information but makes no API call. On success the response carries before/after excerpts (±200 chars), the normalization rung used, pre/post revision IDs, and ``audit_logged``. Errors are returned as typed envelopes with ``error_code``, ``message``, ``diagnostics``, and ``retryable`` so the caller can act on them precisely: ZERO_MATCH – find string not found; near-miss span included MATCH_COUNT_MISMATCH – wrong number of matches; all locations listed REVISION_CONFLICT – document changed mid-call; re-read and retry STRUCTURAL_BOUNDARY – match crosses a paragraph boundary INVALID_INPUT – empty find, or find equals replace TAB_NOT_FOUND – tab_id not in document; available tabs listed

Add a reply to an existing comment thread. Use this tool when you need to respond to a reviewer comment without resolving it. The reply is added to the thread and the tool re-queries the comment to return post-state evidence. Returns comment-state evidence: applied, comment_id, resolved, reply_count, content, quoted_text, audit_logged. Errors: INVALID_INPUT – empty body or comment not found

Resolve a comment on a document and verify the resolution landed. Use this tool when you need to mark a reviewer comment as resolved. Resolves via Drive replies.create(action='resolve') — the only mechanism that actually resolves comments in Drive API v3. Using comments.update with resolved=true is silently ignored (resolved is a read-only field), which is the incumbent server's bug. After issuing the resolve the tool re-queries the comment and returns the actual final state. A comment that is still open after the resolve attempt is reported as COMMENT_STILL_OPEN — never as success. Returns comment-state evidence: applied, comment_id, resolved, reply_count, content, quoted_text, audit_logged. Errors: COMMENT_STILL_OPEN – comment did not resolve; post-state included INVALID_INPUT – comment not found