# DOCX MCP Server

A comprehensive TypeScript-based MCP (Model Context Protocol) server for universal DOCX processing with full OOXML support. Process Word documents programmatically with support for text, tables, images, headers/footers, SDTs, comments, and more.

## Features

- **Complete OOXML Access**: Read/write DOCX parts at ZIP level with full namespace support
- **Text Operations**: Extract, find, and replace text with minimal diff preservation
- **Table Management**: Insert/delete rows, modify cells, merge/split operations
- **Image Handling**: Add inline/positioned images with EMU-based sizing
- **Structured Data Tags (SDT)**: Access content controls by tag or alias
- **Headers/Footers**: List and modify section headers and footers
- **Track Changes**: Accept/reject revisions, handle insertions/deletions
- **Comments**: Manage document comments
- **Metadata**: Read/write core and app properties
- **LRU Caching**: Efficient memory management with part caching
- **Lossless XML**: Preserves document structure with fast-xml-parser

## Installation

```bash
npm install
npm run build
```

## Quick Start

### Start the Server

```bash
npm start
```

The server will listen on stdin/stdout for MCP protocol messages.

### Installation & Configuration

#### Claude Code CLI

```bash
claude mcp install docx \
  --command node \
  --args /full/path/to/docx_mcp_server_ts/dist/index.js \
  --env LOG_LEVEL=INFO
```

#### ~/.claude.json (для Claude Code)

Отредактировать `~/.claude.json` добавить в раздел `"projects"`:

```json
{
  "projects": {
    "/full/path/to/docx_mcp_server_ts": {
      "mcpServers": {
        "docx": {
          "command": "node",
          "args": ["/full/path/to/docx_mcp_server_ts/dist/index.js"],
          "env": {
            "LOG_LEVEL": "INFO"
          }
        }
      }
    }
  }
}
```

**Пример для Linux/WSL:**
```json
{
  "projects": {
    "/mnt/c/Users/pavelk/Desktop/Projects/MCP-servers/docx_mcp_server_ts": {
      "mcpServers": {
        "docx": {
          "command": "node",
          "args": ["/mnt/c/Users/pavelk/Desktop/Projects/MCP-servers/docx_mcp_server_ts/dist/index.js"],
          "env": {
            "LOG_LEVEL": "INFO"
          }
        }
      }
    }
  }
}
```

## MCP Tools

### Document Management

#### `docx.open`
Open a DOCX document from file or base64 buffer.

**Input:**
```json
{
  "path": "/path/to/document.docx",
  "bufferBase64": "..."  // OR provide base64 data
}
```

**Output:**
```json
{
  "docId": "uuid-string",
  "parts": ["word/document.xml", ...],
  "props": { "core": {}, "app": {} }
}
```

#### `docx.close`
Close a document and release resources.

**Input:** `{ "docId": "uuid" }`

#### `docx.save`
Save document to file or return as base64.

**Input:**
```json
{
  "docId": "uuid",
  "path": "/output/path.docx",  // optional
  "returnBase64": true  // optional
}
```

#### `docx.list_parts`
List all parts in document.

#### `docx.part_read` / `docx.part_write`
Read/write individual XML parts for low-level access.

### Text Operations

#### `docx.get_text`
Extract all text from document.

**Input:** `{ "docId": "uuid", "scope": "document|headers|footers|all" }`

#### `docx.replace_text`
Replace text preserving run structure.

**Input:**
```json
{
  "docId": "uuid",
  "match": "search text",
  "replace": "replacement",
  "mode": "literal|regex",
  "where": "document|headers|footers|all"
}
```

**Output:** `{ "replaced": 5 }`

#### `docx.find`
Find text with context.

**Output:**
```json
{
  "hits": [
    {
      "text": "found text",
      "context": "...found text...",
      "offset": 150
    }
  ]
}
```

### Table Operations

#### `docx.tables_list`
List all tables with dimensions.

**Output:**
```json
{
  "tables": [
    {
      "tableXPath": "//w:tbl[1]",
      "rows": 5,
      "colsApprox": 3
    }
  ]
}
```

#### `docx.table_edit`
Perform table operations.

**Input:**
```json
{
  "docId": "uuid",
  "tableXPath": "//w:tbl[1]",
  "op": {
    "kind": "setCellText",
    "row": 0,
    "col": 0,
    "text": "new value"
  }
}
```

**Supported operations:**
- `{ "kind": "setCellText", "row": number, "col": number, "text": string }`
- `{ "kind": "insertRow", "at": number }`
- `{ "kind": "deleteRow", "at": number }`
- `{ "kind": "insertCol", "at": number }`
- `{ "kind": "deleteCol", "at": number }`

### Structured Data Tags (SDT)

#### `docx.sdt_get`
Get content control content.

**Input:** `{ "docId": "uuid", "tagOrAlias": "control_tag" }`

**Output:**
```json
{
  "xml": "<w:p>...</w:p>",
  "textPreview": "Control content..."
}
```

#### `docx.sdt_put`
Update content control.

**Input:**
```json
{
  "docId": "uuid",
  "tagOrAlias": "control_tag",
  "xmlFragment": "<w:p>...</w:p>"
}
```

### Image Operations

#### `docx.images_list`
List all images with metadata.

**Output:**
```json
{
  "images": [
    {
      "rId": "rId4",
      "path": "word/media/image1.png",
      "sizeEMU": { "cx": 914400, "cy": 914400 }
    }
  ]
}
```

#### `docx.image_add`
Insert image inline or anchored.

