Zigflow

Orquestación declarativa de flujos de trabajo para Temporal utilizando la especificación CNCF Serverless Workflow.

Documentación

[!-info] -info Servidor MCP público
https://mcp.zigflow.dev
Alojado, público y de solo lectura. No requiere instalación ni clave de API.

Zigflow ejecuta un servidor Model Context Protocol (MCP) que brinda a las herramientas de desarrollo con IA acceso estructurado y de solo lectura a Zigflow. Expone un pequeño conjunto de herramientas para que un asistente pueda trabajar con ejemplos reales y el esquema DSL exacto de la versión actual de Zigflow, y luego validar el YAML que produce.

Por qué usarlo

Crear un flujo de trabajo a partir de un ejemplo real y compatible, en lugar de desde cero
Validar el YAML del flujo de trabajo contra el esquema DSL actual antes de confirmar cambios
Mantener a tu asistente alineado con el esquema de tu versión de Zigflow
Mantente seguro: el servidor es de solo lectura, nunca se conecta a Temporal y nunca lee tus archivos

Conexión de un cliente

El servidor alojado utiliza el transporte MCP Streamable HTTP. Cualquier cliente MCP que admita servidores remotos (HTTP) puede conectarse usando el endpoint:

https://mcp.zigflow.dev

Agrégalo como servidor MCP remoto en tu cliente. No se requieren credenciales.

[!-secondary] -secondary nota

Cada cliente MCP gestiona los servidores de manera diferente, y esos formatos cambian con frecuencia. Zigflow documenta el endpoint y las herramientas que proporciona. Para saber cómo agregar un servidor MCP remoto en un cliente específico, consulta la documentación oficial de MCP.

Herramientas disponibles

El servidor expone cinco herramientas de solo lectura.

list_examples

Lista los ejemplos de flujos de trabajo incluidos con su nombre, título, descripción y etiquetas. No acepta parámetros. Úsala antes de llamar a get_example para descubrir los patrones disponibles.

get_example

Devuelve un ejemplo con nombre, incluido su contenido YAML y metadatos (nombre, título, descripción y etiquetas). El campo name debe coincidir con un identificador devuelto por list_examples. Si el nombre es desconocido, el mensaje de error lista los nombres disponibles.

get_schema

Devuelve el JSON Schema del DSL de Zigflow para la versión actual. El campo output acepta "json" (el valor predeterminado) o "yaml". Úsala para comprender la estructura válida del flujo de trabajo antes de generar o validar una definición.

Establece el campo opcional def para devolver una definición de esquema única de $defs, por ejemplo { "def": "taskList" }. El nombre debe coincidir exactamente con una clave de $defs. Las definiciones desconocidas devuelven un error de herramienta.

get_task_docs

Devuelve documentación autoritativa para un único tipo de tarea. El campo task_type debe ser uno de los tipos de tarea compatibles: call, do, for, fork, listen, raise, run, set, switch, try o wait. Un tipo de tarea desconocido devuelve un error de herramienta que lista los tipos compatibles.

La respuesta agrega varias fuentes para que un cliente no necesite extraer datos del sitio de documentación:

Campo	Descripción `description` El resumen de la tarea de la definición JSON Schema `subTypes` Las variantes de la tarea donde el esquema las define, por ejemplo `call` devuelve `activity`, `grpc` y `http` `schema` La definición JSON Schema de la tarea, la fuente autoritativa para sus propiedades y campos obligatorios `documentation` La página de referencia Markdown completa de la tarea `relatedLinks` URLs de documentación canónicas para la tarea `examples` Ejemplos de flujos de trabajo incluidos y validados que usan la tarea
`description`	El resumen de la tarea de la definición JSON Schema
`subTypes`	Las variantes de la tarea donde el esquema las define, por ejemplo `call` devuelve `activity`, `grpc` y `http`
`schema`	La definición JSON Schema de la tarea, la fuente autoritativa para sus propiedades y campos obligatorios
`documentation`	La página de referencia Markdown completa de la tarea
`relatedLinks`	URLs de documentación canónicas para la tarea
`examples`	Ejemplos de flujos de trabajo incluidos y validados que usan la tarea

Úsala para aprender cómo funciona un tipo de tarea específico antes de redactar YAML. El esquema y la página de referencia se sirven desde las mismas fuentes que la referencia DSL, por lo que se mantienen sincronizados con el motor.

validate_workflow

Valida una cadena YAML de flujo de trabajo y devuelve errores estructurados. El campo yaml debe contener la definición completa del flujo de trabajo como cadena, no una ruta de archivo.

Cada error incluye un campo stage que identifica dónde ocurrió la falla en el proceso de validación:

Etapa	Significado `input` La entrada YAML falta o está vacía `parse` El YAML no pudo analizarse `schema` El flujo de trabajo falla la validación JSON Schema `load` El flujo de trabajo no puede cargarse en el modelo `struct` El flujo de trabajo falla la validación estructural
`input`	La entrada YAML falta o está vacía
`parse`	El YAML no pudo analizarse
`schema`	El flujo de trabajo falla la validación JSON Schema
`load`	El flujo de trabajo no puede cargarse en el modelo
`struct`	El flujo de trabajo falla la validación estructural

Los errores también incluyen un message. Los errores de las etapas schema y struct incluyen además un path que señala el campo que falla. Los errores de la etapa struct también incluyen campos rule y param que describen la regla que falla. Una respuesta exitosa incluye "valid": true y sin errores.

