Vent

vent-mcp

Permita que seu agente reclame antes que o mesmo problema recorrente se torne o bug de amanhã.

vent-mcp é um pequeno servidor MCP STDIO que dá aos agentes um lugar não destrutivo para enviar feedback acionável enquanto trabalham. Agentes podem relatar trabalho bloqueado, falhas repetidas, capacidades ausentes, fluxos de trabalho confusos ou atritos operacionais sem interromper o fluxo da tarefa.

O crate é nomeado vent-mcp; o binário instalado é nomeado vent. A biblioteca Rust suporta esse binário e não é uma API de incorporação estável.

A ideia combina bem com a palestra de Benjamin Verbeek, O agente que registra seus próprios relatórios de bug e a publicação oficial do blog Lovable.

Início rápido

Use este caminho quando quiser vent disponível para um cliente MCP local e um log de feedback JSONL padrão.

Pré-requisitos

• Rust 1.88 ou mais recente e Cargo, ao instalar a partir do crates.io ou do código-fonte.
• Um cliente MCP que possa executar um servidor STDIO local, como Codex ou Claude.

Instalação

cargo install vent-mcp

Isso instala o binário vent com os recursos padrão cli e webhook.

Criar a configuração padrão

Execute:

vent list

Na primeira execução, vent cria uma configuração padrão em $XDG_CONFIG_HOME/vent-mcp/config.toml ou ~/.config/vent-mcp/config.toml. A configuração padrão contém um canal feedback e um sink JSONL local.

Saída esperada:

feedback (default) - Blocked work, repeated failures, or confusing workflows. Avoid routine progress updates.

Eventos JSONL são gravados em vents.jsonl ao lado do arquivo de configuração, a menos que você defina [logging].jsonl_dir.

Registrar o servidor MCP

Se vent estiver no seu PATH, adicione-o como um servidor MCP STDIO local:

codex mcp add vent -- vent
claude mcp add --transport stdio vent -- vent

Use um caminho absoluto para vent se o seu cliente MCP não herdar o PATH do seu shell.

Instalação

Cargo

cargo install vent-mcp

GitHub Releases

Baixe um arquivo pré-compilado da página GitHub Releases, extraia-o e coloque vent no seu PATH.

A partir do código-fonte

git clone https://github.com/bnomei/vent-mcp.git
cd vent-mcp
cargo build --release

O binário é gravado em target/release/vent.

Compilações com recursos

Compile sem dependências de webhook e HTTP:

cargo build --release --no-default-features

Compile apenas com entrega JSONL mantendo o CLI do shell:

cargo build --release --no-default-features --features cli

Quando o recurso cli está desabilitado, o binário aceita apenas uma invocação simples de servidor MCP. Quaisquer argumentos de CLI saem com erro.

CLI

Sem argumentos, vent inicia o servidor MCP STDIO:

vent

Use o mesmo binário a partir de um shell quando o recurso cli estiver habilitado:

vent list
vent "The queue changed mid-run."
vent --channel automation "The failing check output was hard to correlate."
vent --mcp

A entrega bem-sucedida via CLI imprime o id do evento e o canal:

vented aZ8pQ2xK to feedback

O texto da mensagem é aparado antes da entrega. Mensagens vazias e canais desconhecidos são rejeitados antes que qualquer sink receba um evento.

Ferramentas MCP

vent-mcp expõe uma pequena superfície de ferramentas:

Ferramenta	Propósito
vent	Enviar feedback acionável para o canal padrão configurado ou para um canal nomeado.
list_channels	Listar nomes e descrições de canais configurados quando vários canais estão disponíveis.

Quando a configuração contém apenas o canal padrão, list_channels fica oculto e o esquema de entrada de vent contém apenas message. Quando vários canais existem, list_channels é exposto e vent aceita um channel opcional.

Exemplo de entrada vent com múltiplos canais:

{
  "message": "The failing check output was hard to correlate with the changed file.",
  "channel": "automation"
}

