Content
# fluyo-mcp
Servidor MCP para **Fluyo**: crea, edita y exporta diagramas de arquitectura directamente desde Claude, operando sobre el mismo formato `.fluyo.json` que produce y consume la aplicación.
No depende de un backend nuevo: es una capa delgada sobre el modelo de documento que ya utiliza `fluyo.html` (`serializeProject()`), portado 1:1 (paleta semántica, íconos GCP/AWS/Azure/General, tamaños por forma y exportador SVG). Un documento generado desde este servidor puede abrirse directamente con el botón **Abrir** de Fluyo.
---
# Qué resuelve
- **`create_diagram`** — Crea un diagrama completo a partir de una lista de nodos y aristas (texto → diagrama). Si no se especifican coordenadas (`x/y`), aplica un auto-layout por capas.
- **`edit_diagram`** — Modifica un documento existente mediante operaciones como agregar, eliminar o actualizar nodos y aristas, cambiar el tema o recalcular el layout.
- **`export_diagram`** — Exporta una página a SVG estático utilizando exactamente el mismo renderer que Fluyo.
- **`list_templates`** / **`create_from_template`** — Permiten instanciar patrones de arquitectura predefinidos (Kafka, RAG, microservicios, etc.) con reemplazo de etiquetas.
- **`list_icons`** / **`list_colors`** — Exponen las claves válidas para íconos y colores, evitando que el modelo tenga que adivinarlas.
---
# Instalación
```bash
npm install
npm run build
```
Esto compila `src/` hacia `dist/`.
Para verificar que el servidor funciona correctamente sin necesidad de un cliente MCP real:
```bash
npm run smoke-test
```
El smoke test levanta un cliente y servidor utilizando un transporte en memoria (`InMemoryTransport`) y ejecuta un flujo completo de extremo a extremo.
---
# Conectarlo a Claude
## Claude Code / Claude Desktop
Agrega el siguiente servidor a la configuración MCP:
```json
{
"mcpServers": {
"fluyo": {
"command": "node",
"args": [
"/ruta/absoluta/a/fluyo-mcp/dist/index.js"
]
}
}
}
```
También puede instalarse como ejecutable global (`npm link` o publicado en npm):
```json
{
"mcpServers": {
"fluyo": {
"command": "fluyo-mcp"
}
}
}
```
---
# Ejemplo de uso
### Prompt
> Diagrama un pipeline donde un API Gateway recibe requests, publica eventos en Kafka y dos servicios consumidores procesan los mensajes; uno de ellos persiste en Cloud SQL.
Claude llamará a `create_diagram` con una estructura similar a la siguiente:
```json
{
"pageName": "Pipeline de eventos",
"nodes": [
{
"key": "gw",
"shape": "rect",
"label": "API Gateway",
"color": "Servicio"
},
{
"key": "kafka",
"shape": "icon",
"icon": "kafka",
"label": "Kafka",
"pulse": true,
"color": "Eventos / Kafka"
},
{
"key": "svcA",
"shape": "rect",
"label": "Servicio A",
"color": "Servicio"
},
{
"key": "svcB",
"shape": "rect",
"label": "Servicio B",
"color": "Servicio"
},
{
"key": "db",
"shape": "cylinder",
"label": "Cloud SQL",
"color": "Datos"
}
],
"edges": [
{
"from": "gw",
"to": "kafka",
"label": "evento",
"route": "ortho"
},
{
"from": "kafka",
"to": "svcA",
"label": "topic: A",
"route": "ortho"
},
{
"from": "kafka",
"to": "svcB",
"label": "topic: B",
"route": "ortho"
},
{
"from": "svcB",
"to": "db",
"label": "persistencia",
"dashed": true
}
]
}
```
El resultado es un documento `.fluyo.json` completamente válido, listo para abrir en Fluyo o continuar editando mediante `edit_diagram` y `export_diagram`.
---
# Operaciones disponibles en `edit_diagram`
Las operaciones se envían como una lista dentro del campo `operations` y se ejecutan en orden.
| Operación | Campos principales | Descripción |
|-----------|-------------------|-------------|
| `add_node` | `key`, `shape`, `label`, `color?`, `icon?`, `x?`, `y?` | Agrega un nodo nuevo. `key` solo existe durante esa llamada para permitir referencias posteriores. |
| `update_node` | `id`, ... | Actualiza un nodo existente utilizando su identificador numérico. |
| `remove_node` | `id` | Elimina un nodo y todas sus conexiones. |
| `add_edge` | `from`, `to` | Crea una conexión. Puede referenciar IDs existentes o `key` de nodos creados en la misma llamada. |
| `update_edge` | `id`, ... | Modifica una arista existente. |
| `remove_edge` | `id` | Elimina una arista. |
| `set_theme` | `theme` | Cambia el tema (`dark`, `crema` o `claro`). |
| `rename_page` | `name` | Cambia el nombre de la página. |
| `relayout` | — | Recalcula automáticamente la posición de todos los nodos. |
> **Nota:** para referenciar nodos ya existentes en el documento siempre debe utilizarse su `id` numérico. Las `key` utilizadas durante `add_node` son temporales y no se almacenan dentro del `.fluyo.json`.
---
# Limitaciones actuales
- El exportador genera únicamente **SVG**. La exportación a PNG o GIF requerirá integrar un renderer como `sharp`, `resvg` o `node-canvas`.
- Los nodos de tipo `image` no pueden crearse mediante MCP, ya que dependen de archivos binarios importados manualmente en Fluyo. Sin embargo, sí pueden editarse si ya existen en un documento.
- El SVG exportado no incluye animaciones (flujo de partículas o aparición progresiva), igual que el exportador nativo de Fluyo.
- El algoritmo de auto-layout utiliza un enfoque simple por capas (Sugiyama simplificado). Funciona muy bien para pipelines y arquitecturas convencionales; para grafos complejos puede ser recomendable especificar coordenadas manualmente o utilizar `relayout` seguido de ajustes puntuales.
---
# Estructura del proyecto
```text
src/
schema.ts # Paleta, temas, íconos y tamaños portados desde fluyo.html
model.ts # Esquemas Zod y tipos del documento Fluyo
layout.ts # Auto-layout por capas (Sugiyama simplificado)
diagram.ts # createDiagram / editDiagram
svg.ts # Exportador SVG
templates.ts # Plantillas de arquitectura
server.ts # Registro de tools MCP
index.ts # Entry point (stdio)
scripts/
smoke-test.ts # Cliente + servidor usando InMemoryTransport
```
