che-word-mcp

What this skill does

# che-word-mcp

A Swift-native MCP server for Microsoft Word (.docx) document manipulation. **218+ tools** for reading, writing, and modifying Word documents without requiring Microsoft Word installation. Built on `ooxml-swift` v0.18.0.

Office.js OOXML Roadmap P0 = **100% complete** ([PsychQuant/che-word-mcp#43](https://github.com/PsychQuant/che-word-mcp/issues/43)). Latest: v3.12.0 ships programmatic Track Changes generation.

## Two Modes of Operation

| Mode | Parameter | Use when | Tool count |
|------|-----------|----------|------------|
| **Direct Mode** | `source_path` | Quick read-only access, no state needed | 18 tools |
| **Session Mode** | `doc_id` | Full read/write with open→edit→save lifecycle | All 218+ tools |

### Direct Mode (`source_path`)

Pass `source_path` with the .docx path. No `open_document` needed. Best for quick inspection.

```
list_images:  { "source_path": "/path/to/file.docx" }
search_text:  { "source_path": "/path/to/file.docx", "query": "keyword" }
```

### Session Mode (`doc_id`)

Call `open_document` first, then pass `doc_id`. Required for any edit.

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

## Core Workflows

### Reading Documents

```text
1. open_document(path: "...")          → returns doc_id
2. get_document_text(doc_id: "...")    → plain text
   OR get_paragraphs(doc_id: "...")    → with formatting + indices
3. close_document(doc_id: "...")
```

### Creating Documents

```text
1. create_document(doc_id: "report")
2. insert_paragraph(doc_id, text: "Title", style: "Heading1")
   insert_table(doc_id, rows: 3, cols: 4, data: [...])
   insert_image(doc_id, path: "/image.png")
3. save_document(doc_id, path: "/out.docx")
```

### Modifying Documents

```text
1. open_document(path: "...")
2. update_paragraph(doc_id, paragraph_index: 0, text: "...")
   format_text(doc_id, paragraph_index: 0, bold: true)
   replace_text(doc_id, find: "...", replace: "...")
3. save_document(doc_id, path: "...")
```

### Track Changes Workflow (v3.12.0+)

Two paths: **accept/reject existing revisions** OR **generate new revisions programmatically**.

```text
# Accept/reject existing revisions
1. open_document(path: "...")
2. get_revisions(doc_id)                  → list with revision ids
3. accept_revision(doc_id, revision_id) / reject_revision(...)
   accept_all_revisions(doc_id) / reject_all_revisions(doc_id)

# Generate new revisions (NEW in v3.12.0)
1. enable_track_changes(doc_id, author: "Reviewer A")
2. insert_text_as_revision(doc_id, paragraph_index, position, text)
   delete_text_as_revision(doc_id, paragraph_index, start, end)
   move_text_as_revision(doc_id, source/dest)
   format_text(doc_id, paragraph_index, bold: true, as_revision: true)
   set_paragraph_format(doc_id, paragraph_index, alignment: "center", as_revision: true)
3. save_document(...)
```

**Author resolution chain**: explicit `author` arg → `revisions.settings.author` (set at `enable_track_changes`) → `"Unknown"`.

**Side-effect contract** (important): `as_revision: true` requires track changes to be enabled. If disabled, the call **throws `track_changes_not_enabled`** instead of silently auto-enabling. Call `enable_track_changes` first.

### Content Controls / SDT (v3.9.0+)

```text
insert_content_control(doc_id, paragraph_index, control_type: "richText"|"plainText"|"checkBox"|"dropDownList"|"comboBox"|"date"|"picture")
insert_repeating_section(doc_id, ...)
list_content_controls(doc_id)
get_content_control(doc_id, sdt_id)
update_content_control_text(doc_id, sdt_id, text)
replace_content_control_content(doc_id, sdt_id, content)
delete_content_control(doc_id, sdt_id)
```

SDT ids are auto-allocated via max+1 pattern (scans body + headers + footers + footnotes + endnotes).

### Exporting

```text
export_text(doc_id)                    → plain text
export_markdown(doc_id)                → Markdown
export_revision_summary_markdown(doc_id) → revision summary
export_comment_threads_markdown(doc_id)  → comment threads
export_all_images(doc_id, output_dir)
```

## Tool Categories (218+ total)

### Document Lifecycle

`create_document`, `open_document`, `save_document`, `close_document`, `list_open_documents`, `get_document_info`, `get_document_session_state`, `finalize_document`, `recover_from_autosave`, `revert_to_disk`, `reload_from_disk`, `check_disk_drift`, `checkpoint`

### Document Properties / Theme / Web Settings

`get_document_properties`, `set_document_properties`, `get_theme`, `set_theme`, `update_theme_color`, `update_theme_fonts`, `get_web_settings`, `update_web_settings`, `set_language`

### Content (text + paragraphs)

`get_text`, `get_document_text`, `get_paragraphs`, `get_paragraph_runs`, `get_text_with_formatting`, `insert_paragraph`, `update_paragraph`, `delete_paragraph`, `replace_text`, `replace_text_batch`, `search_text`, `search_text_batch`, `search_text_with_formatting`, `search_by_formatting`, `list_all_formatted_text`

### Formatting

`format_text` (with `as_revision` flag, v3.12.0+), `set_paragraph_format` (with `as_revision` flag), `set_character_spacing`, `set_text_effect`, `set_text_direction`, `set_paragraph_border`, `set_paragraph_shading`

### Styles (v3.10.0+)

`list_styles`, `apply_style`, `create_style`, `update_style`, `delete_style`

### Numbering / Lists (v3.10.0+)

`insert_bullet_list`, `insert_numbered_list`, `set_list_level`, `set_outline_level`

### Sections / Page Setup (v3.10.0+)

`get_section_properties`, `insert_section_break`, `insert_continuous_section_break`, `insert_column_break`, `insert_page_break`, `set_columns`, `set_page_size`, `set_page_margins`, `set_page_orientation`, `set_page_borders`, `set_page_break_before`, `set_keep_lines`, `set_keep_with_next`, `set_widow_orphan`, `set_line_numbers`, `get_word_count_by_section`

### Tables (v3.11.0+)

`insert_table`, `get_tables`, `update_cell`, `add_row_to_table`, `delete_row_from_table`, `add_column_to_table`, `delete_column_from_table`, `merge_cells`, `set_cell_width`, `set_cell_vertical_alignment`, `set_row_height`, `set_header_row`, `set_table_alignment`, `set_table_style`, `delete_table`

### Hyperlinks (v3.11.0+)

`insert_hyperlink`, `update_hyperlink`, `delete_hyperlink`, `list_hyperlinks`, `insert_internal_link`, `insert_cross_reference`

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

`add_header`, `update_header`, `get_header`, `delete_header`, `list_headers`, `add_footer`, `update_footer`, `get_footer`, `delete_footer`, `list_footers`, `insert_page_number`

### Comments

`insert_comment`, `update_comment`, `delete_comment`, `list_comments`, `list_comment_threads`, `get_comment_thread`, `reply_to_comment`, `resolve_comment`, `sync_extended_comments`, `add_person`, `update_person`, `delete_person`, `list_people`

### Track Changes / Revisions (v3.12.0 write side)

`enable_track_changes`, `disable_track_changes`, `get_revisions`, `accept_revision`, `reject_revision`, `accept_all_revisions`, `reject_all_revisions`, `insert_text_as_revision`, `delete_text_as_revision`, `move_text_as_revision`, `export_revision_summary_markdown`

### Content Controls / SDT (v3.9.0+)

`insert_content_control`, `list_content_controls`, `get_content_control`, `update_content_control_text`, `replace_content_control_content`, `delete_content_control`, `insert_repeating_section`, `update_repeating_section_item`, `list_repeating_section_items`, `insert_checkbox`, `insert_dropdown`, `insert_text_field`, `list_custom_xml_parts`

### Images

`insert_image`, `insert_image_from_path`, `insert_floating_image`, `update_image`, `delete_image`, `list_images`, `set_image_style`, `export_image`, `export_all_images`, `insert_drop_cap`

### Footnotes / Endnotes / Equations / Captions

`insert_footnote`, `update_footnote`, `delete_footnote`, `get_footnote`, `list_footnotes`, `insert_endnote