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

> Perform surgical edits on DOCX files with Desktop Commander MCP. Inspect outline, extract XML, and replace blocks for precise document control.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.

```json
{
  "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.

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

```

A typical response reveals the precise XML structure:

```xml
<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)

```json
{
  "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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/files/docx.ts) | Core handler: unzip, pretty-print XML, edit logic, compact, repack | 505+ |
| [`src/utils/files/factory.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/files/factory.ts) | Lazy handler instantiation and `.docx` routing | 54 |
| [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) | API documentation for both DOCX modes | 401, 835 |
| [`skills/desktop-commander-overview/SKILL.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/skills/desktop-commander-overview/SKILL.md) | User workflow documentation | 56-57 |
| [`README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.