PlantUML MCP-Server

Flexibler Model Context Protocol (MCP)-Server, der PlantUML-Snippets in teilbare Diagramme umwandelt. Alle Funktionen werden über HTTP, Server-Sent Events (SSE) und STDIO bereitgestellt, sodass Sie den Server in Claude Desktop, Flowise oder jede andere MCP-kompatible Runtime einbinden können.

Hauptfunktionen

• 🧰 Tools: generate_plantuml_diagram, generate_capability_landscape, generate_business_scenario, encode_plantuml, decode_plantuml

• 🧾 Prompts: plantuml_error_handling, capability_landscape_input_format, archimate_diagram_input_format, business_scenario_input_format

• 📚 Statische Ressourcen: resource://plantuml/server-guide, resource://plantuml/archimate-mapping

• 🔒 Optionale Bearer-Authentifizierung via MCP_API_KEY

• ☁️ Optionaler ob-file-Export über signierte Download-URLs (OB_FILE_API_BASE_URL)

• 🔐 Optionaler OIDC-Client-Credentials-Flow für ob-file (OB_FILE_OIDC_*)

• 📁 Fallback-Export über freigegebenes Volume (GENERATED_FILES_DIR + PUBLIC_FILE_BASE_URL)

Related MCP server: ArchiMate MCP Server

Anforderungen

• Node.js 18+

• npm 9+

npm install
npm run build     # emits dist/plantuml-mcp-server.js

Verwenden Sie npx plantuml-mcp-server oder node dist/plantuml-mcp-server.js nach dem Build.

Transportmodi

HTTP-Transport

MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_PORT=8765 \
MCP_HTTP_PATH=/mcp \
node dist/plantuml-mcp-server.js

• POST /mcp zum Initialisieren und Senden von JSON-RPC-Payloads.

• GET /mcp und DELETE /mcp halten die streamfähige Sitzung aktiv.

• GET /healthz steht für Readiness-Probes zur Verfügung.

• Beispiel-Client-Einstellungen: client_config_http.json.

SSE-Transport

MCP_TRANSPORT=sse \
MCP_HOST=0.0.0.0 \
MCP_PORT=8765 \
MCP_SSE_PATH=/sse \
MCP_SSE_MESSAGES_PATH=/messages \
node dist/plantuml-mcp-server.js

• Clients verbinden sich mit /sse (GET) für Events und senden JSON-Nachrichten per POST an /messages.

• Beispielkonfiguration für Claude Desktop / Flowise: client_config_sse.json.

STDIO-Transport

MCP_TRANSPORT=stdio npx plantuml-mcp-server
# or run the compiled file directly
MCP_TRANSPORT=stdio node dist/plantuml-mcp-server.js

• Ideal für lokale Experimente, mcp CLI oder Flowise-Nodes, die das Binary starten.

• Beispiel-Setups finden Sie in client_config_stdio.json.

Beispiel-Client-Konfigurationen

• client_config_http.json – streamfähiges HTTP (Standard /mcp)

• client_config_sse.json – SSE + dedizierte messagesUrl

• client_config_stdio.json – STDIO-Beispiele für npx und Flowise-verwaltete Prozesse

Kopieren Sie diese Dateien in Ihren MCP-fähigen Client oder übernehmen Sie die Snippets nach Bedarf. Aktualisieren Sie Hostnamen, Ports und API-Schlüssel passend zu Ihrer Bereitstellung.

Umgebungsvariablen

Wenn OB_FILE_API_BASE_URL konfiguriert ist, werden gerenderte Diagramme über ob-file hochgeladen und die MCP-Antwort gibt die von ob-file generierte signierte download_url zurück. Wenn OB_FILE_OIDC_DISCOVERY_URL, OB_FILE_OIDC_CLIENT_ID und OB_FILE_OIDC_CLIENT_SECRET konfiguriert sind, ruft der Server automatisch ein Access-Token über OAuth 2.0 Client Credentials ab und speichert es zwischen. Der Pfad für das freigegebene Volume bleibt als Kompatibilitäts-Fallback für lokale/Dev-Setups erhalten.

Tools, Prompts & Ressourcen

• Tools werden automatisch über tools/list registriert. Sie führen Validierungen und optionale automatische Korrekturen durch und geben strukturierte Metadaten zurück (success, URLs, Markdown-Snippets, kodierte Diagrammdaten und Validierungsfehler).

• Prompts führen das Modell durch die PlantUML-Fehlerbehandlung und bieten eine fertige Vorlage für Capability-Landscapes.

• Ressourcen-Templates stellen Onboarding-Inhalte bereit (resource://plantuml/server-guide), sodass Clients Nutzungshinweise selbst entdecken können.

Docker-Image

Das bereitgestellte Dockerfile baut die TypeScript-Quellen und erstellt ein minimales Runtime-Image:

docker build -t plantuml-mcp-server .
docker run --rm -e MCP_TRANSPORT=http -p 8765:8765 plantuml-mcp-server

Überschreiben Sie Umgebungsvariablen (PLANTUML_SERVER_URL, MCP_API_KEY usw.) nach Bedarf.

Testen & Tooling

• npm run build – TypeScript kompilieren

• npm start – Ausführen mit dem Standard-HTTP-Transport

• npm run start:sse / npm run start:stdio – Komfort-Skripte

• npm run test:business-scenario – Snapshot-Test, der test_files/generate_sequence_diagram/payload.json in PlantUML konvertiert und mit expected.puml vergleicht

• make test-mcp – Smoke-Test-Befehle über die mcp CLI

Hilfe benötigt?

• Überprüfen Sie die Konnektivität mit curl http://<host>:<port>/healthz

• Stellen Sie sicher, dass die Auth-Header mit MCP_API_KEY (Bearer-Token) übereinstimmen, falls aktiviert

• Verwenden Sie den MCP Inspector oder die Flowise-Node-Logs, um JSON-RPC-Payloads nachzuverfolgen

Der Server wird mit allem geliefert, was für den Betrieb über HTTP, SSE und STDIO erforderlich ist. Wählen Sie den Transport, der zu Ihrer Umgebung passt, und beginnen Sie mit der Erstellung von Diagrammen!