che-word-mcp

che-word-mcp

A Swift-native MCP (Model Context Protocol) server for Microsoft Word document (.docx) manipulation. This is the first Swift OOXML library that directly manipulates Office Open XML without any third-party Word dependencies.

中文說明

文件格式 profile（原始碼建置功能，尚未發布）

create_document、open_document、execute_script 新增可選 profile: "inherit" | "official"。此功能需要以 SwiftPM editable dependency 整合尚未發布的 OOXMLSwift profile/store；本機最終驗收使用 OOXMLSwift 3aa221aa3bba3657af68f1c8d22416d3efe9863e，追蹤中的遠端 pin 並非此修補。目前發布 binary 不提供，本次未更新 release 版本。

與新版 macdoc 共用 ~/.config/macdoc/config.json：新建依明示 profile → document.defaultProfile → inherit；開啟既有文件及 replay 僅採明示 profile。以新版 macdoc config document import-official --template /path/to/Normal.dotm 匯入安全快照，再以 config document set-default official 選擇新建預設。匯入不複製正文、不修改 Normal、不自動切換預設；來源變更不影響已保存的快照。

官方繁中字型為標楷體，OOXML 寫入 DFKai-SB。core 992a3d67 產生的 DOCX 已由 Mac Word 16.112.3 與 Windows Word 16.0.20326 實際匯出：兩邊皆為 1 頁 A4、12 pt、左右 90 pt／上下 72 pt、段後 8 pt，PDF 實際嵌入 DFKaiShu-SB-Estd-BF 與 Aptos，PNG 無缺字、裁切或重疊。最終 reader 修補 core 3aa221aa 以原合成測試固定 IDs／時間重新產檔，全部 10 個 package parts 與已驗輸入逐位元組相同，沿用該證據，本輪未重新執行 Word。null、錯誤型別、未知名稱及缺失／損毀快照會明確報錯，沒有 fallback。格式套用成功才註冊 session；既有 inherit 不標 dirty、不觸發 autosave，official 沿用正常修改與存檔保護。execute_script 在驗證與發布前套用，仍沿用原有 overwrite 與驗證錯誤契約。

新建 adapter 在首次序列化前套用 profile；inherit 只移除記憶體中可證明由 factory 產生的預設字型，並保留 caller 明示字型。provenance 不序列化到 OOXML，讀回文件的字型視為來源文件所有，不以 style ID 或相同字型值猜測後刪除。

測試可透過 WordMCPServer(documentConfigURL: temporaryConfigURL) 注入隔離設定；CLI config document 指令接受 --config，convert/render 接受 --document-config。共用 store 的設定寫入保留 AI/OCR 與未知欄位。

Features

• 纯 Swift 实现：无需 Node.js、Python 或外部运行时
• 直接操作 OOXML：直接处理 XML，无需安装 Microsoft Word
• 单一二进制文件：仅需一个可执行文件
• 234 个 MCP 工具：全面支持文档、表格、超链接、页眉、节、样式、编号、内容控件、批注、脚注、公式、域和修订
• Office.js OOXML 路线图 P0 = 100%：全部 8 项 P0 子议题均已关闭（总议题 #43）。如今，所有 P0 能力在读写方面的覆盖范围均可与 Office.js 媲美。
• 往返过程中的静默损坏问题已解决（v3.13.5，#56）：5 轮子栈补全（R5 / R5-CONT / R5-CONT-2 / R5-CONT-3 / R5-CONT-4）关闭了 6-AI 交叉验证第 4 至第 8 轮中的 30 项发现（16 项 P0 + 21 项 P1）。将 ooxml-swift 升级至 v0.19.5（根据验证门禁，v0.19.4 未采用）。MCP 源码未作任何更改——修复架构完全位于 ooxml-swift 中。第 4 轮：页眉、页脚、脚注和尾注的遍历器对称性（accept_revision / reject_revision / get_hyperlinks / replace_text 可访问所有部分）。第 5 轮：每个容器的关系往返（update_hyperlink URL 同步至所属部分的关系）。第 6 轮：delete_hyperlink 镜像处理 + 保留容器 <w:tbl> 捕获。第 7 轮：reject_revision 类型化 clearMarker（文件/API 状态收敛）。第 8 轮：accept_revision 类型化 clearMarker（镜像处理）+ 移除矩阵固定不对称保护 + Document.repairContainerFileNames 将 document.xml.rels + [Content_Types].xml 标记为脏。收敛验证：Devil's Advocate 编写了 5 项针对收敛周期模式的对抗性测试，全部通过。详见关闭总结和 v3.13.5 发行说明。
• 以编程方式处理修订（v3.12.0+，#45）：通过 insert_text_as_revision / delete_text_as_revision / move_text_as_revision 生成原生 Word 可审阅修订，并可在 format_text / set_paragraph_format 中设置 as_revision: true 标志。生成 <w:ins> / <w:del> / <w:moveFrom> / <w:moveTo> / <w:rPrChange> / <w:pPrChange> 标记。副作用约定：as_revision: true 要求启用修订；否则会抛出 track_changes_not_enabled（不会静默自动启用）。作者解析顺序：显式参数 → revisions.settings.author → "Unknown"。
• 表格 / 超链接 / 页眉扩展（v3.11.0+，#49 #50 #51）：新增 16 个工具——表格条件样式（10 种区域类型）/ 嵌套表格（最多 5 层）/ 显式布局 / 表格缩进；三种类型的超链接（URL / 书签 / 邮件）；奇偶页眉切换 / 链接到前一节 / get_section_header_map。
• 样式 + 编号 + 节基础功能（v3.10.0+，#46 #47 #48）：新增 19 个工具 + 扩展 6 个参数——get_style_inheritance_chain、link_styles、set_latent_styles、add_style_name_alias、完整的编号 CRUD 生命周期（定义 / 覆盖 / 列表连续性 / GC）、节垂直对齐 / 页码格式 / 分隔符类型 / 首页不同设置 / 每节页眉引用。
• 内容控件（SDT）读写（v3.9.0+，#44）：新增 7 个工具，支持区分 12 种类型（richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection / repeatingSectionItem）。支持嵌套 SDT 树、确定性的 max+1 SDT ID 分配器、删除时通过 keep_content 解包，以及经过白名单验证的 XML 替换。
• 保存持久性保障（v3.5.3+）：原子重命名保存（#36）、基于 actor 的并发安全（#39）、选择启用 keep_bak 回滚（#38）、autosave_every Design B 突变前快照，并显式调用 recover_from_autosave 恢复（#37、#40，v3.7.0）。默认值为 autosave_every: 1（每次突变前均创建快照）。传入 autosave_every: 0 可选择退出。
• 双模式访问：直接模式（只读，通过 source_path 一步完成）和会话模式（通过 doc_id 支持完整生命周期）
• 真正保留字节的往返保真度（v3.5.0+）：save_document 覆盖模式使用 WordDocument.modifiedParts 脏跟踪，原样保留未经修改的类型化部分（document.xml、styles.xml、fontTable.xml、header*.xml、footer*.xml、comments.xml、footnotes.xml、endnotes.xml）和未知部分（theme/、webSettings.xml、people.xml、commentsExtended/Extensible/Ids、glossary/、customXml/）。文档无操作的 save_document 往返可保留 13 个 fontTable 条目 + 6 个不同页眉 + 4 个页脚 + 三段 PAGE 域 + <w15:presenceInfo> 标识。
• 主题 + 页眉/页脚 CRUD + 水印读写（v3.3.0+，写入端 #208）：编辑 word/theme/theme1.xml、枚举和删除页眉/页脚、检测水印 VML（list_watermarks / get_watermark——可识别 PowerPlusWaterMarkObject 文本特征和 Word 自带的 WordPictureWatermark 图片特征，#209），并支持实际写入（insert_watermark / insert_image_watermark / remove_watermark——将 VML <w:pict> 形状写入每个页眉部分；图片水印要求文档从现有 .docx 文件打开）。文档中文字体修复方式：update_theme_fonts({ minor: { ea: "DFKai-SB" } })。
• 批注线程 + 用户信息 + 笔记更新 + Web 设置（v3.4.0+）：提供 13 个工具，用于协作批注元数据、people.xml 作者记录（双重标识：GUID + 旧式作者）、原位编辑尾注/脚注（保留 ID）以及配置 webSettings.xml。
• insert_equation 的完整 LaTeX 子集（v3.2.0+）：委托给 latex-math-swift。支持 \frac、\sqrt、\hat / \bar / \tilde 重音符号、\left/\right 分隔符、带上下限的 \sum / \int / \prod 多元运算符、函数名称、极限、\text{}、所有希腊字母（包括 \varepsilon 变体）以及常用运算符。
• 文本锚点插入：相对于匹配文本插入题注 / 图片（after_text / before_text），无需预先调用搜索
• 批量操作：replace_text_batch / search_text_batch 将 N 次往返合并为一次
• 会话状态 API：基于 SHA256 + mtime 的磁盘漂移检测，以及 revert_to_disk / reload_from_disk / check_disk_drift
• 结构化回读：提供 list_captions / list_equations / update_all_fields（等效于 F9），用于稿件审阅工作流
• 跨平台：支持 macOS（自 v3.5.1 起提供通用二进制文件 x86_64 + arm64）

