# Office-MCP-Server

A unified MCP server for Word, PowerPoint, and Excel. PowerPoint and Excel are
planned for later phases — this README currently covers the Word engine.

## Word

Direct OOXML manipulation (JSZip + `fast-xml-parser`) with tracked changes and
stable `w14:paraId` paragraph anchors, not a wrapper around `python-docx`.
Every read tool returns human-readable text plus a trailing `<json>` block for
programmatic use. Every write tool locks its target file per-path so
concurrent calls against the same document serialize instead of corrupting it.

### Prerequisites

- Node.js 20+
- LibreOffice, **only** for `word_convert_to_pdf` — install it so `soffice` is
  on your `PATH`, or at one of the standard install locations
  (`/Applications/LibreOffice.app/...` on macOS, `C:\Program
  Files\LibreOffice\program\soffice.exe` on Windows). No other tool needs it.

### Tools

| Category | Tools |
|---|---|
| Reading & search | `word_read_document`, `word_get_document_info`, `word_search_text` |
| Editing (tracked changes by default) | `word_replace_texts`, `word_edit_paragraphs`, `word_insert_paragraphs`, `word_delete_paragraphs`, `word_ensure_anchors` |
| Formatting | `word_format_text`, `word_set_paragraph_formats`, `word_highlight_text`, `word_set_headings` |
| Page layout | `word_get_page_layout`, `word_set_page_layout` |
| Tables | `word_insert_table`, `word_read_table_structure`, `word_read_table_cell`, `word_edit_table_cells`, `word_edit_table_paragraphs`, `word_insert_table_paragraphs`, `word_delete_table_paragraphs` |
| Comments | `word_add_comment`, `word_add_comments`, `word_read_comments`, `word_reply_to_comment`, `word_delete_comment` |
| Track changes | `word_accept_all_changes`, `word_reject_all_changes` |
| Images, headers/footers, footnotes | `word_list_images`, `word_read_header_footer`, `word_read_footnotes` |
| Document creation & styling | `word_create_document`, `word_apply_document_preset`, `word_create_custom_style` |
| Protection & conversion | `word_add_password_protection`, `word_convert_to_pdf` |
| Merging | `word_merge_documents` |

### Notable scope decisions

These keep the engine simple; see `decisions.md`/`phases.md` for the full
rationale if you hit one of these edges:

- Tracked-changes replace/insert/delete is **paragraph-level**, not a
  surgical cross-run replace — an edited paragraph's runs are rewrapped in
  `w:ins`/`w:del` wholesale.
- Formatting tools apply directly, without `w:rPrChange`/`w:pPrChange`
  tracked-revision wrappers.
- Page layout, headers, and footers address only the document's final,
  body-level section — no multi-section support.
- Tables are addressed by `table_index` (0-based, document order), not a
  stable anchor; table-cell paragraphs still get real `w14:paraId`s.
- Comment replies are independent top-level comments anchored to the same
  paragraph, not real `w15:commentsEx` parent/child threading.
- `word_merge_documents` splices paragraphs/tables from later source
  documents into the first source's package as-is (full formatting fidelity)
  but does not remap images/hyperlinks/footnotes/comments — those keep their
  source document's now-meaningless relationship IDs.
- `word_add_password_protection` implements Word's real, Word-enforced
  "Restrict Editing" password (a `w:documentProtection` hash in
  `settings.xml`) — not full document encryption, and no digital-signature
  tool (GongRzhe's own version of that feature isn't real either; see
  ADR-003/ADR-010 in `decisions.md`).

### Example

```json
{
  "tool": "word_replace_texts",
  "arguments": {
    "file_path": "/abs/path/to/report.docx",
    "edits": [{ "search": "Q3 draft", "replace": "Q3 final" }],
    "track_changes": true
  }
}
```