# 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.

```bash
pip install -r requirements.txt
```

2. Verifica que el servidor esté disponible.

```bash
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:

```json
{
  "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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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.