Skip to main content
Glama
README.md
# 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.

[中文說明](README_zh-TW.md)

## 文件格式 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
- **248 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](https://github.com/PsychQuant/che-word-mcp/issues/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](https://github.com/PsychQuant/che-word-mcp/issues/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](https://github.com/PsychQuant/che-word-mcp/issues/56#issuecomment-4322638865) and [v3.13.5 release notes](https://github.com/PsychQuant/che-word-mcp/releases/tag/v3.13.5).
- **Programmatic Track Changes (v3.12.0+, [#45](https://github.com/PsychQuant/che-word-mcp/issues/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](https://github.com/PsychQuant/che-word-mcp/issues/49) [#50](https://github.com/PsychQuant/che-word-mcp/issues/50) [#51](https://github.com/PsychQuant/che-word-mcp/issues/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](https://github.com/PsychQuant/che-word-mcp/issues/46) [#47](https://github.com/PsychQuant/che-word-mcp/issues/47) [#48](https://github.com/PsychQuant/che-word-mcp/issues/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](https://github.com/PsychQuant/che-word-mcp/issues/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](https://github.com/PsychQuant/che-word-mcp/issues/36)), actor-based concurrency safety ([#39](https://github.com/PsychQuant/che-word-mcp/issues/39)), `keep_bak` opt-in rollback ([#38](https://github.com/PsychQuant/che-word-mcp/issues/38)), `autosave_every` Design B pre-mutation snapshot with explicit `recover_from_autosave` ([#37](https://github.com/PsychQuant/che-word-mcp/issues/37), [#40](https://github.com/PsychQuant/che-word-mcp/issues/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. document 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 CRUD + Watermark read/write (v3.3.0+, write-side [#208](https://github.com/PsychQuant/che-word-mcp/issues/208))**: `word/theme/theme1.xml` editing, header/footer enumeration + deletion, watermark VML detection (`list_watermarks` / `get_watermark` — recognises both the `PowerPlusWaterMarkObject` text fingerprint and Word's own `WordPictureWatermark` image fingerprint, [#209](https://github.com/PsychQuant/che-word-mcp/issues/209)) and real writes (`insert_watermark` / `insert_image_watermark` / `remove_watermark` — VML `<w:pict>` shapes into every header part; image watermarks need a document opened from an existing `.docx`). document 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`](https://github.com/PsychQuant/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

Release notes for every version are in [CHANGELOG.md](CHANGELOG.md).

## Quick Start

### For Claude Desktop

#### Option A: MCPB One-Click Install (Recommended)

Download the latest `.mcpb` file from [Releases](https://github.com/PsychQuant/che-word-mcp/releases) and double-click to install.

#### Option B: Manual Configuration

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

```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:

```bash
# 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):

```bash
# 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+

```bash
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](https://github.com/PsychQuant/che-word-mcp/issues/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`:

```bash
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
**peak** resident memory during the largest-legal-table probe (sampled
throughout the sequence, not read once when it finishes — #239) stays
under a ceiling, and at least `FUZZ_MIN_COVERAGE` (default **0.80**, down
from 0.97 — see below) 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. "Reached" requires positive evidence (the response
names the parameter or echoes its value, or is an index/not-found error
addressed at it); a bare successful response is no longer enough by itself
([#239](https://github.com/PsychQuant/che-word-mcp/issues/239) — the old
criterion counted 241/245 on 4.4.0 while an independent audit found about
227/245 actually reached). The honest criterion measures lower coverage
than the old one ever did (~85% against the current, larger parameter
set), which is why the default moved from 0.97 to 0.80: 0.97 was
calibrated against the over-counting criterion and was never really met
once measured honestly. 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):

```bash
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:**

| Category | Tools |
|----------|-------|
| Read content | `get_text`, `get_document_text`, `get_paragraphs`, `get_document_info`, `search_text` |
| List elements | `list_images`, `list_styles`, `get_tables`, `list_comments`, `list_hyperlinks`, `list_bookmarks`, `list_footnotes`, `list_endnotes`, `get_revisions` |
| Properties | `get_document_properties`, `get_section_properties`, `get_word_count_by_section`, `estimate_paragraph_for_page` |
| Export | `export_markdown` |

### 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.

### File-to-file form tools (`source_path` → `output_path`)

`classify_form` and `apply_form` (#300) tidy a filled-in form with ooxml-swift's DocxForm, the library behind `macdoc word form classify|apply`. They take paths only, never `doc_id`: DocxForm edits the named elements of `word/document.xml` as strings and copies every other part byte for byte, so the document never goes through the typed model a session holds. They read the file on disk, so save a session's edits before calling them.

```
classify_form: { "source_path": "/path/to/form.docx", "include_grid": true }
apply_form: { "source_path": "/path/to/form.docx", "output_path": "/path/to/tidy.docx",
              "fields": ["1A2B3C4D"], "table_defaults": [{ "anchor": "1A2B3C4E", "columns": [{ "from": 2 }] }] }
```

## 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

```markdown
## 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

```bash
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 (248 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](docs/paragraph-index-conventions.md)
for the per-tool inventory before reusing an index across tools.

### Document Management (6 tools)

| Tool | Description |
|------|-------------|
| `create_document` | Create a new Word document |
| `open_document` | Open an existing .docx file (track_changes default `false` since v3.0.0) |
| `save_document` | Save document to .docx file |
| `close_document` | Close an open document (pass `discard_changes: true` to drop dirty edits) |
| `finalize_document` | Save and close in one guarded step |
| `list_open_documents` | List all open documents |

### Document Info & Properties (4 tools)

| Tool | Description |
|------|-------------|
| `get_document_info` | Paragraph, word and image counts (images counted by their references in body, headers and footers; Direct Mode) |
| `get_document_properties` | Read core properties: title, author, dates (Direct Mode) |
| `set_document_properties` | Set core properties: title, author, subject, keywords |
| `get_word_count_by_section` | Word count per section, with a custom separator (e.g. References) and excluded sections (Direct Mode) |

### Session State API (7 tools, v3.0.0+)

| Tool | Description |
|------|-------------|
| `get_session_state` | Snapshot `{ source_path, disk_hash_hex, disk_mtime_iso8601, is_dirty, track_changes_enabled }` |
| `get_document_session_state` | Legacy session snapshot (preserved for backward compat) |
| `revert_to_disk` | Re-read source path, discard in-memory edits (destructive-by-design) |
| `reload_from_disk` | Cooperative reload; requires `force: true` on dirty doc |
| `check_disk_drift` | Informational — returns `{ drifted, disk_mtime, stored_mtime, disk_hash_matches }` |
| `checkpoint` | Write the in-memory session to `<source>.autosave.docx` (or a given `path`) without clearing the dirty flag |
| `recover_from_autosave` | Restore the session from `<source>.autosave.docx`; a dirty session needs `discard_changes: true` |

### Content Operations (12 tools)

| Tool | Description |
|------|-------------|
| `get_text` | Get plain text content |
| `get_paragraphs` | Get all paragraphs with formatting |
| `get_document_text` | Full plain text of a .docx (alias of `get_text`; Direct Mode) |
| `get_paragraph_runs` | Runs of one paragraph with their formatting (colour, bold, italic, …) |
| `get_text_with_formatting` | Document text with formatting written as Markdown marks (`**bold**`, `*italic*`, `{{color:red}}`) |
| `estimate_paragraph_for_page` | **v3.18.0+** — estimate a Word UI page number to a `get_paragraphs` candidate range (heuristic JSON with confidence + warning). See [docs/estimate-paragraph-for-page.md](docs/estimate-paragraph-for-page.md) for the `chars_per_page` derivation formula, confidence-tier table, and known limitations. |
| `insert_paragraph` | Insert a new paragraph |
| `insert_text` | Insert text at a position inside a paragraph |
| `update_paragraph` | Update paragraph content |
| `delete_paragraph` | Delete a paragraph |
| `replace_text` | Cross-run-safe find & replace with `scope` (body\|all) + `regex` + `$1..$N` backreferences |
| `replace_text_batch` | **v2.2.0** — sequential N-replacement batch, single save at end, `dry_run` / `stop_on_first_failure` |

### Search (5 tools)

| Tool | Description |
|------|-------------|
| `search_text` | Find text and return every match position, nested tables included (Direct Mode) |
| `search_text_batch` | **v2.2.0** — aggregated multi-query search, works in Direct + Session Mode |
| `search_text_with_formatting` | Find text and return each match with its formatting marks |
| `search_by_formatting` | Find text that carries a given format (e.g. red, bold) |
| `list_all_formatted_text` | List all text with one format (`format_type`: italic, bold, underline, color, highlight, strikethrough) |

### Formatting (4 tools)

| Tool | Description |
|------|-------------|
| `format_text` | Apply text formatting (bold, italic, color, font) |
| `set_paragraph_format` | Set paragraph formatting (alignment, spacing) |
| `apply_style` | Apply built-in or custom styles |
| `set_language` | Set the proofing language of text (spell check) — not implemented: reports success but writes nothing |

### Paragraph Layout (6 tools)

| Tool | Description |
|------|-------------|
| `set_keep_with_next` | Keep the paragraph on the same page as the next one |
| `set_keep_lines` | Keep all lines of the paragraph on one page |
| `set_page_break_before` | Start the paragraph on a new page |
| `set_widow_orphan` | Widow and orphan control |
| `insert_tab_stop` | Add a tab stop to a paragraph |
| `clear_tab_stops` | Remove all tab stops from a paragraph |

### Tables (21 tools, **v3.11.0+ extensions** [#49](https://github.com/PsychQuant/che-word-mcp/issues/49))

Core (6):
| Tool | Description |
|------|-------------|
| `insert_table` | Insert a table with optional data |
| `get_tables` | Get all tables information |
| `update_cell` | Update cell content |
| `delete_table` | Delete a table |
| `merge_cells` | Merge cells horizontally or vertically |
| `set_table_style` | Set table borders and shading |

Row / column / cell (10):
| Tool | Description |
|------|-------------|
| `add_row_to_table` | Add a row |
| `delete_row_from_table` | Delete a row |
| `add_column_to_table` | Add a column |
| `delete_column_from_table` | Delete a column |
| `set_cell_width` | Set cell width |
| `set_cell_vertical_alignment` | Set cell vertical alignment — not implemented: reports success but writes nothing |
| `set_row_height` | Set row height |
| `set_table_alignment` | Set table alignment — not implemented: reports success but writes nothing |
| `get_cell_paragraphs` | Paragraphs inside a table cell with their `paragraph_index` (Direct Mode), for addressing `update_cell_paragraph` |
| `update_cell_paragraph` | Rewrite the text of one paragraph inside a cell; the cell's other paragraphs stay as they are |

Advanced (5, **v3.11.0**):
| Tool | Description |
|------|-------------|
| `set_table_conditional_style` | Apply firstRow / lastRow / bandedRows etc. (10 region types) via `<w:tblStylePr>` |
| `insert_nested_table` | Insert table-in-cell, depth-limited to 5 (throws `nested_too_deep`) |
| `set_table_layout` | Switch fixed / autofit |
| `set_header_row` | Mark row as `<w:tblHeader/>` for repeat-on-page-break |
| `set_table_indent` | Table-level left indent (`<w:tblInd>`) |

### Style Management (8 tools + 6 extended args, **v3.10.0+** [#48](https://github.com/PsychQuant/che-word-mcp/issues/48))

Core (4):
| Tool | Description |
|------|-------------|
| `list_styles` | List all available styles (Direct Mode supported) |
| `create_style` | Create custom style — extended with 6 v3.10 args: `based_on`, `linked_style_id`, `next_style_id`, `q_format`, `hidden`, `semi_hidden` |
| `update_style` | Update style definition — same 6 extended args |
| `delete_style` | Delete custom style |

Inheritance + linkage (4, **v3.10.0**):
| Tool | Description |
|------|-------------|
| `get_style_inheritance_chain` | Traverse `basedOn` chain upward to root with cycle detection |
| `link_styles` | Bidirectional `<w:link>` between paragraph and character style pair |
| `set_latent_styles` | Control Quick Style Gallery defaults via `<w:latentStyles>` block |
| `add_style_name_alias` | Localized `<w:name>` alias per BCP 47 lang code |

### Numbering / Lists (12 tools, **v3.10.0+ definition lifecycle** [#46](https://github.com/PsychQuant/che-word-mcp/issues/46))

Inline list creation (4):
| Tool | Description |
|------|-------------|
| `insert_bullet_list` | Insert bullet list |
| `insert_numbered_list` | Insert numbered list |
| `set_list_level` | Set list indentation level |
| `set_outline_level` | Set paragraph outline level (TOC inclusion) |

Definition CRUD (8, **v3.10.0**):
| Tool | Description |
|------|-------------|
| `list_numbering_definitions` | Enumerate every abstractNum + num pair |
| `get_numbering_definition` | Fetch single num by id |
| `create_numbering_definition` | New abstractNum + paired num (max 9 levels) |
| `override_numbering_level` | `<w:lvlOverride>` for per-level start values |
| `assign_numbering_to_paragraph` | `<w:numPr>` attachment by paragraph index |
| `continue_list` | Resume numbering across paragraphs |
| `start_new_list` | Reset numbering to start |
| `gc_orphan_numbering` | Sweep unreferenced num definitions (abstractNums preserved) |

### Sections / Page Setup (19 tools, **v3.10.0+ extensions** [#47](https://github.com/PsychQuant/che-word-mcp/issues/47))

Basic page setup (12):
| Tool | Description |
|------|-------------|
| `set_page_size` | Set page size (A4, Letter, etc.) |
| `set_page_margins` | Set page margins |
| `set_page_orientation` | Set portrait or landscape |
| `insert_page_break` | Insert page break |
| `insert_section_break` | Insert section break |
| `get_section_properties` | Read section properties such as page setup (Direct Mode) |
| `insert_continuous_section_break` | Insert a continuous section break (no page break) |
| `insert_column_break` | Insert a column break at a paragraph |
| `set_columns` | Number of columns (1–4) and column spacing of the document's last section; `separator` is accepted but not written |
| `set_line_numbers` | Show line numbers for the document — not implemented: reports success but writes nothing (use `set_line_numbers_for_section`) |
| `set_page_borders` | Page borders: each side on or off; style, colour, width and measure-from shared by all sides |
| `set_text_direction` | Text direction of a paragraph or the document (vertical text) — not implemented: reports success but writes nothing |

Section properties (7, **v3.10.0**):
| Tool | Description |
|------|-------------|
| `get_all_sections` | Return SectionInfo array per section in document order |
| `set_section_break_type` | `nextPage` / `continuous` / `evenPage` / `oddPage` |
| `set_section_vertical_alignment` | `<w:vAlign>` for cover pages |
| `set_page_number_format` | `<w:pgNumType w:fmt>` for Roman numerals etc. |
| `set_line_numbers_for_section` | `<w:lnNumType>` for legal documents |
| `set_title_page_distinct` | Toggle `<w:titlePg/>` per section |
| `set_section_header_footer_references` | Assign per-type rId (default/first/even) |

### Headers & Footers (20 tools, **v3.11.0+ even/odd + section map** [#51](https://github.com/PsychQuant/che-word-mcp/issues/51))

Write tools (8):
| Tool | Description |
|------|-------------|
| `add_header` | Add header content (uses `RelationshipIdAllocator` since v3.3.0+ — collision-free rIds in overlay mode) |
| `update_header` | Update header content (preserves filename + rId; in-place tempDir overwrite) |
| `add_footer` | Add footer content |
| `update_footer` | Update footer content |
| `insert_page_number` | Insert page number field |
| `insert_watermark` | Insert a diagonal text watermark into every header part (creates a default header when there is none) |
| `insert_image_watermark` | Insert a centred picture watermark (png, jpg, jpeg, gif, bmp, tif, tiff; up to 10 MB) into every header part; a new document must be saved once first |
| `remove_watermark` | Remove text and picture watermarks from every header part (succeeds when there is none) |

Read + delete tools (8, **v3.3.0+**, closes #26 #27):
| Tool | Description |
|------|-------------|
| `list_headers` | Enumerate header parts with type (default/first/even) + section_id + has_watermark |
| `get_header` | Read text + full XML + watermark structure |
| `delete_header` | Remove typed model entry + tempDir file + Relationship + Content_Types Override |
| `list_watermarks` | Scan all headers for VML watermark shapes — text (`PowerPlusWaterMarkObject`) or image (`WordPictureWatermark`, [#209](https://github.com/PsychQuant/che-word-mcp/issues/209)) |
| `get_watermark` | Single-header watermark detail (returns `null` if no watermark) |
| `list_footers` | Enumerate footer parts with type + section_id + has_page_number |
| `get_footer` | Read text + XML + parsed field structure (PAGE / NUMPAGES / REF / STYLEREF) |
| `delete_footer` | Symmetric with delete_header |

Even/odd + section linkage (4, **v3.11.0**):
| Tool | Description |
|------|-------------|
| `enable_even_odd_headers` | Toggle document-level `<w:evenAndOddHeaders/>` flag |
| `link_section_header_to_previous` | Word-compat clone semantics |
| `unlink_section_header_from_previous` | Symmetric unlink |
| `get_section_header_map` | Return per-section header / footer file assignments |

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

| Tool | Description |
|------|-------------|
| `get_theme` | Read major/minor font slots (latin/ea/cs) + color scheme (accent1-6, hyperlink, followedHyperlink) from `word/theme/theme1.xml` |
| `update_theme_fonts` | Partial-update font slots — e.g. `{ minor: { ea: "DFKai-SB" } }` for document Chinese font fix |
| `update_theme_color` | Slot-named hex color update with validation (rejects invalid slot + non-6-char-hex) |
| `set_theme` | Low-level escape hatch — replace theme1.xml verbatim (validates `<a:theme>` root + well-formed XML) |

### Images (9 tools)

| Tool | Description |
|------|-------------|
| `insert_image` | Insert inline image (PNG, JPEG) |
| `insert_image_from_path` | **v2.0.0+** — width/height optional (auto-aspect via `ImageDimensions.detect`), supports `into_table_cell` + `after_text` / `before_text` anchors. PNG/JPEG, and PDF (rasterizes the `page`-th page via native PDFKit/CoreGraphics, [#16](https://github.com/PsychQuant/che-word-mcp/issues/16)) |
| `insert_floating_image` | Insert floating image with text wrap; `relative_to_h` / `relative_to_v` set the anchor's reference point ([#233](https://github.com/PsychQuant/che-word-mcp/issues/233)) |
| `update_image` | Update image properties |
| `delete_image` | Delete image |
| `list_images` | List images — document body + header/footer, each flagged `referenced: yes/orphan/unknown` against the same package scan `save_document`'s consistency gate uses ([#199](https://github.com/PsychQuant/che-word-mcp/issues/199), [#219](https://github.com/PsychQuant/che-word-mcp/issues/219)) |
| `set_image_style` | Set image border and effects |
| `export_image` | Export one image to a file; looks in document, header, footer and chart parts |
| `export_all_images` | Export every image (document, headers, footers, charts) to a directory; same-name files get `_2`, `_3`, … suffixes |

### Captions (6 tools)

| Tool | Description |
|------|-------------|
| `insert_caption` | **v2.0.0+** — real OOXML SEQ field (not literal text). Accepts English + Chinese labels (`Figure`/`Table`/`Equation`/`圖`/`表`/`公式`), 5-way anchor (`paragraph_index` / `after_image_id` / `after_table_index` / `after_text` / `before_text`), optional `STYLEREF` chapter number prefix |
| `list_captions` | **v3.1.0** — enumerate caption paragraphs with label / sequence_number / caption_text / paragraph_index |
| `get_caption` | **v3.1.0** — detailed single caption info including optional `chapter_number` from STYLEREF |
| `update_caption` | **v3.1.0** — modify caption text or label without breaking the SEQ field structure |
| `delete_caption` | **v3.1.0** — remove caption paragraph |
| `wrap_caption_seq` | Wrap the plain-text number of matching captions in SEQ field runs across the body |

### Equations (8 tools)

| Tool | Description |
|------|-------------|
| `insert_equation` | **v2.0.0+** — emits structurally correct OMML via `MathComponent` AST (9 types). Primary: `components:` tree; fallback: `latex:` subset (`\frac`, `\sqrt`, `x^{y}`, Greek, ∑/∫/∏) |
| `list_equations` | **v3.1.0** — enumerate `<m:oMath>` runs with display_mode flag |
| `get_equation` | **v3.1.0** — detailed single equation info with component summary |
| `update_equation` | **v3.1.0** — replace target equation's components tree |
| `delete_equation` | **v3.1.0** — remove equation run or empty paragraph |
| `find_inline_math_gaps` | Find whitespace gaps that look like missing inline math symbols, with context (Direct Mode) |
| `splice_omath_from_source` | Copy one `<m:oMath>` block verbatim from a paragraph of another document |
| `splice_paragraph_omath_from_source` | Copy every `<m:oMath>` block of a source paragraph into the matching positions of a target paragraph |

### Export (6 tools)

| Tool | Description |
|------|-------------|
| `export_text` | Export as plain text |
| `export_markdown` | Export as Markdown (uses embedded `word-to-md-swift`) |
| `export_revision_summary_markdown` | **v1.19.0** — per-document revision timeline for manuscript review |
| `compare_documents_markdown` | **v1.19.0** — multi-document cumulative revision timeline |
| `compare_documents` | Paragraph-level diff of two documents (text, format or structure mode), returning only the differences |
| `export_comment_threads_markdown` | **v1.19.0** — comment threading with author alias normalization |

### Script Pipeline (3 tools)

| Tool | Description |
|------|-------------|
| `export_script` | docx → full-fidelity `.mdocx.swift` rebuild script (same transcoder as `macdoc word reverse`); optional named slots |
| `get_script_coverage` | Per-part DSL/raw coverage report of a docx (same numbers as `macdoc word reverse --coverage`) |
| `execute_script` | `.mdocx.swift` script → docx; refuses to overwrite an existing `output_path` unless `overwrite: true`; optional byte-equal verification against a reference file |

### Hyperlinks & Bookmarks (12 tools, **v3.11.0+ typed variants** [#50](https://github.com/PsychQuant/che-word-mcp/issues/50))

Generic + bookmarks (9):
| Tool | Description |
|------|-------------|
| `insert_hyperlink` | Insert external hyperlink |
| `insert_internal_link` | Insert link to bookmark |
| `insert_cross_reference` | Insert cross-reference — not implemented: reports success but writes nothing |
| `update_hyperlink` | Update hyperlink |
| `delete_hyperlink` | Delete hyperlink |
| `list_hyperlinks` | List all hyperlinks (Direct Mode) |
| `insert_bookmark` | Insert bookmark |
| `delete_bookmark` | Delete bookmark |
| `list_bookmarks` | List all bookmarks (Direct Mode) |

Typed hyperlinks (3, **v3.11.0**, auto-create Hyperlink character style):
| Tool | Description |
|------|-------------|
| `insert_url_hyperlink` | External URL with optional tooltip + history flag |
| `insert_bookmark_hyperlink` | Internal anchor link (`w:anchor`, no rId) |
| `insert_email_hyperlink` | `mailto:` with optional URL-encoded subject |

### Comments & Revisions (22 tools)

Comment write + read (10):
| Tool | Description |
|------|-------------|
| `insert_comment` | Insert comment |
| `update_comment` | Update comment text |
| `delete_comment` | Delete comment |
| `list_comments` | List all comments |
| `reply_to_comment` | Reply to existing comment |
| `resolve_comment` | Mark comment as resolved |
| `add_comment_reply` | Reply to a root comment, with template/vars, and optionally mark it resolved in the same call |
| `bulk_resolve_comments` | Mark many comments resolved in one call; reports the count and the failures (up to 1000 distinct ids) |
| `find_unresolved_comments` | List unresolved top-level comments, optionally with replies and anchor context (Direct Mode) |
| `list_comment_threads` | **v3.4.0** — enumerate threads (root_comment_id + replies + resolved + durable_id) using typed `Comment.parentId` from `commentsExtended.xml` |

Comment thread tools (2, **v3.4.0+**, closes #29):
| Tool | Description |
|------|-------------|
| `get_comment_thread` | Read root + walk children for full reply tree |
| `sync_extended_comments` | Report typed comment count for triplet sync planning |

Revision tracking — accept/reject side (7):
| Tool | Description |
|------|-------------|
| `enable_track_changes` | Enable track changes (sets `revisions.settings.author` for default author resolution) |
| `disable_track_changes` | Disable track changes |
| `get_revisions` | Enumerate all revisions (Direct Mode supported) |
| `accept_revision` | Accept revision by id |
| `reject_revision` | Reject revision by id |
| `accept_all_revisions` | Bulk accept |
| `reject_all_revisions` | Bulk reject |

Revision tracking — programmatic write side (3, **v3.12.0** [#45](https://github.com/PsychQuant/che-word-mcp/issues/45)):
| Tool | Description |
|------|-------------|
| `insert_text_as_revision` | Insert text wrapped in `<w:ins>` revision markup. Splits straddling runs at `position` (preserves prior + post text + formatting). Args: `doc_id`, `paragraph_index`, `position`, `text`, optional `author`, `date`. |
| `delete_text_as_revision` | Mark `[start, end)` runs with `<w:del>` and substitute `<w:t>` → `<w:delText>`. Single-paragraph only (cross-paragraph delete out of scope). |
| `move_text_as_revision` | Emit paired `<w:moveFrom>` / `<w:moveTo>` with adjacent revision ids. Single-paragraph moves rejected (callers should use delete + insert). |

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)

| Tool | Description |
|------|-------------|
| `list_people` | Parse `<w15:person>` entries from `word/people.xml` |
| `add_person` | Add new entry; auto-create `people.xml` part when absent; duplicate-name `_2` suffix |
| `update_person` | Update display_name (author attribute swap) |
| `delete_person` | Remove entry; report `comments_orphaned` count |

### Footnotes & Endnotes (10 tools)

Write + delete (4):
| Tool | Description |
|------|-------------|
| `insert_footnote` | Insert footnote |
| `delete_footnote` | Delete footnote |
| `insert_endnote` | Insert endnote |
| `delete_endnote` | Delete endnote |

List + read + update (6, **v3.4.0+**, closes #24 #25):
| Tool | Description |
|------|-------------|
| `list_footnotes` | Direct Mode supported |
| `list_endnotes` | Direct Mode supported |
| `get_footnote` | Read text + runs by integer ID |
| `update_footnote` | In-place text replacement, preserves footnote_id (cross-references stay valid) |
| `get_endnote` | Read text + runs by integer ID |
| `update_endnote` | In-place text replacement, preserves endnote_id |

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

| Tool | Description |
|------|-------------|
| `get_web_settings` | Parse `word/webSettings.xml` flag elements (`relyOnVML`, `optimizeForBrowser`, `allowPNG`, `doNotSaveAsSingleFile`); returns `{ error: "no webSettings part" }` when absent |
| `update_web_settings` | Partial update by key; auto-create part if absent |

### Field Codes (7 tools)

| Tool | Description |
|------|-------------|
| `insert_if_field` | Insert IF conditional field |
| `insert_calculation_field` | Insert calculation (SUM, AVERAGE, etc.) |
| `insert_date_field` | Insert date/time field |
| `insert_page_field` | Insert page number field |
| `insert_merge_field` | Insert mail merge field |
| `insert_sequence_field` | Insert auto-numbering sequence |
| `update_all_fields` | **v3.1.0** — F9-equivalent SEQ recount across body + headers + footers + footnotes + endnotes. Supports chapter-reset when `pStyle=="Heading N"` matches SEQ `resetLevel` |

### Content Controls / SDT (13 tools, **v3.9.0+ full read/write** [#44](https://github.com/PsychQuant/che-word-mcp/issues/44))

Insert + form helpers (5):
| Tool | Description |
|------|-------------|
| `insert_content_control` | 12-type discrimination (`richText` / `plainText` / `picture` / `date` / `dropDownList` / `comboBox` / `checkBox` / `bibliography` / `citation` / `group` / `repeatingSection` (rejected — use `insert_repeating_section`) / `repeatingSectionItem`). Optional args: `list_items` (required for dropDown/comboBox), `date_format`, `lock_type`. |
| `insert_repeating_section` | Insert repeating section (Word 2012+); accepts `allow_insert_delete_sections: bool` (default `true`) |
| `insert_checkbox` | Insert checkbox SDT |
| `insert_dropdown` | Insert dropdown SDT |
| `insert_text_field` | Insert plain-text SDT |

Read tools (4):
| Tool | Description |
|------|-------------|
| `list_content_controls` | Enumerate every SDT, flat (default) or nested tree mode (Direct Mode supported) |
| `get_content_control` | Fetch single SDT by `id`, `tag`, or `alias`. Returns full metadata + `<w:sdtContent>` XML. Surfaces `not_found` / `multiple_matches` errors. |
| `list_repeating_section_items` | Enumerate items inside a repeating-section SDT in document order |
| `list_custom_xml_parts` | List CustomXml parts — not implemented yet: always returns an empty list |

Modify tools (4):
| Tool | Description |
|------|-------------|
| `update_content_control_text` | Replace text content of plainText / richText / date / bibliography / citation SDTs. Preserves `<w:sdtPr>` byte-identical. Returns `unsupported_type` for picture / dropdown / combo / checkbox / group / repeatingSection. |
| `replace_content_control_content` | Replace full `<w:sdtContent>` XML with whitelist validation (rejects input containing `<w:sdt>`, `<w:body>`, `<w:sectPr>`, or XML declaration) |
| `delete_content_control` | Remove SDT, optionally unwrapping children (`keep_content: true` default) |
| `update_repeating_section_item` | Replace text of single item by index (`out_of_bounds` for invalid index) |

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).

### Forms (2 tools)

| Tool | Description |
|------|-------------|
| `classify_form` | List the paragraphs of a .docx form that carry `w14:paraId`, with their kind and text (reads the file on disk) |
| `apply_form` | Tidy a filled .docx form (the library behind `macdoc word form apply`) and write it to `output_path` |

### Document Protection (5 tools)

| Tool | Description |
|------|-------------|
| `restrict_editing_region` | Mark paragraphs `[start_paragraph, end_paragraph]` as an editable region with `<w:permStart>`/`<w:permEnd>` (`start_paragraph` ≥ 1); restricts nothing unless the document is already protected (`protect_document` is not implemented, #172) |
| `protect_document` | Restrict editing or make read-only — not implemented: returns isError naming the missing OOXML (#172) |
| `unprotect_document` | Remove document protection — not implemented: returns isError (#172) |
| `set_document_password` | Set an open password — not implemented: returns isError (the password is container encryption outside OOXML, #172) |
| `remove_document_password` | Remove the open password — not implemented: returns isError (#172) |

### Advanced Features (11 tools)

| Tool | Description |
|------|-------------|
| `insert_toc` | Insert table of contents |
| `insert_table_of_figures` | Insert table of figures |
| `insert_index` | Insert an index |
| `insert_index_entry` | Mark an index entry — not implemented: reports success but writes nothing |
| `set_paragraph_border` | Set paragraph border |
| `set_paragraph_shading` | Set paragraph background color |
| `set_character_spacing` | Set character spacing |
| `set_text_effect` | Set text animation effect |
| `insert_horizontal_line` | Insert a horizontal line |
| `insert_drop_cap` | Insert a drop cap |
| `insert_symbol` | Insert a symbol |

> **Note**: The tables above list every tool the server registers; `Issue306ToolCountDocsTests` fails `swift test` when a tool is added or removed without updating them. Run the server and call `tools/list` for each tool's full description and input schema.

## 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](https://github.com/modelcontextprotocol/swift-sdk) (v0.12.0+) — Model Context Protocol implementation
- [ooxml-swift](https://github.com/PsychQuant/ooxml-swift) (**v0.12.0+**) — OOXML parsing + **preserve-by-default round-trip architecture** (PreservedArchive, RelationshipIdAllocator, ContentTypesOverlay), `FieldParser`, `OMMLParser`, `updateAllFields()`, `MathAccent`
- [latex-math-swift](https://github.com/PsychQuant/latex-math-swift) (**v0.1.0+**) — LaTeX subset → OMML `MathComponent` AST parser (used by `insert_equation` v3.2.0+)
- [markdown-swift](https://github.com/PsychQuant/markdown-swift) (v0.2.0+) — Markdown generation
- [word-to-md-swift](https://github.com/PsychQuant/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:

```bash
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 `XCTSkip`s when `test-files/` is empty so
clean clones / CI do not false-fail. Mirrors the `.note` smoke pattern from
[PsychQuant/macdoc#81](https://github.com/PsychQuant/macdoc/issues/81).

## Comparison with Other Solutions

| Feature | Anthropic Word MCP | python-docx | docx npm | **che-word-mcp** |
|---------|-------------------|-------------|----------|------------------|
| Language | Node.js | Python | Node.js | **Swift** |
| Backend | AppleScript | OOXML | OOXML | **OOXML** |
| Requires Word | Yes | No | No | **No** |
| Runtime | Node.js | Python | Node.js | **None** |
| Single Binary | No | No | No | **Yes** |
| Tools Count | ~10 | N/A | N/A | **248** |
| Images | Limited | Yes | Yes | **Yes** |
| Comments | No | Limited | Limited | **Yes** |
| Track Changes | No | No | No | **Yes** |
| TOC | No | Limited | No | **Yes** |
| Form Fields | No | No | No | **Yes** |

## Performance

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

### Read Performance

| File Size | Time |
|-----------|------|
| 40 KB (document outline) | **72 ms** |
| 431 KB (complex document) | **31 ms** |

### Write Performance

| Operation | Content | Time |
|-----------|---------|------|
| Basic write | Create + 3 paragraphs + Save | **19 ms** |
| Complex document | Title + Paragraphs + Table + List | **21 ms** |
| Bulk write | **50 paragraphs** + Save | **28 ms** |

### 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](https://github.com/PsychQuant))

### Contributors

- [@ildunari](https://github.com/ildunari) — session state management (v1.17.0)

## Related Projects

- [che-apple-mail-mcp](https://github.com/PsychQuant/che-apple-mail-mcp) - Apple Mail MCP server
- [che-ical-mcp](https://github.com/PsychQuant/che-ical-mcp) - macOS Calendar MCP server