MCP-BPMN-Server

Ein Model Context Protocol (MCP)-Server für eine getestete Teilmenge der BPMN-2.0-Autorenschaft, einschließlich Mermaid-Konvertierung, lokaler Persistenz, Layout, Validierung und XML- oder SVG-Export.

🎯 Überblick

MCP-BPMN bietet eine zustandsbehaftete Schnittstelle für KI-Assistenten, um jeweils mit einem Geschäftsprozessdiagramm zu arbeiten. Es erstellt wohlgeformtes BPMN-2.0-XML für die unten aufgeführten Konstrukte; es ist kein vollständiger BPMN-2.0-Editor, keine Ausführungs-Engine und kein Bereitstellungs-Client. Tragbarer BPMN-Kern ist der Standard-Autorenvertrag, mit einem optionalen typisierten Camunda-7-Profil, das in ADR 0001 dokumentiert ist.

Hauptfunktionen

• Fokussierte BPMN-Autorenschaft: Unterstützte Ereignisse, Aktivitäten, Gateways, Datenobjekte, Annotationen, Pools, Top-Level-Lanes, Sequenzflüsse und Assoziationen

• Mermaid-Konvertierung: Bootstrap-Diagramme aus der dokumentierten Flowchart-Teilmenge

• Horizontales Auto-Layout: Deterministische Prozess- und Kollaborationsplatzierung

• Lokale Persistenz: Atomares Speichern und erneutes Öffnen von Diagrammen in einem konfigurierten Verzeichnis

• XML- und SVG-Export: XML wird prozessintern generiert; SVG wird über Puppeteer und bpmn-js gerendert

• Tragbare und Camunda-7-Profile: Standardmäßig anbieterfreie Ausgabe, mit drei typisierten Camunda-7-Benutzeraufgabenfeldern, wenn explizit ausgewählt

Related MCP server: BPMN-MCP

🚀 Schnellstart

Voraussetzungen

• Node.js 22.12.0 oder neuer

• npm mit Lockfile-Unterstützung

• Chrome oder Chromium für export({ format: "svg" }); die normale Puppeteer-Installation lädt einen kompatiblen Browser herunter

XML-Autorenschaft, Validierung, Layout, Persistenz und XML-Export starten keinen Browser. SVG-Export schon. Wenn der Puppeteer-Browser-Download absichtlich übersprungen wird, setzen Sie PUPPETEER_EXECUTABLE_PATH auf eine kompatible Chrome- oder Chromium-Ausführungsdatei, bevor Sie den Server starten. Das SVG-Rendering ist headless, auf eine gleichzeitige Renderung pro Serverinstanz beschränkt und hat ein Render-Timeout von zwanzig Sekunden.

Aus einem Quell-Checkout ausführen

git clone https://github.com/oisee/mcp-bpmn.git
cd mcp-bpmn
npm ci
npm run build
npm start

npm run build erzeugt das kanonische ESM-Ausführungsprogramm unter dist/server/index.js. Der Server verwendet stdio, erscheint daher normalerweise im Terminal als inaktiv und ist dafür gedacht, von einem MCP-Client gestartet zu werden.

Konfiguration

Für Claude Desktop

Fügen Sie Ihrer Claude-Desktop-Konfigurationsdatei Folgendes hinzu:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-bpmn": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bpmn/dist/server/index.js"]
    }
  }
}

Für andere MCP-Clients

Verwenden Sie denselben ESM-Einstiegspunkt mit einem absoluten Pfad:

node /absolute/path/to/mcp-bpmn/dist/server/index.js

Ein gepacktes Release-Artefakt installieren

Dieses Repository dokumentiert derzeit eine npm-Tarball-Installation, anstatt anzunehmen, dass mcp-bpmn-server aus der öffentlichen npm-Registry verfügbar ist. Ein Release-Ersteller kann das kanonische CLI-only-Artefakt aus einem Quell-Checkout erstellen:

artifact_dir=$(mktemp -d)
npm pack --pack-destination "$artifact_dir"

Installieren Sie diesen Tarball in ein dediziertes Verbraucherverzeichnis und führen Sie sein gepacktes ausführbares Programm aus:

consumer_dir=$(mktemp -d)
npm install --prefix "$consumer_dir" "$artifact_dir"/mcp-bpmn-server-*.tgz
"$consumer_dir/node_modules/.bin/mcp-bpmn-server"

Für einen MCP-Client verwenden Sie den absoluten Wert von $consumer_dir/node_modules/.bin/mcp-bpmn-server als command und ein leeres args-Array. Das Paket ist eine CLI, keine importierbare JavaScript-Bibliothek.

Für Claude Code und Codex installieren

Aus einem Quell-Checkout verpackt das Installationsprogramm die aktuelle Version in einen stabilen, benutzereigenen Speicherort, registriert ihren MCP-Server und installiert die bpmn-modeler-Fähigkeit für jeden unterstützten Client, der auf PATH gefunden wird:

make install
make doctor

Der Standardprogramm-Speicherort ist ~/.local/share/mcp-bpmn, während Diagramme außerhalb der Installation in ~/mcp-bpmn bleiben. Die Fähigkeit wird nach ~/.codex/skills/bpmn-modeler für Codex und ~/.claude/skills/bpmn-modeler für Claude Code kopiert. Starten Sie die Clients nach der Installation neu, damit sie die neue Fähigkeit und den MCP-Server entdecken.