Version History

版本	日期	变更
v4.0.0	2026-08-19	execute_script 契约修正（重大变更） — 验证失败现在会作为工具错误返回（#180）；新增 overwrite 参数，且默认拒绝覆盖已有的 output_path（#181）。覆盖保护移入 ooxml-swift 的共享入口 scriptPipelineExecute，两端都受到结构性保护；重建结果现在会写入同目录下的临时路径，验证通过后才移入目标位置，因此验证失败不再破坏输出路径。需要 ooxml-swift 3.0.1。5-lens 验证（因配额原因未执行 Codex 环节，已记录）。
v3.22.0	2026-07-18	自生成的 docx 升级为类型化 DSL（通过 idd 关闭 #173，PR #174）。将 ooxml-swift 从 1.4.0 升级至 1.5.0（上游 ooxml-swift#85：转码器规范化创作 — 带有标记的 w14:paraId、元素间无空白、完整的 Word 规范根云）。现在，对 MCP 创作的纯段落文档调用 export_script 时，会在 dsl 通道报告 document.xml（比率为 1.0）；slots 锚定于标记的 paraId。工具描述中已说明部件级边界：富表格或缺少 paraId 的旧内容会使整个部件降级为原始内容，等待 ooxml-swift#86。消费者回归测试 Issue173SelfProducedDSLUpgradeTests（在 1.4.0 上失败／在 1.5.0 上通过）。6-AI 验证通过。
v3.13.5	2026-04-27	R5 栈补全（关闭 #56 中的静默损坏问题）。将 ooxml-swift 从 v0.19.3 升级至 v0.19.5（根据验证门禁暂缓发布 v0.19.4）。在 5 个子栈（R5 / R5-CONT / R5-CONT-2 / R5-CONT-3 / R5-CONT-4）及 6-AI 交叉验证第 4-8 轮中，关闭了 30 个问题（16 个 P0 + 21 个 P1）。第 4 轮：页眉／页脚／脚注／尾注间的遍历器对称性（accept_revision / reject_revision / get_hyperlinks / replace_text 可访问所有部件）。第 5 轮：每个容器的关系往返（update_hyperlink 的 URL 同步目标为所属部件的关系）。第 6 轮：镜像实现 delete_hyperlink + 保留容器 <w:tbl> 捕获。第 7 轮：reject_revision 类型化 clearMarker（文件／API 状态收敛）。第 8 轮：accept_revision 类型化 clearMarker（镜像实现）+ 移除矩阵固定的非对称保护 + repairContainerFileNames 标记关系为脏。收敛：Devil's Advocate 编写了 5 个针对收敛循环模式的对抗性测试；全部通过。che-word-mcp 源码未作任何更改 — 整个修复架构均在 ooxml-swift 中。请参阅结项摘要。
v3.13.4	2026-04-26	（已跳过 — 根据验证门禁暂缓发布）。R3 栈内容并入 v3.13.5。
v3.13.3	2026-04-26	将 ooxml-swift 从 v0.19.2 升级至 v0.19.3。关闭 #56 第 2 轮验证中的 8 个 P0 + 3 个必须修复的 P1 问题（Hyperlink API 路径的视觉样式恢复 / tgtFrame / docLocation Reader 过滤 / 按顺序保留子项的源顺序；排序路径上的 contentControls + commentIds / footnoteIds / endnoteIds / hasPageBreak 发出；保留非文本包装器；嵌套 hyperlink/SDT/fieldSimple 往返；校准 nextBookmarkId；恢复书签环绕）。源码未作更改。
v3.13.2	2026-04-26	将 ooxml-swift 从 v0.19.1 升级至 v0.19.2。关闭 #56 第 1 轮验证中的 4 个阻塞问题（F1 Hyperlink.toXML() 发出 Reader 收集的 runs/rawAttributes/rawChildren；F2 add_bookmark/delete_bookmark 同步 bookmarkMarkers；F3 ins/del/moveFrom/moveTo 往返保留位置+revisionId+包装器；F4 命名空间保留范围从 document.xml 扩展至页眉／页脚／脚注／尾注）。源码未作更改。
v3.13.1	2026-04-25	按位置排序往返时 pPr 重复发出导致静默回归 — 热修复（ooxml-swift v0.19.1）。
v3.13.0	2026-04-25	document.xml 无损往返 + 通过工具编辑包装器（关闭 #56 P0）。混合模型保留命名空间映射（34 个 xmlns）、书签和结构性包装器（<w:hyperlink> / <w:fldSimple> / <mc:AlternateContent>）。
v3.12.0	2026-04-25	以编程方式生成修订（关闭 #45）— 新增 3 个工具（insert_text_as_revision / delete_text_as_revision / move_text_as_revision）+ 为 format_text / set_paragraph_format 新增 as_revision 标记。生成 <w:ins> / <w:del> / <w:moveFrom> / <w:moveTo> / <w:rPrChange> / <w:pPrChange> 标记。
v3.11.0	2026-04-25	表格／超链接／页眉扩展（关闭 #49 #50 #51）— 新增 16 个工具：表格条件样式（10 种区域类型）／嵌套表格（最多 5 层）／显式布局／表格缩进；三种类型化超链接（URL／书签／电子邮件）；奇偶页眉切换／链接到前一节／get_section_header_map。
v3.10.0	2026-04-24	样式 + 编号 + 分节基础功能（关闭 #46 #47 #48）— 新增 19 个工具 + 扩展 6 个参数。get_style_inheritance_chain、link_styles、set_latent_styles、add_style_name_alias；完整的编号增删改查生命周期；分节垂直对齐／页码格式／分节类型／首页不同／每节页眉引用。
v3.9.0	2026-04-24	内容控件（SDT）读写（关闭 #44）— 新增 7 个工具，区分 12 种类型（richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection / repeatingSectionItem）。支持嵌套 SDT 树、确定性 ID 分配器、keep_content 解包、经白名单验证的 XML 替换。
v3.8.0	2026-04-24	保留页眉／页脚原始元素 + 计数器隔离标记（关闭 #52）。
v3.7.2	2026-04-24	#42 验证中的 3 个问题合并修复（关闭 #53、#54、#55 路径遍历加固）。
v3.7.1	2026-04-24	update_all_fields 不再删除页眉／页脚（关闭 #42）。
v3.7.0	2026-04-24	插入崩溃加固 + 自动保存设计 B（关闭 #40、#41）。v3.6.0 发布了 autosave_every 设计 A（变更后计数器），当 K%N≠0 时，在第 K 次操作时崩溃便无法保留前 K-1 次变更。v3.7.0 改为设计 B（每个变更处理器运行时，在变更执行前启动快照）；autosave_every 默认值从 0 改为 1（每次变更都会快照此前状态）。传入 autosave_every: 0 可选择退出。实际上的重大变更：影响依赖设计 A 语义或依赖默认禁用自动保存的调用方。还新增了用于调查 #41 的 Phase A 结构化日志门控 CHE_WORD_MCP_LOG_LEVEL=debug。基于 ooxml-swift 0.13.3 构建，该版本移除了 DocxReader.concurrentPerform（这是 recover_from_autosave 的解析确定性前提），并重构 nextImageRelationshipId，使其使用 rId 分配器。从 v3.6.0 迁移：显式传入 autosave_every: 0 的代码不受影响；未传入该参数的代码现在会使用 1（完整安全保护）— 若要恢复 v3.6.0 默认禁用的行为，请在 open_document 调用中添加 autosave_every: 0。
v3.6.0	2026-04-23	自动保存 + 检查点 + recover_from_autosave（关闭 #37）。open_document 新增参数 autosave_every: Int = 0 — 当 N > 0 时，每 N 次变更会触发一次检查点写入 <source>.autosave.docx（单独文件，不会立即保存到源文件）。新增工具：用于手动快照的 checkpoint(doc_id, path?)，以及用于将内存状态替换为自动保存字节数据的 recover_from_autosave(doc_id, discard_changes?)。get_session_state 新增 autosave_detected + autosave_path 字段。成功调用 save_document / finalize_document 后会清理 <source>.autosave.docx。这是保存持久性栈 SDD 的第 4 阶段。
v3.5.5	2026-04-23	可选启用 keep_bak，提供回滚逃生通道（关闭 #38）。save_document 新增可选参数 keep_bak: Bool = false；当设为 true 且目标文件存在时，服务会在原子重命名保存前将目标文件重命名为 <path>.bak（单个备份槽位，会覆盖先前的 .bak）。如果未来保存操作造成静默 OOXML 损坏，用户可通过 mv <path>.bak <path> 回滚。.bak 位于服务层而非 ooxml-swift — macdoc CLI 用户不会得到多余的 .bak 文件。这是保存持久性栈 SDD 的第 3 阶段。
v3.5.4	2026-04-23	class WordMCPServer → actor WordMCPServer（关闭 #39）。8 个可变会话状态字典现已隔离在 actor 中；编译器会强制所有跨 actor 访问都通过 await。消除了 v3.5.4 之前由 12 个并行 insert_image_from_path 调用触发的 Dictionary 哈希表损坏竞态。这是保存持久性栈 SDD 的第 2 阶段。
v3.5.3	2026-04-23	原子重命名保存（关闭 #36）。升级至 ooxml-swift 0.13.2，该版本重构 DocxWriter.write，使其写入 <url>.tmp.<UUID>，然后执行 fsync + replaceItemAt。写入中途发生任何异常或进程被终止，都会保留原文件字节不变（POSIX rename(2) 由内核保证原子性；跨卷时会回退到复制 + 删除）。ooxml-swift 测试 397/397 通过；新增并发观察者回归测试。这是保存持久性栈 SDD 的第 1 阶段。
v3.5.2	2026-04-23	关系覆盖层合并（关闭 #35）— Reader 加载文档后，对其调用空操作 save_document 并往返保存，现在会保留 theme / webSettings / people / customXml / commentsExtended / commentsIds 关系。v3.5.0/v3.5.1 修复了部件层；v3.5.2 修复了关系层。che-word-mcp 源码未作更改 — 修复完全在 ooxml-swift v0.13.1 中完成（RelationshipsOverlay + 由关系驱动的 extractImages）。
v3.5.1	2026-04-23	通用二进制文件（x86_64 + arm64）— 恢复对 Intel Mac 的兼容性。v3.5.0 仅支持 arm64，因为发布构建跳过了文档中所述的 lipo -create 步骤。源码未作更改 — 可直接替换。
v3.5.0	2026-04-23	通过脏状态跟踪实现真正的字节保留（关闭 #23 round-2 + #32 #33 #34）。Reader 加载的 学位论文在空操作 save_document 往返后仍能保留全部 13 个 fontTable + 6 个不同页眉 + 4 个页脚 + 三段式 PAGE 字段 + <w15:presenceInfo> 身份信息。基于 ooxml-swift 0.13.0 构建（modifiedParts: Set<String> + Header.originalFileName + 覆盖模式下跳过未变更内容）。list_people 返回双重身份信息：person_id（GUID，重命名后仍稳定）+ display_name_id（即旧版 author）。
v3.4.0	2026-04-23	合并第 2B + 2C 阶段（关闭 #24 #25 #29 #30 #31）：评论线程（list_comment_threads / get_comment_thread / sync_extended_comments）、人员（list_people / add_person / update_person / delete_person）、注释更新（get_endnote / update_endnote / get_footnote / update_footnote — 保留注释 ID）、Web 设置（get_web_settings / update_web_settings）。新增 13 个 MCP 工具。
v3.3.0	2026-04-23	第 2A 阶段（关闭 #26 #27 #28）：主题工具（get_theme / update_theme_fonts / update_theme_color / set_theme）、页眉（list_headers / get_header / delete_header）、水印（list_watermarks / get_watermark）、页脚（list_footers / get_footer / delete_footer）。新增 12 个 MCP 工具。升级至 ooxml-swift 0.12.x，以支持默认保留的往返处理。
v3.2.0	2026-04-23	insert_equation 的 LaTeX 解析器改由 latex-math-swift 处理（关闭 #22）。支持完整的 LaTeX 子集：\frac、\sqrt、\hat/\bar/\tilde、\left/\right、带上下限的 \sum/\int/\prod、\ln/\sin/\cos/\tan/\log/\exp/\max/\min/\det、\sup/\inf/\lim、\text{}、所有希腊字母（包括 \varepsilon 变体）以及常见运算符。18 个计量经济学样例公式现均可解析。通过 ooxml-swift 0.11.0 新增 MathAccent。
v3.1.0	2026-04-22	新增 9 个回读工具：题注增删改查（list_captions / get_caption / update_caption / delete_caption）、update_all_fields（等效于 F9 的 SEQ 重新计数）、公式增删改查（list_equations / get_equation / update_equation / delete_equation）。基于新版 ooxml-swift 0.10.0 的 FieldParser + OMMLParser 构建。
v3.0.0	2026-04-22	重大变更：会话状态 API。新增工具 get_session_state / revert_to_disk / reload_from_disk / check_disk_drift。open_document 的 track_changes 默认值从 true 改为 false。close_document 的脏状态检查现在会返回包含恢复选项的 E_DIRTY_DOC 文本响应（save_document / discard_changes: true / finalize_document）。
v2.3.0	2026-04-22	文本锚点复合工具 — insert_caption / insert_image_from_path 接受 after_text / before_text / text_instance。无需再采用 search_text + insert_* 两次调用模式（可为文档题注工作流减少约 50% 的 RPC 调用）。
v2.2.0	2026-04-22	批处理 API — replace_text_batch（按顺序执行，最后只保存一次，含 dry_run/stop_on_first_failure 标记）+ search_text_batch（聚合多查询响应，支持 Direct + Session Mode）。
v2.1.0	2026-04-22	通过 inputSchema 暴露 v2.0.0 参数 — insert_caption / insert_equation / insert_image_from_path / replace_text 的架构现在会声明新参数（中文标签、components、into_table_cell、scope、regex）。
v2.0.0	2026-04-22	重大变更：word-mcp-insertion-primitives Spectra 变更。真实的 OOXML SEQ 字段（此前为字面文本）、OMML MathComponent AST（此前为字符串替换）、自动保持纵横比的图像尺寸调整 + 表格单元格目标，以及支持 scope + 正则反向引用的跨 run 安全 replace_text。
v1.19.0	2026-04-15	导出手稿审阅 Markdown：export_revision_summary_markdown / compare_documents_markdown / export_comment_threads_markdown。重大变更：get_revisions + compare_documents 的 full_text 参数由 summarize 替代（默认值反转）。
v1.18.0	2026-04-14	修复 get_revisions 硬编码截断为 30 个字符的问题（自 v1.2.0 起存在）；新增可选启用的 full_text。
v1.17.0	2026-03-11	会话状态管理：脏状态跟踪、自动保存、finalize_document、get_document_session_state、关闭时刷新（由 @ildunari 贡献）
v1.16.0	2026-03-10	双模式：15 个只读工具现在支持 source_path（Direct Mode）；新增 MCP 服务说明
v1.15.2	2026-03-07	改进 list_all_formatted_text 工具描述，以便 LLM 更好地处理参数
v1.15.1	2026-03-01	修复标题启发式样式回退（从样式继承链解析 fontSize）
v1.15.0	2026-03-01	实用模式：自动将 EMF 转换为 PNG + 为无样式文档提供标题启发式判断
v1.14.0	2026-03-01	嵌入 word-to-md-swift 库：无需外部 macdoc 二进制文件，恢复对 doc_id 的支持
v1.13.0	2026-03-01	将 ooxml-swift 升级至 v0.5.0：并行多核解析（大型文档约需 0.64 秒）
v1.12.1	2026-03-01	将 ooxml-swift 升级至 v0.4.0：修复大型文档性能问题（>30 秒 → 约 2.3 秒）
v1.12.0	2026-02-28	export_markdown 现在仅使用 source_path，移除 doc_id，新增锁文件检查
v1.11.1	2026-02-28	修复 export_markdown 标准输出模式（管道 fsync 问题）
v1.11.0	2026-02-28	export_markdown 改由 macdoc CLI 处理；移除 word-to-md-swift 依赖
v1.9.0	2026-02-28	升级 export_markdown，改用 word-to-md-swift 以生成高质量输出（总计 145 项）
v1.8.0	2026-02-03	移除硬性差异上限；为 compare_documents 新增 max_results 和 heading_styles 参数
v1.7.0	2026-02-03	新增 compare_documents 工具，用于服务端文档差异比较（总计 105 项）
v1.2.1	2026-01-16	修复 MCP SDK 兼容性（actor→class，新增 capabilities）
v1.2.0	2026-01-16	新增 12 个工具（总计 95 项）：搜索、超链接、书签、脚注、尾注、修订、属性
v1.1.0	2026-01-16	修复 Claude Desktop 的 MCPB manifest.json 格式
v1.0.0	2026-01-16	首次发布，包含 83 个工具，并重构为使用 ooxml-swift

