Servidor MCP de PlantUML

Servidor flexible del Protocolo de Contexto de Modelo (MCP) que convierte fragmentos de PlantUML en diagramas compartibles. Todas las capacidades se exponen a través de HTTP, Server-Sent Events (SSE) y STDIO, por lo que puede conectar el servidor a Claude Desktop, Flowise o cualquier otro entorno de ejecución compatible con MCP.

Características principales

• 🧰 Herramientas: 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

• 📚 Recursos estáticos: resource://plantuml/server-guide, resource://plantuml/archimate-mapping

• 🔒 Autenticación Bearer opcional mediante MCP_API_KEY

• ☁️ Exportación opcional ob-file mediante URLs de descarga firmadas (OB_FILE_API_BASE_URL)

• 🔐 Flujo de credenciales de cliente OIDC opcional para ob-file (OB_FILE_OIDC_*)

• 📁 Exportación de respaldo en volumen compartido (GENERATED_FILES_DIR + PUBLIC_FILE_BASE_URL)

Related MCP server: PlantUML MCP Server

Requisitos

• Node.js 18+

• npm 9+

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

Utilice npx plantuml-mcp-server o node dist/plantuml-mcp-server.js una vez compilado.

Modos de transporte

Transporte 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 para inicializar y enviar cargas útiles JSON-RPC.

• GET /mcp y DELETE /mcp mantienen viva la sesión transmitible.

• GET /healthz está disponible para pruebas de preparación.

• Configuración de cliente de muestra: client_config_http.json.

Transporte 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

• Los clientes se conectan a /sse (GET) para eventos y envían mensajes JSON mediante POST a /messages.

• Configuración de muestra para Claude Desktop / Flowise: client_config_sse.json.

Transporte STDIO

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

• Ideal para experimentos locales, CLI mcp o nodos de Flowise que generan el binario.

• Las configuraciones de ejemplo se encuentran en client_config_stdio.json.

Configuraciones de cliente de muestra

• client_config_http.json – HTTP transmitible (predeterminado /mcp)

• client_config_sse.json – SSE + messagesUrl dedicado

• client_config_stdio.json – Ejemplos de STDIO para npx y procesos gestionados por Flowise

Coloque estos archivos en su cliente compatible con MCP o copie los fragmentos según sea necesario. Actualice los nombres de host, puertos y claves API para que coincidan con su implementación.

Variables de entorno

Cuando se configura OB_FILE_API_BASE_URL, los diagramas renderizados se cargan a través de ob-file y la respuesta MCP devuelve la download_url firmada generada por ob-file. Si se configuran OB_FILE_OIDC_DISCOVERY_URL, OB_FILE_OIDC_CLIENT_ID y OB_FILE_OIDC_CLIENT_SECRET, el servidor obtiene y almacena en caché un token de acceso automáticamente mediante credenciales de cliente OAuth 2.0. La ruta del volumen compartido permanece como una alternativa de compatibilidad para configuraciones locales/de desarrollo.

Herramientas, Prompts y Recursos

• Las herramientas se registran automáticamente a través de tools/list. Realizan validación, correcciones automáticas opcionales y devuelven metadatos estructurados (success, URLs, fragmentos de markdown, datos de diagrama codificados y errores de validación).

• Los prompts guían al modelo a través del manejo de errores de PlantUML y proporcionan una plantilla de paisaje de capacidades lista para usar.

• Las plantillas de recursos exponen contenido de incorporación (resource://plantuml/server-guide) para que los clientes puedan descubrir por sí mismos las instrucciones de uso.

Imagen de Docker

El Dockerfile proporcionado compila las fuentes de TypeScript y produce una imagen de tiempo de ejecución mínima:

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

Anule las variables de entorno (PLANTUML_SERVER_URL, MCP_API_KEY, etc.) según sea necesario.

Pruebas y herramientas

• npm run build – compilar TypeScript

• npm start – ejecutar usando el transporte HTTP predeterminado

• npm run start:sse / npm run start:stdio – scripts de conveniencia

• npm run test:business-scenario – prueba de instantánea que convierte test_files/generate_sequence_diagram/payload.json en PlantUML y lo compara con expected.puml

• make test-mcp – comandos de prueba de humo a través de la CLI mcp

¿Necesitas ayuda?

• Verifique la conectividad con curl http://<host>:<port>/healthz

• Confirme que las cabeceras de autenticación coincidan con MCP_API_KEY (token Bearer) si está habilitado

• Utilice el Inspector MCP o los registros de nodos de Flowise para rastrear las cargas útiles JSON-RPC

El servidor se envía con todo lo necesario para operar a través de HTTP, SSE y STDIO. ¡Conecte el transporte que coincida con su entorno y comience a generar diagramas!