Conectores YAML

O mecanismo YAML é o caminho de autoria sem código. Ele compila um manifesto declarativo na mesma superfície MCP de um servidor tipado: ferramentas com parâmetros, Presenters por meio de transformações de resposta, recursos, prompts e conexões. Use-o para envolver rapidamente uma API REST interna; migre para código MVA tipado quando o domínio precisar de comportamento personalizado.

Um manifesto completo

version: "1.0"
server:
  name: billing
  description: Invoice operations for an AI agent
  capabilities:
    tools: true
    resources: true
secrets:
  BILLING_TOKEN:
    label: Billing API token
    type: api_key
    required: true
    sensitive: true
connections:
  billing:
    type: rest
    base_url: https://api.example.com
    auth:
      type: bearer
      token: ${SECRETS.BILLING_TOKEN}
tools:
  - name: list_invoices
    description: List invoices for the current account
    rules:
      - Never expose internal_notes to the model
    parameters:
      account_id:
        type: string
        required: true
        description: Account identifier
    execute:
      connection: billing
      method: GET
      path: /accounts/{{account_id}}/invoices
    response:
      extract: [data]
      max_items: 50

O parser valida o esquema raiz com Zod, verifica referências cruzadas, interpola ${SECRETS.KEY} a partir do ambiente, compila parâmetros para JSON Schema, resolve a conexão e cria um servidor MCP local.

A superfície do manifesto

• server: nome, descrição, capabilities e instruções
• secrets: declarações tipadas como api_key, token, password, url, flags required e sensitive
• connections: URL base REST, autenticação (none, bearer, basic ou custom header), headers, timeout e política de retry
• tools: descrição, instrução, regras, tags, anotações, parâmetros, bloco HTTP execute e transformação de resposta
• resources: templates de URI, conteúdo estático ou obtido, tipo MIME e cache opcional
• prompts: argumentos primitivos planos e templates de mensagens de usuário/assistente com {{argument}}
• settings: declarações de exposition, DLP, FinOps, circuit breaker e ciclo de vida

A CLI

mcpfusion yaml validate mcpfusion.yaml
mcpfusion yaml dev mcpfusion.yaml --transport http --port 3001

A CLI descobre automaticamente mcpfusion.yaml ou mcpfusion.yml no diretório atual. validate para após as verificações de esquema e referências cruzadas. dev executa stdio por padrão ou Streamable HTTP na porta selecionada.

O pacote YAML atual tem os comandos validate e dev na CLI OSS. Faça o deploy do conector compilado pelo fluxo regular de Deploy; não presuma um comando de deploy YAML separado, a menos que a CLI instalada o exponha.

O que o OSS impõe

O mecanismo aberto impõe formato do esquema, campos obrigatórios, tipos de parâmetros, referências cruzadas, interpolação de segredos e execução REST. As chaves de settings para DLP, FinOps, circuit breaker e ciclo de vida são analisadas como parte do manifesto; a aplicação desses controles da plataforma pertence ao Vinkius Cloud. Essa divisão permite executar o mesmo YAML localmente enquanto o conector hospedado recebe o perímetro da plataforma.

Quando o YAML deixa de ser suficiente

Escolha código MVA tipado quando precisar de Presenters dinâmicos, esquemas dependentes da função, middleware personalizado, transações, gates de estado FSM, handlers de geradores ou recuperação de erros específica do domínio. A migração não é uma reescrita do protocolo: as mesmas ferramentas, recursos e prompts podem ser reconstruídos com initMCPFusion() e implantados com o mesmo comando.

Próximos passos

• The MVA pattern: o caminho tipado para o qual o YAML compila
• Credentials: declare segredos gerenciados pelo comprador
• CLI: os comandos compartilhados de desenvolvimento