快速开始

用于 Claude Desktop

选项 A：一键安装 MCPB（推荐）

从 Releases 下载最新的 .mcpb 文件，然后双击安装。

选项 B：手动配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "che-word-mcp": {
      "command": "/usr/local/bin/CheWordMCP"
    }
  }
}

用于 Claude Code（CLI）

选项 A：作为插件安装（推荐）

该插件内置了一个支持版本识别的包装程序，首次使用时会自动下载二进制文件（每次更新插件本身时也会重新下载——无需运行 swift build）。

分两步完成——先注册市场，一次即可；然后安装插件：

# 1. Register the marketplace (one-time)
claude plugin marketplace add PsychQuant/psychquant-claude-plugins

# 2. Install the plugin
claude plugin install che-word-mcp@psychquant-claude-plugins

正在使用 Claude Code？ 斜杠命令 /plugin marketplace add PsychQuant/psychquant-claude-plugins 和 /plugin install che-word-mcp@psychquant-claude-plugins 的效果相同。

注意： 该插件通过自动下载功能包装 MCP 二进制文件。如果 ~/bin/CheWordMCP 中缺少二进制文件（或旁路文件 ~/bin/.CheWordMCP.version 中的版本早于插件固定的版本），则会在下次调用时从 GitHub Releases 下载。