Die Installation ist idempotent: Das erneute Ausführen von make install ersetzt nur Dateien und Registrierungen, die diesem Installationsprogramm gehören. Bestehende Drittanbieter-Registrierungen oder Fähigkeitsverzeichnisse bleiben erhalten, es sei denn, ein Ersatz wird explizit mit FORCE=1 angefordert. Zielen Sie auf einen Client, aktualisieren Sie eine bestehende Installation oder deinstallieren Sie unter Beibehaltung der Diagramme mit:

make install-codex
make install-claude
make update
make uninstall

Setzen Sie PREFIX, um den Programm-Speicherort zu ändern, und MCP_BPMN_DIAGRAMS_PATH, um ein anderes absolutes Diagrammverzeichnis zu verwenden. Ein vorgefertigtes Release-Tarball kann reproduzierbar installiert werden, indem sowohl MCP_BPMN_PACKAGE_TARBALL als auch sein erforderliches MCP_BPMN_PACKAGE_SHA256 gesetzt werden. Führen Sie ./scripts/install-agent-integrations.sh --help für die vollständige Schnittstelle aus. Das Installationsprogramm unterstützt macOS und Linux, einschließlich WSL mit Linux-nativem Node.js und Client-CLIs.

Das Codex-Plugin lokal entwickeln

Das Release-Artefakt ist auch ein Codex-Plugin. Sein Manifest entdeckt die kanonische skills/bpmn-modeler-Fähigkeit und startet einen mcp-bpmn-stdio-Server über einen Launcher, der in den Plugin-Cache kopiert wird. Der Launcher verwendet die stabile private Version, die von make install-codex installiert wurde; er führt kein TypeScript aus und hängt nach der Installation nicht vom Checkout ab.

Erstellen Sie das Release-Artefakt, fügen Sie diesen Checkout als temporären Repo-Marktplatz hinzu und installieren Sie das Plugin mit:

npm ci
npm run build
make install-codex
codex plugin marketplace add .
codex plugin list --available
codex plugin add mcp-bpmn@mcp-bpmn-local

Starten Sie nach der Installation eine neue Codex-Konversation, damit die Fähigkeit und die MCP-Tools geladen werden. Der gebündelte Server verwendet standardmäßig den writes-Genehmigungsmodus: Als schreibgeschützt markierte Tools können automatisch ausgeführt werden, während Diagrammmutationen zur Genehmigung sichtbar bleiben. Entfernen Sie die Entwicklungsinstallation mit:

codex plugin remove mcp-bpmn@mcp-bpmn-local
codex plugin marketplace remove mcp-bpmn-local

Führen Sie den isolierten Marktplatz-, Cache-, Discovery-, MCP-Start- und Entfernungs-Smoke aus, ohne die echte Codex-Konfiguration zu ändern:

npm run test:codex-plugin

Das Claude-Code-Plugin lokal entwickeln

Das Release-Artefakt ist auch ein Claude-Code-Plugin. Claude entdeckt die kanonische skills/bpmn-modeler/SKILL.md als die namespaced Fähigkeit /mcp-bpmn:bpmn-modeler und startet den Inline-mcp-bpmn-Server aus dem Plugin-Cache. Das Plugin verwendet skills/; es enthält keine veraltete commands/-Kopie.

Aus einem Quell-Checkout installieren Sie Abhängigkeiten, erstellen, validieren und laden das Plugin für eine Entwicklungssitzung:

npm ci
npm run build
claude plugin validate .
claude --plugin-dir .

Verwenden Sie in Claude Code /mcp, um den vom Plugin bereitgestellten Server zu bestätigen, rufen Sie /mcp-bpmn:bpmn-modeler auf, um die Fähigkeit zu inspizieren, und führen Sie /reload-plugins aus, nachdem Sie das Manifest oder die MCP-Konfiguration geändert haben. Der Checkout enthält eine Root-CLAUDE.md für Repository-Mitwirkende, daher meldet die Quellvalidierung, dass es sich nicht um Plugin-Kontext handelt; der Befehl wird trotzdem erfolgreich ausgeführt. Das gepackte Plugin schließt diese nur für das Repository bestimmte Datei aus und besteht die strenge Validierung.

Führen Sie den vollständigen lokalen Marktplatz-Smoke mit:

npm run test:claude-plugin

Diese Prüfung verwendet ein temporäres Claude-Home und einen temporären Marktplatz. Sie installiert ein kopiertes Release-Artefakt, prüft die Komponenteninventur von Claude, startet den gecachten MCP-Server, übt ein Neuladen aus und deaktiviert, aktiviert und entfernt dann das Plugin. Sie ändert nicht die echte Claude-Konfiguration des Entwicklers.

Diagramme werden niemals in ${CLAUDE_PLUGIN_ROOT} geschrieben. Sie bleiben in MCP_BPMN_DIAGRAMS_PATH, wenn gesetzt, oder standardmäßig in ~/mcp-bpmn, sodass Plugin-Neuladungen, -Updates, -Deaktivierungen und -Entfernungen sie nicht löschen. Bevor Sie von einer manuellen Claude-MCP-Registrierung zum Plugin wechseln, prüfen Sie claude mcp list und entfernen Sie die alte mcp-bpmn-Registrierung, wenn ihr Befehl sich vom Plugin-Endpunkt unterscheidet; Claude dedupliziert nur Plugin- und Benutzerserver, die auf denselben Befehl auflösen.

