# Word Live MCP

**在 Codex 中下指令，直接修改 Microsoft Word 当前打开的文档。**

A local Windows MCP server for reading and editing the active Microsoft Word document, including unsaved documents and the current selection.

通过 Word 的 COM 接口工作，无需 Word 宏、Office 加载项或额外 API Key。运行时使用标准输入输出连接 Codex，不监听网络端口。

## 能做什么

| 工具 | 功能 |
|---|---|
| `word_get_context` | 读取当前文档、选区、打开的文档列表和状态 |
| `word_read_document` | 分段读取正文及段落的原生 Word 位置 |
| `word_find_text` | 查找正文文字并返回可编辑范围 |
| `word_edit_range` | 替换、插入或删除文字，可启用修订模式 |
| `word_add_comment` | 给指定文字添加批注 |
| `word_format_range` | 设置粗体、斜体、字体、字号、标题样式和对齐 |
| `word_save` | 按要求保存到文档已有路径 |

每次写入都核对文档身份、活动文档、读取时的状态及原文。文档发生变化或目标窗口切换后，旧的写入请求会被拒绝。每次编辑、批注或组合格式调整都对应一个 Word 撤销步骤，可按 **Ctrl+Z** 撤销。

## 环境要求

- Windows 和桌面版 Microsoft Word；已在 Word 16.0 验证。
- Python 3.11 或更新版本；已在 Python 3.12 验证。
- Codex 桌面版或 CLI；自动注册需要 `codex` 命令在 PATH 中可用。
- Word 与 Codex 使用同一个 Windows 账户和相同权限级别运行。

## 安装到 Codex

在 PowerShell 中运行：

```powershell
git clone https://github.com/Klop233/word-live-mcp.git
cd word-live-mcp
py -3.12 install.py
```

没有 `py` 启动器时，也可以使用已安装的 Python 3.11+：

```powershell
python install.py
```

安装脚本在当前检出目录创建独立 `.venv`，安装固定版本依赖，然后将 **`word_live`** 注册为 Codex 的本地 MCP 服务器。如果已有同名连接，注册会更新该连接。请保留虚拟环境所在目录。

打开 Codex 的 **设置 → MCP 服务器**，刷新或重启 `word_live` 连接；如果列表还未更新，重启 Codex。保持 Word 和目标文档打开，然后输入：

> 使用 word_live，读取当前 Word 文档和我选中的文字。

接下来可以直接说：

- “把我选中的这段话润色得简洁一些，直接应用。”
- “把第一段改成正式语气，使用修订模式。”
- “在文末插入一段总结。”
- “把标题设为一级标题并居中。”
- “给这句话加批注：请补充数据来源。”
- “保存当前 Word 文档。”

## 手动配置及其他 MCP 客户端

只安装运行环境：

```powershell
py -3.12 install.py --skip-codex
```

手动注册到 Codex：

```powershell
$wordPython = (Resolve-Path .\.venv\Scripts\python.exe).Path
codex mcp add word_live -- $wordPython -X utf8 -m word_live_mcp
```

其他 MCP 客户端使用相同的 STDIO 命令：环境内的 `python.exe`，参数为 `-X utf8 -m word_live_mcp`。或者直接运行该环境中的 `word-live-mcp.exe`。

移除 Codex 连接：

```powershell
codex mcp remove word_live
```

## Codex 插件包

仓库包含标准 `.codex-plugin/plugin.json` 和 `.mcp.json`，供插件打包使用。插件配置调用 PATH 中的 `word-live-mcp` 命令；使用这一路径前，需要先通过隔离的工具环境安装命令，例如：

```powershell
pipx install .
pipx ensurepath
```

重启 Codex 以加载新的 PATH。插件清单本身不安装 Python 依赖，也不会自动把仓库添加到插件市场。上面的 `install.py` 是直接接入 Codex 的推荐方式，无需配置插件市场。

## 使用范围与数据处理

- 编辑工具覆盖正文及普通表格单元格中的文字。页眉、页脚、脚注和文本框等其他 story 的位置不能当作正文位置使用。
- 保留修改范围以外的格式；替换范围内原有多种字符格式时，新文字遵循 Word 的格式继承行为。尽量使用小范围编辑。
- 工具不会启动或关闭 Word，不会自动解除文档保护、接受已有修订或运行宏。
- `word_save` 只保存到已有路径。新文档第一次保存时，应在 Word 中选择文件名和位置。
- 工具不会在每次编辑后主动保存。如果 Word 自身已开启自动保存，实时修改可能由 Word 自动保存。
- 多个独立 Word 进程同时运行时，Windows 运行对象表可能只返回其中一个实例。建议使用一个实例，并核对工具返回的文档名称。
- 读取结果会进入当前 Codex/MCP 客户端会话，并可能传给该客户端使用的模型。本项目不包含遥测，也不额外上传文档。

## 开发与验证

`word_live_mcp.py` 是服务器实现；`requirements.txt` 固定直接依赖，`requirements.lock.txt` 固定完整的已验证依赖集。安装后的运行环境使用软件包副本；修改源码后重新运行安装脚本并刷新 MCP 连接。

只读诊断（输出当前正文，请只在需要时运行）：

```powershell
.\.venv\Scripts\python.exe -X utf8 -m word_live_mcp --context
```

需要真实 Word 的交互集成验证：

```powershell
.\.venv\Scripts\python.exe -X utf8 test_word_integration.py --work .\work\integration
```

该验证创建临时文档，结束后关闭临时文档并恢复原活动文档。运行期间请等待验证完成后再操作 Word。测试文件保留在被 Git 忽略的 `work/` 中。

已验证：中文及 emoji 范围编辑、分页读取、插入换行、保留未修改段落格式、单次撤销、原文与文档状态校验、活动文档切换保护、批注、标题样式、修订模式、保存文件的独立回读，以及受保护文档的写入限制。

## 常见问题

**连接不到 Word**：确认打开的是桌面版 Microsoft Word，关闭 Word 弹出的对话框，切到 Word 一次再切回 Codex，并确认两个应用处于相同的 Windows 账户和权限级别。

**提示 stale snapshot**：文档自上次读取后已变化。让 Codex 重新读取目标范围，再应用修改。

**修改后没有保存**：请明确要求保存。新文档先在 Word 中完成首次保存。

**工具没有出现**：在 Codex MCP 设置中刷新连接。修改 PATH 或安装新插件后可能需要重启 Codex。

## 参考

- [Codex MCP 配置](https://learn.chatgpt.com/zh-Hans/docs/extend/mcp)
- [Microsoft Word 撤销记录接口](https://learn.microsoft.com/en-us/office/vba/word/concepts/working-with-word/working-with-the-undorecord-object)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)