选项 B：作为独立 MCP 安装

如果你只需要 MCP 服务，不需要插件功能（斜杠命令、技能、SessionStart 钩子）：

# Create ~/bin if needed
mkdir -p ~/bin

# Download the latest release
curl -L https://github.com/PsychQuant/che-word-mcp/releases/latest/download/CheWordMCP -o ~/bin/CheWordMCP
chmod +x ~/bin/CheWordMCP

# Register with Claude Code
# --scope user    : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# --              : separator between claude options and the command
claude mcp add --scope user --transport stdio che-word-mcp -- ~/bin/CheWordMCP

💡 提示： 将二进制文件安装到 ~/bin/ 这样的本地目录中。请避免使用云同步文件夹（Dropbox、iCloud、OneDrive）——同步操作可能会导致 MCP 连接中断。

从源代码构建（可选）

仅在你想跟踪 main 或贡献补丁时使用。

先决条件

• macOS 13.0+（Ventura 或更高版本）
• Swift 5.9+

git clone https://github.com/PsychQuant/che-word-mcp.git
cd che-word-mcp
swift build -c release

# Install
cp .build/release/CheWordMCP ~/bin/

崩溃模糊测试（scripts/fuzz-extreme-params.py）

将极端值（Int.max、Int.min、2^62、2^31、-1、1e300、 -1e300）发送到 tools/list 中声明的每个整数/数字参数，并通过 stdio （MCP JSON-RPC）针对真正编译的二进制运行——每次探测都启动一个全新的 服务进程，因此某次探测崩溃不会导致整个运行中断。在 #234 的 第一轮修复之前发现了 58 个崩溃，之后又发现了 5 个（按该问题自身扩展后的 审计标准），这些问题都被基于 grep 的人工审计遗漏了——完整历史请参阅该问题。 每当新增工具或整数/数字参数时，以及发布涉及 Server.swift 中整数/数字参数处理的 版本之前，都要运行此脚本：

