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

• Pure Swift Implementation: No Node.js, Python, or external runtime required
• Direct OOXML Manipulation: Works directly with XML, no Microsoft Word installation needed
• Single Binary: Just one executable file
• 234 MCP Tools: Comprehensive document manipulation across documents, tables, hyperlinks, headers, sections, styles, numbering, content controls, comments, footnotes, equations, fields, and Track Changes
• Office.js OOXML Roadmap P0 = 100%: All eight P0 sub-issues closed (umbrella #43). Surface coverage is now competitive with Office.js for the read/write side of every P0 capability.
• Round-trip silent corruption closed (v3.13.5, #56): 5 sub-stack-completion rounds (R5 / R5-CONT / R5-CONT-2 / R5-CONT-3 / R5-CONT-4) closed 30 findings (16 P0 + 21 P1) across rounds 4-8 of 6-AI cross-verification. Bumps ooxml-swift to v0.19.5 (v0.19.4 held back per verify-gate). No MCP source changes — fix architecture lives entirely in ooxml-swift. Round 4 walker symmetry across headers/footers/footnotes/endnotes (accept_revision / reject_revision / get_hyperlinks / replace_text reach all parts). Round 5 per-container relationships round-trip (update_hyperlink URL sync targets owning part rels). Round 6 delete_hyperlink mirror + container <w:tbl> capture preserved. Round 7 reject_revision typed clearMarker (file/API state convergence). Round 8 accept_revision typed clearMarker (mirror) + matrix-pin asymmetry-guard removal + Document.repairContainerFileNames marks document.xml.rels + [Content_Types].xml dirty. Convergence: Devil's Advocate wrote 5 adversarial tests targeting the convergence-cycle pattern; all PASSED. See closing summary and v3.13.5 release notes.
• Programmatic Track Changes (v3.12.0+, #45): Generate Word-native reviewable redlines via insert_text_as_revision / delete_text_as_revision / move_text_as_revision, plus as_revision: true flag on format_text / set_paragraph_format. Emits <w:ins> / <w:del> / <w:moveFrom> / <w:moveTo> / <w:rPrChange> / <w:pPrChange> markup. Side-effect contract: as_revision: true requires track changes enabled; throws track_changes_not_enabled otherwise (no silent auto-enable). Author resolution: explicit arg → revisions.settings.author → "Unknown".
• Tables / Hyperlinks / Headers extensions (v3.11.0+, #49 #50 #51): 16 new tools — table conditional styles (10 region types) / nested tables (max 5 deep) / explicit layout / table indent; three typed hyperlinks (URL / bookmark / email); even/odd header toggle / link-to-previous / get_section_header_map.
• Styles + Numbering + Sections foundation (v3.10.0+, #46 #47 #48): 19 new tools + 6 extended args — get_style_inheritance_chain, link_styles, set_latent_styles, add_style_name_alias, full Numbering CRUD lifecycle (definitions / overrides / list continuity / GC), section vertical alignment / page-number format / break-type / title-page distinction / per-section header references.
• Content Controls (SDT) read/write (v3.9.0+, #44): 7 new tools covering 12-type discrimination (richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection / repeatingSectionItem). Nested SDT trees, deterministic max+1 SDT id allocator, keep_content unwrap on delete, whitelist-validated XML replacement.
• Save Durability Stack (v3.5.3+): atomic-rename save (#36), actor-based concurrency safety (#39), keep_bak opt-in rollback (#38), autosave_every Design B pre-mutation snapshot with explicit recover_from_autosave (#37, #40 v3.7.0). Default autosave_every: 1 (every mutation snapshots prior state). Pass autosave_every: 0 to opt out.
• Dual-Mode Access: Direct Mode (read-only, one step via source_path) and Session Mode (full lifecycle via doc_id)
• True Byte-preservation Round-trip Fidelity (v3.5.0+): save_document overlay mode uses WordDocument.modifiedParts dirty tracking — untouched typed parts (document.xml, styles.xml, fontTable.xml, header*.xml, footer*.xml, comments.xml, footnotes.xml, endnotes.xml) and unknown parts (theme/, webSettings.xml, people.xml, commentsExtended/Extensible/Ids, glossary/, customXml/) byte-for-byte preserved. NTPU thesis no-op save_document round-trip retains 13 fontTable entries + 6 distinct headers + 4 footers + three-segment PAGE field + <w15:presenceInfo> identity.
• Theme + Header/Footer/Watermark CRUD (v3.3.0+): word/theme/theme1.xml editing, header/footer enumeration + deletion, watermark VML detection. NTPU thesis Chinese font fix path: update_theme_fonts({ minor: { ea: "DFKai-SB" } }).
• Comment Threads + People + Notes Update + Web Settings (v3.4.0+): 13 tools for collaborative comment metadata, people.xml author records (dual identity: GUID + legacy author), in-place endnote/footnote editing (preserves IDs), webSettings.xml configuration.
• Full LaTeX Subset for insert_equation (v3.2.0+): Delegated to latex-math-swift. Supports \frac, \sqrt, \hat/\bar/\tilde accents, \left/\right delimiters, \sum/\int/\prod n-ary with bounds, function names, limits, \text{}, all Greek letters (including \varepsilon variants), and common operators.
• Text-Anchor Insertion: Insert captions / images relative to matched text (after_text / before_text), no pre-search call required
• Batch Operations: replace_text_batch / search_text_batch collapse N round-trips into one
• Session State API: SHA256 + mtime-based disk drift detection, revert_to_disk / reload_from_disk / check_disk_drift
• Structural Readback: list_captions / list_equations / update_all_fields (F9-equivalent) for manuscript review workflows
• Cross-platform: Works on macOS (universal binary x86_64 + arm64 since v3.5.1)

Version History

Quick Start

For Claude Desktop

Option A: MCPB One-Click Install (Recommended)

Download the latest .mcpb file from Releases and double-click to install.

Option B: Manual Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

For Claude Code (CLI)

Option A: Install as Plugin (Recommended)

The plugin bundles a version-aware wrapper that auto-downloads the binary on first use (and re-downloads whenever the plugin itself is updated — no swift build needed).

Two steps — register the marketplace once, then install the plugin:

# 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

Inside Claude Code? The slash-command equivalents /plugin marketplace add PsychQuant/psychquant-claude-plugins and /plugin install che-word-mcp@psychquant-claude-plugins work the same way.

Note: The plugin wraps the MCP binary with auto-download. If the binary is missing from ~/bin/CheWordMCP (or the sidecar ~/bin/.CheWordMCP.version is older than the plugin's pinned version), it will be downloaded from GitHub Releases on next invocation.

Option B: Install as standalone MCP

If you only need the MCP server without plugin features (slash commands, skills, SessionStart hooks):

# 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

💡 Tip: Install the binary into a local directory like ~/bin/. Avoid cloud-synced folders (Dropbox, iCloud, OneDrive) — their sync operations can break MCP connections.

Build from Source (Optional)

Use this only if you want to track main or contribute patches.

Prerequisites

• macOS 13.0+ (Ventura or later)
• 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/

Crash fuzzing (scripts/fuzz-extreme-params.py)

Sends extreme values (Int.max, Int.min, 2^62, 2^31, -1, 1e300, -1e300) to every integer/number parameter declared in tools/list, against a REAL compiled binary over stdio (MCP JSON-RPC) — one fresh server process per probe, so a crash in one probe can't take the whole run down. Found 58 crashes before #234's first round of fixes, and 5 more (within that same issue's own broadened audit criterion) that a manual grep-based audit had missed — see the issue for the full history. Run it whenever a new tool or a new integer/number parameter is added, and before any release that touches integer/number parameter handling in 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

Exit code is 0 only when there is no crash or hang (including the save that follows every probe), every "(must reject)" probe was rejected, the resident memory at the end of the largest-legal-table probe stays under a ceiling (end of probe, not peak), and at least 97% of the schema's integer/number parameters were judged reached — a probe stopped by an unrelated precondition proves nothing, so a fuzzer that stops reaching its targets fails instead of reporting zero crashes. The reach judgement currently overestimates: on 4.4.0 it counted 241/245, while an independent audit found about 227/245 actually reached (fix tracked in #239). A summary line, a coverage line (with the unreached parameters) and a per-probe TSV (<workdir>/fuzz_results.tsv) are always produced. It's also wired into swift test behind an opt-in gate (not run by default — about 1,300 subprocesses and a compiled binary; with RUN_FUZZ=1 set, a missing or out-of-date binary fails the gate):

RUN_FUZZ=1 swift test --filter FuzzExtremeParamsGateTests

Two Modes of Operation

Direct Mode (source_path) — Read-only, no state

Pass a file path directly. No need to call open_document first. Best for quick inspection.

# 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 tools support Direct Mode:

Session Mode (doc_id) — Full read/write lifecycle

Call open_document first, then use doc_id for all subsequent operations. Required for editing.

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" }

Dual-mode tools accept both source_path and doc_id. If you already have a document open, use doc_id to avoid re-reading from disk.

Usage with AI Agents

Just ask the agent

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

The agent will automatically use Direct Mode (no need to open/close).

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 Skill

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

Available Tools (234 Total)

Paragraph Index Conventions

paragraph_index / index are historical parameter names and do not always count the same OOXML surface. Different insert / mutate / readback tools use different conventions — there is no universal default to assume. Three coordinate systems coexist: body.children insertion index (used by some inserts), top-level paragraph ordinal (used by most mutate operations and inline equation insertion), and get_paragraphs readback order (for inspection). See docs/paragraph-index-conventions.md for the per-tool inventory before reusing an index across tools.

Document Management (6 tools)

Session State API (5 tools, v3.0.0+)

Content Operations (9 tools)

Formatting (3 tools)

Tables (15 tools, v3.11.0+ extensions #49)

Core (6):

Row / column / cell (8):

Advanced (5, v3.11.0):

Style Management (8 tools + 6 extended args, v3.10.0+ #48)

Core (4):

Inheritance + linkage (4, v3.10.0):

Numbering / Lists (12 tools, v3.10.0+ definition lifecycle #46)

Inline list creation (4):

Definition CRUD (8, v3.10.0):

Sections / Page Setup (12 tools, v3.10.0+ extensions #47)

Basic page setup (5):

Section properties (7, v3.10.0):

Headers & Footers (17 tools, v3.11.0+ even/odd + section map #51)

Write tools (5):

Read + delete tools (8, v3.3.0+, closes #26 #27):

Even/odd + section linkage (4, v3.11.0):

Theme Editing (4 tools, v3.3.0+, closes #28)

Images (7 tools)

Captions (5 tools)

Equations (5 tools)

Export (5 tools)

Hyperlinks & Bookmarks (10 tools, v3.11.0+ typed variants #50)

Generic + bookmarks (7):

Typed hyperlinks (3, v3.11.0, auto-create Hyperlink character style):

Comments & Revisions (13 tools)

Comment write + read (7):

Comment thread tools (2, v3.4.0+, closes #29):

Revision tracking — accept/reject side (7):

Revision tracking — programmatic write side (3, v3.12.0 #45):

Plus 2 extended args on existing tools (additive, default false):

• format_text gains as_revision: bool — produces <w:rPrChange> revision instead of silent format mutation. Also accepts run_index, author, date.
• set_paragraph_format gains as_revision: bool — produces <w:pPrChange> revision.

Side-effect contract: as_revision: true requires enable_track_changes to have been called. Disabled track changes throws track_changes_not_enabled instead of silent auto-enable. Author resolution chain: explicit non-empty author arg → revisions.settings.author → literal "Unknown".

People — Comment Authors (4 tools, v3.4.0+, closes #30)

Footnotes & Endnotes (10 tools)

Write + delete (4):

List + read + update (6, v3.4.0+, closes #24 #25):

Web Settings (2 tools, v3.4.0+, closes #31)

Field Codes (7 tools)

Content Controls / SDT (10 tools, v3.9.0+ full read/write #44)

Insert + form helpers (5):

Read tools (3):

Modify tools (4):

SDT id allocation uses deterministic max+1 (was random in pre-v3.9.0). list_custom_xml_parts ships as empty-list stub for forward compat (real impl in che-word-mcp-customxml-databinding Change B).

Advanced Features (10 tools)

Note: The counts above cover key tool categories. Total surface is 233 tools as of v3.13.5 including Document Comparison, Track Changes (read + programmatic write side via <w:ins> / <w:del> / <w:moveFrom> / <w:moveTo> / <w:rPrChange> / <w:pPrChange>), Content Controls (12-type SDT discrimination), Field Codes, Theme Editing, Header/Footer/Watermark CRUD with even/odd + section linkage, Comment Threads + People (dual identity), Notes Update, Web Settings, Styles (inheritance + linkage + latent + alias), Numbering (full definition lifecycle), Sections (vertical alignment + page-number format + title-page distinct + per-section refs), Tables (conditional / nested / layout / indent), Hyperlinks (typed url/bookmark/email), and Formatting helpers (with as_revision flag). Run the server and call tools/list for the complete, authoritative set.

Usage Examples

Create a Document with Headings and Text

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 Table and Images

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 Professional Report

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

Technical Details

OOXML Structure

The server generates valid Office Open XML documents with complete structure:

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

Dependencies

• MCP Swift SDK (v0.12.0+) — Model Context Protocol implementation
• ooxml-swift (v0.12.0+) — OOXML parsing + preserve-by-default round-trip architecture (PreservedArchive, RelationshipIdAllocator, ContentTypesOverlay), FieldParser, OMMLParser, updateAllFields(), MathAccent
• latex-math-swift (v0.1.0+) — LaTeX subset → OMML MathComponent AST parser (used by insert_equation v3.2.0+)
• markdown-swift (v0.2.0+) — Markdown generation
• word-to-md-swift (v0.4.0+) — Word to Markdown conversion

Developer Notes — Real-World Fixture Testing

Tests/CheWordMCPTests/RealWorldDocxRoundTripSmokeTests.swift validates the ooxml-swift Reader / Writer pair against real-world Word output (e.g., academic theses, contracts) rather than synthesized fixtures. Drop confidential .docx files into test-files/ (gitignored — they never reach version control), then:

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

Per-fixture assertions: xmllint --noout clean, bookmark / hyperlink / fldSimple / AlternateContent count parity, SHA256 of concatenated <w:t> content matches. The test silently XCTSkips when test-files/ is empty so clean clones / CI do not false-fail. Mirrors the .note smoke pattern from PsychQuant/macdoc#81.

Comparison with Other Solutions

Performance

Benchmarks on Apple Silicon (M4 Max, 128GB RAM):

Read Performance

Write Performance

Why So Fast?

• Native Swift binary - No interpreter startup overhead
• Direct OOXML manipulation - No Microsoft Word process
• Efficient ZIP handling - ZIPFoundation for compression
• In-memory operations - Only writes to disk on save

Compared to python-docx (~200ms startup) or docx npm (~150ms startup), che-word-mcp is 10-20x faster.

License

MIT License

Author

Che Cheng (@PsychQuant)

Contributors

• @ildunari — session state management (v1.17.0)

Related Projects

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