**Input:**
```json
{
  "docId": "uuid",
  "target": {
    "afterParagraphXPath": "//w:p[1]",
    "sdtTagOrAlias": "imageControl"  // OR use SDT
  },
  "image": {
    "path": "/local/image.png",
    "base64": "...",  // OR base64 data
    "filename": "image.png",
    "contentType": "image/png"
  },
  "placement": {
    "kind": "inline"  // OR { "kind": "anchor", "xEMU": 0, "yEMU": 0 }
  },
  "size": {
    "widthMM": 50,
    "heightMM": 50
  },
  "altText": "Description"
}
```

#### `docx.image_update_position`
Update anchored image position/size.

### Advanced Operations

#### `docx.styles_get` / `docx.styles_set`
Read/write styles.xml

#### `docx.numbering_get` / `docx.numbering_set`
Read/write numbering.xml

#### `docx.headers_footers_list`
List headers and footers with section info.

#### `docx.headers_footers_get` / `docx.headers_footers_set`
Read/write specific header or footer.

#### `docx.comments_list` / `docx.comments_add` / `docx.comments_delete`
Manage document comments.

#### `docx.changes_accept_all`
Accept all tracked changes (remove w:del, unwrap w:ins).

**Output:** `{ "removedDel": 3, "flattenedIns": 5 }`

#### `docx.metadata_get` / `docx.metadata_set`
Read/write document properties (core.xml, app.xml).

## Size Conversions

The server handles EMU (English Metric Unit) conversions internally:
- 1 inch = 914,400 EMU
- 1 mm ≈ 36,000 EMU
- 1 point ≈ 12,700 EMU

## Examples

### Extract and Replace Text

```javascript
// Open document
const openResult = await client.call('docx.open', {
  path: '/tmp/document.docx'
});
const docId = openResult.docId;

// Get text
const textResult = await client.call('docx.get_text', { docId });
console.log(textResult.text);

// Replace text
await client.call('docx.replace_text', {
  docId,
  match: 'old text',
  replace: 'new text',
  mode: 'literal'
});

// Save
await client.call('docx.save', {
  docId,
  path: '/tmp/document-modified.docx'
});

// Close
await client.call('docx.close', { docId });
```

### Modify Table

```javascript
// List tables
const tablesResult = await client.call('docx.tables_list', { docId });
const tableXPath = tablesResult.tables[0].tableXPath;

// Update cell
await client.call('docx.table_edit', {
  docId,
  tableXPath,
  op: {
    kind: 'setCellText',
    row: 0,
    col: 0,
    text: 'Updated Value'
  }
});

// Insert row
await client.call('docx.table_edit', {
  docId,
  tableXPath,
  op: {
    kind: 'insertRow',
    at: 1
  }
});
```

### Add Image

```javascript
const fs = require('fs').promises;

const imageBuffer = await fs.readFile('/path/to/image.png');
const base64 = imageBuffer.toString('base64');

await client.call('docx.image_add', {
  docId,
  target: {
    afterParagraphXPath: '//w:p[1]'
  },
  image: {
    base64,
    filename: 'image.png',
    contentType: 'image/png'
  },
  placement: {
    kind: 'inline'
  },
  size: {
    widthMM: 100,
    heightMM: 75
  },
  altText: 'My image'
});
```

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── logger.ts             # Logging utility
├── errors.ts             # Error types and codes
├── ooxml/
│   ├── namespaces.ts     # OOXML constants and namespaces
│   ├── emu.ts            # Unit conversion utilities
│   ├── dom.ts            # XML DOM utilities (xmldom + fontoxpath)
│   ├── xmlParser.ts      # FXP parser with order preservation
│   ├── parts.ts          # ZIP part reading/writing
│   ├── rels.ts           # Relationship management
│   ├── text.ts           # Text operations with diff-match-patch
│   ├── tables.ts         # Table manipulation
│   ├── sdt.ts            # Structured Data Tags
│   ├── drawings.ts       # Image handling
│   ├── headersFooters.ts # Header/footer operations
│   ├── comments.ts       # Comment management
│   ├── changes.ts        # Track changes handling
│   ├── styles.ts         # Styles XML access
│   └── numbering.ts      # Numbering XML access
├── store/
│   ├── types.ts          # Store type definitions
│   └── docStore.ts       # Document store with LRU cache
└── mcp/
    └── tools.ts          # MCP tool implementations
```

## Performance

- **Memory**: LRU cache limits per-document parts to 50 cached items
- **Total Size**: Supports documents up to 100MB in-memory
- **Partial Access**: Only requested parts are parsed from ZIP
- **Minimal Diffs**: Text replacements preserve run structure when possible

## Limitations

- Page layout calculations are not performed (Word's rendering engine needed)
- Advanced DrawingML transformations are read-only
- VBA macros and embedded OLE objects not supported
- Extremely large documents (>500MB) may require streaming

## Development

```bash
# Install dependencies
npm install

# Type check
npm run type-check

# Build
npm run build

# Run dev server
npm run dev

# Debug with inspector
npm run dev:debug
```

## Logging

Control log level via environment variable:
```bash
LOG_LEVEL=DEBUG npm start     # Verbose
LOG_LEVEL=INFO npm start      # Default
LOG_LEVEL=WARN npm start      # Warnings only
LOG_LEVEL=ERROR npm start     # Errors only
```

## Protocol Support

- **Transport**: stdio
- **Protocol**: MCP (Model Context Protocol)
- **Handler**: @modelcontextprotocol/sdk

## License

MIT

## Resources

- [OOXML Standard](http://www.ecma-international.org/publications/standards/Ecma-376.htm)
- [DrawingML Reference](https://docs.microsoft.com/en-us/office/open-xml/drawingml)
- [jszip](https://stuk.github.io/jszip/)
- [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser)
- [fontoxpath](https://github.com/FontoXML/fontoxpath)