# Che Word Mcp

> Swift-native MCP server for Microsoft Word (.docx) — 233 tools, the first pure-Swift OOXML library (no Word required). v3.13.5 closes #56 round-trip silent corruption (5 sub-stack rounds, 30 findings via 6-AI verify). Office.js Roadmap P0 100%: Track Changes, SDT, styles, numbering, sections, hyperlinks. Byte-preserving overlay save.

- **Type:** MCP server
- **Install:** `agentstack add mcp-psychquant-che-word-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PsychQuant](https://agentstack.voostack.com/s/psychquant)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [PsychQuant](https://github.com/PsychQuant)
- **Source:** https://github.com/PsychQuant/che-word-mcp
- **Website:** https://github.com/PsychQuant/che-word-mcp/releases

## Install

```sh
agentstack add mcp-psychquant-che-word-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## 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](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 `` 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 `` / `` / `` / `` / `` / `` 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. NTPU thesis no-op `save_document` round-trip retains 13 fontTable entries + 6 distinct headers + 4 footers + three-segment PAGE field + `` 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`](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

| Version | Date | Changes |
|---------|------|---------|
| **v3.13.5** | 2026-04-27 | **R5 stack-completion** (closes [#56](https://github.com/PsychQuant/che-word-mcp/issues/56) silent corruption). Bumps ooxml-swift v0.19.3 → v0.19.5 (v0.19.4 held back per verify-gate). 30 findings closed (16 P0 + 21 P1) across 5 sub-stacks (R5 / R5-CONT / R5-CONT-2 / R5-CONT-3 / R5-CONT-4) and rounds 4-8 of 6-AI cross-verification. **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 `` capture preserved. **Round 7** `reject_revision` typed clearMarker (file/API state convergence). **Round 8** `accept_revision` typed clearMarker (mirror) + matrix-pin asymmetry-guard removal + `repairContainerFileNames` rels-dirty. Convergence: Devil's Advocate wrote 5 adversarial tests targeting the convergence-cycle pattern; all PASSED. **No che-word-mcp source changes** — entire fix architecture in ooxml-swift. See [closing summary](https://github.com/PsychQuant/che-word-mcp/issues/56#issuecomment-4322638865). |
| v3.13.4 | 2026-04-26 | **(skipped — held back per verify-gate)**. R3 stack content rolled into v3.13.5. |
| v3.13.3 | 2026-04-26 | Bumps ooxml-swift v0.19.2 → v0.19.3. Closes 8 P0 + 3 must-fix P1 from #56 round-2 verify (Hyperlink API path visual-style restoration / tgtFrame / docLocation Reader filter / ordered children source-order preservation; sort-path contentControls + commentIds / footnoteIds / endnoteIds / hasPageBreak emission; non-text wrapper preservation; nested hyperlink/SDT/fieldSimple round-trip; nextBookmarkId calibration; bookmark wrap-around restoration). No source changes. |
| v3.13.2 | 2026-04-26 | Bumps ooxml-swift v0.19.1 → v0.19.2. Closes 4 blocking findings from #56 round-1 verify (F1 `Hyperlink.toXML()` emits Reader-collected runs/rawAttributes/rawChildren; F2 `add_bookmark`/`delete_bookmark` sync `bookmarkMarkers`; F3 ins/del/moveFrom/moveTo round-trip preserves position+revisionId+wrapper; F4 namespace preservation extends from `document.xml` to header/footer/footnote/endnote). No source changes. |
| v3.13.1 | 2026-04-25 | `pPr` double-emission silent regression on sort-by-position round-trip — hot-fix (ooxml-swift v0.19.1). |
| v3.13.0 | 2026-04-25 | **`document.xml` lossless round-trip + tool-mediated wrapper edits** (closes [#56](https://github.com/PsychQuant/che-word-mcp/issues/56) P0). Hybrid model preserves namespace map (34 xmlns), bookmarks, structural wrappers (`` / `` / ``). |
| v3.12.0 | 2026-04-25 | **Programmatic Track Changes generation** (closes [#45](https://github.com/PsychQuant/che-word-mcp/issues/45)) — 3 new tools (`insert_text_as_revision` / `delete_text_as_revision` / `move_text_as_revision`) + `as_revision` flag on `format_text` / `set_paragraph_format`. Emits `` / `` / `` / `` / `` / `` markup. |
| v3.11.0 | 2026-04-25 | **Tables / Hyperlinks / Headers extensions** (closes [#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`. |
| v3.10.0 | 2026-04-24 | **Styles + Numbering + Sections foundation** (closes [#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; section vertical alignment / page-number format / break-type / title-page distinct / per-section header refs. |
| v3.9.0 | 2026-04-24 | **Content Controls (SDT) read/write** (closes [#44](https://github.com/PsychQuant/che-word-mcp/issues/44)) — 7 new tools, 12-type discrimination (richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection / repeatingSectionItem). Nested SDT trees, deterministic id allocator, `keep_content` unwrap, whitelist-validated XML replacement. |
| v3.8.0 | 2026-04-24 | **Header/footer raw-element preservation + counter-isolation flag** (closes [#52](https://github.com/PsychQuant/che-word-mcp/issues/52)). |
| v3.7.2 | 2026-04-24 | 3-issue bundle from #42 verification (closes [#53](https://github.com/PsychQuant/che-word-mcp/issues/53), [#54](https://github.com/PsychQuant/che-word-mcp/issues/54), [#55](https://github.com/PsychQuant/che-word-mcp/issues/55) path traversal hardening). |
| v3.7.1 | 2026-04-24 | `update_all_fields` no longer strips headers/footers (closes [#42](https://github.com/PsychQuant/che-word-mcp/issues/42)). |
| v3.7.0 | 2026-04-24 | **Insert crash hardening + autosave Design B** (closes [#40](https://github.com/PsychQuant/che-word-mcp/issues/40), [#41](https://github.com/PsychQuant/che-word-mcp/issues/41)). v3.6.0 shipped autosave_every Design A (post-mutation counter) which couldn't preserve K-1 mutations on crash at K when K%N≠0. v3.7.0 switches to **Design B** (snapshot fires at the START of every mutating handler before the mutation runs); default `autosave_every` flipped from `0` to `1` (every mutation snapshots prior state). Pass `autosave_every: 0` to opt out. **BREAKING (effective)**: callers who relied on Design A semantics or default disabled. Also adds Phase A `CHE_WORD_MCP_LOG_LEVEL=debug` structured logging gate for #41 investigation. Built on ooxml-swift 0.13.3 which kills `DocxReader.concurrentPerform` (parsing determinism prerequisite for `recover_from_autosave`) and refactors `nextImageRelationshipId` to use the rId allocator. **Migration from v3.6.0**: code passing `autosave_every: 0` explicitly is unaffected; code that omitted the arg now gets `1` (full safety) — to restore v3.6.0 disabled-by-default behavior, add `autosave_every: 0` to `open_document` calls. |
| v3.6.0 | 2026-04-23 | **Autosave + checkpoint + recover_from_autosave** (closes [#37](https://github.com/PsychQuant/che-word-mcp/issues/37)). `open_document` gains `autosave_every: Int = 0` parameter — when N > 0, every Nth mutation triggers a checkpoint write to `.autosave.docx` (separate file, NOT eager-save to source). New tools: `checkpoint(doc_id, path?)` for manual snapshot, `recover_from_autosave(doc_id, discard_changes?)` to replace in-memory state with autosave bytes. `get_session_state` adds `autosave_detected` + `autosave_path` fields. Successful `save_document` / `finalize_document` cleans up `.autosave.docx`. Phase 4 of save-durability-stack SDD. |
| v3.5.5 | 2026-04-23 | **`keep_bak` opt-in for rollback escape hatch** (closes [#38](https://github.com/PsychQuant/che-word-mcp/issues/38)). `save_document` gains optional `keep_bak: Bool = false`; when `true` and target exists, server renames target → `.bak` BEFORE atomic-rename save (single slot, overwrites prior `.bak`). User can `mv .bak ` to roll back if a future save ships silent OOXML damage. `.bak` lives at server layer NOT ooxml-swift — `macdoc` CLI users don't get unwanted `.bak` files. Phase 3 of save-durability-stack SDD. |
| v3.5.4 | 2026-04-23 | **`class WordMCPServer` → `actor WordMCPServer`** (closes [#39](https://github.com/PsychQuant/che-word-mcp/issues/39)). 8 mutable session state dictionaries become actor-isolated; compiler enforces every cross-actor access via `await`. Eliminates the Dictionary hash-table corruption race that pre-v3.5.4 12-parallel `insert_image_from_path` calls triggered. Phase 2 of save-durability-stack SDD. |
| v3.5.3 | 2026-04-23 | **Atomic-rename save** (closes [#36](https://github.com/PsychQuant/che-word-mcp/issues/36)). Bumps to ooxml-swift 0.13.2 which refactors `DocxWriter.write` to write `.tmp.` + `fsync` + `replaceItemAt`. Any throw or process kill mid-write leaves the original byte-preserved (POSIX `rename(2)` is kernel-atomic; cross-volume falls back to copy+delete). 397/397 ooxml-swift tests pass; concurrent-observer regression test added. Phase 1 of save-durability-stack SDD. |
| v3.5.2 | 2026-04-23 | **Rels overlay merge** (closes [#35](https://github.com/PsychQuant/che-word-mcp/issues/35)) — Reader-loaded NTPU thesis no-op `save_document` round-trip now preserves theme / webSettings / people / customXml / commentsExtended / commentsIds rels. v3.5.0/v3.5.1 fixed the parts layer; v3.5.2 fixes the rels layer. No che-word-mcp source change — fix entirely in ooxml-swift v0.13.1 (`RelationshipsOverlay` + relat

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PsychQuant](https://github.com/PsychQuant)
- **Source:** [PsychQuant/che-word-mcp](https://github.com/PsychQuant/che-word-mcp)
- **License:** MIT
- **Homepage:** https://github.com/PsychQuant/che-word-mcp/releases

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-psychquant-che-word-mcp
- Seller: https://agentstack.voostack.com/s/psychquant
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.