Los errores de validación reconocidos llevan dos campos adicionales:

Campo	Significado `code` Un identificador estable para la clase de error, como `ERR_INVALID_TASK_QUEUE` `documentation` La URL de documentación derivada de `code`
`code`	Un identificador estable para la clase de error, como `ERR_INVALID_TASK_QUEUE`
`documentation`	La URL de documentación derivada de `code`

El code es metadatos aditivos. El message nunca se reescribe para incrustarlo. La URL documentation se deriva del code, por lo que ambos siempre coinciden. La URL se construye poniendo el código en minúsculas, eliminando el prefijo ERR_ y reemplazando los guiones bajos por guiones, por lo que ERR_INVALID_TASK_QUEUE se convierte en https://zigflow.dev/errors/invalid-task-queue.

Los errores sin un code reconocido omiten tanto el campo code como el documentation. Por ejemplo, un taskQueue inválido devuelve:

{
  "stage": "schema",
  "path": "$.document.taskQueue",
  "code": "ERR_INVALID_TASK_QUEUE",
  "message": "pattern: \"Not A Valid Queue\" does not match regular expression \"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$\"",
  "documentation": "https://zigflow.dev/errors/invalid-task-queue"
}

Flujo de trabajo típico

Una sesión típica de redacción asistida por IA:

Llama a list_examples para explorar los patrones disponibles
Llama a get_example para inspeccionar un ejemplo relevante
Llama a get_schema para comprender la estructura DSL
Llama a get_task_docs para aprender un tipo de tarea específico en profundidad
Genera o modifica un YAML de flujo de trabajo
Llama a validate_workflow para verificarlo
Corrige los errores según los campos stage y message
Repite desde el paso 6 hasta que sea válido

Comenzar desde un ejemplo conocido produce resultados más precisos que generar desde cero. El DSL de Zigflow es un subconjunto deliberado de la Open Workflow Specification (anteriormente Serverless Workflow). El esquema y los ejemplos incluidos definen lo que realmente se admite.

[!-secondary] -secondary nota

Los flujos de trabajo generados por IA son un punto de partida. validate_workflow confirma la validez estructural contra el esquema DSL. No verifica que la lógica del flujo de trabajo sea correcta para tu caso de uso. Revisa los flujos de trabajo generados antes de usarlos en producción.

Seguridad

El servidor está intencionalmente limitado en lo que puede hacer, lo que lo mantiene seguro de exponer:

Sin acceso al sistema de archivos. Todas las operaciones de herramientas usan entrada de la solicitud o datos incrustados en el binario. El servidor no lee ni escribe archivos del host.
Sin acceso a Temporal. El servidor no se conecta a Temporal y no puede iniciar, consultar ni afectar ejecuciones de flujos de trabajo.
Operaciones de solo lectura. Cada herramienta devuelve información o valida entrada. Ninguna herramienta muta estado.
Solicitudes sin estado. Cada solicitud es independiente. El transporte HTTP no mantiene estado por sesión, y los cuerpos de solicitud tienen límite de tamaño para acotar el uso de memoria.

El servidor alojado no agrega autenticación propia. Si lo autoalojas y lo expones públicamente, aplica autenticación y control de acceso en la capa de proxy inverso o ingress.

Autoalojamiento

Puedes ejecutar el mismo servidor tú mismo, ya sea por HTTP o por stdio.

HTTP

zigflow mcp --transport http

El servidor escucha en 0.0.0.0:8080 de forma predeterminada. Usa --address para cambiar la dirección de escucha:

zigflow mcp --transport http --address 0.0.0.0:9000

Debido a que el transporte HTTP no tiene estado, funciona bien detrás de un proxy inverso, ingress o servicio como Cloudflare, y se escala horizontalmente sin afinidad de sesión.

stdio

zigflow mcp

El transporte stdio se comunica a través de stdin/stdout y es la opción habitual para un cliente que inicia y gestiona el servidor localmente como subproceso. No está pensado para ejecutarse de forma interactiva en una terminal.

Banderas

Bandera	Predeterminado	Descripción `--transport` `stdio` Transporte a usar: `stdio` o `http`. `--address` `0.0.0.0:8080` Dirección en la que escuchar. Solo transporte HTTP. `--website-url` `https://mcp.zigflow.dev` URL del sitio web anunciada por el servidor.
`--transport`	`stdio`	Transporte a usar: `stdio` o `http`.
`--address`	`0.0.0.0:8080`	Dirección en la que escuchar. Solo transporte HTTP.
`--website-url`	`https://mcp.zigflow.dev`	URL del sitio web anunciada por el servidor.

Un valor desconocido de --transport hace fallar el comando en lugar de recurrir a un valor predeterminado.

Errores comunes

Pasar una ruta de archivo a validate_workflow. La herramienta acepta una cadena YAML, no una ruta de archivo. Lee primero el contenido del archivo y pasa el YAML como cadena.

Ejecutar el transporte stdio directamente en una terminal. Con el transporte stdio predeterminado, el servidor se comunica a través de stdin/stdout usando el protocolo MCP. No imprimirá nada útil cuando se ejecute de forma interactiva. Conéctate a través de un cliente MCP, o usa el transporte HTTP para un servidor orientado a red.

Páginas relacionadas

Referencia DSL: esquema completo para definiciones de flujos de trabajo
Esquema: el JSON Schema para archivos de flujos de trabajo
Ejemplos: patrones de flujos de trabajo incluidos
Uso de la CLI: validación de línea de comandos y ejecución de flujos de trabajo