swift build   # ensure .build/debug/CheWordMCP is up to date first
python3 scripts/fuzz-extreme-params.py .build/debug/CheWordMCP /tmp/fuzz-workdir

只有在没有崩溃或挂起（包括每次探测后执行的保存操作）、所有“（必须拒绝）”探测都被拒绝、最大合法表格探测期间的峰值常驻内存低于上限（在整个序列中采样，而不是在结束时读取一次——#239），并且架构中的整数/数字参数至少有 FUZZ_MIN_COVERAGE（默认为 0.80，从 0.97 下调——见下文）被判定为已触达时，退出码才为 0。被无关前置条件拦截的探测不能证明任何问题，因此，如果模糊测试器无法触达目标参数，就会判定失败，而不是报告零崩溃。“已触达”需要有正面证据（响应中提及参数名称或回显其值，或者返回针对该参数的索引/未找到错误）；仅有一个成功响应不再足够（#239——旧标准在 4.4.0 中将 241/245 计为已触达，但独立审计发现实际上只有约 227/245）。诚实的标准测得的覆盖率低于旧标准曾报告的任何值（相对于当前更大的参数集约为 85%），因此默认值从 0.97 调整为 0.80：0.97 是按高估覆盖率的标准校准的，按诚实标准衡量时实际上从未达到。脚本始终会生成摘要行、覆盖率行（包含未触达参数）以及逐探测 TSV（<workdir>/fuzz_results.tsv）。它也已接入 swift test 的可选开关（默认不运行——需要约 1,300 个子进程和一个已编译的二进制；设置 RUN_FUZZ=1 后，如果二进制缺失或不是最新版本，就会导致门禁失败）：

RUN_FUZZ=1 swift test --filter FuzzExtremeParamsGateTests

两种运行模式

直接模式（source_path）——只读，无状态

直接传入文件路径。无需先调用 open_document。适合快速查看。

# Just pass source_path — one step
list_images: { "source_path": "/path/to/file.docx" }
search_text: { "source_path": "/path/to/file.docx", "query": "keyword" }
get_document_info: { "source_path": "/path/to/file.docx" }

19 个工具支持直接模式：

类别	工具
读取内容	get_text、get_document_text、get_paragraphs、get_document_info、search_text
列出元素	list_images、list_styles、get_tables、list_comments、list_hyperlinks、list_bookmarks、list_footnotes、list_endnotes、get_revisions
属性	get_document_properties、get_section_properties、get_word_count_by_section、estimate_paragraph_for_page
导出	export_markdown

会话模式（doc_id）——完整的读写生命周期

先调用 open_document，然后在所有后续操作中使用 doc_id。编辑时必须使用此模式。

open_document: { "path": "/path/to/file.docx", "doc_id": "mydoc" }
insert_paragraph: { "doc_id": "mydoc", "text": "Hello World" }
save_document: { "doc_id": "mydoc", "path": "/path/to/output.docx" }
close_document: { "doc_id": "mydoc" }

双模式工具同时接受 source_path 和 doc_id。如果文档已经打开，请使用 doc_id，以避免从磁盘重新读取。

与 AI Agent 搭配使用

直接向 Agent 提出请求

Use che-word-mcp to read all images from ~/Documents/report.docx

Agent 会自动使用直接模式（无需打开或关闭文档）。

AGENTS.md / CLAUDE.md

## Word Document Manipulation

Use `che-word-mcp` for reading and writing Microsoft Word (.docx) files.

**Read-only** (Direct Mode — one step):
- `get_document_text` / `get_paragraphs` — read content
- `list_images` / `search_text` — inspect elements
- `export_markdown` — convert to Markdown

**Edit** (Session Mode — open→edit→save):
1. `open_document` → get doc_id
2. `insert_paragraph` / `replace_text` / `format_text` — modify
3. `save_document` → write to disk
4. `close_document` → release memory

Claude Code 技能

mkdir -p .claude/skills/che-word-mcp
curl -o .claude/skills/che-word-mcp/SKILL.md \
  https://raw.githubusercontent.com/PsychQuant/che-word-mcp/main/skills/che-word-mcp/SKILL.md

可用工具（共 234 个）

段落索引约定

paragraph_index / index 是历史参数名称，并不总是对应相同的 OOXML 表面。不同的插入／修改／读回工具 采用不同约定——不能假设存在通用默认规则。 目前有三种坐标系统并存： body.children 插入索引（部分插入操作使用）、顶层段落序号（大多数修改操作和行内公式插入使用）， 以及 get_paragraphs 读回顺序（用于检查）。在不同工具间复用索引前，请参阅 docs/paragraph-index-conventions.md 中各工具的清单。

文档管理（6 个工具）

工具	描述
create_document	创建新的 Word 文档
open_document	打开现有的 .docx 文件（自 v3.0.0 起，track_changes 默认值为 false）
save_document	将文档保存为 .docx 文件
close_document	关闭已打开的文档（传入 discard_changes: true 可丢弃未保存的编辑）
finalize_document	在单个受保护步骤中保存并关闭
list_open_documents	列出所有已打开的文档

会话状态 API（5 个工具，v3.0.0+）

工具	描述
get_session_state	获取 { source_path, disk_hash_hex, disk_mtime_iso8601, is_dirty, track_changes_enabled } 快照
get_document_session_state	旧版会话快照（为保持向后兼容而保留）
revert_to_disk	重新读取源路径并丢弃内存中的编辑（有意设计为破坏性操作）
reload_from_disk	协作式重新加载；文档有未保存修改时需要 force: true
check_disk_drift	提供信息——返回 { drifted, disk_mtime, stored_mtime, disk_hash_matches }

内容操作（9 个工具）

工具	描述
get_text	获取纯文本内容
get_paragraphs	获取所有段落及其格式
estimate_paragraph_for_page	v3.18.0+ — 将 Word UI 页码估算为 get_paragraphs 候选范围（启发式 JSON，包含置信度和警告）。chars_per_page 推导公式、置信度等级表和已知限制请参阅 docs/estimate-paragraph-for-page.md。
insert_paragraph	插入新段落
update_paragraph	更新段落内容
delete_paragraph	删除段落
replace_text	跨运行安全的查找与替换，支持 scope（body|all）、regex 和 $1..$N 反向引用
replace_text_batch	v2.2.0 — 顺序执行 N 次替换的批处理，最后仅保存一次，支持 dry_run / stop_on_first_failure
search_text_batch	v2.2.0 — 聚合多查询搜索，适用于 Direct + Session Mode

格式设置（3 个工具）

工具	描述
format_text	应用文本格式（粗体、斜体、颜色、字体）
set_paragraph_format	设置段落格式（对齐、间距）
apply_style	应用内置或自定义样式

