使用 Safe-DOCX 编辑 .docx 文件

Safe-DOCX 是一个本地 MCP 服务器，专用于精准编辑已有的 .docx 文件。它保留原始格式、自动生成带修订标记（tracked-changes）的比对红标文档（redlines），且安装完成后完全在本地文件系统中运行，全程零网络活动。

源代码与审计

Safe-DOCX 完全开源（MIT 许可证）。请在安装前完整审阅其源代码：

• GitHub: https://github.com/UseJunior/safe-docx
• npm registry: https://www.npmjs.com/package/@usejunior/safe-docx
• 代码覆盖率: 每次发布均通过 Codecov 公布
• 一致性测试套件: CI 系统在每次提交时自动运行规范覆盖测试
• 无 postinstall 脚本 — 验证方式：npm view @usejunior/safe-docx scripts 输出中不包含 postinstall 或 install 钩子

下方所有安全声明均可通过阅读源代码进行验证。

运行时依赖

Safe-DOCX 要求主机上已安装以下二进制程序：

如您不希望使用 npx，请参见下方的离线 / 版本锁定安装部分获取替代方案。

安全模型

Safe-DOCX 的安全模型分为两个明确阶段：安装时（下载包时）和 运行时（MCP 服务器运行期间）。

安装时行为（需网络连接，仅一次）

• npm registry 下载 — 推荐的连接器命令 npx -y @usejunior/safe-docx 在首次运行时从 registry.npmjs.org 下载包；后续运行默认使用缓存副本，除非手动清空缓存。
• 无 postinstall 脚本 — 该包未声明任何 postinstall、preinstall 或 install 钩子。可通过 npm view @usejunior/safe-docx scripts 验证。
• 来源可信性保障 — 所有发布版本均启用 npm provenance（--provenance），您可据此验证该包确由 GitHub 公共仓库经 GitHub Actions 构建而成。
• 如需确保离线安装 — 请锁定特定版本并将其本地化托管（vendored）。详见下一节。

运行时行为（零网络连接）

• 仅限本地 stdio 运行时 — MCP 服务器作为子进程运行，永不绑定端口。验证方式：入口点（src/server.ts）使用 StdioServerTransport，且未配置任何 HTTP 监听器。（源码依据）
• 无出站网络调用 — 运行时，该包不发起任何出站 HTTP 请求。验证方式：grep -r "fetch|http.|https.|net." packages/safe-docx/src/ 在应用代码中（排除测试夹具）不返回任何匹配项。
• 路径访问策略 — 仅允许访问 ~/（用户主目录）及系统临时目录下的文件。符号链接必须解析至允许的根路径内。
• 归档防护机制 — 内置 ZIP 炸弹检测与恶意载荷拦截能力，防范格式异常的 .docx 输入文件。

离线 / 版本锁定安装

在高安全性环境中（例如禁止 npx 自动拉取场景），请手动安装并显式锁定版本：

# 方案一：全局安装并锁定特定版本
npm install -g @usejunior/safe-docx@0.9.0

# 然后在 MCP 客户端中按路径调用：
# command: "safe-docx"
# args: []

# 方案二：将包本地化托管至项目中
npm pack @usejunior/safe-docx@0.9.0
# 检查生成的 tarball，再从本地磁盘安装：
npm install -g ./usejunior-safe-docx-0.9.0.tgz

# 方案三：从源码构建（最可审计）
git clone https://github.com/UseJunior/safe-docx.git
cd safe-docx
git checkout 
npm ci
npm run build
npm link packages/safe-docx

完成任一安装方式后，您的 MCP 客户端配置如下：

{
  "mcpServers": {
    "safe-docx": {
      "command": "safe-docx",
      "args": []
    }
  }
}

使用 command: "safe-docx"（已安装的二进制程序）而非 command: "npx"，可彻底避免每次调用时触发安装阶段的网络拉取操作。

始终锁定版本

即使使用 npx，您也可通过显式指定版本号防止意外升级：

{
  "mcpServers": {
    "safe-docx": {
      "command": "npx",
      "args": ["-y", "@usejunior/safe-docx@0.9.0"]
    }
  }
}

升级前，请查阅更新日志：https://github.com/UseJunior/safe-docx/blob/main/CHANGELOG.md

适用场景

当您需要执行以下操作时，请使用 Safe-DOCX：

• 修改已有 .docx 文件中的条款或段落
• 插入或删除内容，同时保持原有格式
• 为审阅者添加批注（comments）或脚注（footnotes）
• 基于编辑内容生成带修订标记（tracked-changes）的红标文档（redline）
• 对比两个 .docx 文件并输出红标差异
• 将修订内容提取为结构化 JSON 格式
• 应用版式格式设置（如段落间距、表格行高、单元格内边距）

不适用于从零生成文档

Safe-DOCX 仅支持编辑已存在的 .docx 文件，无法从空白创建新文档。对于全新文档生成，请使用模板填充工作流（例如 OpenAgreements）。Safe-DOCX 可在生成后的文档基础上进行下游精修。

快速入门

1. read_file(file_path="~/doc.docx")        → 查看段落及其稳定 _bk_* ID
2. grep(file_path="~/doc.docx", patterns=["目标短语"])  → 查找段落 ID
3. replace_text(session_id, target_paragraph_id, old_string, new_string, instruction)
4. save(session_id, save_to_local_path="~/doc-edited.docx")

核心工作流：读取 → 定位 → 编辑 → 保存

步骤一 — 读取。 调用 read_file 并设置 format: "toon"（高效 token 表示法），以查看段落及其稳定的 _bk_* ID。

步骤二 — 定位。 使用 grep 配合正则表达式模式查找目标段落。该方法将返回匹配段落 ID 及其上下文。

步骤三 — 编辑。 使用 replace_text 替换段落内文本，或使用 insert_paragraph 在锚点段落前后插入新段落。

步骤四 — 保存。 调用 save 写入结果。默认 save_format: "both" 将同时生成干净副本与带修订标记的红标文档。

常见陷阱（务必注意）

要求唯一匹配

replace_text 要求 old_string 在目标段落中**严格匹配且仅出现一次**。若文本多次出现，则返回 MULTIPLE_MATCHES 错误。解决方法：在 old_string 中增加更多上下文。

BAD:  old_string: "the Company"          → 出现 5 次，失败
GOOD: old_string: "the Company shall indemnify"  → 唯一匹配，成功

脚注标记仅为显示用途

read_file 将脚注显示为 [^1]、[^2] 等形式，但这些标记不属于可编辑文本。您无法通过 replace_text 搜索或替换 [^1]。如需修改脚注，请使用专用工具：add_footnote、update_footnote 和 delete_footnote。

超链接为只读

read_file 将超链接显示为 text，但您无法通过 replace_text 或 insert_paragraph 创建新超链接。 标签会在新文本中被自动剥离。编辑周围文本时，原有超链接将被保留。

1. read_file / grep  → 收集段落 ID 与文本
2. apply_plan(file_path, steps=[
     { step_id: "1", operation: "replace_text", target_paragraph_id, old_string, new_string, instruction },
     { step_id: "2", operation: "insert_paragraph", positional_anchor_node_id, new_string, instruction },
     ...
   ])
3. save(session_id, save_to_local_path)