Skip to main content
Glama

word-agent-mcp

让 AI agent 以**修订模式(Track Changes)**编辑 Word 文档的 MCP server —— 律师版 "Claude Code for Word" 的文档操作层。

核心理念

程序员审代码用 diff,律师审文书用修订。本项目让 agent 的每一处修改都以标准 Word 修订(红线删除 + 下划线插入)写入 .docx,律师在 Word「审阅」界面逐条接受/拒绝——agent 永远不能未经审阅直接改动文书。

修订直接写入 OOXML(w:ins/w:del),不需要安装 Word、跨平台(Mac 开发、Windows 交付零移植)。

Related MCP server: MCP Word Commander

架构

src/word_agent_mcp/
├── server.py          # MCP 工具层(read_document / replace_text / insert_paragraph / ...)
├── revisions.py       # OOXML 修订标记核心(w:ins / w:del 生成、run 拆分、修订扫描)
└── backend/
    ├── base.py        # WordBackend 抽象接口(按 Windows COM 能力超集设计)
    └── ooxml.py       # 文件后端:python-docx + lxml,跨平台
                       # (规划)com.py:Windows COM 后端,实时操控打开中的 Word

工具层只依赖 WordBackend 接口。阶段 2 在 Windows 上补一个 COM 后端即可获得"实时看着 agent 改文档"的体验,工具层零改动。

快速开始

uv sync                          # 安装依赖(自动准备 Python 3.11+)
uv run pytest                    # 跑测试
uv run python examples/demo.py   # 生成演示合同并修订,用 Word 打开看红线

接入 Claude Code

claude mcp add word-agent -- uv --directory /path/to/word-agent-mcp run word-agent-mcp

或在项目 .mcp.json 里:

{
  "mcpServers": {
    "word-agent": {
      "command": "uv",
      "args": ["--directory", "/path/to/word-agent-mcp", "run", "word-agent-mcp"]
    }
  }
}

然后直接对话:「读一下 ~/Desktop/租赁合同.docx,把租金改成 9000 并加一条逾期解约条款」。

MCP 工具

工具

说明

read_document

读取全部段落(index / style / 有效文本)

replace_text

修订式替换;不唯一时要求更长上下文或 replace_all

insert_paragraph

在指定段后修订式插入新段落

delete_paragraph

修订式删除段落

list_revisions

列出文档全部修订(自检 / 汇报用)

安全设计:每次编辑前自动留 .bak 备份;所有修改必须过 Word 审阅这一关。

已知限制(MVP)

  • 只处理正文段落,表格/页眉页脚/脚注暂不支持

  • 匹配区间内含制表符、图片等复杂 run 结构时会明确报错(不会静默破坏文档)

  • 批注(comments)待加入

  • Windows 上 Word 正在打开的文件会被锁定:请让 agent 改副本,或关闭文档后编辑

Available Tools

5 tools
delete_paragraphA

以修订方式删除第 index 段(从 0 计,见 read_document)。

Inputs: path (required), index (required), author. Returns: result

insert_paragraphA

在第 after_index 段(从 0 计,见 read_document)之后以修订方式插入新段落。

style 可选,填文档已有的段落样式名(如 "Heading 2")。

Inputs: path (required), text (required), after_index (required), style, +1 more. Returns: result

list_revisionsA

列出文档中现存的全部修订(含此前人工修订),返回 JSON。

用于编辑后自检,或向用户汇报"本次共产生了哪些修订"。

Inputs: path (required). Returns: result

read_documentA

读取 Word 文档(.docx)的全部段落。path 必须是绝对路径。

返回 JSON 数组,每段含 index(段落序号,编辑工具以此定位)、style(样式名)、 text(接受全部现有修订后的有效文本)。编辑前必须先读取文档。

Inputs: path (required). Returns: result

replace_textA

以修订模式(Track Changes)替换文档中的文本。

修改不会直接生效,而是写成 Word 修订(删除线 + 下划线),由用户在 Word 审阅界面逐条接受/拒绝。old_text 在全文只出现一次时才会替换;出现多次时 需提供更长的唯一上下文,或明确 replace_all=True 全部替换。 new_text 传空字符串表示纯删除。

Inputs: path (required), new_text (required), old_text (required), author, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: reading, deleting paragraphs, inserting paragraphs, replacing text, and listing revisions. No overlap exists.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (delete_paragraph, insert_paragraph, list_revisions, read_document, replace_text).

    Tool Count5/5

    Five tools is well-scoped for a Word document editing server, covering essential operations without bloat.

    Completeness4/5

    Core CRUD operations are present (read, insert, delete, replace text, list revisions), but missing tools like modify paragraph style or accept revisions are minor gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers