doc-agent-mcp

Сервер Model Context Protocol, который предоставляет AI-агентам стабильные, семантические операции с документами — вместо того, чтобы заставлять их перетасовывать сырой текст.

Human ─────┐
           ↓
        Document          ← Markdown (.md/.markdown) and DOCX today,
           ↑                 Tiptap / SuperDoc / Shimo / Google Docs tomorrow
AI Agent ──┘

LLM-агенты, редактирующие документы как одну большую строку, ломают вещи: они портят форматирование, которое не видят, теряют изображения и комментарии и не могут выразить «вставить абзац после раздела 3». doc-agent-mcp представляет документ как нормализованную, адресуемую структуру (заголовки, абзацы, элементы списков, таблицы со стабильными ID) и позволяет агентам работать в безопасном цикле:

read  →  propose change  →  inspect diff  →  apply  →  export

Ничто не касается вашего файла, пока не вызван apply_changes. Каждое чтение принимает doc_hash, поэтому если файл изменится под агентом в середине задачи, дальнейшие правки завершатся с ошибкой (stale_document) вместо повреждения файла.

Проблема, которую это решает

Related MCP server: docx-mcp-server

Архитектура

MCP interface (13 tools)
        ↓
Document operation layer      ← staging, diffs, hashes, search, sessions
        ↓                          (doc_agent_mcp/service.py)
Normalized document model     ← Block(h-0, p-1, li-2, tbl-0), Comment,
        ↓                          ProposedChange   (core/model.py)
Backend adapters              ← parse() + serialize() per format
        ↓                          (adapters/*_adapter.py)
Markdown · DOCX · future editors (Tiptap, SuperDoc, Shimo, Google Docs)

Ключевое свойство: инструменты MCP никогда не знают, какой бэкенд под ними. Добавление нового редакторского бэкенда означает реализацию двух методов — см. ADAPTER_GUIDE.md.

Установка

Из PyPI (рекомендуется для пользователей):

pip install doc-agent-mcp

Требуется Python 3.10+.

Из исходников (для разработки):

git clone https://github.com/xyyyang97/doc-agent-mcp.git
cd doc-agent-mcp

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Проверка:

doc-agent-mcp --version
# doc-agent-mcp 0.1.0

Конфигурация MCP

Сервер говорит на стандартном MCP через stdio.

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "doc-agent": {
      "command": "/absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp",
      "args": ["--roots", "/Users/you/Documents"]
    }
  }
}

Claude Code / Codex CLI

claude mcp add doc-agent -- /absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp --roots ~/Documents

Универсальный MCP-клиент (JSON)

{
  "mcpServers": {
    "doc-agent": {
      "command": "/absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp",
      "args": [],
      "env": {}
    }
  }
}

--roots DIR [DIR ...] опционально ограничивает все чтения/записи этими каталогами (рекомендуется). Без него сервер может касаться любого пути, который доступен его процессу — относитесь к конфигурации сервера как к учётным данным файловой системы.

Доступные инструменты

Операции чтения (никогда не изменяют)

Операции предложения (этап изменения; пока ничего не записано)

Фиксация и проверка

Каждый изменяющий/читающий вызов принимает doc_hash, полученный из предыдущего вызова. Если файл изменился с тех пор (включая изменения другим процессом), вы получаете {"code": "stale_document", ...}, и ваши стадированные изменения отбрасываются — сначала перечитайте.

Пример рабочего процесса

Это точный цикл, который выполняет examples/demo_workflow.py (на реальных файлах):

from doc_agent_mcp.service import DocumentService

svc = DocumentService()                      # same facade the MCP tools wrap

# 1. Understand the document
outline = svc.get_outline("brief.md")
summary = next(h for h in outline["headings"] if h["title"] == "Executive Summary")
section = svc.read_document("brief.md", section_id=summary["id"])

# 2. Locate exact text
hit = svc.find_text("brief.md", "30 percent")["matches"][0]

# 3. Stage a change (file is untouched)
proposal = svc.propose_replace_text(
    "brief.md", hit["element_id"], hit["start"], hit["end"],
    "at least 30 percent (validated with finance)",
)

# 4. Review the diff
changes = svc.get_changes("brief.md")
print(changes["changes"][0]["diff"])

# 5. Commit, then export
svc.apply_changes("brief.md", doc_hash=proposal["doc_hash"])
svc.export_document("brief.md", "docx", output_path="brief.docx")

Через MCP те же шаги — это один вызов инструмента каждый — см. таблицу инструментов выше.

Запустите полную демонстрацию (Markdown + DOCX + экспорт + защита от устаревания, всё проверено):

.venv/bin/python examples/demo_workflow.py

Примеры документов находятся в examples/documents/: sample.md и sample.docx (последний с двумя нативными комментариями Word, воспроизводимый через scripts/make_sample_docx.py).

Обработка ошибок

Все ошибки — структурированный JSON, без traceback через провод:

{
  "code": "element_not_found",
  "message": "Element 'p-99' not found. Call get_outline ...",
  "details": {"element_id": "p-99"}
}

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

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                 # unit + integration + MCP protocol tests
.venv/bin/ruff check src tests   # lint
.venv/bin/ruff format --check .  # formatting
.venv/bin/mypy                   # strict type checking

Набор включает тесты DOCX-циклов (правки проверяются повторным открытием сохранённого файла с помощью python-docx и на уровне сырого OOXML) и сквозной MCP-тест, который запускает сервер через stdio и общается реальными сообщениями протокола.

Ограничения (по замыслу, а не случайно)

Нормализованная модель покрывает то, что Markdown и DOCX могут надёжно представлять вместе. Всё остальное явно отображается как unmodeled_features при каждом чтении — никогда не уничтожается молча:

• DOCX: изображения/рисунки, верхние и нижние колонтитулы, сноски/концевые сноски, элементы управления содержимым, отслеживаемые изменения в исходнике сохраняются нетронутыми, но невидимы для модели. Таблицы — это ячейки с обычным текстом (форматирование ячеек не моделируется). replace_text отказывается от абзацев, содержащих гиперссылки (перезапись их уничтожила бы).

• Markdown: сериализация верна модели, а не байтам — контент переживает циклы, но исходные переносы строк/стиль маркеров могут не сохраниться. Блочные цитаты уплощаются до их абзацев (помечаются). Определения ссылок в стиле reference разрешаются и встраиваются. У комментариев нет нативного дома: propose_add_comment хранит их только для сессии и сообщает об этом.

• Таблицы: доступны для поиска (помечены editable: false), но редактирование на уровне ячеек ещё не реализовано — вместо этого удаляйте и вставляйте заново.

• Конкурентные агенты: последний пишущий побеждает для каждого файла, защищено проверками хеша; механизма слияния нет.

Идеи для дорожной карты

• Операции с ячейками таблиц (update_table_cell)

• Адаптеры Tiptap/SuperDoc поверх их JSON-моделей

• Адаптер Google Docs через Drive API (комментарии отображаются нативно)

• Режим закреплённых предложений для Markdown (блоки <!-- suggestion -->)

• Многофайловые рабочие пространства и сессии, безопасные для переименования

Лицензия

MIT