doc-agent-mcp
Planned adapter for Google Docs via Drive API, enabling the same semantic document operations (read, propose, apply) with native comment mapping.
Provides structured, addressable operations on Markdown documents, including reading, searching, proposing and applying changes, plus export to DOCX.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@doc-agent-mcp Replace second paragraph of Introduction with 'We are happy to announce our new product.'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
doc-agent-mcp
A Model Context Protocol server that gives AI agents stable, semantic operations on documents — instead of making them shuffle raw text.
Human ─────┐
↓
Document ← Markdown (.md/.markdown) and DOCX today,
↑ Tiptap / SuperDoc / Shimo / Google Docs tomorrow
AI Agent ──┘LLM agents editing documents as one big string break things: they mangle
formatting they cannot see, lose images and comments, and cannot express
"insert a paragraph after section 3". doc-agent-mcp exposes the document as
a normalized, addressable structure (headings, paragraphs, list items,
tables with stable IDs) and lets agents work in a safe loop:
read → propose change → inspect diff → apply → exportNothing touches your file until apply_changes is called. Every read accepts
a doc_hash, so if the file changes underneath the agent mid-task, further
edits fail loudly (stale_document) instead of corrupting the file.
The problem this solves
Raw-text editing (typical today) | doc-agent-mcp |
Agent rewrites the whole file to change one word | Agent replaces an exact character range in one block |
DOCX round-trips through text converters destroy styles/comments | Edits are applied inside the original OOXML package; untouched content passes through |
No way to review what will change before it changes | Every edit is staged with a unified diff; apply is explicit |
Silent conflicts when humans edit concurrently | Content-hash optimistic locking; stale edits are rejected |
Format-specific hacks hardcoded into prompts | One tool surface, any backend |
Related MCP server: docx-mcp-server
Architecture
MCP interface (13 tools)
↓
Document operation layer ← staging, diffs, hashes, search, sessions
↓ (doc_agent_mcp/service.py)
Normalized document model ← Block(h-0, p-1, li-2, tbl-0), Comment,
↓ ProposedChange (core/model.py)
Backend adapters ← parse() + serialize() per format
↓ (adapters/*_adapter.py)
Markdown · DOCX · future editors (Tiptap, SuperDoc, Shimo, Google Docs)Key property: the MCP tools never know which backend is underneath. Adding a new editor backend means implementing two methods — see ADAPTER_GUIDE.md.
Installation
From PyPI (recommended for users):
pip install doc-agent-mcpRequires Python 3.10+.
From source (development):
git clone https://github.com/xyyyang97/doc-agent-mcp.git
cd doc-agent-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"Verify:
doc-agent-mcp --version
# doc-agent-mcp 0.1.0MCP configuration
The server speaks standard MCP over stdio.
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"doc-agent": {
"command": "/absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp",
"args": ["--roots", "/Users/you/Documents"]
}
}
}Claude Code / Codex CLI
claude mcp add doc-agent -- /absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp --roots ~/DocumentsGeneric MCP client (JSON)
{
"mcpServers": {
"doc-agent": {
"command": "/absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp",
"args": [],
"env": {}
}
}
}--roots DIR [DIR ...] optionally restricts all reads/writes to those
directories (recommended). Without it the server can touch any path its
process can reach — treat server configuration like filesystem credentials.
Available tools
Read operations (never mutate)
Tool | Purpose |
| Structured blocks with IDs; optional single-section view; reports |
| Headings flat + nested tree with paths |
| Exact occurrences with |
| Native comments (author, body, anchor element, quoted range) |
Propose operations (stage a change; nothing written yet)
Tool | Purpose |
| Replace character range inside one block; returns diff preview |
| Insert paragraph/heading/list item before or after any element (covers insert-before/after/append) |
| Delete one whole block |
| Native Word comment (DOCX); session-only for Markdown (see limitations) |
Commit & review
Tool | Purpose |
| All staged changes with unified diffs |
| Drop staged changes (all or selected) |
| Write to disk atomically; returns new |
| Convert via the model: md↔docx both directions |
| Registered backends and supported conversions |
Every mutating/read call accepts the doc_hash you got from the previous
call. If the file changed since (including by another process), you get
{"code": "stale_document", ...} and your staged changes are dropped —
re-read first.
Example workflow
This is the exact loop examples/demo_workflow.py runs (against real files):
from doc_agent_mcp.service import DocumentService
svc = DocumentService() # same facade the MCP tools wrap
# 1. Understand the document
outline = svc.get_outline("brief.md")
summary = next(h for h in outline["headings"] if h["title"] == "Executive Summary")
section = svc.read_document("brief.md", section_id=summary["id"])
# 2. Locate exact text
hit = svc.find_text("brief.md", "30 percent")["matches"][0]
# 3. Stage a change (file is untouched)
proposal = svc.propose_replace_text(
"brief.md", hit["element_id"], hit["start"], hit["end"],
"at least 30 percent (validated with finance)",
)
# 4. Review the diff
changes = svc.get_changes("brief.md")
print(changes["changes"][0]["diff"])
# 5. Commit, then export
svc.apply_changes("brief.md", doc_hash=proposal["doc_hash"])
svc.export_document("brief.md", "docx", output_path="brief.docx")Over MCP the same steps are one tool call each — see the tool table above.
Run the full demo (Markdown + DOCX + export + stale-guard, all verified):
.venv/bin/python examples/demo_workflow.pySample documents live in examples/documents/:
sample.md and sample.docx (the latter with two native Word comments,
regenerable via scripts/make_sample_docx.py).
Error handling
All errors are structured JSON — no tracebacks across the wire:
{
"code": "element_not_found",
"message": "Element 'p-99' not found. Call get_outline ...",
"details": {"element_id": "p-99"}
}Code | Meaning |
| Path does not exist |
| No backend for this extension |
| Stale/unknown element ID |
| Search found nothing / reserved for disambiguation |
| Bad range, bad quote anchor, table-cell replace, path outside roots... |
| File changed since your snapshot; staged changes were dropped |
| Unknown or already-discarded |
| Unsupported conversion pair |
Testing
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest # unit + integration + MCP protocol tests
.venv/bin/ruff check src tests # lint
.venv/bin/ruff format --check . # formatting
.venv/bin/mypy # strict type checkingThe suite includes DOCX round-trip tests (edits verified by re-opening the saved file with python-docx and at raw OOXML level) and an end-to-end MCP test that spawns the server over stdio and speaks real protocol messages.
Limitations (by design, not by accident)
The normalized model covers what Markdown and DOCX can both represent
reliably. Everything else is explicitly surfaced as
unmodeled_features on every read — never silently destroyed:
DOCX: images/drawings, headers & footers, footnotes/endnotes, content controls, tracked changes present in source are preserved untouched but invisible to the model. Tables are plain-text cells (cell formatting not modeled).
replace_textrefuses paragraphs containing hyperlinks (the rewrite would destroy them).Markdown: serialization is model-faithful, not byte-faithful — content survives round-trips, original line wrapping/marker style may not. Blockquotes are flattened to their paragraphs (flagged). Reference-style link definitions are resolved and inlined. Comments have no native home:
propose_add_commentstores them session-only and says so.Tables: searchable (flagged
editable: false) but cell-level editing is not implemented yet — delete/re-insert instead.Concurrent agents: last-writer-wins per file, guarded by hash checks; there is no merge engine.
Roadmap ideas
Table cell operations (
update_table_cell)Tiptap/SuperDoc adapters over their JSON models
Google Docs adapter via Drive API (comments map natively)
Anchored suggestions mode for Markdown (
<!-- suggestion -->blocks)Multi-file workspaces and rename-safe sessions
License
Available Tools
13 toolsapply_changesA
Commit staged changes to the file (all, or selected change ids).
Writes atomically, re-reads the file and returns the new doc_hash plus warnings about unmodeled features present in the document.
Inputs: path (required), doc_hash, change_ids. Returns: object
discard_changesB
Drop staged changes (all of them, or specific change ids).
Inputs: path (required), change_ids. Returns: object
export_documentA
Convert the document to another supported format ('markdown'|'docx').
Conversion goes through the normalized model: markdown->docx builds a fresh Word file (headings, lists, tables, comments); docx->markdown serializes parsed blocks back to Markdown. Unsupported pairs raise a clear export_error listing supported conversions.
Inputs: path (required), target_format (required), title, output_path, +1 more. Returns: object
find_textA
Find exact occurrences of text inside document blocks.
Returns every match as (element_id, start, end) character offsets plus a snippet - feed these offsets directly into propose_replace_text. Tables are skipped (cell-level search not supported).
Inputs: path (required), query (required), doc_hash, is_regex, +2 more. Returns: object
get_changesA
Review all staged changes with diffs before committing.
Replace changes carry unified diffs; inserts/deletes/comments show their content. Apply selectively with apply_changes(change_ids=[...]).
Inputs: path (required). Returns: object
get_commentsB
List comments anchored in the document (native DOCX comments).
Each comment carries id, author, body, element_id and quoted range. For Markdown (which has no comment concept) the list is empty.
Inputs: path (required), doc_hash. Returns: object
get_outlineA
Get the heading outline of a document.
Returns flat heading entries (id, level, title, path) plus a nested tree. Use heading ids to read sections or anchor edits.
Inputs: path (required), doc_hash. Returns: object
list_backendsA
List registered format backends and their file extensions.
Inputs: no named parameters. Returns: object
propose_add_commentB
Stage adding a comment anchored to an element.
DOCX: creates a real Word comment (visible in Word/Google Docs). Markdown: stored in the session only - surfaced by get_comments until the process exits, because Markdown has no native comment storage; the tool result states this limitation explicitly. quote must appear inside the anchor element.
Inputs: body (required), path (required), anchor_id (required), end, +4 more. Returns: object
propose_delete_blockB
Stage deleting one whole block (heading, paragraph, item or table).
Inputs: path (required), element_id (required), doc_hash. Returns: object
propose_insert_blockB
Stage inserting a new block before or after an existing element.
position: 'before' | 'after' (relative to anchor_id). kind: 'paragraph' | 'heading' (set level 1-6) | 'list_item'. This single tool covers insert-before, insert-after and append use cases (anchor on the last element and position='after').
Inputs: path (required), position (required), anchor_id (required), kind, +3 more. Returns: object
propose_replace_textA
Stage replacing character range [start:end) inside one block.
Offsets come from find_text or read_document. The staged change includes before/after previews; nothing is written until apply_changes. Table cells are not supported (delete/re-insert the table instead).
Inputs: end (required), path (required), text (required), start (required), +2 more. Returns: object
read_documentA
Read a Markdown or DOCX document as structured blocks.
Returns headings, paragraphs, list items and tables with stable IDs (h-0, p-1, li-2, tbl-0). Prefer section_id= over reading whole documents. Pass doc_hash from a previous call to detect external modifications. Lists unmodeled_features so you know what the model cannot represent (images, footnotes, ...).
Inputs: path (required), doc_hash, section_id, include_spans. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct operation: reading (read_document), outlining (get_outline), searching (find_text), comments (get_comments/propose_add_comment), editing via staging (propose_replace_text/insert/delete), change management (get/discard/apply_changes), and export/list backends. No two tools overlap in purpose, and the propose_* set is clearly separated from apply_changes.
All 13 tools follow a consistent snake_case verb_noun pattern (e.g., read_document, propose_insert_block, discard_changes). Verbs are descriptive and uniformly applied, making the naming predictable and easy to infer.
13 tools is well-scoped for a document editing server. Each tool covers a distinct lifecycle stage—read, inspect, search, comment, edit (staging), apply, export—without redundancy or excessive granularity.
The surface covers the core document workflow: reading, outlining, text search, editing (replace/insert/delete), comment creation, change staging/commit, and export. Minor gaps include no comment deletion/editing and no document creation, but these are outside the stated purpose of working with existing documents.
Maintenance
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
One link any agent can edit: shared docs for people and AI agents, live. No login.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables collaborative document authoring and composition with project-based organization, transforming Markdown and LaTeX content into professional PDFs with conflict-free multi-agent editing capabilities.620MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to read, edit, and create Microsoft Word documents (.docx) with support for rich text, tables, and images, deployable locally or via SSE.3MIT
- AlicenseAqualityCmaintenanceEnables AI agents to edit Google Docs via text anchors rather than character indices, preserving version history and enabling surgical edits without full document rewrites.147MIT
- AlicenseBqualityDmaintenanceEnables safe, human-in-the-loop AI document collaboration by letting agents create isolated workspaces, edit tracked files, open reviewable Change Requests, and get human approval before merging, with Git-backed conflict detection and resolution.35MIT