Agenten-Workflows evaluieren

Das kanonische maschinenlesbare Korpus ist evals/bpmn-modeler/cases.json. Beide Client-Adapter verwenden genau diese Prompts und semantischen Erwartungen. Die deterministische Prüfung ist für normale Entwicklung und CI sicher: Sie verifiziert Aktivierungsgrenzen, Fähigkeitsmetadaten, Toolnamen, Client-Parität und die Sequenz create/mutate/validate/layout/validate/export, ohne ein Modell aufzurufen:

npm run test:evaluations

Authentifizierte Modellläufe sind opt-in. Erstellen Sie zuerst, wählen Sie dann einen begrenzten Fall aus, während Sie iterieren:

npm run build
npm run eval:codex -- --case direct-process-svg
npm run eval:claude -- --case direct-process-svg

Der Codex-Adapter führt codex exec in einem temporären Projekt aus, das die kanonische Fähigkeit und eine projektspezifische stdio-MCP-Konfiguration enthält. Der Claude-Adapter materialisiert dieselben Fälle als native claude plugin eval-Fälle in einer temporären Plugin-Kopie. Beide setzen MCP_BPMN_DIAGRAMS_PATH auf ein temporäres Verzeichnis, kopieren nur deklarierte Setup-Fixtures dorthin und entfernen das Verzeichnis danach; sie lesen, überschreiben oder löschen niemals Diagramme aus dem echten Speicher des Benutzers. Lassen Sie --case weg, um das vollständige Korpus auszuführen. Diese Befehle können Modellkontingent verbrauchen und sind absichtlich von npm run check und CI ausgeschlossen.

Optionales CommonJS-Bundle

Das CommonJS-Bundle ist ein separater Quell-Checkout-Build und wird nicht von npm run build erzeugt oder in das kanonische npm-Tarball aufgenommen:

npm run build:bundle
npm run start:bundle

📚 API-Referenz

Zustandsbehaftetes Kontextmanagement

MCP-BPMN verwendet ein zustandsbehaftetes API-Design, bei dem Sie jeweils mit einem Diagramm arbeiten. Alle Operationen gelten für den aktuellen Diagrammkontext, wodurch die Notwendigkeit von processId-Parametern entfällt.

Beworbene Tool-Matrix

Die Überschriften in dieser API-Referenz zählen jedes Tool auf, das von tools/list zurückgegeben wird. Die ausführbare Paritätsbasislinie ist tests/contracts/engine-contract.test.ts, mit fokussiertem Verhalten in den Unit-, Integrations- und End-to-End-Suiten.

Jedes beworbene Tool enthält auch die standardmäßigen MCP-Annotationen readOnlyHint, destructiveHint, idempotentHint und openWorldHint. Diese Annotationen beschreiben beobachtbares Serververhalten: Autorenaufrufe speichern automatisch, Ersetzungs- und Löschaufrufe können vorhandenen Zustand zerstören, und alle Operationen bleiben innerhalb des konfigurierten lokalen Diagrammspeichers. MCP-Annotationen sind beratende Hinweise, keine Autorisierungsgrenze; Clients müssen weiterhin ihre eigenen Vertrauens- und Genehmigungsrichtlinien anwenden.

Erstellungstools

new_bpmn

Erstellen Sie ein neues BPMN-Prozess- oder Kollaborationsdiagramm und setzen Sie es als aktuellen Kontext.

{
  name: "Order Processing",
  type: "process" // or "collaboration" (optional, defaults to "process")
}

new_from_mermaid

Erstellen Sie ein neues BPMN-Diagramm aus Mermaid-Code und legen Sie es als aktuellen Kontext fest.

{
  name: "My Process",
  mermaidCode: "graph TD\n  A[Start] --> B[Task] --> C[End]"
}

Mermaid-Konvertierung unterstützt absichtlich eine fokussierte Flowchart-Teilmenge:

Wenn ein Subgraph vorhanden ist, muss jeder Knoten zu genau einem Top-Level-Subgraph gehören. Verschachtelte Subgraphen und Sequenzflussverbindungen zu Datenknoten werden vor dem BPMN-Export abgelehnt. Styling, Klick-Handler, CSS-Klassen und gepunktete Kantendarstellung werden in BPMN nicht dargestellt; akzeptierte verlustbehaftete Syntax gibt eine Konvertierungswarnung zurück. Textbeschriftungen und Subgraph-Namen werden XML-escaped und durchlaufen BPMN unverändert.

Dateioperationen

open_bpmn

Öffnen Sie eine vorhandene BPMN-Datei und legen Sie sie als aktuellen Kontext fest.

{
  filename: "my-process.bpmn"
}

open_mermaid_file

Öffnen und konvertieren Sie eine Mermaid-Datei in BPMN und legen Sie sie als aktuellen Kontext fest.

{
  filename: "my-flowchart.mmd"
}

save

Speichern Sie das aktuelle Diagramm atomar in seiner aktiven Datei. Neue und geöffnete Diagramme haben bereits einen aktiven Dateinamen, und erfolgreiche Mutationen speichern automatisch in derselben Datei.

{}

