How to Perform Surgical Edits on DOCX Files with Desktop Commander MCP

Desktop Commander MCP enables precise, XML-level editing of Word documents through a three-step workflow: outline inspection, raw XML extraction, and targeted block replacement.

Desktop Commander MCP treats DOCX files as structured zip archives containing XML parts rather than opaque binary blobs. This architectural choice, implemented in the DocxFileHandler class, allows developers to modify single paragraphs, table cells, or style tags without regenerating entire documents. The following guide explains the exact workflow, API calls, and source code mechanics for performing surgical edits on DOCX files.

Understanding the DOCX Handler Architecture

The DocxFileHandler in src/utils/files/docx.ts (starting at line 505) manages all DOCX interactions for the system. This handler is registered automatically by the file factory at src/utils/files/factory.ts line 54, routing any .docx request through the specialized handler rather than generic file operations.

The handler performs two core functions:

• Decompression and pretty-printing: Extracts XML from the zip archive and formats it for human readability
• Validation and repacking: Ensures edits preserve XML structure before compacting and re-archiving

The Two-Mode Read System

Desktop Commander MCP exposes two distinct read modes for DOCX files, as documented in src/server.ts at lines 401 and 835. The mode is selected automatically based on the offset parameter you provide.

Outline Mode: Finding Your Target

When offset equals 0, the handler returns a concise document outline containing headings and paragraph text. This helps you locate the specific region requiring modification without drowning in XML noise.

{
  "action": "read_file",
  "path": "/reports/quarterly.docx",
  "offset": 0,
  "length": 0
}

The outline response provides paragraph indices and text previews, enabling you to identify the exact offset value for your target content.

Raw-XML Mode: Exposing the Surgical Field

When offset is greater than 0, the handler returns pretty-printed XML fragments surrounding that position. This exposes the exact <w:t> tags and surrounding WordprocessingML structure that contain your target text.

{
  "action": "read_file",
  "path": "/reports/quarterly.docx",
  "offset": 1,
  "length": 2000
}

A typical response reveals the precise XML structure:

<w:p>
  <w:r>
    <w:t>Current revenue forecast is $12 M.</w:t>
  </w:r>
</w:p>

Capture this XML snippet exactly—it becomes the old_string parameter for your edit operation.

Executing Surgical Edits with edit_block

The edit_block tool performs XML find-and-replace operations on DOCX files. Unlike generic text replacement, it validates that both strings exist and handles XML compaction automatically before repacking the archive.

The edit operation requires three mandatory parameters:

• old_string: The exact XML snippet from your raw-XML read
• new_string: Your modified XML with the desired changes
• expected_replacements: Number of occurrences to replace (typically 1 for surgical edits)

{
  "action": "edit_block",
  "file_path": "/reports/quarterly.docx",
  "old_string": "<w:p><w:r><w:t>Current revenue forecast is $12 M.</w:t></w:r></w:p>",
  "new_string": "<w:p><w:r><w:t>Current revenue forecast is $14 M.</w:t></w:r></w:p>",
  "expected_replacements": 1
}

Validation logic around line 636 in src/utils/files/docx.ts checks for missing parameters and reports specific errors. A successful response includes "success": true and "editsApplied": 1, confirming your modification persisted to the DOCX archive.

Complete Workflow Example

The user-facing guide at skills/desktop-commander-overview/SKILL.md (lines 56-57) documents this three-call pattern in plain language:

1. Inspect: Call read_file with offset: 0 to get the document outline
2. Expose: Re-call read_file with a non-zero offset to retrieve underlying XML
3. Modify: Invoke edit_block with the captured snippet

This workflow minimizes risk by ensuring you target exactly the XML structure you inspected, with validation catching common errors like mismatched tags or missing parameters.

Key Files and Their Responsibilities

File	Purpose	Critical Lines
src/utils/files/docx.ts	Core handler: unzip, pretty-print XML, edit logic, compact, repack	505+
src/utils/files/factory.ts	Lazy handler instantiation and .docx routing	54
src/server.ts	API documentation for both DOCX modes	401, 835
skills/desktop-commander-overview/SKILL.md	User workflow documentation	56-57
README.md	High-level feature confirmation	62

Summary

• Desktop Commander MCP treats DOCX files as zip archives with XML parts, enabling precise manipulation through DocxFileHandler
• Use offset: 0 for outline inspection and offset > 0 for raw XML extraction
• The edit_block tool requires exact XML snippets and validates replacements before repacking
• All operations are reversible through version control since edits target specific, inspectable XML structures

Frequently Asked Questions

What makes DOCX editing in Desktop Commander MCP "surgical"?

Traditional DOCX libraries often require document regeneration or high-level API abstractions. Desktop Commander MCP exposes the underlying WordprocessingML, allowing you to target individual <w:t> elements, table cells, or style attributes with precision. The two-read workflow ensures you verify the exact XML structure before modifying it.

Can I break a DOCX file with edit_block?

The handler includes multiple safeguards: XML validation before repacking, parameter presence checks (line 636), and pretty-print preservation. However, malformed new_string values—such as unclosed tags or invalid WordprocessingML—can corrupt the document. Always test edits on copies and validate XML structure before applying.

Does Desktop Commander MCP support creating new DOCX files?

Yes. According to src/server.ts line 401, the system supports DOCX creation from markdown via the write_file action. This differs from edit_block, which performs XML find/replace on existing documents.

How does the factory automatically route DOCX requests?

The file factory at src/utils/files/factory.ts line 54 instantiates DocxFileHandler lazily based on file extension. Any read_file or edit_block request targeting .docx automatically uses the dedicated handler without manual configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}