Zigflow

[!-info] -info Servidor MCP público

https://mcp.zigflow.dev

Hospedado, público e somente leitura. Sem instalação e sem necessidade de chave de API.

O Zigflow executa um servidor Model Context Protocol (MCP) que dá às ferramentas de desenvolvimento de IA acesso estruturado e somente leitura ao Zigflow. Ele expõe um pequeno conjunto de ferramentas para que um assistente possa trabalhar com exemplos reais e o esquema DSL exato da versão atual do Zigflow e, em seguida, validar o YAML que produz.

Por que usar

• Estruture um workflow a partir de um exemplo real e suportado, em vez de começar do zero
• Valide o YAML do workflow contra o esquema DSL atual antes de fazer commit
• Mantenha seu assistente alinhado ao esquema da sua versão do Zigflow
• Fique seguro: o servidor é somente leitura, nunca se conecta ao Temporal e nunca lê seus arquivos

Conectando um cliente

O servidor hospedado usa o transporte MCP Streamable HTTP. Qualquer cliente MCP que suporte servidores remotos (HTTP) pode se conectar usando o endpoint:

https://mcp.zigflow.dev

Adicione-o como um servidor MCP remoto no seu cliente. Nenhuma credencial é necessária.

[!-secondary] -secondary nota

Cada cliente MCP gerencia servidores de forma diferente, e esses formatos mudam com frequência. O Zigflow documenta o endpoint e as ferramentas que fornece. Para saber como adicionar um servidor MCP remoto em um cliente específico, consulte a documentação oficial do MCP.

Ferramentas disponíveis

O servidor expõe cinco ferramentas somente leitura.

list_examples

Lista os exemplos de workflow incluídos com nome, título, descrição e tags. Não recebe parâmetros. Use antes de chamar get_example para descobrir os padrões disponíveis.

get_example

Retorna um exemplo nomeado, incluindo seu conteúdo YAML e metadados (nome, título, descrição e tags). O campo name deve corresponder a um identificador retornado por list_examples. Se o nome for desconhecido, a mensagem de erro lista os nomes disponíveis.

get_schema

Retorna o JSON Schema da DSL do Zigflow para a versão atual. O campo output aceita "json" (o padrão) ou "yaml". Use para entender a estrutura válida de workflow antes de gerar ou validar uma definição.

Defina o campo opcional def para retornar uma única definição de esquema de $defs, por exemplo { "def": "taskList" }. O nome deve corresponder exatamente a uma chave de $defs. Definições desconhecidas retornam um erro de ferramenta.

get_task_docs

Retorna documentação autoritativa para um único tipo de tarefa. O campo task_type deve ser um dos tipos de tarefa suportados: call, do, for, fork, listen, raise, run, set, switch, try ou wait. Um tipo de tarefa desconhecido retorna um erro de ferramenta que lista os tipos suportados.

A resposta agrega várias fontes para que um cliente não precise fazer scraping do site de documentação:

Campo	Descrição description O resumo da tarefa da definição do JSON Schema subTypes As variantes da tarefa onde o esquema as define, por exemplo call retorna activity, grpc e http schema A definição do JSON Schema da tarefa, a fonte autoritativa para suas propriedades e campos obrigatórios documentation A página de referência Markdown completa da tarefa relatedLinks URLs canônicas de documentação da tarefa examples Exemplos de workflow validados e incluídos que usam a tarefa
description	O resumo da tarefa da definição do JSON Schema
subTypes	As variantes da tarefa onde o esquema as define, por exemplo call retorna activity, grpc e http
schema	A definição do JSON Schema da tarefa, a fonte autoritativa para suas propriedades e campos obrigatórios
documentation	A página de referência Markdown completa da tarefa
relatedLinks	URLs canônicas de documentação da tarefa
examples	Exemplos de workflow validados e incluídos que usam a tarefa

Use para aprender como um tipo específico de tarefa funciona antes de criar YAML. O esquema e a página de referência são servidos das mesmas fontes da referência DSL, então permanecem em sincronia com o mecanismo.

validate_workflow

Valida uma string YAML de workflow e retorna erros estruturados. O campo yaml deve conter a definição completa do workflow como string, não um caminho de arquivo.

Cada erro inclui um campo stage que identifica onde no pipeline de validação a falha ocorreu:

Estágio	Significado input A entrada YAML está ausente ou vazia parse O YAML não pôde ser analisado schema O workflow falha na validação do JSON Schema load O workflow não pode ser carregado no modelo struct O workflow falha na validação estrutural
input	A entrada YAML está ausente ou vazia
parse	O YAML não pôde ser analisado
schema	O workflow falha na validação do JSON Schema
load	O workflow não pode ser carregado no modelo
struct	O workflow falha na validação estrutural

Os erros também incluem um message. Erros dos estágios schema e struct incluem adicionalmente um path que aponta o campo com falha. Erros do estágio struct também incluem campos rule e param descrevendo a regra com falha. Uma resposta bem-sucedida inclui "valid": true e nenhum erro.

