# 🧩 plantuml-mcp

Servidor **MCP** (Model Context Protocol) que le da a Claude la capacidad de **generar diagramas UML con PlantUML** y devolverte la imagen directamente en el chat.

Le pides *"hazme un diagrama de secuencia del flujo de un McDonald's"* → Claude escribe el código PlantUML → el MCP lo renderiza → ves el diagrama.

![Ejemplo: diagrama de secuencia de McDonald's](docs/ejemplo-mcdonalds.png)

<sub>Código fuente del ejemplo: [`examples/mcdonalds-secuencia.puml`](examples/mcdonalds-secuencia.puml)</sub>

---

## ✨ Qué incluye

| Herramienta | Qué hace |
|---|---|
| `render_diagram` | Renderiza código PlantUML a **PNG** (Claude ve la imagen), **SVG** o **TXT** (ASCII art). Puede guardarlo en un archivo con `output_path`. Si hay un error de sintaxis, indica la línea exacta para que Claude lo corrija solo. |
| `get_diagram_urls` | Genera enlaces para compartir (PNG/SVG/TXT) y un enlace al editor online de PlantUML. |
| `decode_diagram_url` | Recupera el código fuente a partir de una URL de PlantUML. |

Funciona con todos los tipos de diagrama de PlantUML: clases, secuencia, casos de uso, actividad, estados, componentes, despliegue, ER, mindmap, Gantt, etc. Si olvidas `@startuml` / `@enduml`, se agregan automáticamente.

## 📋 Requisitos

- [Node.js](https://nodejs.org/) **18 o superior**
- Conexión a internet (usa el servidor público de PlantUML, ver [Privacidad](#-privacidad))
- **No** necesitas Java ni instalar PlantUML

## 🚀 Instalación

```sh
git clone https://github.com/Vlonetatii3/PlantUML.git
cd PlantUML
npm install
npm test        # comprueba que todo funciona
```

Luego configúralo en tu cliente de IA:

### Opción A — Claude Code

**Solo en este proyecto:** el repo ya trae un `.mcp.json`. Abre Claude Code dentro de la carpeta y acepta el servidor `plantuml` cuando te lo pregunte.

**En todos tus proyectos** (recomendado):

```sh
claude mcp add plantuml --scope user -- node /ruta/absoluta/a/PlantUML/src/index.js
```

Comprueba que está conectado con `/mcp` dentro de Claude Code.

### Opción B — Claude Desktop

Edita el archivo de configuración:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "plantuml": {
      "command": "node",
      "args": ["/ruta/absoluta/a/PlantUML/src/index.js"]
    }
  }
}
```

> En Windows usa barras dobles: `"C:\\Users\\tu_usuario\\PlantUML\\src\\index.js"`

Reinicia Claude Desktop y verás las herramientas en el icono de 🔨.

### Opción C — Otros clientes MCP

Cualquier cliente compatible con MCP por `stdio` (Cursor, VS Code, etc.) sirve: el comando es `node /ruta/a/PlantUML/src/index.js`.

## 💬 Ejemplos de uso

Una vez configurado, simplemente pídelo en lenguaje natural:

- *"Hazme un diagrama de clases de un sistema de biblioteca con Libro, Socio y Préstamo"*
- *"Diagrama de casos de uso de un cajero automático"*
- *"Diagrama de actividad del proceso de inscripción a la universidad"*
- *"Diagrama de secuencia del login con JWT y guárdalo en `diagramas/login.png`"*
- *"Pásame el diagrama anterior en ASCII"*

## 🔒 Privacidad

Por defecto los diagramas se renderizan en el servidor público **https://www.plantuml.com/plantuml**, así que **el código de tus diagramas se envía a ese servidor**. Para trabajos de clase normalmente no hay problema, pero si trabajas con información sensible puedes usar tu propio servidor con Docker:

```sh
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
```

Y define la variable de entorno `PLANTUML_SERVER`:

```sh
# Claude Code
claude mcp add plantuml --scope user -e PLANTUML_SERVER=http://localhost:8080 -- node /ruta/a/PlantUML/src/index.js
```

```json
// Claude Desktop
"plantuml": {
  "command": "node",
  "args": ["/ruta/a/PlantUML/src/index.js"],
  "env": { "PLANTUML_SERVER": "http://localhost:8080" }
}
```

## 🛠️ Solución de problemas

| Problema | Solución |
|---|---|
| Claude no ve las herramientas | Reinicia el cliente después de configurarlo. En Claude Code revisa con `/mcp`. |
| `Cannot find module '@modelcontextprotocol/sdk'` | Te faltó `npm install` dentro de la carpeta del proyecto. |
| `PlantUML server responded 5xx` | El servidor público está caído o saturado; reintenta o usa uno propio con Docker. |
| Diagramas muy grandes fallan | Las URLs tienen límite de tamaño; divide el diagrama o usa un servidor propio. |

## 📁 Estructura

```
├── src/
│   ├── index.js       # Servidor MCP y definición de herramientas
│   └── plantuml.js    # Codificación PlantUML y llamadas al servidor
├── test/smoke.mjs     # Prueba rápida (npm test)
├── examples/          # Código .puml de ejemplo
├── docs/              # Imágenes del README
└── .mcp.json          # Configuración para Claude Code (alcance de proyecto)
```

## 📄 Licencia

[MIT](LICENSE) — úsalo, modifícalo y compártelo libremente.