bizagi-mcp

Verwandeln Sie eine Prozessbeschreibung in ein BPMN-2.0-Diagramm, das sich sauber in Bizagi Modeler öffnen lässt.

Ein MCP-Server, der BPMN-2.0-Diagramme erzeugt, liest, prüft und als Vorschau darstellt – und die Bizagi-Modeler-Desktop-App unter Windows steuert.

Erzeugt aus einer 60-zeiligen JSON-Spezifikation. Jede Koordinate oben wurde berechnet, nicht von Hand platziert.

Warum es das gibt

Bizagi Modeler hat keine Skript-API. Der einzige Integrationspfad, den es unterstützt, ist das offene BPMN-2.0-XML-Format über die Registerkarte Export / Import.

Aber es gibt einen Haken, der naive Generierung nutzlos macht: Bizagi importiert die in der Datei geschriebenen Koordinaten wörtlich. Es legt kein Diagramm für Sie an. Wenn Sie eine strukturell perfekte BPMN-Datei ohne Geometrie ausgeben, öffnet sie sich als ein Haufen übereinander gestapelter Boxen am Ursprung.

Der schwierige Teil dieses Servers ist also nicht das XML. Es ist das Layout.

Related MCP server: camunda-mcp

Was er tut

Die ersten acht sind reines Python und laufen auf jedem Betriebssystem, mit oder ohne installiertem Bizagi. Nur die vier bizagi_*-Tools benötigen Windows.

Die Layout-Engine

Ein bahnbewusstes, geschichtetes Layout, in der Reihenfolge, in der es läuft:

1. Zyklen aufbrechen, damit der Graph überhaupt geschichtet werden kann

2. Längster-Pfad-Schichtung → die horizontale Spalte jedes Knotens

3. Baryzentrum-Ordnung pro (Spalte, Bahn) → weniger sich kreuzende Linien

4. Adaptive Bahnhöhen, dimensioniert auf die höchste Zelle, die jedes Band enthält

5. Reservierte Streifen – ein Umgehungsband entlang der Oberseite jeder Bahn, die einen spaltenüberspringenden Zweig trägt, und ein Kanalstreifen am unteren Rand für Rückschleifen

6. Orthogonales Routing, das um Hindernisse herumgeht statt durch sie hindurch

7. Label-Trennung als letzter Durchgang

Was es garantiert

Das sind keine Wunschvorstellungen. Jede einzelne ist ein Test, der fehlschlägt, wenn die Regel entfernt wird:

• Keine zwei Formen überlappen sich

• Keine Kante wird durch eine Form gezeichnet, die nicht ihr eigener Endpunkt ist

• Jedes Element sitzt innerhalb seines Pools

• Nachrichtenflüsse verlaufen im leeren Korridor zwischen den Pools, niemals horizontal durch einen Pool

• Jeder Nachrichtenfluss bekommt seine eigene Linie in diesem Korridor, und der Korridor wird danach dimensioniert, wie viele Flüsse ihn kreuzen – so stapeln sich ihre Labels nicht

• Rückschleifen bekommen jeweils ihren eigenen Kanal in einem Streifen, der reserviert wird, während die Bahnen dimensioniert werden

• Ein Zweig, der Spalten überspringt, macht einen Umweg innerhalb seiner eigenen Bahn, über die Aktivitäten, die er überspringt

• Die Zweige eines Gateways verlassen es an sichtbar unterschiedlichen Punkten, sodass eine Zwei-Wege-Verzweigung nicht wie ein einzelner Pfeil wirkt

• Randereignis-Flüsse verlaufen nach unten, nie zurück durch die Host-Aktivität

• Anmerkungen und Datenspeicher liegen neben dem, was sie beschreiben – oder, wenn sie keine Assoziation haben, innerhalb des Pools, den sie deklarieren, statt außerhalb der Zeichenfläche

• Kein Label wird über ein anderes Label oder über eine Form geschrieben

Designhinweise

Ein paar Entscheidungen, die leicht falsch gemacht werden:

• Ein Label ist so breit wie sein Text. Wenn man für jedes Label eine flache Box reserviert, werden Kollisionen zwischen den langen Labels für alles, was die reservierte Box misst, unsichtbar.

• Reservierter Raum muss aus der Zentrierung herausgehalten werden. Wenn man eine Bahn vergrößert, um Platz für einen Kanal zu schaffen, und dann die Formen darin zentriert, wird die Hälfte des neuen Raums als Polsterung nach oben zurückgegeben – der Kanal wird am Ende zu dünn, um ihn zu nutzen.

• Ein Umweg gehört in die Lücken zwischen den Formen, nicht um alle herum. Wenn man über oder unter allem routet, landet die Linie außerhalb des Pools, und die Vertikalen, die sie erreichen, kreuzen dann jede Bahn auf dem Weg.

• Ein Datenspeicher kann mit vielen Aktivitäten assoziiert sein, sitzt aber neben einer. Wenn man ihn für jede Assoziation einmal platziert, bleiben Löcher in den Bahnen, wo die früheren Platzierungen waren.

Installation

pip install -e .

Für die Windows-Desktop-Tools:

pip install -e ".[desktop]"

Python ≥ 3.10.

Bei Claude registrieren

claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "bizagi-modeler": {
      "command": "bizagi-mcp",
      "env": {
        "BIZAGI_MCP_ROOT": "C:\\Users\\you\\Documents\\Bizagi"
      }
    }
  }
}

Wenn bizagi-mcp nicht im PATH ist:

{
  "mcpServers": {
    "bizagi-modeler": {
      "command": "python",
      "args": ["-m", "bizagi_mcp.server"],
      "env": { "BIZAGI_MCP_ROOT": "C:\\Users\\you\\Documents\\Bizagi" }
    }
  }
}

Für Claude Code: claude mcp add bizagi-modeler -- bizagi-mcp

Umgebungsvariablen

Verwendung

Ein Diagramm erzeugen

„Modellieren Sie einen Urlaubsantrag: Der Mitarbeiter reicht ihn ein, der Vorgesetzte genehmigt oder lehnt ihn ab, die Personalabteilung erfasst das Ergebnis. Speichern Sie ihn unter D:\Prozesse\urlaub.bpmn."

Dann in Bizagi Modeler: Export / Import ▸ Import ▸ BPMN.

Ein vorhandenes Modell analysieren

Exportieren Sie zuerst aus Bizagi (Export / Import ▸ Export ▸ BPMN), dann:

„Lesen Sie D:\Prozesse\einkauf.bpmn, führen Sie mich durch und sagen Sie mir, was daran falsch ist."

Beispiel

Siehe examples/purchase_request.json (die Spezifikation), .bpmn (erzeugt) und .svg (Vorschau).

Validierungsregeln

Struktur (BPMN001–BPMN020, Schweregrad error / warning)

Fehlende Start- oder Endereignisse · nicht erreichbare Elemente · Sackgassen · Sequenzflüsse, die Pools kreuzen · Nachrichtenflüsse innerhalb eines Pools · Gateways, die ohne Bedingungen verzweigen · Ziele ereignisbasierter Gateways · implizite Verzweigung und Zusammenführung · Randereignisse an Nicht-Aktivitäten · doppelte IDs · ein Standardfluss, der auch eine Bedingung trägt · Gateways mit einem Eingang und einem Ausgang.

Konventionen (BP001–BP017, Schweregrad warning / info)

Benennung von Aktivitäten (Verb + Objekt) · Gateways nicht als Fragen formuliert · unbeschriftete Zweige · Dokumentationsabdeckung · Pools ohne Bahnen · leere Bahnen · Diagrammgröße · doppelte Namen · Pools, die nie Nachrichten austauschen.

Jeder Befund nennt das betroffene Element und den konkreten Schritt zur Behebung.

Steuerung der Desktop-App

bizagi_open ist der zuverlässige Weg: Modeler akzeptiert eine Datei als Befehlszeilenargument, sodass kein Menü gesteuert werden muss.

bizagi_import_bpmn steuert das Menüband und ist dabei ehrlich:

• Es beansprucht den Vordergrund und verifiziert, dass es ihn bekommen hat. Windows verweigert SetForegroundWindow einem Prozess, der nicht den Vordergrund besitzt, und set_focus() kehrt so zurück, als hätte es funktioniert – wenn man trotzdem klickt, wird ein echter Mausklick in das gesendet, woran der Benutzer gerade arbeitet.

• Es zählt die Diagramm-Registerkarten vorher und nachher und meldet imported: true / false anhand dieser Beweise, nicht aus Hoffnung.

• Beide Zählungen werden bei angehobenem Fenster durchgeführt, weil ein Fenster, das dahinter liegt, einen unvollständigen Barrierefreiheitsbaum zurückgeben kann.

Es gibt keinen Hintergrundmodus

Der Import kann nicht laufen, während der Rechner für etwas anderes verwendet wird. Drei Wege wurden gegen Modeler 4.3.0.008 getestet, und alle drei sind verschlossen:

Das Menüband reagiert nur auf echte Mauseingaben in einem fokussierten Fenster. Für unbeaufsichtigte Läufe geben Sie Bizagi eine eigene Windows-Sitzung oder VM. Wenn Sie das dokumentiert haben möchten, damit niemand es erneut versucht: Diese Tabelle ist der Beleg.

Sicherheit

• Pfade werden vollständig aufgelöst (~, .., Symlinks) bevor sie geprüft werden, und dann auf BIZAGI_MCP_ROOT beschränkt, wenn es gesetzt ist

• XML-Parsing läuft über defusedxml, wenn verfügbar (XXE, Billion Laughs)

• Dateien werden nie ohne overwrite=true überschrieben

• Bizagi wird mit einer Argumentliste und ohne Shell gestartet, sodass ein Dateiname nie zu einem Befehl werden kann

• Jeder Fehler kommt als Daten zurück ({"ok": false, ...}), nie als Traceback

Tests

pip install -e ".[dev]"
pytest -q

72 Tests: Spezifikationsnormalisierung, XSD-Elementreihenfolge, BPMNDI-Vollständigkeit, jede oben aufgeführte Layout-Garantie, Label-Kollisionen, Round-Trips, jede Validierungsregel, Pfad-Traversal, Auswahl von Menüband-Schaltflächen, Vordergrund-Verifizierung und der Fehlervertrag jedes Tools.

Bekannte Einschränkungen

• .bpm wird nicht gelesen. Es ist Bizagis proprietäres Format; exportieren Sie zuerst nach BPMN. list_processes listet .bpm-Dateien trotzdem auf und kennzeichnet sie.

• Desktop-Steuerung ist nur unter Windows und benötigt pywinauto.

• Diagramme werden eine Ebene tief erzeugt. Ein Unterprozess erscheint als kollabierte Form; sein Inhalt wird nicht erzeugt.

• Layout-Sauberkeit ist für die in die Datei geschriebene Geometrie garantiert. Bizagi platziert Knotennamen nach eigenen Regeln, die der Diagramm-Austauschabschnitt nicht steuert.

Lizenz

MIT – siehe LICENSE.