A resposta de vent é um reconhecimento:

{
  "ok": true,
  "eventId": "aZ8pQ2xK",
  "channel": "automation"
}

Se a entrega falhar, ok é false e error contém a primeira falha do sink. O eventId é um id de rastreamento curto, não uma chave de deduplicação. Agentes não devem enviar reclamações repetidas para o mesmo problema, a menos que tenham novas evidências de causa raiz.

Configuração

vent resolve a configuração nesta ordem:

1. VENT_MCP_CONFIG
2. $XDG_CONFIG_HOME/vent-mcp/config.toml
3. ~/.config/vent-mcp/config.toml

Configurações implícitas de XDG ou diretório pessoal são criadas quando ausentes. Se VENT_MCP_CONFIG apontar para um arquivo ausente, a inicialização falha em vez de criá-lo.

Comece pelo configs/config.sample.toml ou pela configuração padrão gerada.

Configuração mínima

default_channel = "feedback"

[[channels]]
name = "feedback"
description = "Blocked work, repeated failures, or confusing workflows. Avoid routine progress updates."
sinks = ["log"]

[[sinks]]
type = "jsonl"
name = "log"

Referência de configuração

Configuração	Obrigatória	Descrição
default_channel	Sim	Canal usado quando os chamadores omitem channel. Deve corresponder a uma entrada de [[channels]].
[logging].jsonl_dir	Não	Diretório para vents.jsonl. Valores vazios ou omitidos usam o diretório de configuração. ~ e ~/... expandem a partir de HOME.
[[channels]].name	Sim	Nome do canal que os agentes podem escolher. Nomes devem ser letras ASCII minúsculas, dígitos, sublinhados ou hífens, até 64 caracteres.
[[channels]].description	Sim	Descrição curta exposta aos clientes MCP e vent list.
[[channels]].sinks	Sim	Um ou mais nomes de sinks. Cada sink referenciado deve existir. Um canal pode referenciar no máximo um sink JSONL.
[[sinks]].type	Sim	jsonl ou, com o recurso webhook, webhook.
[[sinks]].name	Sim	Nome único do sink referenciado pelos canais.
[[sinks]].url	Somente webhook	Endpoint HTTP ou HTTPS.
[[sinks]].provider	Não	Mapa de provedor integrado ou personalizado. Omita-o ou use raw para enviar o JSON canônico do evento.
[[sinks]].headers	Não	Cabeçalhos de webhook baseados em ambiente. Os valores dos cabeçalhos são lidos quando o evento é enviado.
[[sinks]].timeout_ms	Somente webhook	Tempo limite positivo em milissegundos. O padrão é 10000.
[providers.<name>]	Não	Mapeia campos canônicos do evento para caminhos de saída JSON do webhook.

Todo evento de reclamação contém:

{
  "id": "aZ8pQ2xK",
  "timestamp": "2026-06-03T12:34:56Z",
  "channel": "automation",
  "message": "The failing check output was hard to correlate with the changed file.",
  "project": "my-repo"
}

O valor de project é apenas o nome do diretório atual. vent-mcp não registra o caminho completo do workspace local.

Canais, sinks e provedores

vent-mcp mantém o roteamento deliberadamente simples:

• Um canal é a rota que o agente pode escolher, ou omitir para usar default_channel.
• Um sink é um destino concreto, como registro JSONL local ou um webhook.
• Um provedor é um formato de payload de webhook.

Nomes de sinks e nomes de canais não precisam corresponder. Por exemplo, um canal automation pode gravar no log padrão e postar no Discord:

default_channel = "feedback"

[[channels]]
name = "feedback"
description = "General feedback."
sinks = ["log"]

[[channels]]
name = "automation"
description = "Build, test, CI/CD, deployment, scheduler, or pipeline failures that blocked progress."
sinks = ["log", "discord-automation"]

[[sinks]]
type = "jsonl"
name = "log"

