Skip to main content
Glama
deenesjakoruzh
xyyyang97

doc-agent-mcp

by xyyyang97
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

doc-agent-mcp

CI PyPI Python License: MIT

一个模型上下文协议（Model Context Protocol）服务器，为 AI 代理提供稳定、语义化的文档操作——而不是让它们处理原始文本。

Human ─────┐
           ↓
        Document          ← Markdown (.md/.markdown) and DOCX today,
           ↑                 Tiptap / SuperDoc / Shimo / Google Docs tomorrow
AI Agent ──┘

LLM 代理将文档当作一个大字符串进行编辑时容易出错：它们会破坏自己看不到的格式、丢失图片和评论，也无法表达“在第 3 节之后插入一个段落”。doc-agent-mcp 将文档暴露为规范化、可寻址的结构（标题、段落、列表项、带稳定 ID 的表格），并让代理在安全循环中工作：

read  →  propose change  →  inspect diff  →  apply  →  export

在调用 apply_changes 之前，不会触碰你的文件。每次读取都接受 doc_hash，因此如果文件在代理任务中途发生变化，后续编辑会大声失败（stale_document），而不是损坏文件。

此方案解决的问题

原始文本编辑（当前常见方式）

doc-agent-mcp

代理重写整个文件来更改一个词

代理替换一个块中的精确字符范围

DOCX 通过文本转换器往返会破坏样式/评论

编辑在原始 OOXML 包内应用；未触碰的内容原样通过

无法在更改前审查将要发生的变化

每次编辑都带有统一差异暂存；应用是显式的

人类并发编辑时静默冲突

内容哈希乐观锁；过期编辑被拒绝

针对格式的硬编码提示词

一个工具表面，任何后端

Related MCP server: docx-mcp-server

架构

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)

关键属性：MCP 工具永远不知道底层是哪个后端。 添加新的编辑器后端意味着实现两个方法——参见 ADAPTER_GUIDE.md。

安装

从 PyPI 安装（推荐给用户）：

pip install doc-agent-mcp

需要 Python 3.10+。

从源码安装（开发）：

git clone https://github.com/xyyyang97/doc-agent-mcp.git
cd doc-agent-mcp

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

验证：

doc-agent-mcp --version
# doc-agent-mcp 0.1.0

MCP 配置

服务器通过 stdio 支持标准 MCP。

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 ~/Documents

通用 MCP 客户端（JSON）

{
  "mcpServers": {
    "doc-agent": {
      "command": "/absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp",
      "args": [],
      "env": {}
    }
  }
}

--roots DIR [DIR ...] 可选地将所有读写限制在这些目录中（推荐）。没有它，服务器可以访问其进程能到达的任何路径——请将服务器配置视为文件系统凭据。

可用工具

读取操作（绝不修改）

工具

用途

read_document(path, section_id?, include_spans?, doc_hash?)

带 ID 的结构化块；可选单节视图；报告 unmodeled_features

get_outline(path, doc_hash?)

标题扁平 + 嵌套树，带路径

find_text(path, query, scope_element_id?, is_regex?, case_sensitive?, doc_hash?)

精确出现位置，带 (element_id, start, end) 偏移量，可直接用于 propose_replace_text；表格命中标记为 editable: false

get_comments(path, doc_hash?)

原生评论（作者、正文、锚点元素、引用范围）

提议操作（暂存更改；尚未写入任何内容）

工具

用途

propose_replace_text(path, element_id, start, end, text)

替换一个块内的字符范围；返回差异预览

propose_insert_block(path, anchor_id, position, kind, text, level?)

在任何元素之前或之后插入段落/标题/列表项（涵盖插入前/后/追加）

propose_delete_block(path, element_id)

删除一个完整块

propose_add_comment(path, anchor_id, body, quote?, author?)

原生 Word 评论（DOCX）；Markdown 仅会话内（见限制）

提交与审查

工具

用途

get_changes(path)

所有暂存更改及统一差异

discard_changes(path, change_ids?)

丢弃暂存更改（全部或选定）

apply_changes(path, change_ids?, doc_hash?)

原子写入磁盘；返回新的 doc_hash + 警告

export_document(path, target_format, output_path?, title?)

通过模型转换：md↔docx 双向

list_backends()

已注册的后端及支持的转换

每个修改/读取调用都接受你从上次调用获得的 doc_hash。如果文件自那以后发生了变化（包括由其他进程），你会得到 {"code": "stale_document", ...}，并且你的暂存更改会被丢弃——请先重新读取。

示例工作流

这是 examples/demo_workflow.py 运行的确切循环（针对真实文件）：

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")

通过 MCP，同样的步骤每次只需一个工具调用——参见上面的工具表。

运行完整演示（Markdown + DOCX + 导出 + 过期保护，全部验证）：

.venv/bin/python examples/demo_workflow.py

示例文档位于 examples/documents/：sample.md 和 sample.docx（后者带有两个原生 Word 评论，可通过 scripts/make_sample_docx.py 重新生成）。

错误处理

所有错误都是结构化 JSON——不会跨线路传输回溯：

{
  "code": "element_not_found",
  "message": "Element 'p-99' not found. Call get_outline ...",
  "details": {"element_id": "p-99"}
}

代码

含义

document_not_found

路径不存在

unsupported_format

没有此扩展名的后端

element_not_found

过期/未知的元素 ID

match_not_found / ambiguous_match

搜索未找到 / 保留用于消歧

validation_error

范围错误、引用锚点错误、表格单元格替换、路径超出根目录...

stale_document

文件自快照后已更改；暂存更改已丢弃

change_not_found

未知或已丢弃的 change_id

export_error

不支持的转换对

测试

.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 checking

测试套件包括 DOCX 往返测试（通过重新打开保存的文件并使用 python-docx 及原始 OOXML 级别验证编辑）以及一个端到端 MCP 测试，该测试通过 stdio 启动服务器并发送真实协议消息。

限制（有意设计，而非偶然）

规范化模型涵盖了 Markdown 和 DOCX 都能可靠表示的内容。其他所有内容在每次读取时都会明确地作为 unmodeled_features 暴露——绝不会静默破坏：

  • DOCX：源中的图像/绘图、页眉和页脚、脚注/尾注、内容控件、跟踪更改均被原样保留，但对模型不可见。表格是纯文本单元格（单元格格式未建模）。replace_text 拒绝包含超链接的段落（重写会破坏它们）。

  • Markdown：序列化是模型忠实，而非字节忠实——内容在往返中保留，但原始换行/标记样式可能不同。块引用被扁平化为其段落（已标记）。引用式链接定义被解析并内联。评论没有原生位置：propose_add_comment 仅将会话内存储并明确说明。

  • 表格：可搜索（标记为 editable: false），但单元格级编辑尚未实现——请改用删除/重新插入。

  • 并发代理：每个文件最后写入者胜出，由哈希检查保护；没有合并引擎。

路线图想法

  • 表格单元格操作（update_table_cell）

  • Tiptap/SuperDoc 适配器，基于其 JSON 模型

  • 通过 Drive API 的 Google Docs 适配器（评论原生映射）

  • Markdown 的锚定建议模式（<!-- suggestion --> 块）

  • 多文件工作区和重命名安全会话

许可证

MIT

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • writespace-mcp

    Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.

  • TablaCognita

    MCP-native collaborative markdown editor with real-time AI document editing

  • superdocs

    AI document editing for agents: draft, edit, export .docx/PDF. 37 MCP tools; agent self-signup.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xyyyang97/doc-agent-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server