fluyo-mcp
Summary: This MCP server exposes tools for creating, editing, exporting, and discovering Fluyo architecture diagrams.
Create complete
.fluyo.jsondiagrams from nodes and edges with auto-layout, themes, custom backgrounds, fonts, colors, icons/anims, edge routing/animation, and optional build staggering.Edit existing Fluyo documents via node/edge add-update-remove operations, theme changes, page renaming, and full relayout.
Export a selected page to static SVG with scale and crop options.
List available icons, semantic colors, animated GIFs, fonts, and architecture templates.
Instantiate predefined architecture templates with custom label overrides.
Schema note: it still exposes the legacy
edit_diagramtool and omits newer README tools such asauthor_document,propose_layout, and story/run tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fluyo-mcp Create a diagram of an event-driven architecture with API Gateway, Kafka, and two consumers."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fluyo-mcp
Servidor MCP para Fluyo: crea, edita y exporta diagramas de arquitectura desde un asistente de IA, operando sobre el mismo formato .fluyo.json que produce y consume la aplicación.
No necesita backend. Es una capa delgada sobre el modelo de documento de Fluyo, así que lo que genera se abre con el botón Abrir del editor sin conversión de por medio, y un diagrama guardado desde la app se puede seguir editando desde aquí.
Qué resuelve
Tool | Para qué |
| Texto → diagrama. Nodos y aristas; si no das |
| Renderiza una página a SVG estático. |
| Instancia patrones de arquitectura predefinidos (Kafka, RAG, microservicios) con reemplazo de etiquetas. |
| Las 72 claves de ícono, agrupadas en 8 grupos (General, GCP, AWS, Azure, Estados, Seguridad, DevOps, Varios). |
| Los 14 colores semánticos de la paleta. |
| Los 8 GIFs animados para nodos |
| Las 14 tipografías disponibles (las 12 históricas, Playfair Display e IBM Plex Mono). |
| Lee un documento Fluyo (v1–v5) y lo resume para un agente: páginas, elementos, conexiones, biblioteca de eventos, Historias con sus pasos, validación de integridad, versiones de schema y motor. No modifica nada. |
| Crea, modifica y elimina el diagrama ( |
| Solo lectura. Calcula con el auto-layout por capas (el de |
| Cambia el tema ( |
| Orden Z de elementos de UNA página: |
| Duplica uno o varios elementos ( |
| Ejecuta una Historia con el mismo motor que el editor y devuelve el Trace, el resultado de cada paso, los errores de validación y las versiones. No simula nada: el motor es el de Fluyo. |
Las quince son funciones puras: reciben JSON y devuelven JSON, sin tocar disco, red ni ningún estado externo. Van anotadas como tal (readOnlyHint, idempotentHint).
edit_diagram se retiró en FLUYO-018.10 (era LEGACY desde 018.5). Su sustituto es author_document (y propose_layout para recolocar); ver «Retirada de edit_diagram».
Related MCP server: AI Charts
Instalación
npm install
npm run buildRequiere Node 22.18 o superior.
npm test # contrato contra los ejemplos reales de Fluyo, tools y rendererConectarlo
Hay dos transportes sobre el mismo núcleo. Las quince tools, sus schemas y el renderer son idénticos en los dos; lo único que cambia es por dónde entran los mensajes.
stdio | Streamable HTTP | |
Entry point |
|
|
Uso | local, el proceso lo lanza el cliente | conector remoto en |
Sesiones | una por proceso | ninguna: stateless, cada petición se procesa y se descarta |
Topes | ninguno | 1 MB de entrada, 200 KB por respuesta de tool, 30 req/min por IP |
Como conector remoto
POST https://mcp.fluyo.space/mcpSin autenticación y sin Mcp-Session-Id. Pega esa URL donde tu cliente pida un servidor MCP remoto.
Como proceso local (stdio)
Añade el servidor a la configuración MCP de Claude Code o Claude Desktop:
{
"mcpServers": {
"fluyo": {
"command": "node",
"args": ["/ruta/absoluta/a/fluyo-mcp/dist/index.js"]
}
}
}O como ejecutable global (npm link):
{
"mcpServers": {
"fluyo": { "command": "fluyo-mcp" }
}
}Historias: leer, validar y ejecutar (describe_document, run_story)
Estas dos tools no escriben: leen un documento, lo validan y ejecutan una Historia. La autoría de Historias (crear, duplicar, editar pasos) es de author_document (sección siguiente).
fluyo/js (kernel) ──sync:kernel──▶ src/generated/kernel-sources.ts ──▶ vm aislado por llamada
modelo · motor · FluyoStory · FluyoIntegrity (copia verbatim + sha256) describe_document · run_storyEl motor no se reimplementa.
npm run sync:kernelcopia, sin modificarlos, los scripts defluyo/js(config,safe-svg,model,scenario-engine,scenario-playback,story-playback,story-clock,document-integrity,story-authoring). Cada llamada los carga en un contextovmnuevo.npm run check:kernel(y el jobdrift) falla si la copia se desvía defluyo/. Cada resultado trae elkernelId(hash del conjunto) para poder reproducirlo. Elvmno trae los globals web que el kernel da por existentes;src/kernel.tsenvuelveatob,btoa,TextEncoderyTextDecoderde Node en la frontera (los usan los nodosimageal leer un documento). Eso no modifica el kernel ni cambia elkernelId.Validación única. La integridad (referencias a elementos, conexiones y eventos, acciones compatibles con su evento, Behaviors, ids, versión de schema y de motor) la decide
FluyoIntegrityde Fluyo, no este servidor.Un paso
OCCURRENCEes siemprenarrated: el motor lo registra aunque el elemento esté no disponible; no prueba que ocurriera nada real. Reintentos, colas, timeouts y lógica interna de los elementos no están en el modelo y se declaran enunmodeled.Si una Historia no es válida (p. ej. apunta a una conexión eliminada) no hay Trace: se devuelven los errores con su Historia y Step.
El desenlace de una Historia es el mismo que muestran el editor, Present y el Viewer: sale de
FluyoStoryClock.outcome, el archivo del producto, no de una copia. Lo dadescribe_documenten cada Historia (outcome),run_story(storyOutcome) yauthor_documenten las que toca (stories[].outcome). Es un dato estructurado; el texto visible es de la app y de su idioma:{ "status": "no_failures" } { "status": "failed", "moment": 3, "stepId": 3, "reason": "target_down", "reasonNode": { "id": 3, "label": "Bank" } } { "status": "empty" } { "status": "not_executable" }momentempieza en 1, como «Falla en el paso N» de la app;steps[].momentderun_storyempieza en 0.Sentido del recorrido: un paso que recorre su conexión al revés (
reverse:true, ver la autoría) sale endescribe_documenty enrun_storycontarget.reverse:true.target.from/target.toson siempre los de la conexión;target.label, la frase y el motivo de un fallo (reasonNode) van en el sentido del recorrido. Sus eventos del Trace (send_started,send_succeeded,send_failed) llevanreverse:truedetrás deedgeId. Sinreverse, la salida es la de siempre, clave a clave.
Escribir una Historia: el recorrido mínimo
enlace o documento ─▶ describe_document (detail:"summary") ─▶ author_document (baseRevision, detail:"summary") ─▶ editorUrl para la persona
revision, ids, eventos, outcome stories[].outcome, warnings, storyRefs, resultRevisionDos llamadas.
run_storysolo hace falta para ver el Trace o cada paso: el desenlace ya viene en la respuesta, también condryRun:true.Un enlace de una persona.
describe_documentlo lee sinbaseRevisiony da surevisioncanónica (conlinkRevisionUnverified:true, porque sin revisión no se puede comprobar una copia). Es solo para leer: cualquier escritura sigue exigiendobaseRevision, y lo truncado o corrupto se rechaza sin reconstruir nada. Un enlace de Compartir (/s/) lo marcalinkKind:"viewer": es una instantánea, sin las Historias de otras páginas.Un fallo es del motor. El destino pasa a
DOWNcon un eventoSET_AVAILABILITYen un momento anterior al envío: el envío quedanot_completedyoutcomeesfailed, con el mismo Trace que «Falla aquí» de la app. En el mismo momento no falla, y unmessagenunca causa un fallo.Otras Historias.
set_initial_availabilityes de la página y afecta a todas sus Historias. Si un lote cambia el desenlace de una Historia que no editó, sigue siendook:true, perowarnings[]llevaSTORY_OUTCOME_CHANGEDconbeforeyafter.Idioma.
nameymessagevan en el idioma de la petición del usuario, aunque el catálogo esté en español. Los elementos del documento no se traducen.detail:"summary"quita lo que no hace falta para escribir: endescribe_document, coordenadas, pasos ycapabilities; enauthor_document,changesyunmodeled; enrun_story,traceyunmodeled. Sin él, las respuestas son las de siempre, con los campos nuevos añadidos.Errores de schema. Lo que Zod rechaza antes de llegar a la tool lleva un 2.º bloque
{ok:false, errors:[{code:"SCHEMA_INVALID", path, operationIndex, operation, issue, expected, received}]}.TARGET_NOT_FOUNDyTARGET_INCOMPATIBLEtraencandidatesde esa página.Sin parentesco. Una variante es otra Historia de la misma página:
duplicate_storyyremove_stepdan lo mismo que «Otra forma desde aquí». El modelo no guarda de qué Historia sale.
Autoría del diagrama, Historias y eventos (author_document)
describe_document (revision) ──▶ author_document (baseRevision + operaciones) ──▶ run_story
│ copia → lote → FluyoIntegrity (estado final)
▼
documento nuevo + resultRevision | rechazo: sin documentoAtómico: o se aplica todo el lote o nada; el documento recibido nunca se modifica.
dryRun:truevalida y devuelve loschangessin documento;returnDocument:falseaplica el lote y omite el documento si traeeditorUrl(ver «Respuestas sin el documento»).Revisión optimista, sin estado:
baseRevisiones larevisiondel documento (sha256 del JSON canónico del documento normalizado): la que anunciadescribe_document, la del resumen decreate_*o elresultRevisionde la autoría anterior. Si no coincide →REVISION_MISMATCHcon la real enactual; siactuales la revisión del documento que devolvió la última llamada, basta reintentar con ella, sin releerlo.resultRevisiones determinista.Un paso = evento + objetivo:
eventTypeId+target({edgeId, reverse?}/{from,to}para conexiones;{nodeId}para elementos; o{ref}de lo creado en el lote; los ids deedgeId/nodeId/from/totambién admiten{ref}). La acción la decide el evento; no se escribeaction,stateniat.Sentido de un paso FLOW (
reverse, contrato de Fluyo STEP-REVERSE): unSENDpuede recorrer su conexión detoafrom. Así la respuesta va por la misma conexión que la petición, sin dibujar la inversa. Formas detarget:{from, to}: busca primero la conexión directafrom → to(sentido normal); si no hay ninguna, la inversato → fromconreverse:true. Varias en el nivel que decide →AMBIGUOUS_TARGET; ninguna en ningún sentido →TARGET_NOT_FOUND. Con{from, to}no se escribereverse: la forma ya dice el sentido.{edgeId, reverse}y{ref, reverse}: la forma explícita.reversesolo vale para una conexión (sobre un elemento,TARGET_INCOMPATIBLE).reverse:falsees el sentido normal y no se guarda: en el documento la clave está ausente o valetrue.retarget_step: eltargetdescribe el recorrido completo (sinreverse= normal).{edgeId: la misma, reverse:true}da la vuelta en el sitio. Suchanges[]traereverseypreviousReversesolo si alguno estrue.add_stepyduplicate_steptraenreverse:truecuando aplica.La conexión no cambia nunca. Si se reconecta, el paso sigue a la conexión.
engineVersionsigue en 2 y el documento en v5. Un kernel anterior (o una app con caché antigua) rechaza el documento en vez de leerlo mal.
Patrón petición/respuesta. Diagrama: Cliente (1) → API (2) → DB (3), con las conexiones 4 (1→2) y 5 (2→3). Eventos: 1 «Petición» (
{source} pide a {target}) y 2 «Respuesta» ({source} responde a {target}). Las respuestas usan las conexiones 5 y 4 al revés:[ {"op":"create_story","scope":"story","pageIndex":0,"ref":"h","name":"Petición y respuesta"}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"h"},"eventTypeId":1,"target":{"from":1,"to":2},"waitMs":0}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"h"},"eventTypeId":1,"target":{"from":2,"to":3},"waitMs":500}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"h"},"eventTypeId":2,"target":{"from":3,"to":2},"waitMs":500}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"h"},"eventTypeId":2,"target":{"edgeId":4,"reverse":true},"waitMs":500} ]El tercer paso no tiene conexión 3 → 2, así que usa la 5 con
reverse:true. El cuarto lo pide de forma explícita. Pasos guardados:{"id":1,"at":0,"action":"SEND","edgeId":4,"eventTypeId":1} {"id":2,"at":500,"action":"SEND","edgeId":5,"eventTypeId":1} {"id":3,"at":1000,"action":"SEND","edgeId":5,"eventTypeId":2,"reverse":true} {"id":4,"at":1500,"action":"SEND","edgeId":4,"eventTypeId":2,"reverse":true}Respuesta de
run_storypara el paso 3 con DB caída (set_initial_availabilityDOWN):{"stepId":3,"target":{"kind":"connection","id":5,"from":2,"to":3,"reverse":true,"label":"DB → API"}, "sentence":"DB responde a API", "outcome":{"status":"not_completed","reason":"source_down","reasonNode":{"id":3,"label":"DB"}}}En el Trace:
{"at":1000,"type":"send_failed","stepId":3,"edgeId":5,"reverse":true,"reason":"source_down"}. Quien no puede responder es DB, el origen del recorrido. La petición del paso 2 falla en cambio contarget_down, también sobre DB. El resultado es el mismo que con una conexión DB → API dibujada.Mensaje de un paso (contrato de Fluyo STEP-MESSAGE-001 y PRODUCT-NARRATION-001, decisiones 255 y 258): cualquier paso, también un envío (
SEND), puede llevarmessage, la frase que cuenta qué ocurre en ese paso. Al reproducir en Fluyo (editor, Presentar y enlace compartido) es el título del momento en vez del nombre del evento y, en un paso de elemento (OCCURRENCEoSET_STATE), también el texto de su globo. Así no hace falta un evento por frase: un evento «Petición» y cada paso con su frase («Cliente solicita el checkout», «Pagos cobra la tarjeta»…).add_step {message}lo escribe al crear el paso yset_step_message {stepId, message}lo cambia o, connull, lo quita (changed:falsesi no cambia; solo afecta a ese paso). Son 1 a 120 caracteres que no sean solo espacios. El evento y su frase (sentence) no cambian, ni los tiempos, las dependencias o el Trace.duplicate_stepyretarget_steplo conservan.describe_documentyrun_storydanmessagejunto asentence, solo si el paso lo tiene. Un kernel anterior (o una app con caché antigua) rechaza el documento en vez de leerlo mal.Tiempo narrativo:
waitMsal añadir al final oset_waitpor momento; «al mismo tiempo» conplacement.sameMomentAs. Eliminar colapsa la espera; duplicar entra en el mismo momento.waitMsse cuenta desde el inicio del momento anterior y no incluye ni espera el viaje visual del token de unSEND(presentación:motionfast/normal/slow = 500/1100/1800 ms; no sirve para calcular esperas).Dependencias de llegada (explícitas, nunca inferidas de las conexiones):
add_stepconwaitsForArrivalOfoset_arrival_dependencies(reemplaza;[]las quita) declaran que el momento de un paso no empieza, al reproducir en Fluyo, hasta que llegue el token de envíos (SEND) anteriores de la misma Historia. Se guardan en la Historia (arrivalDependencies), no en el paso; el Trace no cambia. Lo inválido se rechaza conINVALID_ARRIVAL_DEPENDENCYy su razón. Patrón (FLUYO-018.28): todo paso que narre la recepción, el procesamiento o la consecuencia de un envío declarawaitsForArrivalOfde eseSEND; lo que no dependa de una llegada (otro nodo cae, otro envío) lleva solowaitMsy no se retrasa; un paso sobre el nodo destino sin dependencia no es una recepción (Fluyo no la deduce). Un envío fallido (destino caído) también «llega»: el momento que lo espera empieza cuando se ve el fallo en el destino.Incorrecto —el error habitual: usar
waitMscomo si fuera «lo que tarda en llegar el mensaje»; con un viaje normal (1100 ms), «B procesa» se ve a los 500 ms, 600 ms antes de que llegue el token—:[ {"op":"create_story","scope":"story","pageIndex":0,"ref":"cadena","name":"A → B → C"}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m1","eventTypeId":1,"target":{"edgeId":5},"waitMs":0}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m2","eventTypeId":2,"target":{"nodeId":2},"waitMs":500}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m3","eventTypeId":1,"target":{"edgeId":6},"waitMs":500}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m4","eventTypeId":2,"target":{"nodeId":3},"waitMs":500} ]Se ve: 0 → 500 → 1000 → 1500, con el token A→B llegando en 1100 y el de B→C en 2100.
Correcto —los mismos
waitMs; cada recepción declara el envío que espera—:[ {"op":"create_story","scope":"story","pageIndex":0,"ref":"cadena","name":"A → B → C"}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m1","eventTypeId":1,"target":{"edgeId":5},"waitMs":0}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m2","eventTypeId":2,"target":{"nodeId":2},"waitMs":500,"waitsForArrivalOf":[{"ref":"m1"}]}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m3","eventTypeId":1,"target":{"edgeId":6},"waitMs":500}, {"op":"add_step","scope":"story","pageIndex":0,"storyId":{"ref":"cadena"},"ref":"m4","eventTypeId":2,"target":{"nodeId":3},"waitMs":500,"waitsForArrivalOf":[{"ref":"m3"}]} ]Se ve: 0 → 1100 → 1600 → 2700. El Trace del motor es el mismo en los dos casos: solo cambia cuándo se ve cada momento.
describe_documentlo muestra enwaitsForde cada momento.B2: si el estado final dejaría una Historia inválida, se rechaza el lote con
REFERENCED_ENTITY(entidad, Historias y pasos afectados). Retargetear y borrar en el mismo lote es válido. (El editor de Fluyo aplica la misma detección pero confirma en lugar de rechazar —una persona ve el resultado y tiene Undo—; ninguno de los dos borra Steps ni Historias en silencio.)EventTypes (scope
eventType, globales al documento, sinpageIndex):create_event_type(name,primitiveFLOW | OCCURRENCE | SET_AVAILABILITY,sentencecon{source}/{target}/{name},symbol?,motion?sólo FLOW,availabilitysólo y obligatoria en SET_AVAILABILITY,presentation?como parche,ref?),update_event_typeydelete_event_type. Un evento creado en el lote se usa con{ref}enadd_step. La acción del paso la deriva la primitiva (FLOW→SEND, OCCURRENCE→OCCURRENCE, SET_AVAILABILITY→SET_STATE); nunca se escribe.Reglas del editor, las mismas: de un evento usado no cambian
primitiveniavailability(EVENT_TYPE_LOCKED, con el campo y los usos) y no se elimina (REFERENCED_ENTITYcon el EventType, las Historias y los Steps afectados). Nombre, frase, símbolo, movimiento y presentación sí cambian y se ven en todos sus usos; los Steps y el Trace no cambian. Un nombre repetido se acepta y se avisa (DUPLICATE_EVENT_TYPE_NAME).describe_documentlista cada evento conusedByyusedIn(página, Historia, Steps).Crear elementos y conexiones (scope
page, FLUYO-018.2):create_node{pageIndex, spec:{shape,x,y,w?,h?,label?,…}, ref?}ycreate_connection{pageIndex, source, target, spec?:{label?,route?,fromSide?,toSide?,waypoints?,…}, ref?}. Los campos son los del documento (w/h, colores en hex tal cual); sin ellos rigen los defaults del editor. Todas las formas salvoimage(necesita bytes de imagen, igual quecreate_diagram). Lo decidecreateNodeIn/createConnectionInde Fluyo —las mismas funciones que el editor—: forma, ids,source/target, auto-lazo (SELF_LOOP), ids duplicados (DUPLICATE_ID), geometría por defecto. Este servidor no calcula ninguna geometría.refdel lote: nombre que das a lo que creas; NO se guarda en el documento.source/targetson{ref}(algo creado antes en el lote, en la misma página: las refs son por página, así queclientepuede existir en la página 0 y en la 1) o{id}(un elemento existente). Así se construye Cliente → Comercio → Banco en una sola llamada sin conocer ningún id:
[
{"op":"create_node","scope":"page","pageIndex":0,"ref":"cliente","spec":{"shape":"rect","x":200,"y":300,"label":"Cliente"}},
{"op":"create_node","scope":"page","pageIndex":0,"ref":"comercio","spec":{"shape":"rect","x":600,"y":300,"label":"Comercio"}},
{"op":"create_connection","scope":"page","pageIndex":0,"ref":"pago","source":{"ref":"cliente"},"target":{"ref":"comercio"}}
] La respuesta trae changes (qué se creó, dónde, con qué ref e id) y refs: [{ref, type:"node"|"connection", pageIndex, id}] para seguir trabajando (también con dryRun, que no devuelve documento). Errores estructurados: UNKNOWN_REF, DUPLICATE_REF, SOURCE_NOT_FOUND, TARGET_NOT_FOUND, SELF_LOOP, DUPLICATE_ID, INVALID_FIELD (con field), PAGE_NOT_FOUND.
Límites: 200 operaciones por lote (se rechazan antes de ejecutar nada);
label≤ 500,waypoints≤ 100 por conexión,keywords≤ 200, campos de texto cortos con tope.Modificar (scope
page, FLUYO-018.3):update_node{pageIndex, node:{id}|{ref}, spec:{…}}yupdate_connection{pageIndex, connection:{id}|{ref}, source?, target?, spec?:{…}}.speces un parche: solo cambia lo que envías (undefined/ausente no toca nada;nullvacía lo anulable). Mover =x/y; redimensionar =w/h. Campos de un elemento:x, y, w, h, shape, label, color, fill, border, lblPos, textBg, textColor, font, bold, pulse, order, fsy, según la forma,tint(icono) olang, keywords, kwBg, kwColor(código); la forma solo cambia entre las del selector del editor (rect, cylinder, diamond, circle, hex, text, code; no desde/hacia image, icon, anim). De una conexión:label, route, fromSide, toSide, waypoints, font, bold, fs, animated, dashed, startArrow, endArrow, flowDir, lineColor, dotColor, speedFac, dots, dotsGlobal, arrowSize(FLUYO-018.27: tamaño de las puntas,1= el de siempre,1.5,2; el kernel acota en [1, 2] ynulllo quita; ausente = 1 sin migrar; solo cambia el dibujo de la punta, nunca la ruta).id,icon,anim,imgyrefno se modifican; un campo desconocido esINVALID_FIELD. Retarget =source/targeten la operación ({ref}|{id}; extremo inexistente →SOURCE_NOT_FOUND/TARGET_NOT_FOUND, auto-lazo →SELF_LOOP). Los waypoints solo cambian si los envías (mover, redimensionar o retargetear los conservan;waypoints:[]vuelve a la ruta automática):changes[].affects.connectionsWithWaypointsavisa de las conexiones con ruta manual afectadas por un movimiento. Este servidor no calcula geometría: la ruta se deriva en el editor.Eliminar (scope
page):delete_node{pageIndex, node}(quita también las conexiones del elemento y su disponibilidad inicial;changes[].cascadelo informa) ydelete_connection{pageIndex, connection}. Las Historias mandan (B2): la validación es sobre el estado final del lote, así que el orden no importa; si alguna Historia quedaría con un paso que apunta a lo eliminado se rechaza TODO conREFERENCED_ENTITY{entity, affectedStories[{storyId,storyName,stepIds}], affectedSteps, operationIndex, operation, reason, cascadedFrom?}(una conexión eliminada en cascada con su elemento llevacascadedFrom). No se limpia nada en silencio: ni Steps, ni EventTypes, ni Historias. Para eliminar algo usado, retargetea (retarget_step) o quita (remove_step) esos pasos en el mismo lote.Páginas (scope
document, FLUYO-018.5):create_page{name?}(añade siempre al final, no cambia la página activa; sin nombre usa el del editor; 1–80 caracteres) yrename_page{pageIndex, name}.create_pagedevuelve elpageIndexcreado enchanges[].pageIndex: las operaciones siguientes del mismo lote ya pueden usarlo (create_node,create_connection,create_story…). Las páginas no tienen id. SoncreatePageIn/renamePageIndemodel.js, las mismas que ejecuta el editor.delete_page{pageIndex, expectedName}(FLUYO-018.7c):expectedNamees obligatorio y debe ser el nombre ACTUAL exacto de la página (si no,PAGE_MISMATCH {pageIndex, expectedName, actualName}): un índice desactualizado nunca borra otra página. La página se va con sus elementos, conexiones, disponibilidad inicial e Historias (changes[].contentsychanges[].affects.stories); los eventos de la biblioteca se conservan siempre, también los que solo usaba esa página:affects.eventTypesFreedsolo informa de cuáles quedan sin ninguna referencia (para eliminarlos,delete_event_typeen otro lote o en el mismo). Nunca se borra la única página (CANNOT_DELETE_LAST_PAGE). La página activa sigue siendo la misma si sobrevive; si se borra, pasa a la siguiente (o a la anterior si era la última). Dentro del lote lospageIndexno se desplazan (los del inicio, más los quecreate_pageañade al final); usar una página eliminada esPAGE_DELETED. La respuesta traepageMap: [{from, to}](to: null= eliminada) para traducir los índices del lote a los del documento nuevo;changes[]usa los del lote yrefs/touchedStorieslos finales. EsdeletePageIndemodel.js, la misma que la ✕ del editor.Aspecto, orden Z y duplicado (FLUYO-018.7a; además son tools de una sola operación con el mismo nombre):
set_theme{theme?, customBg?}(scopedocument; parche e idempotente;customBgsolo HEX,nullo""lo quita; no entra en Undo del editor),reorder_nodes{pageIndex, nodes:[{id}|{ref}], to:"front"|"back"|"forward"|"backward"}(el Z es la posición del elemento en la página; las conexiones van siempre debajo; el orden relativo lo fija el documento, no la lista; no cambiar nada es válido:changed:false) yduplicate_node{pageIndex, nodes:[{source:{id}|{ref}, ref?}], connections?:"internal"|"none", offset?:{x,y}}(una operación atómica; ids nuevos por orden del documento, conexiones entre los duplicados con sus waypoints desplazados, Behaviors copiados; nunca pasos ni Historias;changes[].created=[{kind,from,id,ref?}]; las conexiones copiadas no reciben ref).describe_documentpublicatheme,customBg,capabilities.themesyzen cada elemento (0 = fondo).Reglas de entrada de
create_node/update_node(FLUYO-018.5;fill:"none"y colores de conexión: FLUYO-018.6): colores solo HEX (#rgb,#rrggbb,#rrggbbaa), yfilladmite además"none"(«Sin relleno», forma hueca; solo enfill);lineColor/dotColordecreate_connection/update_connectionsiguen la misma regla (onull= color del tema) y un valor inválido esINVALID_FIELDcon el campo;icon/animdeben existir en el catálogo (list_icons,list_anims) y las formasicon/animlos exigen;borderadmitenone.update_nodesolo valida lo que cambia: un valor antiguo inválido de un documento existente no impide editarlo.Límites de autoría (FLUYO-018.5;
describe_document→capabilities.limits):coordMax100000 (±,x/yy puntos dewaypoints),sizeMin/sizeMax10–5000 (w/h),maxNodesPerPage300,maxConnectionsPerPage600. Se evalúan sobre el estado final del lote (crear y borrar dentro del mismo lote, o cruzar un tope y volver, es válido) y solo sobre lo que el lote escribe: un documento antiguo que ya los excede se abre, se describe y se edita igual. Si no se cumplen se rechaza todo conLIMIT_EXCEEDED{limit, limitName, actual, field, pageIndex, entity?, operationIndex}.propose_layout(FLUYO-018.6, solo lectura):{document, pageIndex?, clearWaypoints?=true, baseRevision?}. Calcula con el auto-layout por capas de siempre (el decreate_diagram; no hay otro motor) dónde colocar los elementos de una página y devuelvebatches: lotes deauthor_document(≤200 operaciones;update_node {x,y}solo de los que cambian, yupdate_connection {waypoints:[]}solo de las conexiones con ruta manual cuyos extremos se mueven) que se aplican en orden (elbaseRevisionde cada lote es elresultRevisiondel anterior; el primero, larevisiondel documento). No modifica nada, no guarda estado y es determinista. Respeta los límites: si el layout necesita |x| o |y| >coordMaxno recorta, respondeLAYOUT_EXCEEDS_LIMITS{limit, limitValue, actual, field, nodeId, offendingNodes, required}. Otros errores:PAGE_NOT_FOUND,REVISION_MISMATCH,DOCUMENT_UNREADABLE. Flujo:describe_document→propose_layout→author_document(cada lote).Semántica de las conexiones y ruta observada (fluyo SCENARIOS-SEMANTICS-001 FASE 5):
kindenspecdecreate_connection/update_connectiony en las aristas decreate_diagram="FLOWS_TO"(Flujo: la ruta va desourceatarget, aunque la punta visible apunte al revés) |"REQUIRES"(Requisito:sourcenecesita atarget; nunca forma parte de una ruta) |null(quita la clave: conexión genérica). Lo decide el autor: nada se infiere.set_observed_flow(scopestory){pageIndex, storyId, source, target}(id o{ref}de elementos de la página, distintos) guarda la ruta observada de la Historia (observedFlow {from,to}) con la misma función que el editor (setObservedFlowIn);source:null, target:nullla quita (ruta automática); repetir lo guardado dachanged:false; no toca pasos ni tiempos.delete_nodesigue podando la ruta que nombraba el elemento (cascade.observedFlows).describe_documentpublicaconnectionKindsolo en Flujo y Requisito (nombre distinto detarget.kindde los pasos),observedFlow {source, target, sourceLabel, targetLabel}solo si está guardado ywarningssolo si los hay (observed_flow_endpoint_missing,unknown_connection_kind; no invalidan). El MCP no calcula si una ruta está disponible: eso lo enseña Fluyo al reproducir.export_diagrampinta las marcas (cuñas de Flujo, anillo de Requisito) como «Exportar → SVG» de la app (golden compartido); sinkind, el SVG de siempre.Refs en update/delete y en destinos:
node/connection/source/targetdeupdate_*/delete_*aceptan{ref}(algo creado antes en el lote, en la misma página) o{id}. Una ref desconocida (o de otra página) →UNKNOWN_REF; repetida →DUPLICATE_REF; usar una entidad que el propio lote ya eliminó →NODE_NOT_FOUND/CONNECTION_NOT_FOUNDindicando qué operación la eliminó. Las refs de lo eliminado en el lote no se devuelven enrefs.
[
{"op":"update_node","scope":"page","pageIndex":0,"node":{"id":1},"spec":{"x":240,"w":200,"label":"Cliente final"}},
{"op":"update_connection","scope":"page","pageIndex":0,"connection":{"id":4},"target":{"id":3},"spec":{"label":"Pago","route":"ortho","waypoints":[]}},
{"op":"delete_node","scope":"page","pageIndex":0,"node":{"id":2}}
] Errores nuevos: NODE_NOT_FOUND, CONNECTION_NOT_FOUND, REFERENCED_ENTITY (diagrama). describe_document añade lo necesario para modificar sin volcar el documento: por elemento x,y,w,h; por conexión route, fromSide/toSide y waypoints (solo si existen); por página bounds {minX,minY,maxX,maxY} (agregado de las cajas, sin rutas). Las refs son efímeras y no aparecen.
Ejemplo de uso
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.
El modelo llamará a create_diagram con algo así:
{
"pageName": "Pipeline de eventos",
"nodes": [
{ "key": "gw", "shape": "rect", "label": "API Gateway", "color": "Servicio" },
{ "key": "kafka", "shape": "icon", "label": "Kafka", "icon": "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 .fluyo.json completo, y el resumen de la respuesta trae un enlace
fluyo.space/#d=… que lo abre ya animado en la app, sin guardar ningún archivo. También se
puede guardar el JSON y abrirlo con el botón Abrir, o seguir editándolo con author_document
(la revision sale de describe_document).
create_diagram y create_from_template por el dominio (FLUYO-018.9)
Las dos tools son adaptadores de entrada: no construyen el documento. Traducen su contrato
(key → refs del lote, nombres de color → HEX, auto-layout para los nodos sin x/y) a operaciones
de author_document (rename_page, set_theme, create_node, create_connection) sobre el
documento en blanco del editor (con los ajustes pedidos, normalizados por la carga del editor) y
las aplica FluyoAuthoring —las mismas funciones que el editor— en lotes de ≤200 encadenados.
Salida: documento v5 canónico, el mismo byte a byte (y con la misma
revision) que construir ese diagrama conauthor_document. Sinmeta.generator(nada lo leía y el editor lo descartaba al guardar), sin claves heredadas (fs,lineColor,dotColorsolo si se piden) y con los defaults del dominio (p. ej.codenace con el SQL de ejemplo ylang,keywords,kwBg,kwColor).Colores: los nombres de
list_colors(sin distinguir mayúsculas ni acentos) solo existen en la entrada de estas dos tools y se traducen a HEX antes del dominio; cualquier otro valor lo valida el kernel (#rgb,#rrggbb,#rrggbbaa;filladmite"none"). El documento solo contiene HEX. Enexport_diagram, el relleno automático (sinfill) es el color del nodo al 16 % en crema y al 18 % en el resto, como en la app: un#rrggbbaamultiplica esa opacidad por su alfa y un#rgbse expande (FLUYO-019.5).Reglas y límites del dominio (más estrictos que antes): auto-lazo (
SELF_LOOP), 300 nodos y 600 conexiones por página,|x|,|y| ≤ 100000,w/hentre 10 y 5000 (LIMIT_EXCEEDED), nombre de página de 1 a 80 caracteres (INVALID_NAME), HEX inválido ocustomBgque no es HEX (INVALID_FIELD), icono/GIF desconocido. Nada se recorta en silencio.Ajustes:
speed0,2–2 ystagger0,2–1,2 (los rangos de los controles del editor; fuera, el schema rechaza); una tipografía global que el editor no conoce esINVALID_FIELD font. Lo omitido (página, tema, ajustes) toma el valor del documento en blanco del editor.Errores estructurados como los de
author_document:[resumen, JSON {ok:false, valid:false, errors:[{code, message, field, input, key?…}]}],isError, sin documento.inputseñala la entrada (nodes[i],edges[j],pageName,customBg,font…). Laskeyrepetidas sonDUPLICATE_REFy una arista hacia unakeyinexistenteUNKNOWN_REF; encreate_from_template,TEMPLATE_NOT_FOUNDeINVALID_FIELD(labelOverrides.<clave>).Los campos desconocidos de la entrada se siguen ignorando, como antes.
El enlace fluyo.space/#d=…
Toda respuesta que trae un documento lleva el enlace que lo abre ya animado en la app: create_diagram y
create_from_template en el resumen, y author_document (y set_theme, reorder_nodes, duplicate_node) en el
campo editorUrl del 2.º bloque (una sola vez: el resumen lo señala sin repetir la URL), apuntando al documento FINAL del lote (todas las páginas, tema, Historias, eventos y
disponibilidad). Una sola codificación (src/link.ts) para todas. dryRun y los rechazos no traen enlace. Es el paso que faltaba: antes había que
copiar el JSON del chat, guardarlo como .fluyo.json y abrirlo a mano.
El diagrama viaja dentro del enlace. No hay backend, no hay nada que dar de alta y no hay
nada que caduque. Va detrás de la almohadilla a propósito: el navegador no envía el
fragmento al servidor, ni en la petición ni en la cabecera Referer, así que el contenido
no llega a ningún registro de acceso — ni al de fluyo.space, ni al de nadie.
La contrapartida, dicha claramente: va codificado, no cifrado. Quien reciba el enlace puede leer el diagrama. Trátalo como tratarías el archivo.
Formato, por si alguien quiere generarlos por su cuenta:
#d= base64url( [1 byte de versión] + [carga] )
1 → deflate-raw ← lo que emite este servidor
0 → JSON en UTF-8 tal cual ← lo entiende el lector, no se emiteTamaño. Medido sobre los ocho ejemplos que publica Fluyo: 3.971 bytes de JSON minificado de media acaban en 1.061 caracteres de URL — factor 5, porque este JSON repite las mismas claves en cada nodo y eso es justo lo que come el deflate. Un diagrama de 8 nodos son 987 caracteres; uno de 30, 2.429.
Cuándo no hay enlace. Por encima de 16.000 caracteres no se emite (nunca se trunca), y la respuesta explica
por qué; en author_document, además, como editorUrlError {code:"LINK_TOO_LARGE", chars, maxChars, message}. El límite no lo pone el navegador —Chrome traga fragmentos de dos millones de
caracteres— sino el medio por el que viaja el enlace: un cliente de correo en texto plano
parte las líneas largas, y una URL partida ya no abre nada. Lo que dispara el tope en la
práctica no es el número de nodos, son los nodos image: llevan la imagen entera dentro como
data URI y uno solo puede pesar más que un diagrama de cien nodos.
Pasar el enlace en vez del JSON (MCP-TOKEN-EFFICIENCY-003)
Las ocho tools que reciben document (export_diagram, describe_document, run_story, author_document,
propose_layout, set_theme, reorder_nodes, duplicate_node) aceptan el enlace en lugar del objeto: el
editorUrl de la última autoría o el enlace del resumen de create_*, copiado exacto. Es lo que más ahorra en una
sesión: el documento era ~91 % de lo que emite el agente, y el enlace ocupa entre 4 y 9 veces menos (medido: −53 % de tokens
emitidos con 10 nodos, −72 % con 60). Las respuestas no cambian ni un byte.
{ "document": "https://fluyo.space/#d=Ae2ZXY7b…", "baseRevision": "sha256:…", "operations": [ … ] }Con un enlace,
baseRevisiones obligatorio en las ocho (export_diagram,describe_documentyrun_storylo aceptan opcional para un objeto; si se pasa, se comprueba como enpropose_layout). Es larevisiondel resumen decreate_*o elresultRevisionde la respuesta que trajo el enlace.La tool trabaja sobre el documento normalizado de esa revisión. Una copia inexacta no llega nunca como otro documento: o no se lee, o no coincide la revisión.
Vale cualquier prefijo (
https://fluyo.space/, un self-host o solo#d=…). No se recortan espacios ni saltos de línea.Si no hay enlace (más de 16.000 caracteres,
dryRun), se pasa el JSON como siempre.
Código | Cuándo | Qué hacer |
| la cadena no es un enlace legible | copiarlo exacto o pasar el JSON |
| enlace sin | pasar la revisión de la respuesta que trajo el enlace |
| la revisión no es la del enlace: casi siempre, una copia inexacta | copiarlo de nuevo o pasar el JSON; no reintentar con otra revisión |
En author_document, las tools de una operación y propose_layout el error va estructurado en errors[]; en
export_diagram, describe_document y run_story, como Error: <CODE> …. La lectura es la de la app
(fluyo/js/link-codec.js): base64url canónico, versiones 1 (deflate-raw) y 0 (UTF-8), y 2 MiB como tope de lo descomprimido.
Respuestas sin el documento: returnDocument:false (MCP-TOKEN-EFFICIENCY-004)
Quien sigue trabajando con el enlace no necesita el JSON del documento en cada respuesta: el editorUrl lo codifica
entero, y el documento era la mitad de lo que recibía el agente. author_document y create_diagram aceptan
returnDocument (por defecto true, es decir, como siempre):
falsecon enlace:author_documentno trae la clavedocument(el resto,editorUrlyresultRevisionincluidos, es igual) y su resumen dice «Sin documento (returnDocument:false)…»;create_diagramcontesta con un solo bloque, el resumen de siempre (enlace,revision, ids por key y de aristas) más esa línea. Medido: −31 % a −57 % de lo recibido, sin llamadas extra.falsesin enlace (LINK_TOO_LARGE): el documento sale igual, porque es la única forma de seguir.dryRuny los rechazos no cambian: nunca traen documento.Solo esas dos tools:
create_from_templatey las de una operación (set_theme,reorder_nodes,duplicate_node) no lo publican (el catálogo no da para más) y lo ignoran; sus operaciones están enauthor_document.
Si vas a necesitar el archivo .fluyo.json, no pongas false en la última escritura. Para recuperarlo después basta
repetir esa misma llamada sin el flag: las tools son deterministas y dan el mismo resultRevision con su documento (una llamada
más). Normalmente no hace falta: el entregable es el enlace, que abre el diagrama en Fluyo y desde ahí se guarda. Las x/y que
eligió el auto-layout de create_diagram tampoco vienen sin el documento: si las necesitas, describe_document.
Retirada de edit_diagram (FLUYO-018.10)
edit_diagram era la tool de edición anterior a author_document (LEGACY desde 018.5). Se retiró: ya no aparece en
tools/list y llamarla devuelve el error de tool inexistente. Cada operación tiene sustituto:
| Sustituto | Diferencia |
|
|
|
|
| Solo las claves del editor: no cambia |
|
| Quita también su disponibilidad inicial; rechazado si una Historia lo usa. |
|
|
|
|
|
|
|
| Solo vacía los waypoints de las conexiones cuyos extremos se mueven (antes, todos). |
enlace |
| Misma codificación. |
author_document pide baseRevision (la revision de describe_document) y devuelve el documento normalizado
del editor (v5), no una copia que conserve claves desconocidas.
Fidelidad con la aplicación
Importa ser preciso aquí, porque una versión anterior de este README prometía paridad que el código no daba.
Derivado mecánicamente de Fluyo — npm run sync:config lee fluyo/js/config.js y fluyo/js/state.js y genera src/generated/config.ts. La paleta, los temas, los 72 íconos con su SVG, los 8 GIFs, las 12 tipografías y los tamaños por forma no se copian a mano: se extraen. CI comprueba que sigan sincronizados.
Portado a mano, verificado por tests — la geometría de aristas y el exportador SVG son ports de fluyo/js/geometry.js y fluyo/js/export.js. No hay forma de derivarlos automáticamente, así que el renderer se compara en cada CI contra los SVG que produjo el exportador de la propia app para los cinco ejemplos publicados.
Deliberadamente distinto — dos cosas:
La medición de texto es una heurística. La app pide
getBBox()al navegador; aquí no hay DOM y se estima sumando anchos por carácter. Las etiquetas que caben en su forma salen idénticas; las que hay que encoger pueden quedar a un tamaño de fuente ligeramente distinto, y el fondo de una etiqueta de arista, unos píxeles más ancho o estrecho.export_diagramno anima. Igual que "Exportar → SVG" en la app: sin puntos de flujo ni aparición escalonada. Para el GIF animado hay que abrir el documento en Fluyo.
Aspecto «construido» (2.5D) (FLUYO-019.3): un documento con settings.skin: "built" se exporta con la misma piel que Present, el Viewer y «Exportar → SVG» de la app. Bloques con tapa y lateral, cilindro con tapa clara y banda, iconos sobre una peana, la punta posada en la cara visible y un anillo de salida. Las rutas, las anclas y las etiquetas no cambian; solo la voz del rótulo pasa a IBM Plex Mono si el nodo no trae fuente y la global es la de serie. Sin la clave (o con "flat" o cualquier otro valor) se exporta plano, byte a byte como antes. La regla la dicta el kernel de Fluyo: solo "built" se guarda, y lo demás se lee como ausente y no se rechaza. create_diagram acepta skin: "built" o "flat" (que equivale a no pedirlo). La piel es un port de fluyo/js/skin.js (src/skin.ts), verificado capa a capa contra sus goldens y contra el skin.js real en vm. Un color #rrggbbaa se pinta como el color opaco que se ve sobre el fondo, y uno ilegible cae en el primer color de la paleta, igual que en la app.
Lectura sin pérdida — un documento guardado por la app se lee (export_diagram) sin perder un solo campo, incluidos los que el servidor todavía no sabe interpretar. Lo verifica un test de contrato contra los ejemplos reales de fluyo/ejemplos/data/. No es un detalle: una versión anterior descartaba en silencio 16 campos de estilo en cada llamada. La edición (author_document) devuelve el documento normalizado por el kernel de Fluyo, exactamente el que la app tendría al abrirlo y guardarlo: solo cambia lo pedido.
Limitaciones actuales
Solo SVG. PNG y GIF necesitan un renderer de canvas (
sharp,resvg,node-canvas).El endpoint remoto tiene topes que el local no tiene. 1 MB de cuerpo, 200 KB por respuesta de tool y 30 peticiones por minuto y por IP. Un diagrama con nodos
imagepuede pasarse de cualquiera de los dos primeros; por stdio no hay ninguno.Los nodos
imageno se pueden crear, porque llevan los bytes de la imagen dentro (img, un data URI que se pega o arrastra en la app). Los que ya existen se leen, editan y exportan con normalidad. Losanimsí se pueden crear: sus claves son un catálogo cerrado (list_anims).No se leen documentos del formato v1. La app los migra al abrirlos; ábrelo y vuelve a guardarlo.
El auto-layout es un Sugiyama simplificado. Va muy bien en pipelines y arquitecturas convencionales; para grafos muy ramificados conviene dar coordenadas o retocar lo que propone
propose_layout.author_documentreenvía el documento entero en la entrada y en la salida. En sesiones de edición largas sobre diagramas grandes eso consume bastante contexto.El tiempo de una Historia lo decide el autor, no el motor. Fluyo no calcula latencia, no mantiene colas, no reintenta ni entrega más tarde un envío fallido, y no deduce que un mensaje «llegó»:
waitMssolo separa momentos, y la única forma de que un momento empiece cuando llega un envío es declararlo conwaitsForArrivalOf.
Privacidad
Este servidor no almacena los diagramas. No hay base de datos, no hay disco, no hay caché y no hay sesiones: cada petición HTTP construye un servidor, procesa el mensaje y lo descarta.
El registro de operación anota exactamente esto, una línea JSON por petición en stderr:
{"ts":"…","route":"/mcp","method":"POST","status":200,"outcome":"ok",
"durationMs":31,"requestBytes":1462,"responseBytes":9038,"tools":["export_diagram"]}Y nada más. No se registra el documento, ni las etiquetas, ni los argumentos de las tools, ni el cuerpo de la respuesta, ni los mensajes de error, ni stack traces, ni la IP del cliente, ni cabeceras. No hay modo debug que levante esas restricciones.
Que siga siendo cierto no depende de la disciplina de quien edite el código: el tipo RequestLog de src/http-logging.ts es un enum cerrado sin ningún campo donde quepa texto libre del usuario, y test/http.test.ts mete marcadores irrepetibles en las etiquetas de un diagrama y falla si aparecen en alguna línea de log.
Detalle honesto sobre las IPs: el limitador de caudal guarda en memoria la IP del cliente y las marcas de tiempo de sus últimas peticiones, durante la ventana de un minuto. Nunca se escribe a disco ni al log, y desaparece al reciclarse la instancia.
Fuera de este proceso, Cloud Run escribe automáticamente sus propios request logs (IP del cliente, ruta, código de estado, latencia, user-agent) en Cloud Logging. Eso no lo controla este código: lo genera la plataforma antes de que la petición llegue al contenedor. La retención está fijada a 7 días en el bucket _Default — ver Retención de logs, donde está el comando que lo fija, para que el número de la política de privacidad sea reproducible y no una promesa.
Desplegar en Cloud Run
El servidor se despliega como servicio propio de Cloud Run en mcp.fluyo.space — no dentro del deployment de fluyo/, que es estático a propósito y publica «no hay backend» como argumento de privacidad. Ver DRIFT.md §6.
Por qué Cloud Run y no Vercel. El plan Hobby de Vercel restringe el uso a personal no comercial y, al exceder los límites, pausa el servicio 30 días. Para un servidor listado en un directorio público eso es inaceptable: el modo de fallo es quedarse caído un mes sin recurso. Cloud Run no tiene esa restricción y su modo de fallo es facturar, que sí se puede acotar — de ahí los topes de la sección siguiente.
Piezas
Archivo | Papel |
| Multi-stage: compila con todas las dependencias, y la imagen final solo lleva |
| Mantiene el contexto de build pequeño; |
| 21 comprobaciones contra el despliegue ya en marcha |
No hay archivos estáticos. En Vercel robots.txt lo servía la plataforma desde public/; aquí el contenedor es lo único que contesta, así que la ruta /robots.txt la sirve src/http.ts como cualquier otra.
Variables de entorno
Se fijan por revisión: cambiar una crea una revisión nueva, y hasta que esa revisión reciba tráfico el cambio no surte efecto. Ninguna es un secreto; ninguna es obligatoria salvo la del challenge, y esa solo mientras dure la verificación de OpenAI.
Variable | Por defecto | Para qué |
| — | Valor que sirve |
| los de Claude, ChatGPT y Fluyo | Lista blanca de |
|
| Peticiones por IP y por ventana en |
|
| Tamaño de la ventana deslizante. |
|
| Tope del cuerpo de la petición. Por encima: 413. |
|
| Tope del resultado de una tool. Por encima se sustituye por un error que explica cómo reducir el diagrama. |
|
| Base de los enlaces |
| activado |
|
PORT no se configura. La inyecta Cloud Run y el contenedor la lee; fijarla a mano rompe el despliegue. En local sí se usa (PORT=3000 npm run start:http).
Topes de coste
Estos valores no son negociables y son la razón por la que este servicio no puede sorprender con una factura:
--max-instances=2 # techo de cómputo. Ver la aritmética de abajo
--concurrency=80 # peticiones simultáneas por instancia
--timeout=30s
--min-instances=0 # sin tráfico, no se paga nada
--cpu=1 --memory=512Mi
--cpu-boost # arranque en frío más rápidoLa aritmética del techo. Con max-instances=2, cpu=1 y memory=512Mi, el peor caso es que las dos instancias estén saturadas las 24 horas:
2 instancias × 86.400 s = 172.800 instancia-segundos/día
CPU: 172.800 × 1 × $0,000024 = $4,15/día
Memoria:172.800 × 0,5 × $0,0000025 = $0,22/día
─────────
≈ $4,4/día ← el máximo posibleEn operación normal la cifra real es una fracción de eso, porque con min-instances=0 no se factura nada mientras no hay tráfico.
--concurrency=80no se toca. Es contraintuitivo: bajarlo multiplica el coste. Cada instancia atiende hasta 80 peticiones a la vez; conconcurrency=10harían falta ocho veces más instancias para el mismo tráfico, se toparía antes enmax-instances=2y los usuarios recibirían 429 de la plataforma antes que del rate limiter. Las quince tools son funciones puras que no comparten estado, así que 80 simultáneas por instancia no tienen ningún inconveniente.
Primer despliegue
PROJECT=tu-proyecto-gcp
REGION=us-central1
gcloud config set project "$PROJECT"
gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com
# Construye desde el Dockerfile y despliega en un solo paso.
gcloud run deploy fluyo-mcp \
--source . \
--region "$REGION" \
--platform managed \
--allow-unauthenticated \
--max-instances=2 \
--concurrency=80 \
--timeout=30s \
--min-instances=0 \
--cpu=1 --memory=512Mi --cpu-boost \
--set-env-vars "OPENAI_APPS_CHALLENGE=el-valor-que-te-dio-openai"--allow-unauthenticated es deliberado: es un servidor MCP público sin credenciales. Lo que lo protege del abuso es el rate limiter y max-instances, no IAM.
Después, verifica el despliegue entero de una vez:
./scripts/verify-deploy.sh https://mcp.fluyo.spaceSon 21 comprobaciones con ✓/✗ y código de salida distinto de cero si algo falla. Cubre lo que los tests no pueden ver, porque corren contra un handler en memoria: redirecciones, cabeceras que añada la plataforma y el mapeo de dominio.
Dominio mcp.fluyo.space
gcloud beta run domain-mappings create \
--service fluyo-mcp \
--domain mcp.fluyo.space \
--region "$REGION"El comando imprime el registro DNS que hay que crear en la zona de fluyo.space:
CNAME mcp ghs.googlehosted.com.El certificado lo emite Google automáticamente una vez propagado el DNS; suele tardar entre unos minutos y un par de horas. Mientras tanto el servicio ya responde en su URL *.run.app.
Si tu región no ofrece domain mappings, la alternativa es un balanceador de carga HTTP(S) global con un backend serverless NEG apuntando al servicio. Cuesta más y añade una pieza; el mapeo directo basta para este caso.
Retención de logs
Cloud Run escribe request logs automáticamente. La política de privacidad publica una retención de 7 días, y esto es lo que la hace cierta:
gcloud logging buckets update _Default \
--location=global \
--retention-days=7 \
--project="$PROJECT"
# Comprobarlo:
gcloud logging buckets describe _Default --location=global --format='value(retentionDays)'El valor por defecto de _Default son 30 días. Si no se ejecuta ese comando, la política dice 7 y la realidad son 30, que es exactamente el tipo de desajuste que hace falsa una declaración de privacidad. Va aquí, y no solo en un runbook, para que sea reproducible.
Esto es independiente del logger de la aplicación: src/http-logging.ts no escribe ningún dato de usuario, y eso sigue siendo cierto pase lo que pase con la retención de la plataforma.
La ruta del challenge de OpenAI
Es el punto que más fácil se rompe, así que conviene entenderlo antes de poner nada delante del servicio:
El verificador de OpenAI elimina el subpath. Da igual que el MCP esté montado en /mcp: siempre pide https://mcp.fluyo.space/.well-known/openai-apps-challenge, en la raíz del host. Y tiene que contestar 200 directo con text/plain. Una redirección hacia la ruta «correcta», aunque acabe en el sitio adecuado, cuenta como fallo.
Lo que garantiza que eso se cumpla:
El contenedor no redirige nunca.
normalizePath()ensrc/http.tsquita la query string y la barra final sobrante sin emitir un 301. Si aparece una redirección, viene de delante: del mapeo de dominio o de un balanceador.La ruta se atiende antes que nada en
route()— antes del rate limit y antes de la comprobación deOrigin. El verificador nunca puede recibir un 429 ni un 403.Cloud Run reenvía la petición tal cual al contenedor, sin reescribir rutas ni añadir barras. No hay equivalente de
cleanUrls/trailingSlashque pueda estropearlo por defecto.Hay un test (
test/http.test.ts) que pide la ruta conredirect: "manual"y exige exactamente 200 ytext/plain, yverify-deploy.shrepite la comprobación contra el despliegue real.
Rotar el challenge:
gcloud run services update fluyo-mcp \
--region "$REGION" \
--update-env-vars "OPENAI_APPS_CHALLENGE=el-valor-nuevo"Eso crea una revisión nueva y le manda el tráfico. Las variables de entorno de Cloud Run pertenecen a la revisión, no al servicio: hasta que la revisión nueva esté sirviendo, la ruta sigue devolviendo el valor viejo. Verifica con:
curl -i https://mcp.fluyo.space/.well-known/openai-apps-challenge
gcloud run services describe fluyo-mcp --region "$REGION" \
--format='value(spec.template.spec.containers[0].env)'Probar la imagen en local antes de subir
npm run build
npm run start:http # sin contenedor: http://localhost:3000/mcp
# Con el contenedor real, que es lo que corre en Cloud Run:
docker build -t fluyo-mcp .
docker run --rm -p 8080:8080 \
-e PORT=8080 \
-e OPENAI_APPS_CHALLENGE=prueba \
fluyo-mcp
./scripts/verify-deploy.sh http://localhost:8080El script pasa igual contra el contenedor local que contra producción, salvo la comprobación del challenge si no le pasas la variable.
Cómo se comporta el rate limit aquí
src/http-security.ts lee la IP del cliente de x-forwarded-for, y Cloud Run la rellena con el mismo formato que cualquier proxy: el primer valor es el cliente y el resto la cadena de saltos (203.0.113.45, 130.211.0.1). El código toma el primero, así que dos clientes detrás del mismo front-end de Google no comparten cubo. Es la misma lectura que se hacía en Vercel; no hubo que cambiar nada.
Un matiz que conviene tener presente: el estado del limitador vive en la memoria de cada instancia. Con max-instances=2, el límite efectivo puede llegar a ser el doble del configurado. Es una barrera contra el abuso accidental y los bucles de reintentos, no una cuota exacta — para eso haría falta un almacén compartido, y almacenar algo es justo lo que este servicio evita.
Estructura del proyecto
src/
generated/
config.ts # GENERADO por sync:config desde fluyo/. No editar a mano.
schema.ts # Reexporta las constantes + helpers (iconDataUri, resolveColor…)
model.ts # Esquemas Zod y tipos del documento Fluyo
errors.ts # Traduce los fallos de validación a frases accionables
layout.ts # Auto-layout por capas
diagram.ts # createDiagram / editDiagram
svg.ts # Exportador SVG
templates.ts # Plantillas de arquitectura
link.ts # Enlace fluyo.space/#d=… (deflate-raw + base64url)
link-input.ts # El enlace #d= como document: lectura, baseRevision y documento normalizado
schema-errors.ts # Los rechazos de Zod, estructurados y cortos (SCHEMA_INVALID)
server.ts # Registro de las tools MCP — común a los dos transportes
index.ts # Entry point 1: stdio
http.ts # Entry point 2: Streamable HTTP (stateless) + rutas del host
http-security.ts # Origin, rate limit, tope de cuerpo, gzip
http-logging.ts # Qué se registra, y sobre todo qué no
Dockerfile # Imagen de Cloud Run: multi-stage, no-root, lee PORT
.dockerignore # Contexto de build mínimo
scripts/
sync-config.ts # Genera src/generated/config.ts desde fluyo/
sync-fixtures.ts # Refresca test/fixtures/ desde los ejemplos de fluyo/
verify-deploy.sh # 21 comprobaciones contra un despliegue en marcha
test/
contract.test.ts # Los 5 ejemplos reales: se aceptan, round-trip sin pérdida, exportan
tools.test.ts # Flujo extremo a extremo de las tools
render.test.ts # El SVG cuadra con el que produce la app
http.test.ts # Handshake por HTTP, paridad con stdio, seguridad y privacidad del log
link.test.ts # Formato del enlace, tope de tamaño; lo creado ya no lleva meta.generator (018.9)
fluyo-018-9.test.ts # create_diagram/create_from_template = dominio (golden, reglas, errores, stdio)
fluyo-018-10.test.ts # editorUrl en author_document; retirada de edit_diagram (15 tools)
fluyo-mcp-token-efficiency-002.test.ts # JSON compacto, revision e ids en create_*, enlace una vez, schema sin topes de entero seguro
fluyo-mcp-token-efficiency-003.test.ts # el enlace #d= como document: equivalencia byte a byte, revisión, corrupción, topes
fluyo-mcp-token-efficiency-004.test.ts # returnDocument:false: catálogo, identidad sin el flag, sin enlace, rechazos, encadenado
fluyo-mcp-story-authoring-001.test.ts # Desenlace, aviso de efectos, enlace de una persona, errores de schema, candidatos y summary
fixtures/ # Copias de fluyo/ejemplos/ (datos y previews de referencia)Contribuir
Lee CONTRIBUTING.md. Lo importante en dos líneas: src/generated/config.ts no se edita a mano, y si añades un campo al formato tiene que sobrevivir al test de contrato.
Licencia
MIT. Ver LICENSE.
Available Tools
9 toolscreate_diagramCrear diagrama FluyoARead-onlyIdempotent
Crea un diagrama de arquitectura completo (formato .fluyo.json) a partir de una lista de nodos y aristas. Si un nodo no trae x/y, se posiciona automáticamente en capas de izquierda a derecha según las aristas (auto-layout). El JSON resultante se puede abrir directo en fluyo (botón Abrir) o seguir editando con edit_diagram / exportando con export_diagram. Usa list_icons para ver íconos válidos y list_templates si el patrón ya existe como plantilla.
Inputs: nodes (required), dots, font, grid, +9 more.
create_from_templateCrear diagrama desde un templateCRead-onlyIdempotent
Instancia uno de los templates de list_templates como un documento Fluyo completo, con auto-layout aplicado. Se pueden personalizar los labels de los nodos vía 'labelOverrides' (mapa key -> nuevo texto).
Inputs: templateId (required), theme, pageName, labelOverrides.
edit_diagramEditar diagrama FluyoARead-onlyIdempotent
Aplica una lista de operaciones (add_node, update_node, remove_node, add_edge, update_edge, remove_edge, set_theme, rename_page, relayout) sobre un documento Fluyo existente (el JSON completo devuelto por create_diagram o cargado desde un .fluyo.json). Las operaciones se aplican en orden; add_node puede definir un 'key' temporal que add_edge referencia en la misma llamada. Para editar nodos/aristas ya existentes en el documento, usa su 'id' numérico (visible en el JSON del documento).
Inputs: document (required), operations (required), pageIndex.
export_diagramExportar diagrama Fluyo a SVGARead-onlyIdempotent
Renderiza una página de un documento Fluyo a SVG estático, con las mismas formas, colores, íconos, rellenos, bordes y tipografías que produce 'Exportar → SVG' dentro de la app. Útil para pegar el diagrama en Notion/Confluence/Markdown o previsualizarlo sin abrir Fluyo. No incluye animación (puntos de flujo ni aparición escalonada), igual que el SVG que exporta la app; para el GIF animado hay que abrir el documento en Fluyo. PNG y GIF no están disponibles aquí: necesitan un renderer de canvas.
Inputs: document (required), crop, scale, pageIndex.
list_animsListar GIFs animadosARead-onlyIdempotent
Devuelve las claves válidas para nodos shape='anim'. Son pequeñas animaciones que Fluyo dibuja fotograma a fotograma en el lienzo y en el GIF exportado (un spinner girando, una barra de progreso avanzando, un tick que se traza). En un SVG estático se ve su fotograma de referencia. Sirven para señalar estados —cargando, procesando, error— dentro de un diagrama.
Inputs: no named parameters.
list_colorsListar colores semánticosARead-onlyIdempotent
Devuelve los nombres de color semántico aceptados en 'color', 'lineColor' y 'dotColor' (también se acepta cualquier hex #rrggbb).
Inputs: no named parameters.
list_fontsListar tipografíasARead-onlyIdempotent
Devuelve las familias tipográficas que ofrece Fluyo, para el campo 'font' de nodos y aristas. El valor que se guarda en el documento es la familia CSS completa, no el nombre corto. Un nodo sin 'font' hereda la tipografía global del documento.
Inputs: no named parameters.
list_iconsListar íconos disponiblesARead-onlyIdempotent
Devuelve las claves de ícono válidas para nodos shape='icon', agrupadas (General, GCP, AWS, Azure, Estados, Varios). Son los mismos íconos que ofrece el cajón de la aplicación.
Inputs: no named parameters.
list_templatesListar templates de diagramasARead-onlyIdempotent
Devuelve los patrones de arquitectura predefinidos disponibles para instanciar con create_from_template.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The tools are mostly distinct: create/edit/export handle the document lifecycle, list_* tools are metadata queries, and create_from_template is a special creation path. There's slight overlap between create_diagram and create_from_template (both create documents), but their inputs are sufficiently different that confusion is unlikely. Overall clear separation.
The naming follows a mostly consistent verb_noun pattern: create_diagram, edit_diagram, export_diagram, list_icons, list_colors, list_anims, list_fonts, list_templates, create_from_template. The minor inconsistency is 'create_from_template' vs 'create_diagram' — template creation isn't prefixed with 'diagram' — and 'list_anims' uses an abbreviation instead of 'animations'. Otherwise very consistent.
9 tools is well within the ideal 3-15 range. The set breaks into three coherent groups: document creation (create_diagram, create_from_template), document editing (edit_diagram, export_diagram), and metadata lookup (list_icons, list_colors, list_anims, list_fonts, list_templates). Each tool earns its place with no obvious bloat.
The tool surface covers the full document lifecycle: create a diagram from scratch (create_diagram), create from a template (create_from_template), edit it (edit_diagram), and export it (export_diagram). All the lookup needs for valid enum values (icons, colors, anims, fonts, templates) are covered. There's no obvious gap — loading/reading an existing .fluyo.json is handled via edit_diagram which accepts the full JSON document.
Maintenance
Related MCP Connectors
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseBqualityCmaintenanceAn MCP server that generates beautiful Excalidraw architecture diagrams with perfect auto-layout, stateful editing, and architecture-aware component styling.226219 PyPI164MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to programmatically create and manage flowcharts, ERDs, and swimlane diagrams. It provides tools for manipulating diagram structures, performing auto-layouts, and exporting to Mermaid or Markdown formats.MIT
- AlicenseBqualityDmaintenanceMCP server that enables LLMs to create and edit draw.io diagrams using high-level intent commands, with automatic layout and styling.47 npm4MIT
- FlicenseNot gradedqualityCmaintenanceMCP server that lets Claude (and other MCP clients) create, list, read, update, and delete drawings in ExcaliDash via its REST API. It allows users to create diagrams directly from natural language commands like 'draw a flowchart'.-