表格（15 个工具，v3.11.0+ 扩展 #49）

核心（6 个）：

工具	描述
insert_table	插入表格，可选择是否包含数据
get_tables	获取所有表格信息
update_cell	更新单元格内容
delete_table	删除表格
merge_cells	横向或纵向合并单元格
set_table_style	设置表格边框和底纹

行 / 列 / 单元格（8 个）：

工具	描述
add_row_to_table, delete_row_from_table	行管理
add_column_to_table, delete_column_from_table	列管理
set_cell_width, set_cell_vertical_alignment	单元格尺寸和对齐方式
set_row_height, set_table_alignment	行高和表格对齐方式

高级（5 个，v3.11.0）：

工具	描述
set_table_conditional_style	通过 <w:tblStylePr> 应用 firstRow / lastRow / bandedRows 等样式（10 种区域类型）
insert_nested_table	在单元格中插入表格，嵌套深度限制为 5（超出时抛出 nested_too_deep）
set_table_layout	切换固定布局 / 自动调整
set_header_row	将行标记为 <w:tblHeader/>，使其在分页符处重复显示
set_table_indent	设置表格级左缩进（<w:tblInd>）

样式管理（8 个工具 + 6 个扩展参数，v3.10.0+ #48）

核心（4 个）：

工具	描述
list_styles	列出所有可用样式（支持 Direct Mode）
create_style	创建自定义样式 — 扩展支持 6 个 v3.10 参数：based_on、linked_style_id、next_style_id、q_format、hidden、semi_hidden
update_style	更新样式定义 — 同样支持上述 6 个扩展参数
delete_style	删除自定义样式

继承与关联（4 个，v3.10.0）：

工具	描述
get_style_inheritance_chain	向上遍历 basedOn 链直至根节点，并检测循环
link_styles	在段落样式与字符样式之间建立双向 <w:link> 关联
set_latent_styles	通过 <w:latentStyles> 块控制“快速样式库”的默认样式
add_style_name_alias	按 BCP 47 语言代码添加本地化的 <w:name> 别名

编号 / 列表（12 个工具，v3.10.0+ 定义生命周期 #46）

内联列表创建（4 个）：

工具	描述
insert_bullet_list	插入项目符号列表
insert_numbered_list	插入编号列表
set_list_level	设置列表缩进级别
set_outline_level	设置段落大纲级别（用于目录收录）

定义的增删改查（8 个，v3.10.0）：

工具	描述
list_numbering_definitions	枚举所有 abstractNum + num 配对
get_numbering_definition	按 ID 获取单个 num
create_numbering_definition	新建 abstractNum + 配对 num（最多 9 级）
override_numbering_level	使用 <w:lvlOverride> 设置各级起始值
assign_numbering_to_paragraph	按段落索引通过 <w:numPr> 关联编号
continue_list	跨段落继续编号
start_new_list	重置编号并从头开始
gc_orphan_numbering	清理未引用的 num 定义（保留 abstractNums）

分节 / 页面设置（12 个工具，v3.10.0+ 扩展 #47）

基本页面设置（5 个）：

工具	描述
set_page_size	设置页面大小（A4、Letter 等）
set_page_margins	设置页边距
set_page_orientation	设置纵向或横向
insert_page_break	插入分页符
insert_section_break	插入分节符

分节属性（7 个，v3.10.0）：

工具	描述
get_all_sections	按文档顺序返回每个分节的 SectionInfo 数组
set_section_break_type	nextPage / continuous / evenPage / oddPage
set_section_vertical_alignment	用于封面的 <w:vAlign>
set_page_number_format	用于罗马数字等的 <w:pgNumType w:fmt>
set_line_numbers_for_section	用于法律文档的 <w:lnNumType>
set_title_page_distinct	切换每个分节的 <w:titlePg/>
set_section_header_footer_references	按类型（default/first/even）分配 rId

页眉和页脚（17 个工具，v3.11.0+ 偶数页/奇数页 + 分节映射 #51）

写入工具（5 个）：

工具	描述
add_header	添加页眉内容（自 v3.3.0+ 起使用 RelationshipIdAllocator——覆盖模式下的 rId 不会冲突）
update_header	更新页眉内容（保留文件名和 rId；原位覆盖 tempDir）
add_footer	添加页脚内容
update_footer	更新页脚内容
insert_page_number	插入页码字段

读取 + 删除工具（8 个，v3.3.0+，解决 #26 #27）：

工具	描述
list_headers	枚举页眉部件及其类型（default/first/even）、section_id 和 has_watermark
get_header	读取文本 + 完整 XML + 水印结构
delete_header	移除类型化模型条目 + tempDir 文件 + Relationship + Content_Types Override
list_watermarks	扫描所有页眉中的 VML 水印形状——文本（PowerPlusWaterMarkObject）或图像（WordPictureWatermark，#209）
get_watermark	单个页眉的水印详情（无水印时返回 null）
list_footers	枚举页脚部件及其类型、section_id 和 has_page_number
get_footer	读取文本 + XML + 解析后的字段结构（PAGE / NUMPAGES / REF / STYLEREF）
delete_footer	与 delete_header 对称

偶数页/奇数页 + 分节关联（4 个，v3.11.0）：

工具	描述
enable_even_odd_headers	切换文档级 <w:evenAndOddHeaders/> 标志
link_section_header_to_previous	Word 兼容的克隆语义
unlink_section_header_from_previous	对称地取消关联
get_section_header_map	返回每个分节的页眉 / 页脚文件分配情况

主题编辑（4 个工具，v3.3.0+，解决 #28）

工具	描述
get_theme	从 word/theme/theme1.xml 读取主要/次要字体槽（latin/ea/cs）+ 配色方案（accent1-6、hyperlink、followedHyperlink）
update_theme_fonts	局部更新字体槽——例如 { minor: { ea: "DFKai-SB" } }，用于修复文档中的中文字体
update_theme_color	按槽名称更新十六进制颜色并进行验证（拒绝无效槽和非 6 位十六进制值）
set_theme	低级备用方案——原样替换 theme1.xml（验证 <a:theme> 根元素及 XML 格式正确）

图片（7 个工具）

工具	描述
insert_image	插入内嵌图片（PNG、JPEG）
insert_image_from_path	v2.0.0+ — 宽度和高度可选（通过 ImageDimensions.detect 自动保持纵横比），支持 into_table_cell 以及 after_text / before_text 锚点。支持 PNG/JPEG 和 PDF（通过原生 PDFKit/CoreGraphics 栅格化第 page 页，#16）
insert_floating_image	插入带文字环绕的浮动图片；relative_to_h / relative_to_v 用于设置锚点的参考点（#233）
update_image	更新图片属性
delete_image	删除图片
list_images	列出图片 — 文档正文及页眉/页脚中的图片均会标记 referenced: yes/orphan/unknown；标记结果基于与 save_document 一致性门禁相同的软件包扫描（#199，#219）
set_image_style	设置图片边框和效果

题注（5 个工具）