[[sinks]]
type = "webhook"
name = "discord-automation"
provider = "discord"
url = "https://discord.com/api/webhooks/..."
timeout_ms = 10000

Com esta configuração, reclamações de channel = "automation" são gravadas em vents.jsonl e postadas no Discord. Outros canais vão apenas para os sinks que listam.

Provedores de webhook

Sinks de webhook fazem POST de JSON. Sem provedor, ou com provider = "raw", o evento bruto de reclamação é enviado inalterado.

Mapas de provedores integrados incluem:

Provedor	Formato
zapier, make, n8n, pipedream, workato	Campos canônicos brutos do evento.
ifttt	message, channel e project mapeados para value1, value2 e value3.
slack, mattermost	Texto mais campo de projeto no estilo anexo.
discord	content mais um campo embed para projeto.
microsoft_teams, google_chat, webex	Campo de mensagem somente texto.

Mapas de provedores personalizados ficam no mesmo arquivo de configuração TOML. O lado esquerdo é um campo canônico do evento e o valor é um caminho de saída JSON com pontos. Segmentos de caminho numéricos criam arrays. Se field_label_key estiver definido, caminhos que terminam em .value também recebem um rótulo gerado, como Project.

[providers.discord]
field_label_key = "name"
message = "content"
project = "embeds.0.fields.0.value"

[[sinks]]
type = "webhook"
name = "discord-automation"
provider = "discord"
url = "https://discord.com/api/webhooks/..."
timeout_ms = 10000

Cabeçalhos de webhook leem valores de variáveis de ambiente:

[[sinks]]
type = "webhook"
name = "private-endpoint"
url = "https://example.test/vent"

[[sinks.headers]]
name = "Authorization"
env = "VENT_WEBHOOK_AUTH"

Se um webhook retornar uma resposta não-2xx, a prévia do erro é encurtada e segredos conhecidos de URL ou cabeçalho são mascarados antes que o chamador veja.

Solução de problemas

config file not found

Causa: VENT_MCP_CONFIG aponta para um caminho que não existe.

Correção: Crie o arquivo nesse caminho, remova a definição de VENT_MCP_CONFIG ou aponte-o para uma configuração TOML existente.

unknown channel: <name>

Causa: O chamador CLI ou MCP solicitou um canal que não está declarado em [[channels]].

Correção: Execute vent list, escolha um dos nomes configurados ou adicione o canal e sua rota de sink à configuração.

message must not be empty

Causa: A mensagem estava vazia após remover espaços em branco.

Correção: Envie uma mensagem específica e acionável que diga o que falhou e o que desbloquearia o trabalho.

missing environment variable <NAME>

Causa: Um cabeçalho de webhook referencia uma variável de ambiente que não está definida no ambiente do processo vent.

Correção: Exporte a variável antes de iniciar o cliente MCP ou remova o cabeçalho do sink.

CLI mode is disabled

Causa: O binário foi compilado sem o recurso cli e recebeu argumentos de CLI.

Correção: Use o binário apenas como servidor MCP ou recompile com --features cli.

Desenvolvimento

Execute a suíte de testes:

cargo test

Compile um binário de release:

cargo build --release

Âncoras de código-fonte:

• src/main.rs: seleção de modo binário, carregamento de configuração, saída CLI e inicialização do servidor MCP.
• src/config.rs: resolução de caminho de configuração, padrões, validação e mapas de provedores integrados.
• src/server.rs: definições de ferramentas MCP e modelagem dinâmica da superfície de ferramentas.
• src/delivery.rs: remoção de espaços da mensagem, seleção de canal, construção de eventos e saída de reconhecimento.
• src/sinks.rs: gravação JSONL, entrega via webhook, cabeçalhos baseados em ambiente, tratamento de tempo limite e mascaramento de erros.
• src/provider.rs: validação de caminho de provedor e renderização JSON de webhook.
• tests/cli.rs: comportamento de CLI em nível de processo e cobertura de inicialização de configuração.