save_as

Speichern Sie das aktuelle Diagramm atomar mit einem neuen Dateinamen und machen Sie diesen Dateinamen aktiv. Spätere Mutationen aktualisieren nur die neue Datei; die vorherige Datei bleibt eine unveränderte Momentaufnahme.

{
  filename: "my-process.bpmn"
}

close

Schließen Sie das aktuelle Diagramm und leeren Sie den Kontext.

{}

current

Informationen über das aktuelle Diagramm abrufen.

{}

Werkzeuge zur Elementbearbeitung

add_event

Fügen Sie Ereignisse (Start, Ende, Zwischen, Rand) zum aktuellen Diagramm hinzu.

{
  eventType: "start", // start, end, intermediate-throw, intermediate-catch, boundary
  name: "Order Received",
  eventDefinition: "message", // optional; only BPMN-legal event kind/definition pairs are accepted
  eventDefinitionPayload: {
    reference: { name: "Order received" } // root ID is generated when omitted
  },
  position: { x: 100, y: 200 } // optional
}

Timer-Definitionen erfordern timer: { type: "timeDate" | "timeDuration" | "timeCycle", expression, language? }; bedingte Definitionen erfordern condition: { expression, language? }. Fehler- und Eskalationsreferenzen können auch code enthalten. Kompensations-Throws können activityRef und waitForCompletion enthalten; Kompensations-Randereignisse sind nicht unterbrechend.

add_activity

Fügen Sie Aktivitäten (Aufgaben, Teilprozesse) zum aktuellen Diagramm hinzu.

{
  activityType: "userTask", // task, userTask, serviceTask, scriptTask, etc.
  name: "Review Order",
  position: { x: 250, y: 200 }, // optional
  properties: { // optional; Camunda 7 profile only on userTask
    assignee: "reviewer",
    candidateGroups: ["operations", "approvers"],
    dueDate: "${dueDate}"
  }
}

Neue BPMN- und Mermaid-Dokumente akzeptieren extensionProfile: "portable" | "camunda7"; der Standard ist portable. Der portable Modus lehnt die drei Herstellerfelder ab und gibt keinen Hersteller-Namespace aus. Camunda-Updates akzeptieren null für jedes davon, um das entsprechende XML-Attribut zu entfernen. Kandidatengruppeneinträge dürfen keine Kommas enthalten. Importiertes BPMN erkennt die tatsächliche Verwendung des Camunda-Namespace und bewahrt andere warnungsfreie Erweiterungen opak.

Aufrufaktivitäten werden als bpmn:callActivity serialisiert. Ihr optionales properties.calledElement ist ein lexikalischer BPMN-QName, der das aufrufbare Element identifiziert; es muss nicht mit einer Prozess-ID im aktuellen Diagramm übereinstimmen.

Aktivitäten können standardmäßige BPMN-Multi-Instance-Schleifenmerkmale verwenden. Setzen Sie isSequential auf false für parallele Instanzen oder auf true für sequenzielle Instanzen:

{
  activityType: "serviceTask",
  name: "Process Batch",
  properties: {
    multiInstance: {
      isSequential: false,
      loopCardinality: {
        body: "requestedInstanceCount",
        language: "urn:example:expression-language"
      },
      completionCondition: {
        body: "completedInstanceCount >= requiredInstanceCount",
        language: "urn:example:expression-language"
      },
      loopDataInputRef: "DataObjectReference_Input",  // optional ItemAwareElement ID
      loopDataOutputRef: "DataObjectReference_Output" // optional ItemAwareElement ID
    }
  }
}

Der Server bewahrt Ausdruckskörper exakt und serialisiert sie als BPMN-FormalExpression-Werte. Er parst oder wertet sie nicht aus, wählen Sie also eine Sprache/Profil, die von der BPMN-Engine unterstützt wird, die das exportierte Diagramm ausführen wird. Die Schleifendatenreferenzen müssen vorhandene BPMN-ItemAwareElement-Instanzen identifizieren; das portable Schema gibt kein herstellerspezifisches collection-Attribut aus. Herstellerspezifische Bindungs- oder Versionsattribute werden vom portablen BPMN-Dialekt nicht ausgegeben.

{
  activityType: "callActivity",
  name: "Invoke fulfillment",
  properties: { calledElement: "FulfillmentProcess" }
}

add_gateway

Fügen Sie Gateways für Verzweigungslogik zum aktuellen Diagramm hinzu.

{
  gatewayType: "exclusive", // exclusive, parallel, inclusive, eventBased, complex
  name: "Payment Check",
  position: { x: 400, y: 200 } // optional
}

add_data_object

Fügen Sie eine sichtbare bpmn:dataObjectReference und ihr verknüpftes, nicht gerendertes bpmn:dataObject hinzu. Der Sammlungszustand gehört zum zugrunde liegenden Objekt. Ein optionales itemSubjectRef muss eine vorhandene bpmn:itemDefinition identifizieren, z. B. eine aus einem importierten Diagramm geladene.

{
  name: "Order records",
  position: { x: 400, y: 320 }, // optional reference position
  isCollection: true, // optional, defaults to false
  itemSubjectRef: "ItemDefinition_Order" // optional existing definition ID
}

Daten-Eingabe-/Ausgabe-Assoziationen sind BPMN-Konstrukte, die Aktivitäten gehören, und werden nicht von add_association erstellt, das die generische Artefakt-Assoziation bleibt.

