DOCX Redline MCP

Local stdio MCP server for inspecting and editing Microsoft .docx files through OOXML package parts.

It is intended for agent workflows that need to:

• open a local .docx
• inspect OOXML parts such as word/document.xml
• apply real Word tracked changes through @ansonlai/docx-redline-js
• add comments and maintenance operations safely
• save back in place or to a new output path

Status

Current behavior is hardened around the failure modes discovered during end-to-end Word testing:

• MCP logging is routed to stderr so stdio transport is not corrupted
• package updates are validated before the in-memory session is committed
• invalid comment/revision combinations are rejected and rolled back
• delete_all_comments clears both inline anchors and word/comments.xml
• redline operations normalize hidden field scaffolding (w:fldChar, w:instrText) and proofing markers (w:proofErr) in the matched target paragraph before diffing
• batch redline application is supported through apply_operations

Requirements

• Node.js 18 or newer

Install

npm install

Run

node src/index.js

Package binary:

npx docx-redline-mcp

MCP Tools

open_docx

Open a .docx file and create a working handle.

{
  "path": "C:/contracts/master-services-agreement.docx"
}

list_parts

List package parts for an open handle.

{
  "handle": "doc_..."
}

read_part

Read an OOXML part as XML text or get a binary summary.

{
  "handle": "doc_...",
  "partPath": "word/document.xml",
  "maxChars": 12000
}

Binary export:

{
  "handle": "doc_...",
  "partPath": "word/media/image1.png",
  "includeBase64": true
}

write_part

Replace a writable XML part in memory.

{
  "handle": "doc_...",
  "partPath": "word/document.xml",
  "xml": "<w:document>...</w:document>"
}

Writable XML parts:

• word/document.xml
• word/comments.xml
• word/numbering.xml
• word/header*.xml
• word/footer*.xml
• [Content_Types].xml

apply_operation

Apply one structured operation to word/document.xml.

Redline example:

{
  "handle": "doc_...",
  "author": "Roo",
  "operation": {
    "type": "redline",
    "target": "Original text",
    "modified": "Updated text"
  }
}

Comment example:

{
  "handle": "doc_...",
  "author": "Roo",
  "operation": {
    "type": "comment",
    "target": "Original paragraph text",
    "textToComment": "Original",
    "commentContent": "Explain the change"
  }
}

Maintenance operations:

• accept_all_tracked_changes
• reject_all_tracked_changes
• delete_all_comments

apply_operations

Apply multiple structured operations in a single batch. This is the preferred path when one edit session needs several redlines/comments against the same open document.

{
  "handle": "doc_...",
  "author": "Roo",
  "operations": [
    {
      "type": "redline",
      "target": "Original text",
      "modified": "Updated text"
    },
    {
      "type": "comment",
      "target": "Other paragraph",
      "textToComment": "Other",
      "commentContent": "Reasoning"
    }
  ]
}

save_docx

Save the working package.

In place:

{
  "handle": "doc_..."
}

To a separate file:

{
  "handle": "doc_...",
  "outputPath": "C:/contracts/master-services-agreement-copy.docx"
}

Behavior Notes

• Each open_docx call creates an in-memory working session.
• save_docx writes back to the original file unless outputPath is supplied.
• Non-XML parts are read-only.
• write_part validates XML before accepting it.
• apply_operation and apply_operations validate the resulting package before updating the session state.
• On failure, the server rolls back the affected word/document.xml and word/comments.xml state.
• For redlines, the server preserves visible Word cross-reference output such as 9.1 or 10.6 but removes hidden field instruction scaffolding before diffing.
• Comment anchors that cross tracked insertion/deletion boundaries are rejected because Word commonly refuses to open those packages.

Logging

• Default MCP log level is warn
• Logs are written to stderr, not stdout
• To enable engine diagnostics safely:

$env:DOCX_REDLINE_MCP_LOG_LEVEL = "info"
node src/index.js

Troubleshooting

• Transport closed during a tool call:
  • check for any dependency or local logging writing to stdout
• Word rejects the saved file even though XML looks valid:
  • inspect the revised paragraph for hidden field runs (w:fldChar, w:instrText) or proofing markers (w:proofErr)
  • prefer the server redline path over direct XML surgery so the normalization step runs
• Comment operation rejected because of a tracked-change boundary:
  • re-anchor the comment to stable text outside the revised span

Test

npm test

The test suite covers:

• basic tool handler behavior
• package read/write/save
• rollback on invalid comment/revision markup
• batch operation handling
• real-DOCX diagnostic generation
• field/proofing normalization regressions

License

MIT. See LICENSE.