工具	描述
insert_caption	v2.0.0+ — 使用真正的 OOXML SEQ 字段（而非纯文本）。支持英文和中文标签（Figure/Table/Equation/圖/表/公式）、5 种锚点（paragraph_index / after_image_id / after_table_index / after_text / before_text），以及可选的 STYLEREF 章节编号前缀
list_captions	v3.1.0 — 枚举题注段落，包含 label / sequence_number / caption_text / paragraph_index
get_caption	v3.1.0 — 获取单个题注的详细信息，包括可选的 STYLEREF 章节编号 chapter_number
update_caption	v3.1.0 — 修改题注文本或标签，同时保留 SEQ 字段结构
delete_caption	v3.1.0 — 移除题注段落

公式（5 个工具）

工具	描述
insert_equation	v2.0.0+ — 通过 MathComponent AST（9 种类型）生成结构正确的 OMML。主要方式：components: 树；备用方式：latex: 子集（\frac、\sqrt、x^{y}、希腊字母、∑/∫/∏）
list_equations	v3.1.0 — 枚举 <m:oMath> 片段，并附带 display_mode 标记
get_equation	v3.1.0 — 获取单个公式的详细信息及组件摘要
update_equation	v3.1.0 — 替换目标公式的组件树
delete_equation	v3.1.0 — 移除公式片段或空段落

导出（5 个工具）

工具	描述
export_text	导出为纯文本
export_markdown	导出为 Markdown（使用内嵌的 word-to-md-swift）
export_revision_summary_markdown	v1.19.0 — 用于稿件审阅的逐文档修订时间线
compare_documents_markdown	v1.19.0 — 多文档累计修订时间线
export_comment_threads_markdown	v1.19.0 — 评论串及作者别名规范化

超链接和书签（10 个工具，v3.11.0+ 类型化变体 #50)

通用工具 + 书签（7 个）：

工具	描述
insert_hyperlink	插入外部超链接
insert_internal_link	插入指向书签的链接
insert_cross_reference	插入交叉引用
update_hyperlink	更新超链接
delete_hyperlink	删除超链接
insert_bookmark	插入书签
delete_bookmark	删除书签

类型化超链接（3 个，v3.11.0，自动创建 Hyperlink 字符样式）：

工具	描述
insert_url_hyperlink	外部 URL，可选提示文字和历史记录标记
insert_bookmark_hyperlink	内部锚点链接（w:anchor，无 rId）
insert_email_hyperlink	mailto:，可选经过 URL 编码的主题

评论与修订（13 个工具）

评论写入 + 读取（7）：

工具	描述
insert_comment	插入评论
update_comment	更新评论文本
delete_comment	删除评论
list_comments	列出所有评论
reply_to_comment	回复现有评论
resolve_comment	将评论标记为已解决
list_comment_threads	v3.4.0 — 使用 commentsExtended.xml 中类型化的 Comment.parentId 枚举评论线程（root_comment_id + 回复 + 已解决状态 + durable_id）

评论线程工具（2，v3.4.0+，解决 #29）：

工具	描述
get_comment_thread	读取根评论并遍历子评论，获取完整回复树
sync_extended_comments	报告用于三方同步规划的类型化评论数量

修订跟踪 — 接受/拒绝操作（7）：

工具	描述
enable_track_changes	启用修订跟踪（设置 revisions.settings.author，用于解析默认作者）
disable_track_changes	禁用修订跟踪
get_revisions	枚举所有修订（支持 Direct Mode）
accept_revision	按 ID 接受修订
reject_revision	按 ID 拒绝修订
accept_all_revisions	批量接受
reject_all_revisions	批量拒绝

修订跟踪 — 程序化写入操作（3，v3.12.0 #45）：

工具	描述
insert_text_as_revision	插入由 <w:ins> 修订标记包裹的文本。在 position 处分割跨越该位置的文本运行（保留之前和之后的文本及格式）。参数：doc_id、paragraph_index、position、text，以及可选的 author、date。
delete_text_as_revision	使用 <w:del> 标记 [start, end) 范围内的文本运行，并将 <w:t> 替换为 <w:delText>。仅限单个段落（不支持跨段落删除）。
move_text_as_revision	使用相邻的修订 ID 生成成对的 <w:moveFrom> / <w:moveTo>。不接受单段落内的移动（调用方应使用删除 + 插入）。

现有工具还新增 2 个扩展参数（增量添加，默认值为 false）：

• format_text 新增 as_revision: bool — 生成 <w:rPrChange> 修订，而非静默修改格式。还接受 run_index、author、date。
• set_paragraph_format 新增 as_revision: bool — 生成 <w:pPrChange> 修订。

副作用约定：as_revision: true 要求此前已调用 enable_track_changes。如果修订跟踪已禁用，则会抛出 track_changes_not_enabled，而不是静默自动启用。作者解析链：显式的非空 author 参数 → revisions.settings.author → 字面值 "Unknown"。

人员 — 评论作者（4 个工具，v3.4.0+，解决 #30）

工具	描述
list_people	解析 word/people.xml 中的 <w15:person> 条目
add_person	添加新条目；若 people.xml 不存在则自动创建该部件；重名时添加 _2 后缀
update_person	更新 display_name（替换 author 属性）
delete_person	移除条目；报告 comments_orphaned 数量

脚注与尾注（10 个工具）

写入 + 删除（4）：

工具	描述
insert_footnote	插入脚注
delete_footnote	删除脚注
insert_endnote	插入尾注
delete_endnote	删除尾注

列表 + 读取 + 更新（6，v3.4.0+，解决 #24 #25）：

工具	描述
list_footnotes	支持 Direct Mode
list_endnotes	支持 Direct Mode
get_footnote	按整数 ID 读取文本 + 文本运行
update_footnote	原位替换文本，保留 footnote_id（交叉引用仍有效）
get_endnote	按整数 ID 读取文本 + 文本运行
update_endnote	原位替换文本，保留 endnote_id

Web 设置（2 个工具，v3.4.0+，关闭 #31）

工具	描述
get_web_settings	解析 word/webSettings.xml 中的标志元素（relyOnVML、optimizeForBrowser、allowPNG、doNotSaveAsSingleFile）；缺少时返回 { error: "no webSettings part" }
update_web_settings	按键进行部分更新；如果部分不存在则自动创建

域代码（7 个工具）

工具	描述
insert_if_field	插入 IF 条件域
insert_calculation_field	插入计算域（SUM、AVERAGE 等）
insert_date_field	插入日期/时间域
insert_page_field	插入页码域
insert_merge_field	插入邮件合并域
insert_sequence_field	插入自动编号序列
update_all_fields	v3.1.0 — 等效于按下 F9，可在正文、页眉、页脚、脚注和尾注中重新计数 SEQ。支持章节重置：当 pStyle=="Heading N" 与 SEQ 的 resetLevel 匹配时触发

内容控件 / SDT（10 个工具，v3.9.0+ 完整读写 #44）

插入和表单辅助工具（5 个）：

工具	描述
insert_content_control	区分 12 种类型（richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection（不接受——请使用 insert_repeating_section）/ repeatingSectionItem）。可选参数：list_items（dropDown/comboBox 必需）、date_format、lock_type。
insert_repeating_section	插入重复节（Word 2012+）；接受 allow_insert_delete_sections: bool（默认为 true）
insert_checkbox	插入复选框 SDT
insert_dropdown	插入下拉列表 SDT
insert_text_field	插入纯文本 SDT

读取工具（3 个）：

