PlantUML MCP Server

Servidor MCP para generar diagramas PlantUML desde Claude Desktop u otro cliente compatible con MCP. El proyecto permite renderizar y guardar diagramas directamente en el espacio de trabajo, además de obtener la URL pública del render o una versión ASCII para vista rápida.

Qué hace

• Convierte texto PlantUML en una imagen renderizada por el servidor público de PlantUML.
• Guarda diagramas en la carpeta diagrams/ del proyecto.
• Expone tres herramientas MCP principales:
  • render_and_save_diagram: genera y guarda un archivo png o svg.
  • get_diagram_url: devuelve la URL del render para visualizarlo en web.
  • render_ascii_art: devuelve una versión textual del diagrama.

Requisitos

• Python 3.10 o superior.
• Acceso a Internet para consultar el servidor público de PlantUML.
• Claude Desktop u otro cliente MCP compatible.

Estructura del proyecto

• server.py: servidor MCP con las herramientas de PlantUML.
• test_plantuml.py: prueba rápida para validar la codificación y la conexión.
• claude_desktop_config.json: ejemplo de configuración para Claude Desktop.
• diagrams/: carpeta de salida de los diagramas generados.

Instalación paso a paso

1. Instala las dependencias del proyecto.

pip install -r requirements.txt

2. Verifica que el servidor esté disponible.

python test_plantuml.py

3. Revisa la configuración de Claude Desktop.

El archivo claude_desktop_config.json ya incluye una entrada MCP similar a esta:

{
  "mcpServers": {
    "plantuml": {
      "command": "python",
      "args": ["c:/Users/risse/Downloads/DIAGRAM SEQ/server.py"]
    }
  }
}

4. Reinicia Claude Desktop para que detecte el servidor MCP.

Cómo usarlo

Opción 1: generar y guardar un diagrama

Pídele al asistente que use la herramienta render_and_save_diagram con un bloque PlantUML completo. Si no incluyes @startuml y @enduml, el servidor los agrega automáticamente.

Ejemplo de salida esperada:

• Archivo guardado en diagrams/mi_diagrama.svg
• URL pública del render

Opción 2: obtener solo la URL

Usa get_diagram_url cuando quieras revisar el resultado en el navegador antes de guardar el archivo.

Opción 3: obtener una vista rápida en texto

Usa render_ascii_art para revisar la estructura del diagrama sin abrir una imagen.

Buenas prácticas para prompts

• Describe el objetivo del proceso antes de pedir el diagrama.
• Indica el tipo de diagrama que necesitas.
• Define los participantes, sistemas, bases de datos y decisiones.
• Pide que el diagrama sea detallado si necesitas activaciones, fragmentos alt, opt o loop.
• Si el flujo es empresarial, aclara el dominio y los términos del negocio.
• Si quieres un archivo final, especifica el nombre exacto del SVG o PNG.

Prompts recomendados para diagramas de secuencia

1. Proceso de nómina

Genera un diagrama de secuencia en PlantUML para el proceso de cálculo de nómina mensual. Incluye actor, interfaz, controlador, entidades de base de datos, lectura de infotipos, validaciones, cálculo de conceptos y persistencia final. Usa fragmentos alt y loop cuando aplique.

2. Integración SAP HCM con SAP B1

Crea un diagrama de secuencia detallado de la integración entre SAP HCM y SAP B1. Incluye autenticación, envío de datos por protocolo de comunicación, validación de respuesta, manejo de errores y confirmación de registro.

3. Liquidación por cese

Diseña un diagrama de secuencia para la liquidación por desvinculación de un colaborador. Incluye consulta de baja en Infotipo 0000, cálculo de gratificación trunca, CTS trunca, vacaciones no gozadas, descuentos por préstamos y persistencia en el clúster de nómina.

4. Beneficios legales semestrales

Elabora un diagrama de secuencia para el cálculo semestral de beneficios legales en Perú. Incluye gratificaciones, CTS, bonificación extraordinaria, promedios de variables, validación de habitualidad y escritura por bloque en el clúster.

5. Cálculo de retenciones y aportes

Genera un diagrama de secuencia del cálculo de retenciones y aportes previsionales. Incluye evaluación ONP o AFP, aporte obligatorio, comisión, prima de seguro, EsSalud, validaciones y registro final de deducciones.

Prompts para otros diagramas PlantUML

Diagramas de actividad

Genera un diagrama de actividad en PlantUML para el alta de un colaborador. Incluye decisiones, validaciones, aprobaciones y un flujo alterno para datos incompletos.

Diagramas de casos de uso

Crea un diagrama de casos de uso para un sistema de nómina. Incluye analista de personal, administrador, auditor y los casos principales de cálculo, consulta, aprobación y reporte.

Diagramas de clases

Diseña un diagrama de clases PlantUML para una solución de nómina. Incluye empleado, contrato, concepto, incidencia, cálculo, liquidación y clúster de nómina con sus relaciones.

Diagramas de componentes

Genera un diagrama de componentes para una arquitectura de RR. HH. con frontend, API, motor de cálculo, servicio de integración, base de datos y sistemas externos.

Diagramas de despliegue

Crea un diagrama de despliegue que muestre cliente, servidor de aplicaciones, base de datos, servidor de integración y servicios externos en una arquitectura empresarial.

Diagramas de estados

Elabora un diagrama de estados para el ciclo de vida de un colaborador: preingreso, activo, suspendido, cesado y liquidado.

Plantillas de prompt reutilizables

Plantilla básica

Genera un diagrama de [tipo de diagrama] en PlantUML para [proceso].
Incluye: [actores / sistemas / datos / decisiones].
Hazlo detallado y listo para exportar a SVG.

Plantilla para secuencia avanzada

Genera un diagrama de secuencia en PlantUML con estas condiciones:
- Actor principal: [actor]
- Sistema de frontera: [UI o API]
- Controlador: [motor o servicio]
- Entidades: [bases de datos o tablas]
- Fragmentos: alt, opt y loop cuando haya validaciones o iteraciones
- Persistencia final: [sí/no]
- Nombre de archivo sugerido: [archivo.svg]

Archivos generados

Los diagramas se guardan automáticamente en la carpeta diagrams/. Algunos ejemplos del repositorio son:

• 04_calculo_nominal_mensual.svg
• 05_calculo_retenciones_prevision_social.svg
• 06_calcular_beneficios_legales_semestrales.svg
• 07_procesar_desvinculacion_beneficios_trucos.svg

Solución de problemas

• Si no se genera la imagen, verifica que tengas conexión a Internet.
• Si Claude Desktop no detecta el servidor, revisa la ruta de server.py en claude_desktop_config.json y reinicia la aplicación.
• Si el diagrama sale incompleto, pide más detalle explícitamente en el prompt y solicita activaciones, validaciones o fragmentos condicionales.