Erros de validação reconhecidos carregam dois campos adicionais:

Campo	Significado code Um identificador estável para a classe de erro, como ERR_INVALID_TASK_QUEUE documentation A URL de documentação derivada de code
code	Um identificador estável para a classe de erro, como ERR_INVALID_TASK_QUEUE
documentation	A URL de documentação derivada de code

O code é metadado aditivo. O message nunca é reescrito para incorporá-lo. A URL documentation é derivada do code, então os dois sempre concordam. A URL é construída convertendo o código para minúsculas, removendo o prefixo ERR_ e substituindo underscores por hífens, então ERR_INVALID_TASK_QUEUE se torna https://zigflow.dev/errors/invalid-task-queue.

Erros sem um code reconhecido omitem tanto os campos code quanto documentation. Por exemplo, um taskQueue inválido retorna:

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

Fluxo de trabalho típico

Uma sessão típica de criação assistida por IA:

1. Chame list_examples para navegar pelos padrões disponíveis
2. Chame get_example para inspecionar um exemplo relevante
3. Chame get_schema para entender a estrutura da DSL
4. Chame get_task_docs para aprender um tipo específico de tarefa em profundidade
5. Gere ou modifique um YAML de workflow
6. Chame validate_workflow para verificá-lo
7. Corrija erros com base nos campos stage e message
8. Repita a partir do passo 6 até que seja válido

Começar de um exemplo conhecido produz resultados mais precisos do que gerar do zero. A DSL do Zigflow é um subconjunto deliberado da Open Workflow Specification (anteriormente Serverless Workflow). O esquema e os exemplos incluídos definem o que é realmente suportado.

[!-secondary] -secondary nota

Workflows gerados por IA são um ponto de partida. validate_workflow confirma a validade estrutural contra o esquema DSL. Ele não verifica se a lógica do workflow está correta para o seu caso de uso. Revise os workflows gerados antes de usá-los em produção.

Segurança

O servidor é intencionalmente limitado no que pode fazer, o que o mantém seguro para exposição:

• Sem acesso ao sistema de arquivos. Todas as operações das ferramentas usam entrada da requisição ou dados embutidos no binário. O servidor não lê nem grava arquivos do host.
• Sem acesso ao Temporal. O servidor não se conecta ao Temporal e não pode iniciar, consultar ou afetar execuções de workflow.
• Operações somente leitura. Cada ferramenta retorna informações ou valida entrada. Nenhuma ferramenta altera estado.
• Requisições sem estado. Cada requisição é independente. O transporte HTTP não mantém estado por sessão, e os corpos das requisições têm limite de tamanho para limitar o uso de memória.

O servidor hospedado não adiciona autenticação própria. Se você fizer self-hosting e expô-lo publicamente, aplique autenticação e controle de acesso na camada de reverse proxy ou ingress.

Self-hosting

Você pode executar o mesmo servidor, seja via HTTP ou via stdio.

HTTP

zigflow mcp --transport http

O servidor escuta em 0.0.0.0:8080 por padrão. Use --address para alterar o endereço de escuta:

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

Como o transporte HTTP é sem estado, ele funciona bem atrás de um reverse proxy, ingress ou serviço como Cloudflare, e escala horizontalmente sem afinidade de sessão.

stdio

zigflow mcp

O transporte stdio se comunica via stdin/stdout e é a escolha usual para um cliente que inicia e gerencia o servidor localmente como subprocesso. Ele não foi feito para ser executado interativamente em um terminal.

Flags

Flag	Padrão	Descrição --transport stdio Transporte a usar: stdio ou http. --address 0.0.0.0:8080 Endereço para escutar. Somente transporte HTTP. --website-url https://mcp.zigflow.dev URL do site anunciada pelo servidor.
--transport	stdio	Transporte a usar: stdio ou http.
--address	0.0.0.0:8080	Endereço para escutar. Somente transporte HTTP.
--website-url	https://mcp.zigflow.dev	URL do site anunciada pelo servidor.

Um valor --transport desconhecido faz o comando falhar em vez de recorrer a um padrão.

Erros comuns

Passar um caminho de arquivo para validate_workflow. A ferramenta aceita uma string YAML, não um caminho de arquivo. Leia o conteúdo do arquivo primeiro e passe o YAML como string.

Executar o transporte stdio diretamente em um terminal. Com o transporte stdio padrão, o servidor se comunica via stdin/stdout usando o protocolo MCP. Ele não imprimirá nada útil quando executado interativamente. Conecte-se a ele por meio de um cliente MCP, ou use o transporte HTTP para um servidor voltado para rede.

Páginas relacionadas

• Referência DSL: esquema completo para definições de workflow
• Esquema: o JSON Schema para arquivos de workflow
• Exemplos: padrões de workflow incluídos
• Usando a CLI: validação por linha de comando e execução de workflow