PlantUML MCP Server

Flexible Model Context Protocol (MCP) server that turns PlantUML snippets into shareable diagrams.
All capabilities are exposed over HTTP, Server-Sent Events (SSE), and STDIO, so you can plug the server into Claude Desktop, Flowise, or any other MCP-compatible runtime.

---

Key Features

• 🧰 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
• 📚 Static resources: resource://plantuml/server-guide, resource://plantuml/archimate-mapping
• 🔒 Optional Bearer authentication via MCP_API_KEY
• ☁️ Optional shared storage export (GENERATED_FILES_DIR + PUBLIC_FILE_BASE_URL)

---

Requirements

• Node.js 18+
• npm 9+

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

Use npx plantuml-mcp-server or node dist/plantuml-mcp-server.js once built.

---

Transport Modes

Mode	When to use	How to start
HTTP (default)	Direct REST-style integration, reverse proxies, health checks	MCP_TRANSPORT=http node dist/plantuml-mcp-server.js
SSE	Claude Desktop / Flowise over the network with push updates	MCP_TRANSPORT=sse node dist/plantuml-mcp-server.js
STDIO	Local CLI tools (npx, Claude Code CLI, Flowise managed process)	MCP_TRANSPORT=stdio npx plantuml-mcp-server

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 to initialize and send JSON-RPC payloads.
• GET /mcp and DELETE /mcp keep the streamable session alive.
• GET /healthz is available for readiness probes.
• Sample client settings: 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 connect to /sse (GET) for events and POST JSON messages to /messages.
• Sample config for 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 for local experiments, mcp CLI, or Flowise nodes that spawn the binary.
• Example setups live in client_config_stdio.json.

---

Sample Client Configurations

• client_config_http.json – streamable HTTP (default /mcp)
• client_config_sse.json – SSE + dedicated messagesUrl
• client_config_stdio.json – STDIO examples for npx and Flowise-managed processes

Drop these files into your MCP-aware client or copy the snippets as needed. Update hostnames, ports, and API keys to match your deployment.

---

Environment Variables

Variable	Default	Purpose
LOG_LEVEL	info	emergency → debug supported
PLANTUML_SERVER_URL	https://www.plantuml.com/plantuml	Upstream PlantUML renderer
MCP_TRANSPORT	http	http, sse, or stdio
MCP_HOST / MCP_PORT	0.0.0.0 / 3000	Bind address + port (HTTP/SSE)
MCP_HTTP_PATH	/mcp	HTTP JSON-RPC endpoint
MCP_HTTP_ENABLE_JSON_RESPONSES	false	Return JSON body when true (for debugging)
MCP_SSE_PATH	/sse	SSE stream endpoint
MCP_SSE_MESSAGES_PATH	/messages	Message ingestion endpoint
MCP_API_KEY	unset	Enables Bearer auth when provided
GENERATED_FILES_DIR	/generated-files	Where rendered diagrams are persisted
PUBLIC_FILE_BASE_URL	https://ob-file.fmpn.fr/files	Base URL returned to clients for persisted diagrams
PLANTUML_MCP_SKIP_AUTO_START	unset	When true, skips auto-start so scripts can import the server class without launching transports

---

Tools, Prompts & Resources

• Tools are automatically registered through tools/list. They perform validation, optional auto-fixes, and return structured metadata (success, URLs, markdown snippets, encoded diagram data, and validation errors).
• Prompts guide the model through PlantUML error handling and provide a ready-made capability landscape template.
• Resource templates expose onboarding content (resource://plantuml/server-guide) so clients can self-discover usage instructions.

---

Docker Image

The provided Dockerfile builds the TypeScript sources and produces a minimal runtime image:

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

Override environment variables (PLANTUML_SERVER_URL, MCP_API_KEY, etc.) as needed.

---

Testing & Tooling

• npm run build – compile TypeScript
• npm start – run using the default HTTP transport
• npm run start:sse / npm run start:stdio – convenience scripts
• npm run test:business-scenario – snapshot test that converts test_files/generate_sequence_diagram/payload.json into PlantUML and compares it to expected.puml
• make test-mcp – smoke-test commands through the mcp CLI

---

Need Help?

• Verify connectivity with curl http://<host>:<port>/healthz
• Confirm auth headers match MCP_API_KEY (Bearer token) if enabled
• Use the MCP Inspector or Flowise node logs to trace JSON-RPC payloads

The server ships with everything required to operate over HTTP, SSE, and STDIO. Plug in the transport that matches your environment and start generating diagrams!