add_text_annotation

Fügen Sie eine BPMN-Textannotation hinzu. Text wird exakt erhalten, einschließlich Zeilenumbrüchen und XML-Metazeichen. textFormat standardmäßig auf BPMNs text/plain; Position und Größe standardmäßig auf die Annotationsgeometrie der Engine. Die Angabe von associatedElementId erstellt auch eine separate, ungerichtete BPMN-Assoziation von der Annotation zu diesem Element.

{
  text: "Review the exception path\nbefore approval",
  textFormat: "text/markdown", // optional
  position: { x: 400, y: 320 }, // optional
  size: { width: 220, height: 80 }, // optional
  associatedElementId: "UserTask_1" // optional
}

connect

Verbinden Sie zwei Elemente mit einem Sequenzfluss im aktuellen Diagramm.

{
  sourceId: "ExclusiveGateway_1",
  targetId: "UserTask_1",
  label: "Start Flow", // optional
  condition: "amount > 1000", // optional, for conditional sequence flows
  conditionLanguage: "FEEL", // optional
  conditionType: "bpmn:FormalExpression", // optional
  isDefault: false // optional; default flows cannot have conditions
}

Bedingungen und Standardwerte werden für Aktivitäten und exklusive, inklusive oder komplexe Gateways unterstützt. Ein Standardfluss kann nicht auch eine Bedingung haben.

add_association

Fügen Sie ein BPMN-Assoziationsartefakt zwischen zwei BaseElements in einem kompatiblen Prozess- oder Kollaborationsbereich hinzu. Dies unterscheidet sich von Sequenz- und Nachrichtenflüssen. associationDirection standardmäßig auf BPMNs None-Wert.

{
  sourceId: "TextAnnotation_1",
  targetId: "UserTask_1",
  associationDirection: "One" // None, One, or Both
}

add_pool

Fügen Sie einen Pool (Teilnehmer) zu einem Kollaborationsdiagramm hinzu.

{
  name: "Customer",
  position: { x: 100, y: 100 }, // optional
  size: { width: 600, height: 250 }, // optional
  blackBox: false // optional; true creates a participant without an owned process
}

add_lane

Fügen Sie eine Spur zu einem White-Box-Pool hinzu und weisen Sie direkte Prozessflussknoten zu. Knoten, die bereits einer anderen Spur zugewiesen sind, werden in die neue Spur verschoben.

{
  poolId: "Participant_1",
  name: "Sales Department",
  flowNodeIds: ["StartEvent_1", "UserTask_1"],
  position: "bottom" // optional
}

Abfrage- und Bearbeitungswerkzeuge

list_elements

Listen Sie eine stabile, nach ID geordnete Seite von Elementen und Assoziationsartefakten im aktuellen Diagramm auf. Filtern Sie mit elementType: "bpmn:Association", um nur Assoziationen aufzulisten.

