word-ai-mcp

v0.8.6

Published

6 days ago

Unscoped compatibility package for the Word AI MCP server and Office.js bridge

Downloads

403

0High
0Medium
0Low

wybaby168

mcp model-context-protocol word docx office office-js ooxml openxml codex claude

Word AI

| 文档 | 预览 | | --- | --- | | 中文 | 面向 AI Agent 的 Word DOCX 结构稳定编辑；支持 .NET 后端、Office.js 会话和安全 PatchSet。 | | English | Structure-preserving Word DOCX editing MCP server with a .NET Open XML backend and Office.js live sessions. |

面向 AI Agent 的 Word（DOCX）结构稳定编辑系统。

Word AI 是一个开源 MCP Server 与 Office.js Bridge，用于安全、可审计、可回滚地增量编辑 Microsoft Word 文档。它面向 Codex、OpenAI Agents 和其他 MCP 客户端，核心目标是避免“整篇重建”导致样式、编号、表格、图片、字段、页眉页脚和关系文件漂移。

为什么需要 Word AI

大模型擅长生成文本，但 Word 文档不是纯文本，而是复杂的 OOXML 包结构。直接把 DOCX 转成 Markdown/HTML 再转回 DOCX，容易破坏编号、样式、字段、交叉引用、图片关系和版式。Word AI 的设计原则是：

模型只生成受约束的 PatchSet。
本地执行层对 OOXML / Open XML 做定点修改。
每次写入必须经过评估、dry-run、备份、验证、审计和 diff。
Office.js 加载项负责 Word 端锚点治理和人工审批体验。

核心能力

63 个 MCP tools，覆盖 DOCX 检查、锚点、标题、段落、表格、字段、图片、批注、修订、PatchSet 规划、dry-run、正式写入、验证、回滚、diff、Word 打开会话内编辑，以及可选 OfficeCLI 只读证据能力。
所有正式写入收口到 PatchSet，默认不覆盖源文件。
Agent 友好的 PatchSet 归一化，兼容 operation、target_tag、new_text、text_sha256 和 camelCase 操作名等常见字段，但不绕过正式安全门禁。
优先使用内容控件 tag，例如 WORD-AI:SRS:1.0:overview。
并发安全前置条件：source_sha256、expected_old_sha256、expected_old_text。
结构验证：保护 package parts、内容控件、表格、段落、字段、图片、批注、修订痕迹和正文块顺序。
Python MCP facade 与 bridge runtime，负责本地 Agent 集成、路径策略、session 队列和分发兼容。
.NET 8 Open XML SDK 引擎，作为离线 DOCX 事务的权威后端；优先使用打包 native 二进制或 Release DLL。
单文件 standalone 二进制与 quickstart 包，离线 DOCX 编辑无需 clone 源码、创建 venv、安装 pip 依赖或本地 .NET SDK，并可一键安装 Agent Skill。
Office.js taskpane，支持创建/列出锚点、构建 PatchSet、预览、dry-run、apply，以及对当前打开的 Word 文档进行 hash 校验后的内容控件写入。
Word 会话 MCP 工具，Codex 可以通过 word_session_* 读取当前打开文档、预览 PatchSet、调用 Office.js 写入并获取审计和 rollback PatchSet。

快速开始

请优先使用 Agent host 原生支持的分发方式：

优先 MCP Registry / MCPB：在支持 MCP Registry 或 MCP marketplace 的客户端里安装 io.github.flyfish-dev/word-ai。
最低门槛本地启动使用 standalone quickstart：需要一个能运行 MCP、安装 Skill、生成 Codex 配置且无需源码 checkout 的本地命令时，下载当前平台 GitHub Release 包。
同时安装 Agent Skill：安装 word-ai Skill，让 Codex、Claude Code 等 Agent 明确知道何时使用离线 docx_*，何时使用 live word_session_*。
完整 Word 会话能力使用本地源码安装：需要 Office.js taskpane、localhost bridge、.NET Open XML 回归或开发调试时使用。
npm 是第二渠道：仅作为 MCP host 暂不支持 Registry/MCPB，或需要免 clone stdio server 命令时的便利入口。

MCP Registry 信息：

MCP server 名称：io.github.flyfish-dev/word-ai
Registry 元数据：server.json
MCPB 包：https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
Registry latest API：https://registry.modelcontextprotocol.io/v0.1/servers/io.github.flyfish-dev%2Fword-ai/versions/latest

使用 standalone quickstart 快速本地启动：

tar -xzf word-ai-quickstart-0.8.6-osx-arm64.tar.gz
cd word-ai-quickstart-0.8.6-osx-arm64

./word-ai install-skill
./word-ai codex-config --output .wordai/codex-config.toml
./word-ai mcp --root "$PWD" --allow-root "$HOME/Downloads" --allow-root "$HOME/Documents"

按平台选择 linux-x64、linux-arm64、osx-arm64、osx-x64、win-x64 或 win-arm64。完整资产策略见分发说明。

