ipe-mcp

ipe-mcp ist ein local-first, host-agnostischer MCP-Server in der Entwicklung, der das Erstellen, Bearbeiten, Validieren und Rendern editierbarer Ipe-Dokumente und Präsentationen durch KI-Agenten ermöglicht.

Das Projekt kombiniert ein versioniertes semantisches Dokumentmodell mit deterministischem Ipe-XML und nativer Ipe-Validierung. Die Basis bilden Ipe 7.2.30 und das XML-Format 70218. Die anfängliche Zielumgebung ist Ubuntu 26.04 unter WSL.

[!IMPORTANT] Dieses Repository ist pre-MVP. Die Meilensteine M0–M3 sind abgeschlossen und umfassen Kompatibilitätsverträge, das Konformitätslabor, das semantische IR, transaktionale Persistenz, Koordinaten und Layout. Der stdio-MCP-Server ist für M8 geplant, daher ist das Repository noch keine installierbare MCP-Integration.

Ziele

• Agents semantische Operationen für Seiten, Ebenen, Ansichten, Objekte, Stile, Layout, Einblendungen und Export bieten, ohne dass sie rohes XML manipulieren müssen.

• Die Bearbeitbarkeit und die unterstützten Ipe-Inhalte über Parsing, Mutation, Speichern, erneutes Laden in nativem Ipe und Wiederherstellung hinweg erhalten.

• Ebenen, Zeichenreihenfolge und Präsentationsansichten als getrennte Konzepte beibehalten.

• Jede Mutation revisionssicher, atomar, validiert und wiederherstellbar machen.

• Codex und andere MCP-Hosts über hostneutrale Verträge unterstützen.

• .ipe-, PDF- und Raster-Vorschauartefakte mit expliziter Validierung und Kompatibilitätsdiagnosen erzeugen.

Related MCP server: docx-mcp-server

Aktueller Stand

Den vollständigen Umfang, die Gates, Risiken und Designentscheidungen finden Sie in der Roadmap.

Architektur

Die Implementierung ist um einige strikte Grenzen organisiert:

Agent or MCP host
        |
        v
Semantic operations and layout
        |
        v
Versioned document IR
        |
        +--> transactional session and sidecar
        |
        v
Deterministic Ipe XML codec
        |
        v
Ipe 7.2.30 native validation, rendering, and export

Die reguläre API stellt typisierte Dokumentoperationen bereit, nicht beliebiges XML. Native Ipe-Werkzeuge bleiben maßgeblich für Verhaltensweisen, die nicht strukturell validiert werden können, einschließlich Stilauflösung, LaTeX, Rendering und Export.

Wichtige Quellbereiche:

• src/domain: semantisches IR, Schemas, Validierung und stabile Identitäten;

• src/ipe/xml: deterministischer Parser, Projektor und Serialisierer;

• src/persistence: begrenzte Lesevorgänge, atomare Schreibvorgänge, Sitzungen, Snapshots und Sidecars;

• src/layout: Koordinatenräume, Matrizen, Anker, Constraints, Layout und Konnektoren;

• fixtures/conformance: Dokumente und Golddaten für den Vergleich mit nativem Ipe.

Voraussetzungen

• Node.js 20 oder höher;

• npm;

• Ipe 7.2.30 für den unterstützten Vollvalidierungspfad;

• pdfLaTeX für die Textkompilierung und native Rendering-Workflows.

Die verifizierte Umgebung verwendet das Ubuntu-Paket ipe 7.2.30-1build2 unter Ubuntu 26.04 WSL. Befolgen Sie SETUP-WSL.md für die Installation und die Verifizierung der nativen Werkzeuge.

Entwicklungsumgebung

git clone https://github.com/Mik1810/ipe-mcp.git
cd ipe-mcp
npm ci
npm run build
npm test

Das Paket ist derzeit privat und bietet weder eine veröffentlichte ausführbare Datei noch einen Einstiegspunkt für einen MCP-Server.

Verifikation

Führen Sie die Meilenstein-Gates aus dem Stammverzeichnis des Repository aus:

bash scripts/check-m0.sh
bash scripts/check-m1.sh
bash scripts/check-m2.sh
bash scripts/check-m3.sh

Die Gates bauen aufeinander auf und umfassen Strukturprüfungen, native Ipe-Round-Trips, semantische Fixpunkte, Persistenz, numerisches Verhalten und Layout-Fixtures. M1 unterstützt außerdem eine optionale Source-Build-Lane:

IPE_M1_SOURCE_BIN_DIR=/path/to/ipe/build/bin bash scripts/check-m1.sh

Ohne diese Variable wird das verifizierte Ubuntu-Paket verwendet und die optionale Source-Lane als übersprungen gemeldet.

Kompatibilitätsmodi

Das Design unterscheidet drei explizite Modi:

• structural-only: Parsen, Inspizieren und Generieren mit strukturellen Diagnosen, ohne native Verifizierung zu beanspruchen;

• full 7.2.30: der unterstützte Release-Pfad mit nativer Validierung;

• nightly 7.3.x: experimentelle Kompatibilität, niemals verwendet, um ein stabiles Dokument ohne Zustimmung neu zu schreiben.

Siehe docs/compatibility-modes.md für die genaue Fähigkeiten- und Fehlermatrix.

Dokumentation

• ROADMAP.md: Architektur, Meilensteine, Gates und zukünftige Arbeiten;

• docs/adr: akzeptierte Architekturentscheidungen;

• docs/conformance-m1.md: natives Konformitätslabor;

• docs/core-m2.md: IR, XML, Identität und Persistenz;

• docs/core-m3.md: Koordinaten und Layout;

• report-source.md: Quelldossier und Rückverfolgbarkeit;

• ORCHESTRATOR_PROMPT.md: Meilenstein-Ausführung und Review-Protokoll.

Projektprinzipien

• Das Originaldokument niemals vor einem expliziten Speichern verändern.

• Jede Top-Level-Objektebene und jede serialisierungsempfindliche Standardeinstellung explizit behandeln.

• Semantisch und mit nativem Ipe validieren; das bloße Öffnen einer Datei ist kein ausreichendes Gate.

• Unbekannte unterstützte Inhalte so weit wie möglich bewahren und jedes beeinträchtigte Verhalten melden.

• Protokollverträge unabhängig von Codex-spezifischen Prompts, Skills oder UI-Direktiven halten.