doc-agent-mcp

Ein Model Context Protocol-Server, der KI-Agenten stabile, semantische Operationen auf Dokumenten bietet – anstatt sie rohen Text hin- und herschieben zu lassen.

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

LLM-Agenten, die Dokumente als einen großen String bearbeiten, zerstören Dinge: Sie verunstalten Formatierungen, die sie nicht sehen können, verlieren Bilder und Kommentare und können nicht ausdrücken „einen Absatz nach Abschnitt 3 einfügen“. doc-agent-mcp stellt das Dokument als normalisierte, adressierbare Struktur dar (Überschriften, Absätze, Listenelemente, Tabellen mit stabilen IDs) und ermöglicht Agenten, in einer sicheren Schleife zu arbeiten:

read  →  propose change  →  inspect diff  →  apply  →  export

Nichts berührt Ihre Datei, bis apply_changes aufgerufen wird. Jeder Lesevorgang akzeptiert einen doc_hash, sodass, wenn sich die Datei während der Aufgabe unter dem Agenten ändert, weitere Bearbeitungen lautstark fehlschlagen (stale_document), anstatt die Datei zu beschädigen.

Das Problem, das dies löst

Related MCP server: docx-mcp-server

Architektur

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)

Wichtige Eigenschaft: Die MCP-Tools wissen nie, welches Backend darunterliegt. Das Hinzufügen eines neuen Editor-Backends bedeutet, zwei Methoden zu implementieren – siehe ADAPTER_GUIDE.md.

Installation

Von PyPI (empfohlen für Benutzer):

pip install doc-agent-mcp

Erfordert Python 3.10+.

Aus dem Quellcode (Entwicklung):

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

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

Überprüfen:

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

MCP-Konfiguration

Der Server spricht standardmäßiges MCP über 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

Generischer MCP-Client (JSON)

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

--roots DIR [DIR ...] schränkt optional alle Lese-/Schreibvorgänge auf diese Verzeichnisse ein (empfohlen). Ohne diese Option kann der Server jeden Pfad berühren, den sein Prozess erreichen kann – behandeln Sie die Serverkonfiguration wie Dateisystem-Anmeldeinformationen.

Verfügbare Tools

Leseoperationen (mutieren nie)

Vorschlagsoperationen (Änderung stufen; noch nichts geschrieben)

Committen & Überprüfen

Jeder mutierende/Lese-Aufruf akzeptiert den doc_hash, den Sie vom vorherigen Aufruf erhalten haben. Wenn sich die Datei seitdem geändert hat (auch durch einen anderen Prozess), erhalten Sie {"code": "stale_document", ...} und Ihre bereitgestellten Änderungen werden verworfen – lesen Sie zuerst erneut.

Beispiel-Workflow

Dies ist die exakte Schleife, die examples/demo_workflow.py ausführt (gegen echte Dateien):

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

Über MCP sind dieselben Schritte jeweils ein Tool-Aufruf – siehe Tool-Tabelle oben.

Führen Sie die vollständige Demo aus (Markdown + DOCX + Export + Stale-Guard, alles verifiziert):

.venv/bin/python examples/demo_workflow.py

Beispieldokumente befinden sich in examples/documents/: sample.md und sample.docx (letzteres mit zwei nativen Word-Kommentaren, regenerierbar über scripts/make_sample_docx.py).

Fehlerbehandlung

Alle Fehler sind strukturiertes JSON – keine Tracebacks über die Leitung:

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

Testen

.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

Die Suite enthält DOCX-Roundtrip-Tests (Bearbeitungen werden durch erneutes Öffnen der gespeicherten Datei mit python-docx und auf roher OOXML-Ebene verifiziert) sowie einen End-to-End-MCP-Test, der den Server über stdio startet und echte Protokollnachrichten spricht.

Einschränkungen (mit Absicht, nicht aus Versehen)

Das normalisierte Modell deckt ab, was Markdown und DOCX zuverlässig darstellen können. Alles andere wird explizit als unmodeled_features bei jedem Lesevorgang angezeigt – nie stillschweigend zerstört:

• DOCX: Bilder/Zeichnungen, Kopf- und Fußzeilen, Fußnoten/Endnoten, Inhaltssteuerelemente, nachverfolgte Änderungen in der Quelle werden unberührt erhalten, sind aber für das Modell unsichtbar. Tabellen sind reine Textzellen (Zellenformatierung nicht modelliert). replace_text lehnt Absätze mit Hyperlinks ab (die Umschreibung würde sie zerstören).

• Markdown: Die Serialisierung ist modelltreu, nicht bytetreu – Inhalte überleben Roundtrips, die ursprüngliche Zeilenumbruch-/Markierungsstil kann es nicht. Blockzitate werden auf ihre Absätze reduziert (gekennzeichnet). Referenzstil-Linkdefinitionen werden aufgelöst und inline eingefügt. Kommentare haben keine native Heimat: propose_add_comment speichert sie nur für die Sitzung und weist darauf hin.

• Tabellen: durchsuchbar (als editable: false gekennzeichnet), aber Zellenebene-Bearbeitung ist noch nicht implementiert – stattdessen löschen/neu einfügen.

• Gleichzeitige Agenten: Letzter Schreiber gewinnt pro Datei, abgesichert durch Hash-Prüfungen; es gibt keine Merge-Engine.

Roadmap-Ideen

• Tabellenzellen-Operationen (update_table_cell)

• Tiptap/SuperDoc-Adapter über ihre JSON-Modelle

• Google-Docs-Adapter über Drive-API (Kommentare werden nativ abgebildet)

• Verankerter Vorschlagsmodus für Markdown (<!-- suggestion -->-Blöcke)

• Multi-Datei-Arbeitsbereiche und umbenennungssichere Sitzungen

Lizenz

MIT