安装 Skill 和完整本地运行时：

git clone https://github.com/flyfish-dev/word-ai.git
cd word-ai

bash scripts/install.sh
bash scripts/start.sh

安装脚本会安装 Python MCP facade 依赖、构建 Office.js taskpane、在可用时构建 .NET Open XML 后端、生成 .wordai/codex-config.toml，并把正式 word-ai Skill 安装到 Codex、Claude Code 以及已检测到的兼容 Agent 客户端。

只安装或刷新 Agent Skill：

python3 scripts/install_agent_skills.py

浏览器调试 taskpane：

bash scripts/start.sh --http

Windows PowerShell：

powershell -ExecutionPolicy Bypass -File scripts\install.ps1
powershell -ExecutionPolicy Bypass -File scripts\start.ps1

健康检查：

.venv/bin/word-ai --root "$PWD" doctor

开发者验证：

PYTHONPATH=. .venv/bin/python scripts/run_smoke_test.py
PYTHONPATH=. .venv/bin/python scripts/run_structure_regression.py
PYTHONPATH=. .venv/bin/python scripts/run_outline_regression.py
PYTHONPATH=. .venv/bin/python scripts/run_engine_selection_regression.py

构建 .NET 引擎：

dotnet --version  # 需要 .NET SDK 8
dotnet build dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj -c Release
scripts/publish_dotnet.sh           # 当前主机 RID 到 dist/native/<rid>
scripts/publish_dotnet.sh --all     # 所有支持的 release RID
PYTHONPATH=. .venv/bin/python scripts/run_dotnet_regression.py

离线引擎选择

离线文件事务默认优先使用 .NET Open XML 后端。选择顺序：

WORD_AI_DOTNET_EXE 或 native/<rid>/、dist/native/<rid>/ 下的 native executable。
WORD_AI_DOTNET_DLL 或本地 Release DLL：dotnet/WordAi.OpenXml/bin/Release/net8.0/WordAi.OpenXml.dll。
本地源码工程：dotnet run --project dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj。
只有在 WORD_AI_ENGINE=auto 且 .NET 不可用时，才回退到 Python OOXML。

MCPB 内置 osx-arm64、osx-x64、linux-x64、linux-arm64、linux-musl-x64、linux-musl-arm64、win-x64 和 win-arm64 的 self-contained native 后端。Standalone quickstart 包覆盖标准 hosted 平台：linux-x64、linux-arm64、osx-arm64、osx-x64、win-x64 和 win-arm64，并把对应 Open XML 后端链接进单文件 executable。运行时会自动检测当前 RID，包括 Linux glibc 与 musl 的 native 后端选择，并加载匹配二进制。npm 启动器保持轻量：首次运行只会从 GitHub Release 下载当前平台 quickstart 包并执行其中的 word-ai。高级部署可用 WORD_AI_DOTNET_RID、WORD_AI_DOTNET_EXE 或 WORD_AI_DOTNET_NATIVE_DIR 覆盖检测；只有明确需要旧 npm Python venv 路径时才设置 WORD_AI_NPM_USE_SOURCE_BOOTSTRAP=1。

可通过 WORD_AI_ENGINE=auto|dotnet|python 控制，也可在 docx_assess_patchset、docx_dry_run_patchset、docx_apply_patchset、docx_validate 调用中传入 engine。生产环境建议设置 WORD_AI_ENGINE=dotnet，让后端缺失时直接失败，而不是静默回退。

构建 Office 加载项：

cd office-addin
npm install
npm run build

Agent Skill 一键安装

Word AI 内置正式 word-ai Agent Skill。即使 MCP Server 已通过 MCP Registry 安装，也建议同时安装 Skill，因为它定义了安全编辑流程、OfficeCLI 边界和 live/offline 选择规则。默认安装会自动写入：

Codex 官方用户 skill：~/.agents/skills/word-ai
Codex app 兼容 skill：~/.codex/skills/word-ai
Claude Code 个人 skill：~/.claude/skills/word-ai
如果本机已存在 Cursor、Windsurf、GitHub Copilot、OpenClaw 的 skill 目录，也会自动安装

只安装或刷新 skill：

python3 scripts/install_agent_skills.py

安装到所有已知目标或项目级目录：

python3 scripts/install_agent_skills.py --agents all
python3 scripts/install_agent_skills.py --project

安装后新开 Agent 会话；如果客户端未立即显示 skill，重启客户端即可。之后可直接用 word-ai / $word-ai 调用，也可以让 Agent 在 Word、DOCX、Office.js、内容控件、PatchSet、验证、回滚、审计等任务中自动识别。

全球 MCP 分发

Word AI 已通过官方 MCP Registry 和 MCPB 包进行全球发现和安装。对于 MCP host，这是优先推荐渠道，因为它提供标准化 server 元数据、版本、transport 与来源验证：