工具	描述
list_content_controls	枚举所有 SDT，支持扁平模式（默认）或嵌套树模式（支持直接模式）
get_content_control	按 id、tag 或 alias 获取单个 SDT。返回完整元数据和 <w:sdtContent> XML。会显示 not_found / multiple_matches 错误。
list_repeating_section_items	按文档顺序枚举重复节 SDT 中的项目

修改工具（4 个）：

工具	描述
update_content_control_text	替换 plainText / richText / date / bibliography / citation SDT 的文本内容。保持 <w:sdtPr> 字节级不变。picture / dropdown / combo / checkbox / group / repeatingSection 类型会返回 unsupported_type。
replace_content_control_content	使用白名单验证替换整个 <w:sdtContent> XML（拒绝包含 <w:sdt>、<w:body>、<w:sectPr> 或 XML 声明的输入）
delete_content_control	移除 SDT，可选择取消包裹子元素（keep_content: true 为默认值）
update_repeating_section_item	按索引替换单个项目的文本（索引无效时返回 out_of_bounds）

SDT id 使用确定性的最大值加 1 分配（v3.9.0 之前为随机分配）。list_custom_xml_parts 提供空列表桩以保持向前兼容（实际实现位于 che-word-mcp-customxml-databinding Change B）。

高级功能（10 个工具）

工具	描述
insert_toc	插入目录
insert_table_of_figures	插入图表目录
insert_index, insert_index_entry	生成索引
set_paragraph_border	设置段落边框
set_paragraph_shading	设置段落背景颜色
set_character_spacing	设置字符间距
set_text_effect	设置文本动画效果
insert_horizontal_line, insert_drop_cap, insert_symbol	装饰元素

注意：以上计数涵盖主要工具类别。截至 v3.13.5，工具总数为 233 个，包括文档比较、修订（读取 + 通过 <w:ins> / <w:del> / <w:moveFrom> / <w:moveTo> / <w:rPrChange> / <w:pPrChange> 进行程序化写入）、内容控件（12 种类型的 SDT 判别）、域代码、主题编辑、页眉/页脚 CRUD + 水印读取（尚未实现写入，#201/#208），支持奇偶页 + 分节链接、批注线程 + 人员（双重身份）、更新注释、Web 设置、样式（继承 + 链接 + 潜在样式 + 别名）、编号（完整定义生命周期）、分节（垂直对齐 + 页码格式 + 独立首页 + 每节引用）、表格（条件 / 嵌套 / 布局 / 缩进）、超链接（类型化 URL / 书签 / 电子邮件）以及格式辅助工具（带有 as_revision 标记）。运行服务并调用 tools/list，即可获取完整且权威的工具列表。

使用示例

创建包含标题和文本的文档

Create a new Word document called "report" with:
- Title: "Quarterly Report"
- Heading: "Introduction"
- A paragraph explaining the report purpose
Save it to ~/Documents/report.docx

创建包含表格和图像的文档

Create a document with:
- A title "Product Catalog"
- Insert an image from ~/images/logo.png
- A 4x3 table with product information
- Apply borders to the table
Save it to ~/Documents/catalog.docx

创建专业报告

Create a document with:
- Custom page margins (1 inch all around)
- A header with company name
- A footer with page numbers
- Table of contents
- Multiple sections with headings
- Footnotes for references
Save it as ~/Documents/annual_report.docx

技术细节

OOXML 结构

该服务会生成结构完整且有效的 Office Open XML 文档：

document.docx (ZIP)
├── [Content_Types].xml
├── _rels/
│   └── .rels
├── word/
│   ├── document.xml      # Main content
│   ├── styles.xml        # Style definitions
│   ├── settings.xml      # Document settings
│   ├── fontTable.xml     # Font definitions
│   ├── numbering.xml     # List definitions
│   ├── comments.xml      # Comments
│   ├── footnotes.xml     # Footnotes
│   ├── endnotes.xml      # Endnotes
│   ├── header1.xml       # Header content
│   ├── footer1.xml       # Footer content
│   ├── media/            # Embedded images
│   │   └── image*.{png,jpeg}
│   └── _rels/
│       └── document.xml.rels
└── docProps/
    ├── core.xml          # Metadata
    └── app.xml           # Application info

依赖项

• MCP Swift SDK（v0.12.0+）— Model Context Protocol 实现
• ooxml-swift（v0.12.0+）— OOXML 解析 + 默认保留的往返架构（PreservedArchive、RelationshipIdAllocator、ContentTypesOverlay）、FieldParser、OMMLParser、updateAllFields()、MathAccent
• latex-math-swift（v0.1.0+）— LaTeX 子集 → OMML MathComponent AST 解析器（由 insert_equation v3.2.0+ 使用）
• markdown-swift（v0.2.0+）— Markdown 生成
• word-to-md-swift（v0.4.0+）— Word 转 Markdown

开发者说明 — 真实场景样例测试

Tests/CheWordMCPTests/RealWorldDocxRoundTripSmokeTests.swift 使用真实 Word 输出（例如学术论文、合同），而非合成样例，验证 ooxml-swift Reader / Writer 配对。将机密 .docx 文件放入 test-files/（已添加到 gitignore，不会进入版本控制），然后：

cd mcp/che-word-mcp
swift test --filter RealWorldDocxRoundTripSmokeTests

每个样例的断言包括：xmllint --noout 检查通过，书签 / 超链接 / fldSimple / AlternateContent 数量一致，拼接后的 <w:t> 内容的 SHA256 值匹配。如果 test-files/ 为空，测试会静默执行 XCTSkip，因此干净克隆 / CI 不会误报失败。此测试与 PsychQuant/macdoc#81 中的 .note 冒烟测试模式相同。

与其他解决方案的比较

功能	Anthropic Word MCP	python-docx	docx npm	che-word-mcp
语言	Node.js	Python	Node.js	Swift
后端	AppleScript	OOXML	OOXML	OOXML
是否需要 Word	是	否	否	否
运行时	Node.js	Python	Node.js	无
单一二进制文件	否	否	否	是
工具数量	~10	N/A	N/A	233
图像	有限	是	是	是
批注	否	有限	有限	是
修订	否	否	否	是
目录	否	有限	否	是
表单域	否	否	否	是

性能

Apple Silicon（M4 Max，128GB RAM）上的基准测试：

读取性能

文件大小	耗时
40 KB（文档大纲）	72 ms
431 KB（复杂文档）	31 ms

写入性能

操作	内容	耗时
基本写入	创建 + 3 个段落 + 保存	19 ms
复杂文档	标题 + 段落 + 表格 + 列表	21 ms
批量写入	50 个段落 + 保存	28 ms

为什么这么快？

• 原生 Swift 二进制程序 - 无解释器启动开销
• 直接操作 OOXML - 无需启动 Microsoft Word 进程
• 高效的 ZIP 处理 - 使用 ZIPFoundation 进行压缩
• 内存中操作 - 仅在保存时写入磁盘

与 python-docx（启动约需 200ms）或 docx npm（启动约需 150ms）相比，che-word-mcp 的速度快 10-20 倍。

许可证

MIT 许可证

作者

Che Cheng（@PsychQuant）

贡献者

• @ildunari — 会话状态管理（v1.17.0）

相关项目

• che-apple-mail-mcp - Apple Mail MCP 服务
• che-ical-mcp - macOS Calendar MCP 服务