doc-agent-mcp

Un servidor de Model Context Protocol que brinda a los agentes de IA operaciones estables y semánticas sobre documentos, en lugar de hacer que manipulen texto sin formato.

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

Los agentes LLM que editan documentos como una gran cadena de texto rompen cosas: estropean el formato que no pueden ver, pierden imágenes y comentarios, y no pueden expresar "insertar un párrafo después de la sección 3". doc-agent-mcp expone el documento como una estructura normalizada y direccionable (encabezados, párrafos, elementos de lista, tablas con IDs estables) y permite que los agentes trabajen en un bucle seguro:

read  →  propose change  →  inspect diff  →  apply  →  export

Nada toca tu archivo hasta que se llama a apply_changes. Cada lectura acepta un doc_hash, de modo que si el archivo cambia debajo del agente a mitad de tarea, las ediciones posteriores fallan de forma ruidosa (stale_document) en lugar de corromper el archivo.

El problema que esto resuelve

Related MCP server: docx-mcp-server

Arquitectura

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)

Propiedad clave: las herramientas MCP nunca saben qué backend hay debajo. Agregar un nuevo backend de edición significa implementar dos métodos — ver ADAPTER_GUIDE.md.

Instalación

Desde PyPI (recomendado para usuarios):

pip install doc-agent-mcp

Requiere Python 3.10+.

Desde el código fuente (desarrollo):

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

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

Verificar:

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

Configuración de MCP

El servidor habla MCP estándar sobre 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

Cliente MCP genérico (JSON)

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

--roots DIR [DIR ...] opcionalmente restringe todas las lecturas/escrituras a esos directorios (recomendado). Sin él, el servidor puede tocar cualquier ruta que su proceso pueda alcanzar — trata la configuración del servidor como credenciales del sistema de archivos.

Herramientas disponibles

Operaciones de lectura (nunca mutan)

Operaciones de propuesta (preparan un cambio; nada se escribe aún)

Confirmar y revisar

Cada llamada de mutación/lectura acepta el doc_hash que obtuviste de la llamada anterior. Si el archivo cambió desde entonces (incluso por otro proceso), obtienes {"code": "stale_document", ...} y tus cambios preparados se descartan — vuelve a leer primero.

Ejemplo de flujo de trabajo

Este es el bucle exacto que ejecuta examples/demo_workflow.py (contra archivos reales):

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")

Sobre MCP, los mismos pasos son una llamada de herramienta cada uno — ver la tabla de herramientas anterior.

Ejecuta la demo completa (Markdown + DOCX + exportación + guardia de obsoleto, todo verificado):

.venv/bin/python examples/demo_workflow.py

Los documentos de muestra viven en examples/documents/: sample.md y sample.docx (este último con dos comentarios nativos de Word, regenerables mediante scripts/make_sample_docx.py).

Manejo de errores

Todos los errores son JSON estructurado — sin tracebacks a través del cable:

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

Pruebas

.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

La suite incluye pruebas de ida y vuelta de DOCX (ediciones verificadas al reabrir el archivo guardado con python-docx y a nivel de OOXML crudo) y una prueba MCP de extremo a extremo que inicia el servidor sobre stdio y habla mensajes de protocolo reales.

Limitaciones (por diseño, no por accidente)

El modelo normalizado cubre lo que Markdown y DOCX pueden representar de manera confiable. Todo lo demás se expone explícitamente como unmodeled_features en cada lectura — nunca se destruye silenciosamente:

• DOCX: imágenes/dibujos, encabezados y pies de página, notas al pie/finales, controles de contenido, cambios rastreados presentes en la fuente se conservan intactos pero invisibles para el modelo. Las tablas son celdas de texto plano (el formato de celda no se modela). replace_text rechaza párrafos que contienen hipervínculos (la reescritura los destruiría).

• Markdown: la serialización es fiel al modelo, no fiel al byte — el contenido sobrevive a los viajes de ida y vuelta, el ajuste de línea original/estilo de marcador puede no sobrevivir. Las citas en bloque se aplanan a sus párrafos (marcadas). Las definiciones de enlaces de estilo referencia se resuelven y se insertan en línea. Los comentarios no tienen hogar nativo: propose_add_comment los almacena solo de sesión y lo dice.

• Tablas: buscables (marcadas editable: false) pero la edición a nivel de celda no está implementada aún — eliminar/reinsertar en su lugar.

• Agentes concurrentes: el último escritor gana por archivo, protegido por verificaciones de hash; no hay motor de fusión.

Ideas de hoja de ruta

• Operaciones de celda de tabla (update_table_cell)

• Adaptadores Tiptap/SuperDoc sobre sus modelos JSON

• Adaptador de Google Docs mediante la API de Drive (los comentarios se mapean de forma nativa)

• Modo de sugerencias ancladas para Markdown (bloques <!-- suggestion -->)

• Espacios de trabajo de múltiples archivos y sesiones seguras para renombrar

Licencia

MIT