word-engine-mcp

한국어 안내 → README.ko.md

A local MCP server that drives the real Word desktop application (COM automation) to do the things python-docx fundamentally cannot: compute field/TOC values, count real pages, render true-fidelity PDF, convert/repair legacy formats, produce redline comparisons, and run native mail merge.

Design philosophy: this server complements library workflows instead of replacing them. Editing text, tables and styles is faster with python-docx — but a document built with python-docx has ? where TOC page numbers should be, and no library has a concept of "pages" (that requires a layout engine). This MCP handles only the engine-exclusive part, keeping its tool surface tiny (8 tools).

Requirements

• Windows 10+ with a logged-in interactive desktop session (Word has no true headless mode)
• Microsoft Office (Word) installed and licensed — verified on Office 2016+ (Word 16.0)
• Python 3.10+ — verified on 3.12
• Claude Code or any MCP client

Install

git clone https://github.com/Feynman520/d01-p04-word-engine-mcp.git
cd d01-p04-word-engine-mcp
py -3.12 -m venv .venv          # or: python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Register with Claude Code

Run this in the cloned folder (uses absolute paths, so it works from anywhere afterwards):

claude mcp add word-automation --scope user -- "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"

--scope user makes it available in every project. Use --scope project to limit it to one project.

Verify

$py = ".\.venv\Scripts\python.exe"; $env:PYTHONUTF8 = "1"
& $py tests\smoke_com.py      # field update / page stats / PDF / convert / compare / mail merge
& $py tests\server_tools.py   # MCP tool registration (does not launch Word)

Tools (6 core + 2 diagnostics)

#	Tool	Input → Output	Why engine-only
①	word_update_fields	src_path, out_path → {out_path,fields_updated}	Computes displayed values of TOC, cross-references, PAGE/SEQ, index (python-docx stores field codes only — shown as ?)
②	word_read_layout	path, update_fields?, include_readability? → {pages,words,lines,characters,...}	Real page count and layout statistics (libraries have no page concept)
③	word_export_pdf	src_path, out_path, update_fields?, pdf_a?, from_page?, to_page?, create_bookmarks? → {out_path}	Word render engine PDF (PDF/A, heading bookmarks, page ranges)
④	word_convert	src_path, out_path, repair? → {out_path,format,repaired}	.doc/.rtf/.odt/.html/.txt ↔ .docx conversion and corrupt-file repair (python-docx is .docx-only)
⑤	word_compare	original_path, revised_path, out_path, author?, granularity? → {out_path,revisions}	Native CompareDocuments redline (no library equivalent)
⑥	word_mail_merge	template_path, data_path, out_path → {out_path,records}	Native mail merge (per-record documents)
—	word_health	→ {alive, word_version}	Session check (launches Word on first call)
—	word_restart	→ {alive}	Recovery from COM errors

Typical flow: build a .docx with python-docx → word_update_fields to bake TOC/numbers → word_read_layout to check the real page count → word_export_pdf for the final PDF. Originals are never modified; results are always written to out_path.

Mail merge data source

The most reliable source is a .docx containing a table with one header row + data rows (no database driver involved, fully unattended). .csv/.xlsx are also accepted, but some environments show Word's SQL confirmation prompt (depends on an HKCU setting).

Architecture notes

• Single STA worker thread (engine/session.py): every Word call is serialized onto one dedicated thread (win32com COM objects are thread-bound; FastMCP may hop threads).
• Lazy session: Word starts on the first tool call, is reused, and closes with the server.
• DispatchEx + early binding (gencache.EnsureDispatch): a dedicated instance, and argument-heavy methods like ExportAsFixedFormat/CompareDocuments are marshalled correctly via the type library. The one-time makepy output is redirected away from stdout (the JSON-RPC channel).
• Visible=False, macros blocked on open via AutomationSecurity=ForceDisable.
• Originals preserved: inputs open read-only, results are written to new paths, then Close(SaveChanges=False).
• Zombie prevention: Word gives no stable window handle, so the dedicated instance PID is identified by diffing the WINWORD.EXE process list before/after DispatchEx, and force-killed at shutdown if it survives Quit().
• RPC-rejection retry: RPC_E_CALL_REJECTED right after startup is retried with backoff.

Limitations

• Not suitable for unattended/service sessions (needs an interactive desktop).
• Text/table/style editing is faster with python-docx — that is by design.

License

MIT