MCP server 名称：io.github.flyfish-dev/word-ai
MCPB 包：https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
Registry 元数据：server.json
发布说明：MCP Registry 发布说明
Standalone 与 quickstart 说明：分发说明

本地容器 smoke test：

docker build -t word-ai:local .
docker run --rm -i \
  -v "$PWD:/workspace" \
  -v "$HOME/Downloads:/documents/Downloads" \
  word-ai:local

MCP Registry 正式发布使用公开 MCPB 资产，便于本地 MCP Server 一键安装。Standalone quickstart 是最低摩擦的本地命令路径，因为它把 Python facade、依赖、当前平台 .NET Open XML 后端、schemas 和 Skill 模板放进一个 executable。MCPB 包要求 Python 3.10+，首次运行会自动创建本地虚拟环境并安装依赖。Dockerfile 继续保留给本地或自托管构建使用。完整 Office.js live session 编辑仍建议使用本地源码安装方式，因为 Word taskpane 和 localhost bridge 需要运行在用户机器上。

npm 第二渠道

npm 是便利备用渠道，适合暂不支持 MCP Registry/MCPB 的客户端、CI smoke test、或免 clone 启动 stdio server。它不是首选发现渠道。

在 Codex 中使用

安装脚本会生成可合并到 Codex 的 MCP 配置片段：

cat .wordai/codex-config.toml

将其加入 Codex MCP 配置。生成的配置已经把写入类工具设置为审批模式。最小手动配置如下：

[mcp_servers.word_ai]
command = "/absolute/path/to/word-ai/.venv/bin/python"
args = [
  "-m", "word_ai_mcp.server",
  "--root", "/absolute/path/to/word-ai",
  "--allow-root", "/Users/you/Downloads",
  "--allow-root", "/Users/you/Documents"
]
enabled = true
startup_timeout_sec = 30

[mcp_servers.word_ai.env]
PYTHONPATH = "/absolute/path/to/word-ai"

npm 版 Codex 配置适合作为第二渠道，用于暂不能通过 MCP Registry/MCPB 安装的 host：

[mcp_servers.word_ai]
command = "npm"
args = [
  "exec",
  "--yes",
  "--package",
  "@flyfish-dev/word-ai",
  "--",
  "word-ai-mcp",
  "--root",
  "/absolute/path/to/workspace",
  "--allow-root",
  "/Users/you/Downloads",
  "--allow-root",
  "/Users/you/Documents"
]
enabled = true
startup_timeout_sec = 60

如果偏好非 scope 包名，也可以在 npm 版 Codex 配置中把 @flyfish-dev/word-ai 替换为 word-ai-mcp。

--root 是相对路径和 .wordai sidecar 的主工作区。需要编辑 Downloads、Documents 或团队目录中的原始 DOCX 时，重复添加 --allow-root。安装脚本生成的 .wordai/codex-config.toml 会自动加入常见用户文档目录。

推荐将写入类工具设置为需要审批，尤其是 docx_apply_patchset、docx_restore_backup、docx_rollback。打开的 Word 文档会话写入也应审批：word_session_apply_patchset、word_session_wrap_selection、word_session_rollback。

对于当前已在 Word 中打开的文档，先加载 Office add-in 并连接 bridge，然后可以让 Codex 使用：

使用 word_ai 列出 active Word sessions，读取 live session 中 WORD-AI:SRS:1.0:overview 的内容控件文本，先通过 Office.js preview PatchSet，再 apply 到当前打开文档，并返回 audit 与 rollback PatchSet。

OfficeCLI 兼容策略

Word AI 可以把 OfficeCLI 作为辅助证据来源，但默认只允许只读/低风险能力：view html、view screenshot、view issues、query --json、validate。OfficeCLI 的 set、add、remove、raw-set、batch、merge 等写入/变更命令，不作为 Word AI 默认流程开放；除非未来被包进 Word AI 的 PatchSet、dry-run、audit、rollback 和显式审批机制。

MCP Server 只通过白名单 wrapper 暴露该集成：officecli_view_html、officecli_view_screenshot、officecli_view_issues、officecli_query、officecli_validate。如果本机未安装 OfficeCLI，这些工具会返回 available=false，核心 Word AI 流程仍继续使用 docx_* 和 word_session_*。

Word AI 会借鉴 OfficeCLI 的 schema/help-first、semantic path、watch/render、template merge、dump/batch 等设计，但正式写入模型仍以 Word AI PatchSet 为准。

标准安全流程

docx_health_check
  -> docx_map / docx_list_anchors / docx_list_content_controls
  -> docx_read_content_control / docx_read_table_cell / docx_read_paragraph
  -> 生成带 hash 前置条件的 PatchSet
  -> docx_assess_patchset
  -> docx_dry_run_patchset
  -> docx_backup
  -> docx_apply_patchset
  -> docx_validate / docx_compare_structure
  -> docx_text_diff

文档

许可证

GNU Affero General Public License v3.0 or later（AGPL-3.0-or-later）。详见 LICENSE。