DOCX MCP Server

Универсальный сервер обработки DOCX, реализующий протокол Model Context Protocol (MCP) с полной поддержкой OOXML.

Возможности

• Полная поддержка OOXML: чтение/запись всех частей документа DOCX (document.xml, styles, numbering, headers/footers и т.д.)

• Текстовые операции: извлечение, поиск и замена текста с использованием литерального или регулярного режимов

• Редактирование таблиц: вставка/удаление строк и столбцов, объединение ячеек, установка содержимого ячеек

• Структурированные теги данных (SDT): получение/установка элементов управления содержимым по тегу или псевдониму

• Изображения: список изображений, вставка встроенных или плавающих изображений с управлением положением и размером

• Комментарии и изменения: список комментариев, добавление/удаление комментариев, принятие всех отслеживаемых изменений

• Свойства документа: чтение/запись метаданных (название, автор, тема и т.д.)

• LRU-кэширование: эффективное кэширование частей документа с ограничением памяти

• Stdio-транспорт: взаимодействие MCP через stdin/stdout

Установка

npm install
npm run build

Запуск

Разработка

npm run dev

Продакшн

npm start

С Claude Code

claude mcp add --scope user --transport stdio docx -- node /path/to/dist/index.js

Инструменты

Управление документами

docx.open

Открыть документ DOCX из файла или base64

{
  "docId": "uuid",
  "parts": ["word/document.xml", "word/styles.xml", ...],
  "partCount": 42,
  "props": { "core": {...}, "app": {...} }
}

docx.close

Закрыть и выгрузить документ

docx.save

Сохранить документ в файл или вернуть в формате base64

Управление частями

docx.list_parts

Вывести список всех частей документа

docx.part_read

Прочитать необработанный XML конкретной части

docx.part_write

Записать/обновить XML-содержимое части

Текстовые операции

docx.get_text

Извлечь весь текст из документа

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

docx.find

Поиск текста с контекстом

{
  "docId": "uuid",
  "query": "search term",
  "mode": "literal" | "regex"
}

docx.replace_text

Замена текста в документе

{
  "docId": "uuid",
  "match": "old text",
  "replace": "new text",
  "mode": "literal" | "regex"
}

Таблицы

docx.tables_list

Вывести список всех таблиц с размерами

{
  "tables": [
    {
      "xpath": "/w:document/w:body/w:tbl[1]",
      "rows": 3,
      "colsApprox": 4
    }
  ]
}

docx.table_edit

Изменить структуру и содержимое таблицы

{
  "docId": "uuid",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": {
    "kind": "setCellText",
    "row": 0,
    "col": 1,
    "text": "new value"
  }
}

Операции:

• setCellText(row, col, text) — установить содержимое ячейки

• insertRow(at) — вставить строку в позицию

• deleteRow(at) — удалить строку

• insertCol(at) — вставить столбец

• deleteCol(at) — удалить столбец

Структурированные данные (SDT)

docx.sdt_get

Получить содержимое элемента управления содержимым по тегу или псевдониму

docx.sdt_put

Обновить элемент управления содержимым

Изображения

docx.images_list

Вывести список всех изображений с метаданными

docx.image_add

Вставить изображение встроенно или плавающе

Стили и нумерация

docx.styles_get / docx.styles_set

Чтение/запись styles.xml

docx.numbering_get / docx.numbering_set

Чтение/запись numbering.xml

Колонтитулы

docx.headers_footers_list

Вывести список всех частей верхних и нижних колонтитулов

Комментарии

docx.comments_list

Вывести список всех комментариев

docx.comments_add

Добавить новый комментарий

docx.changes_accept_all

Принять все отслеживаемые изменения в документе

Метаданные

docx.metadata_get

Получить свойства документа (название, автор, тема, дата создания, дата изменения и т.д.)

Тестовые сценарии

1. Базовое чтение/запись

# Open document
docx.open: { "path": "/path/to/document.docx" }

# Get text
docx.get_text: { "docId": "returned-id" }

# Replace text
docx.replace_text: {
  "docId": "returned-id",
  "match": "old text",
  "replace": "new text"
}

# Save
docx.save: { "docId": "returned-id", "returnBase64": true }

2. Работа с таблицами

# List tables
docx.tables_list: { "docId": "id" }

# Edit cell
docx.table_edit: {
  "docId": "id",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": { "kind": "setCellText", "row": 0, "col": 0, "text": "Hello" }
}

3. Изображения

# List images
docx.images_list: { "docId": "id" }

4. Отслеживаемые изменения

# Accept all changes
docx.changes_accept_all: { "docId": "id" }

Архитектура

src/
  index.ts                    # Entry point
  errors.ts                   # Error definitions
  logger.ts                   # Logging utilities
  ooxml/
    namespaces.ts            # XML namespace definitions
    emu.ts                    # EMU conversion utilities
    dom.ts                    # XML DOM utilities (xmldom + fontoxpath)
    xmlParser.ts              # fast-xml-parser wrapper
    parts.ts                  # DOCX ZIP part management
    rels.ts                   # Relationships management
    text.ts                   # Text extraction & replacement
    tables.ts                 # Table operations
    sdt.ts                    # Structured Data Tags
    drawings.ts               # Images & DrawingML
    headersFooters.ts         # Headers/Footers
    styles.ts                 # Style operations
    numbering.ts              # Numbering operations
    changes.ts                # Track changes
    comments.ts               # Comments
  store/
    types.ts                  # Type definitions
    docStore.ts               # Document store + LRU cache
  mcp/
    schemas.ts                # Tool input schemas
    tools.ts                  # Tool implementations
    server.ts                 # MCP server setup

Зависимости

• @modelcontextprotocol/sdk — реализация MCP

• jszip — работа с ZIP-архивами

• fast-xml-parser — быстрый разбор XML без потерь

• @xmldom/xmldom — DOM-реализация

• fontoxpath — XPath-запросы

• diff-match-patch — сравнение текста

• lru-cache — эффективное кэширование с ограничением памяти

• uuid — генерация идентификаторов документов

Примечания по производительности

• Поддерживаются документы размером до 10 МБ

• LRU-кэш с ограничением в 100 частей и лимитом памяти 1 ГБ

• Части загружаются по требованию, а не полностью в память

• Оптимизация изменённых частей: сохраняются только изменённые части в ZIP

• Без глубокого копирования XML-структур

Ограничения

• Верхние/нижние колонтитулы: базовая поддержка (сложные структуры разделов могут потребовать ручной настройки)

• Комментарии: базовые операции список/добавление/удаление (цепочки ответов полностью не поддерживаются)

• Отслеживаемые изменения: доступно принятие всех изменений; детальный просмотр изменений ограничен

• Стили: чтение/запись полного XML; выборочное объединение стилей отсутствует

• EMU/размеры: расчёт выполняется, но фактическое отображение зависит от механизма рендеринга Word

Лицензия

MIT