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

npm install
npm run build

Esto compila src/ hacia dist/.

Para verificar que el servidor funciona correctamente sin necesidad de un cliente MCP real:

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:

{
  "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):

{
  "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:

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

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