PlantUML MCP 服务器

灵活的模型上下文协议 (MCP) 服务器，可将 PlantUML 代码片段转换为可共享的图表。 所有功能均通过 HTTP、服务器发送事件 (SSE) 和 STDIO 公开，因此您可以将此服务器接入 Claude Desktop、Flowise 或任何其他兼容 MCP 的运行时。

主要功能

• 🧰 工具：generate_plantuml_diagram, generate_capability_landscape, generate_business_scenario, encode_plantuml, decode_plantuml

• 🧾 提示词：plantuml_error_handling, capability_landscape_input_format, archimate_diagram_input_format, business_scenario_input_format

• 📚 静态资源：resource://plantuml/server-guide, resource://plantuml/archimate-mapping

• 🔒 可选的 Bearer 身份验证（通过 MCP_API_KEY）

• ☁️ 可选的 ob-file 导出（通过签名下载 URL，OB_FILE_API_BASE_URL）

• 🔐 可选的 ob-file OIDC 客户端凭据流 (OB_FILE_OIDC_*)

• 📁 后备共享卷导出 (GENERATED_FILES_DIR + PUBLIC_FILE_BASE_URL)

Related MCP server: PlantUML MCP Server

要求

• Node.js 18+

• npm 9+

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

构建完成后，使用 npx plantuml-mcp-server 或 node dist/plantuml-mcp-server.js。

传输模式

HTTP 传输

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

• POST /mcp 用于初始化并发送 JSON-RPC 有效负载。

• GET /mcp 和 DELETE /mcp 用于保持可流式传输的会话活跃。

• GET /healthz 可用于就绪状态探测。

• 客户端设置示例：client_config_http.json。

SSE 传输

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

• 客户端连接到 /sse (GET) 以获取事件，并向 /messages POST JSON 消息。

• Claude Desktop / Flowise 的配置示例：client_config_sse.json。

STDIO 传输

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

• 适用于本地实验、mcp CLI 或生成二进制文件的 Flowise 节点。

• 设置示例位于 client_config_stdio.json。

客户端配置示例

• client_config_http.json – 可流式传输的 HTTP (默认 /mcp)

• client_config_sse.json – SSE + 专用 messagesUrl

• client_config_stdio.json – 用于 npx 和 Flowise 管理进程的 STDIO 示例

将这些文件放入您的 MCP 兼容客户端，或根据需要复制片段。请根据您的部署更新主机名、端口和 API 密钥。

环境变量

当配置了 OB_FILE_API_BASE_URL 时，渲染后的图表将通过 ob-file 上传，MCP 响应将返回由 ob-file 生成的签名 download_url。如果配置了 OB_FILE_OIDC_DISCOVERY_URL、OB_FILE_OIDC_CLIENT_ID 和 OB_FILE_OIDC_CLIENT_SECRET，服务器将通过 OAuth 2.0 客户端凭据自动获取并缓存访问令牌。共享卷路径仍作为本地/开发设置的兼容性后备方案。

工具、提示词与资源

• 工具 通过 tools/list 自动注册。它们执行验证、可选的自动修复，并返回结构化元数据（success、URL、Markdown 片段、编码后的图表数据和验证错误）。

• 提示词 指导模型处理 PlantUML 错误，并提供现成的能力全景图模板。

• 资源模板 公开入门内容 (resource://plantuml/server-guide)，以便客户端可以自行发现使用说明。

Docker 镜像

提供的 Dockerfile 构建 TypeScript 源码并生成最小化的运行时镜像：

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

根据需要覆盖环境变量 (PLANTUML_SERVER_URL, MCP_API_KEY 等)。

测试与工具

• npm run build – 编译 TypeScript

• npm start – 使用默认的 HTTP 传输运行

• npm run start:sse / npm run start:stdio – 便捷脚本

• npm run test:business-scenario – 快照测试，将 test_files/generate_sequence_diagram/payload.json 转换为 PlantUML 并与 expected.puml 进行比较

• make test-mcp – 通过 mcp CLI 进行冒烟测试

需要帮助？

• 使用 curl http://<host>:<port>/healthz 验证连接性

• 如果启用了身份验证，请确认授权标头与 MCP_API_KEY (Bearer 令牌) 匹配

• 使用 MCP Inspector 或 Flowise 节点日志来跟踪 JSON-RPC 有效负载

该服务器附带了通过 HTTP、SSE 和 STDIO 操作所需的一切。插入符合您环境的传输方式并开始生成图表吧！