{
  elementType: "bpmn:Task", // optional filter
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

Die Antwort ist { count, returnedCount, offset, limit, hasMore, elements }. Kompatibilitätshinweis: Der Paginierungs-Envelope ersetzt die frühere Bare-Array-Antwort; Clients, die gegen diesen Vertrag geschrieben wurden, müssen jetzt elements lesen. Die vorhandenen Elementfelder behalten ihre Bedeutung; zusätzliche Metadatenfelder und Spureinträge können vorhanden sein.

get_element

Details eines bestimmten Elements oder einer Assoziation abrufen.

{
  elementId: "UserTask_1"
}

update_element

Elementeigenschaften aktualisieren.

{
  elementId: "UserTask_1",
  name: "Updated Task Name",
  properties: { assignee: "john.doe", candidateGroups: ["reviewers"] },
  defaultFlow: "Flow_2" // outgoing flow ID, or null to clear
}

delete_element

Löschen Sie ein Element und seine anfallenden Verbindungen. Das Übergeben einer Assoziations-ID löscht nur diese Assoziation und lässt ihre Endpunkte intakt; das Löschen eines Endpunkts, einschließlich einer Textannotation, kaskadiert auf seine Assoziationen.

{
  elementId: "Task_1"
}

Dienstprogrammwerkzeuge

export

Exportieren Sie das aktuelle Diagramm als BPMN 2.0 XML oder als gerendertes SVG.

{
  format: "xml", // "xml" or "svg"; defaults to "xml"
  formatted: true // optional; applies to XML and defaults to true
}

XML-Export gibt Text zurück und startet keinen Browser. SVG-Export startet einen Headless-Browser über Puppeteer, rendert mit bpmn-js, bereinigt das Ergebnis und gibt eine eingebettete image/svg+xml-Ressource zurück. Es erfordert eine verfügbare Chrome/Chromium-Ausführungsdatei und behält die sichtbare bpmn.io-Zuschreibung bei, die unter Lizenz beschrieben ist.

validate

Validieren Sie die Struktur des aktuellen Diagramms.

{
  level: "full" // "syntax", "semantic", or "full"; defaults to "full"
}

Validierungsstufen sind kumulativ. syntax parst XML und löst Referenzen auf; semantic fügt besitzerbewusste Ereignis-, Fluss-, Teilprozess-, Spuren- und Kollaborationsregeln hinzu; full fügt auch Start-/Ende-/Konnektivitätsrichtlinien für ausführbare Profile hinzu.

auto_layout

Wenden Sie automatisches Layout an, um Elemente im aktuellen Diagramm zu positionieren.

{
  algorithm: "horizontal" // currently only horizontal is supported
}

Das Layout läuft in einem beendbaren Unterprozess mit einem standardmäßigen Fünf-Sekunden-Budget. Eine benchmarkbasierte Vorprüfung akzeptiert höchstens 2.000 Elemente, 2.000 Verbindungen und 10 Verbindungen pro Element; Eingaben über einem Limit werden vor dem Layout abgelehnt. Bei Kollaborationen wird jeder Teilnehmerprozess unabhängig eingestuft, sodass Nachrichtenflüsse die Reihenfolge der Sequenzflüsse nicht ändern. Automatisches Layout ersetzt manuelle Knoten- und Containerkoordinaten, aber angeforderte/importierte Teilnehmer- und Spurabmessungen bleiben untere Grenzen. Pools werden dann ohne Überlappung gestapelt; Spuren und zugehörige Knoten bleiben enthalten, und Nachrichtenflüsse werden erst nach der endgültigen Poolplatzierung geroutet. Nicht verbundene Knoten werden deterministisch in ihrem Besitzerprozess gepackt, verschachtelte Teilprozesse behalten semantische Containment, und Black-Box-Teilnehmer behalten ihre angeforderte Mindestgröße ohne erfundenen Prozessinhalt.

Dateiverwaltungswerkzeuge

list_diagrams

Listen Sie eine stabile, nach Dateinamen geordnete Seite gespeicherter BPMN-Diagramme auf.

{
  limit: 100, // optional, defaults to 100; maximum 500
  offset: 0 // optional, defaults to 0
}

Die vorhandenen Antwortfelder { count, diagrams, path } bleiben verfügbar; returnedCount, offset, limit und hasMore beschreiben die ausgewählte Seite. Nur Dateien auf der ausgewählten Seite werden für eingebettete BPMN-Metadaten gelesen, und das aggregierte Metadatenlesen ist standardmäßig auf 5 MiB begrenzt.

delete_diagram_file

Löschen Sie eine gespeicherte Diagrammdatei.

{
  filename: "old-process.bpmn"
}

get_diagrams_path

Den Speicherpfad für Diagramme abrufen.

{}

🔄 Kontextverwaltung

Der MCP-BPMN-Server verwendet ein zustandsbehaftetes Design, bei dem Sie jeweils mit einem Diagramm arbeiten:

1. Erstellen oder Öffnen: Beginnen Sie mit dem Erstellen eines neuen Diagramms (new_bpmn, new_from_mermaid) oder dem Öffnen eines vorhandenen (open_bpmn, open_mermaid_file)

2. Bearbeiten: Alle Operationen (add_event, connect usw.) gelten für das aktuelle Diagramm

3. Speichern: Speichern Sie Ihre Arbeit mit save oder save_as

4. Schließen: Schließen Sie das aktuelle Diagramm mit close

Wenn Sie versuchen, Operationen ohne aktuellen Kontext auszuführen, erhalten Sie eine hilfreiche Fehlermeldung:

No current context. Please create a diagram first with:
  - new_bpmn(name) to create a new BPMN diagram
  - new_from_mermaid(name, mermaidCode) to convert from Mermaid
  - open_bpmn(filename) to open an existing BPMN file
  - open_mermaid_file(filename) to convert a Mermaid file

💡 Beispiele

Beispiel 1: Erstellen eines Genehmigungsprozesses von Grund auf

// Step 1: Create a new process (sets it as current context)
await new_bpmn({ name: "Approval Workflow" });

// Step 2: Add elements (all operations apply to current diagram)
await add_event({ eventType: "start", name: "Request Received" });
await add_activity({ activityType: "userTask", name: "Review Request" });
await add_gateway({ gatewayType: "exclusive", name: "Approved?" });
await add_activity({ activityType: "serviceTask", name: "Process Approval" });
await add_activity({ activityType: "userTask", name: "Handle Rejection" });
await add_event({ eventType: "end", name: "Complete" });

// Step 3: Connect elements
await connect({ sourceId: "StartEvent_1", targetId: "UserTask_1" });
await connect({ sourceId: "UserTask_1", targetId: "ExclusiveGateway_1" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "ServiceTask_1", label: "Yes" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "UserTask_2", label: "No" });
await connect({ sourceId: "ServiceTask_1", targetId: "EndEvent_1" });
await connect({ sourceId: "UserTask_2", targetId: "EndEvent_1" });

// Step 4: Apply auto-layout for proper positioning
await auto_layout();

// Step 5: Save and export the diagram
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();

Beispiel 2: Bootstrap aus Mermaid (empfohlen für geringeren Token-Verbrauch)

// Step 1: Create from Mermaid syntax (much more concise!)
await new_from_mermaid({ 
  name: "Approval Workflow",
  extensionProfile: "camunda7",
  mermaidCode: `
    graph TD
      A((Request Received)) --> B[Review Request]
      B --> C{Approved?}
      C -->|Yes| D[Process Approval]
      C -->|No| E[Handle Rejection]
      D --> F((Complete))
      E --> F
  `
});

// Step 2: Apply auto-layout (Mermaid conversion includes basic layout)
await auto_layout();

// Step 3: Make additional edits if needed
await update_element({ 
  elementId: "UserTask_1", 
  properties: { assignee: "reviewer" }
});

// Step 4: Save and export
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();

Beispiel 3: Arbeiten mit mehreren Diagrammen

// Create first diagram
await new_bpmn({ name: "Process A" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task A" });
await save_as({ filename: "process-a.bpmn" });

// Create second diagram (automatically closes the first)
await new_bpmn({ name: "Process B" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task B" });
await save_as({ filename: "process-b.bpmn" });

// Go back to first diagram
await open_bpmn({ filename: "process-a.bpmn" });
await add_event({ eventType: "end" });
await save();

// Check current diagram info
const info = await current();
console.log(info); // Shows: { name: "Process A", filename: "process-a.bpmn", ... }

🗂️ Dateispeicherung

BPMN-Diagramme werden automatisch in Ihrem lokalen Dateisystem gespeichert:

• Unix/Linux/Mac: ~/mcp-bpmn/

• Windows: %USERPROFILE%\mcp-bpmn\

Benutzerdefinierter Pfad über Umgebungsvariable:

export MCP_BPMN_DIAGRAMS_PATH=/custom/path

Ressourcengrenzen können mit MCP_BPMN_MAX_IMPORT_BYTES, MCP_BPMN_MAX_MERMAID_BYTES, MCP_BPMN_MAX_LAYOUT_ELEMENTS, MCP_BPMN_MAX_LAYOUT_CONNECTIONS, MCP_BPMN_MAX_LAYOUT_DENSITY, MCP_BPMN_MAX_LAYOUT_BYTES, MCP_BPMN_MAX_CONCURRENT_LAYOUTS, MCP_BPMN_MAX_LISTING_ITEMS, MCP_BPMN_MAX_LISTING_METADATA_BYTES und MCP_BPMN_LAYOUT_TIMEOUT_MS eingestellt werden. Die Frist für das ordnungsgemäße Herunterfahren kann mit MCP_BPMN_SHUTDOWN_TIMEOUT_MS überschrieben werden. Standardwerte sind 5 MiB pro importiertem/Layout-Eingang und pro Metadaten-Seite, 2.000 Layout-Elemente/Verbindungen, Dichte 10, zwei gleichzeitige Layout-Unterprozesse, 10.000 Auflistungskandidaten und 5.000 ms. Die Layout-Standardwerte stammen aus lokalen Sparse/Dense-Benchmarks: 2.000/1.999 in etwa 1,4 s, 25/300 in etwa 4,8 s und 26/325 überschritten fünf Sekunden.

Bei SIGINT, SIGTERM oder stdin-EOF stoppt der Server die Annahme von Tool-Aufrufen und lässt akzeptierte Operationen und deren atomare Persistenz abschließen, bevor er Renderer-/Layout-Unterprozesse und den stdio-Transport schließt. Das ordnungsgemäße Herunterfahren hat eine harte 15-Sekunden-Frist; deren Überschreitung erzwingt einen Exit mit Nicht-Null-Status.

Neue Diagramme beginnen mit dem Dateinamen {ProcessId}_{ProcessName}.bpmn. Jedes Diagramm hat genau einen aktiven Dateinamen: Beim Öffnen wird der geöffnete Dateiname übernommen und save_as wechselt ihn, nachdem die neue Datei erfolgreich geschrieben wurde. Hinzufügen, Aktualisieren, Löschen, Verbinden und Layout-Operationen serialisieren und speichern die aktive Datei atomar automatisch; fehlgeschlagene Serialisierung oder Schreibvorgänge belassen sowohl Speicher als auch Festplatte im letzten erfolgreichen Zustand.

🏗️ Architektur

Technologie-Stack

• TypeScript - Typsichere Entwicklung

• Node.js - Laufzeitumgebung

• MCP SDK - Implementierung des Model Context Protocol

• Jest - Test-Framework

Schlüsselkomponenten

• SimpleBpmnEngine - Kanonische BPMN-Dokumentmutation, Persistenz und XML-Export

• BpmnSvgRenderer - Isoliertes, browserbasiertes bpmn-js-SVG-Rendering

• DiagramContext - Zustandsbehaftetes Kontextmanagement für das aktuelle Diagramm

• BpmnAutoLayoutV2Adapter - BPMN-Auto-Layout-Integration

• BpmnRequestHandler - MCP-Anfrageverarbeitung

• MermaidConverter - Mermaid-zu-BPMN-Konvertierung

• TypeMappings - BPMN-Elementtyp-Konvertierungen

• IdGenerator - Konsistente ID-Generierung

Projektstruktur

mcp-bpmn/
├── src/
│   ├── core/           # Core BPMN engine
│   ├── server/         # MCP server implementation
│   ├── utils/          # Utilities (layout, ID generation)
│   ├── types/          # TypeScript type definitions
│   └── config/         # Configuration
├── tests/
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── e2e/           # End-to-end tests
├── dist/              # Compiled output
└── docs/              # Documentation

🧪 Entwicklung

Verfügbare Skripte

npm run build        # Build TypeScript
npm run build:bundle # Build CommonJS bundle
npm run build:watch  # Build with watch mode
npm run check        # Complete clean contributor/CI quality gate
npm test            # Run source-level tests (no build output required)
npm run test:all    # Clean, build, and run every test including e2e
npm run test:unit   # Run unit tests only
npm run test:integration # Run integration tests only
npm run test:e2e    # Run end-to-end tests
npm run lint        # Run ESLint
npm run dev         # Development mode with hot reload
npm start           # Start the MCP server

Testen

Das Projekt umfasst eine umfassende Testabdeckung. Befehle auf Quellcode-Ebene lesen dist/ nicht, sodass ein alter Build ihr Ergebnis nicht beeinflussen kann:

• Unit-Tests: Testen der Kernfunktionalität

• Integrationstests: Testen von Handler und Werkzeugen

• E2E-Tests: Vollständiges Testen des MCP-Protokolls

Führen Sie Tests aus mit:

npm test                    # Source-level tests
npm run test:all            # Clean build plus all tests
npm run check               # Complete clean contributor/CI quality gate
npm run test:coverage       # Source-level tests with coverage
npm run test:watch          # Source-level tests in watch mode

📈 Leistung

Das kanonische Release-Artefakt wurde am 22.08.2026 mit Node 25.9.0 und npm 11.12.1 gemessen mit:

npm pack --dry-run --json

Dieser Befehl meldete ungefähr 195 kB komprimiert und 1104270 ungepackte Bytes. Diese Zahlen beschreiben das npm-Tarball, nicht einen installierten Server: Das Tarball bündelt keine Produktionsabhängigkeiten, während die Installation die neun direkten Laufzeitabhängigkeiten in package.json und deren transitive Abhängigkeiten auflöst. Der von Puppeteer verwaltete Chrome-Download liegt ebenfalls außerhalb der Tarball-Messung. Führen Sie den Befehl für das aktuelle Artefakt erneut aus, anstatt diese datierte Momentaufnahme als dauerhafte Größengarantie zu behandeln.

Das optionale CommonJS-Bundle ist nicht das Release-Artefakt und hat keinen Größenanspruch. Layout-Eingabelimits und die datierten Benchmark-Beobachtungen, die zur Auswahl ihrer Standardwerte verwendet wurden, sind unter Dateispeicher dokumentiert.

🐛 Bekannte Einschränkungen

• Die Autoren-API ist eine fokussierte BPMN-2.0-Teilmenge, keine vollständige BPMN-2.0-Abdeckung. Nicht unterstützte importierte Konstrukte können abgelehnt werden, anstatt verlustfrei bearbeitet zu werden.

• connect bietet keine direkte Autorenunterstützung für Nachrichtenflüsse. Die Mermaid-Kollaborations-Teilmenge kann Nachrichtenflüsse zwischen Teilgraphen erstellen.

• add_lane erstellt Top-Level-Swimlanes in White-Box-Pools; es kann keine importierte verschachtelte Lane-Hierarchie erweitern.

• Auto-Layout unterstützt nur horizontales Layout. Vertikale und radiale Algorithmen werden nicht beworben.

• Die Validierung bietet die dokumentierten Syntax-, Semantik- und vollständigen Anleitungsebenen; sie ist keine BPMN-XSD-Zertifizierung oder Validierung gegen eine Bereitstellungs-Engine.

• Das Camunda-7-Autorenprofil ist auf assignee, candidateGroups und dueDate bei Benutzeraufgaben beschränkt. Es ist keine allgemeine Camunda-Modeler-Abdeckung.

• Der SVG-Export erfordert Chrome/Chromium über Puppeteer und erlaubt nur ein gleichzeitiges Rendering pro Serverinstanz. XML-Workflows bleiben browserfrei.

• Der Server führt BPMN-Prozesse nicht aus, simuliert sie nicht und stellt sie nicht bereit.

🚧 Roadmap

Geplante Arbeiten und bekannte Lücken werden als Beads-Issues verfolgt und nicht als implementierte Funktionen in diesem Release-Dokument versprochen.

🤝 Mitwirken

Beiträge sind willkommen! Bitte:

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Führen Sie das vollständige Qualitätsgate aus (npm run check)

4. Committen Sie Ihre Änderungen (git commit -m 'Add amazing feature')

5. Pushen Sie den Branch (git push origin feature/amazing-feature)

6. Öffnen Sie einen Pull-Request

Codestil

• TypeScript mit striktem Modus

• ESLint-Konfiguration bereitgestellt

• Jest zum Testen

• Konventionelle Commits

📝 Lizenz

MIT-Lizenz – siehe Datei LICENSE für Details.

Der SVG-Export verwendet bpmn-js@17.11.1. Jedes exportierte SVG enthält ein sichtbares „Powered by bpmn.io“-Logo, das mit https://bpmn.io verlinkt ist; Clients sollten diese Zuordnung nicht zuschneiden, abdecken oder entfernen. Siehe THIRD_PARTY_NOTICES.md für die Lizenzbedingungen der Abhängigkeit und ADR 0002 für die Release-Entscheidung.

📞 Support

• Issues: GitHub Issues

• Dokumentation: Siehe Ordner /docs für ausführliche Anleitungen

🙏 Danksagungen

• Basierend auf der Model Context Protocol-Spezifikation

• Inspiriert von bpmn-js für BPMN-Standards

• Dank an das Anthropic-Team für die MCP-Entwicklung