Vibe Check

Vibe Check MCP

Este projeto está em modo de manutenção. O desenvolvimento ativo de funcionalidades foi encerrado; apenas patches de manutenção (correções de segurança e bugs) são publicados. v2.9.0 é a versão de manutenção mais recente. O servidor permanece totalmente funcional. Forks da comunidade e contribuições são bem-vindos sob a licença MIT.

Diga adeus a agentes excessivamente zelosos. Ferramenta de supervisão de agentes plug & play.

Baseado em pesquisa:
Em nosso estudo, agentes que usam o Vibe Check melhoraram o sucesso em +27% e reduziram pela metade as ações prejudiciais -41%

_{Destaque no PulseMCP "Mais Popular (Esta Semana)" • 5k+ chamadas mensais no Smithery.ai • supervisão baseada em pesquisa • transporte STDIO + HTTP streamable}

Camada de mentoria plug-and-play que impede agentes de superengenharia e os mantém no caminho mínimo viável — servidor MCP baseado em pesquisa que mantém LLMs alinhados, reflexivos e seguros.

Início Rápido (npx)

Execute o servidor diretamente do npm sem instalação local. Requer Node >=20. Escolha um transporte:

Opção 1 – Cliente MCP via STDIO

npx -y @pv-bhat/vibe-check-mcp start --stdio

• Inicie a partir de um cliente compatível com MCP (Claude Desktop, Cursor, Windsurf, etc.).
• [MCP] stdio transport connected indica que o processo está aguardando o cliente.
• Adicione este bloco à configuração do seu cliente para que ele execute o comando:

{
  "mcpServers": {
    "vibe-check-mcp": {
      "command": "npx",
      "args": ["-y", "@pv-bhat/vibe-check-mcp", "start", "--stdio"]
    }
  }
}

Opção 2 – Inspeção HTTP manual

npx -y @pv-bhat/vibe-check-mcp start --http --port 2091

• curl http://127.0.0.1:2091/healthz para confirmar que o serviço está ativo.
• Envie solicitações JSON-RPC para http://127.0.0.1:2091/mcp.

O npx baixa o pacote sob demanda para ambas as opções. Para configuração detalhada do cliente e outros comandos como install e doctor, consulte a documentação abaixo.

Reconhecimento

• Destaque na página inicial do PulseMCP "Mais Popular (Esta Semana)" (semana de 13 de outubro de 2025) 🔗
• Listado no repositório oficial do Model Context Protocol da Anthropic 🔗
• Localizável no Registro MCP oficial 🔗
• Destaque no Top 9 de servidores MCP para vibe coders de Sean Kochel 🔗

Sumário

• Início Rápido (npx)
• O que é o Vibe Check MCP?
• Visão Geral
• O Problema: Inércia de Padrões e Bloqueio de Raciocínio
• Principais Recursos
• Novidades
• Configuração de Desenvolvimento
• Lançamento
• Exemplos de Uso
• Interrupções Metacognitivas Adaptativas (CPI)
• Fundamentos de Prompting para Agentes
• Quando Usar Cada Ferramenta
• Documentação
• Pesquisa e Filosofia
• Segurança
• Roteiro
• Colaboradores e Comunidade
• FAQ
• Listado em
• Créditos e Licença

---

O que é o Vibe Check MCP?

O Vibe Check MCP mantém os agentes no caminho mínimo viável e aumenta a complexidade apenas quando as evidências exigem. O Vibe Check MCP é um servidor leve que implementa o Model Context Protocol da Anthropic. Ele atua como um meta-mentor de IA para seus agentes, interrompendo a inércia de padrões com Interrupções de Padrão em Cadeia (CPI) para prevenir o Bloqueio de Raciocínio (RLI). Pense nele como um depurador de pato de borracha para LLMs – uma verificação rápida de sanidade antes que seu agente siga pelo caminho errado.

Visão Geral

O Vibe Check MCP combina uma camada de sinal metacognitivo com CPI para que os agentes possam pausar quando o risco aumenta. O Vibe Check expõe características, incerteza e pontuações de risco; o CPI consome esses gatilhos e aplica uma política de intervenção antes que o agente continue. Consulte o guia de integração CPI e o repositório CPI em https://github.com/PV-Bhat/cpi para detalhes de conexão.

O Vibe Check invoca um segundo LLM para fornecer feedback metacognitivo ao seu agente principal. Integrar chamadas vibe_check nos prompts de sistema do agente e instruir chamadas de ferramentas antes de ações irreversíveis melhora significativamente o alinhamento e o senso comum do agente. O mapa de componentes de alto nível: docs/architecture.md, enquanto o diagrama de transferência CPI e o exemplo de shim estão em docs/integrations/cpi.md.

O Problema: Inércia de Padrões e Bloqueio de Raciocínio

Modelos de linguagem grandes podem seguir planos falhos com confiança. Sem um estímulo externo, eles podem entrar em espiral de superengenharia ou desalinhamento. O Vibe Check fornece esse estímulo por meio de pausas reflexivas curtas, melhorando a confiabilidade e a segurança.

Principais Recursos

Recurso	Descrição	Benefícios
Interrupções Adaptativas CPI	Prompts sensíveis à fase que desafiam suposições	alinhamento, robustez
LLM multi-provedor	Suporte a Gemini 3.6, Claude 5, GPT-5.6 e OpenRouter	flexibilidade
Continuidade de Histórico	Resume conselhos anteriores quando sessionId é fornecido	retenção de contexto
vibe_learn opcional	Registra erros e correções para reflexão futura	autoaperfeiçoamento

Novidades na v2.9.0 (Atualização de Segurança e Modelos)

Aviso de Manutenção: Este projeto está em modo de manutenção e não está mais em desenvolvimento ativo de funcionalidades. Ele permanece totalmente funcional e disponível sob a licença MIT. Forks da comunidade são bem-vindos. Para detalhes, consulte o Changelog.

• Modelos atuais: Gemini 3.6 Flash, Claude Sonnet 5 / Opus 5 / Fable 5 e GPT-5.6 Sol / Terra / Luna agora são os padrões suportados, definidos em um único registro (src/utils/models.ts)
• Google AI Studio nativo: migrado do pacote descontinuado @google/generative-ai para o SDK unificado @google/genai
• Reforço HTTP: CORS agora usa como padrão origens de loopback em vez de *, cabeçalhos Host são validados para bloquear rebinding de DNS, e o limite de corpo JSON é explícito e validado
• Segurança: npm audit está limpo — 10 avisos resolvidos em axios, pilha Hono do SDK MCP, form-data, fast-uri, postcss e a cadeia de ferramentas de teste
• Dependências: MCP SDK 1.29, axios 1.18, OpenAI SDK 6.x, vitest 4.x; a dependência direta não utilizada body-parser foi removida

Constituição de Sessão (regras por sessão)

Use uma "constituição" leve para aplicar regras por sessionId que o CPI respeitará. Ex.: regras de constituição: "sem chamadas de rede externas", "prefira testes unitários antes de refatorações", "nunca grave segredos em disco."

API (ferramentas):

• update_constitution({ sessionId, rules }) → mescla/define o conjunto de regras para a sessão
• reset_constitution({ sessionId }) → limpa as regras da sessão
• check_constitution({ sessionId }) → retorna as regras efetivas da sessão

Configuração de Desenvolvimento

# Clone and install
git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git
cd vibe-check-mcp-server
npm ci
npm run build
npm test

Use npm para todos os fluxos de trabalho (npm ci, npm run build, npm test). Este projeto tem como alvo Node >=20.

Crie um arquivo .env com as chaves de API que você planeja usar:

# Gemini (default)
GEMINI_API_KEY=your_gemini_api_key
# Optional providers / Anthropic-compatible endpoints
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_AUTH_TOKEN=your_proxy_bearer_token
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_VERSION=2023-06-01
# Optional overrides
# DEFAULT_LLM_PROVIDER accepts gemini | openai | openrouter | anthropic
DEFAULT_LLM_PROVIDER=gemini
# Leave DEFAULT_MODEL unset to use each provider's default (see table below)
# DEFAULT_MODEL=gemini-3.6-flash

Provedores e modelos

O Gemini é executado nativamente contra o Google AI Studio (a API do Gemini Developer) por meio do SDK unificado @google/genai. Qualquer ID de modelo que o provedor aceite funcionará — a tabela lista os padrões e as sugestões apresentadas aos agentes no esquema da ferramenta vibe_check.

Provedor	Modelo padrão	Também suportado
gemini	gemini-3.6-flash	gemini-3.5-flash, gemini-3.5-flash-lite, gemini-2.5-pro, gemini-2.5-flash
anthropic	claude-sonnet-5	claude-opus-5, claude-fable-5, claude-haiku-4-5-20251001
openai	gpt-5.6-terra	gpt-5.6-sol, gpt-5.6-luna
openrouter	(nenhum — obrigatório)	qualquer slug do OpenRouter, ex.: google/gemini-3.6-flash

Defina o padrão globalmente com DEFAULT_LLM_PROVIDER / DEFAULT_MODEL, ou por chamada com modelOverride. DEFAULT_MODEL nomeia um modelo de DEFAULT_LLM_PROVIDER; uma chamada que substitui o provedor sem nomear um modelo usa o padrão desse provedor em vez de reutilizá-lo.

{ "goal": "...", "plan": "...", "modelOverride": { "provider": "anthropic", "model": "claude-opus-5" } }

Se uma chamada Gemini falhar, o servidor tenta novamente uma vez contra gemini-3.5-flash-lite antes de recorrer a perguntas estáticas.

Reforço de transporte HTTP

Estes se aplicam apenas ao modo --http; stdio não é afetado.

Variável	Padrão	Finalidade
CORS_ORIGIN	apenas origens de loopback	Lista de permissões de origens de navegador separadas por vírgula. * restaura o curinga pré-2.9.
MCP_ALLOWED_HOSTS	localhost, 127.0.0.1, ::1	Lista de permissões de cabeçalho Host (proteção contra rebinding de DNS). * desativa a verificação.
MCP_MAX_BODY_SIZE	100kb	Limite de corpo JSON. Valores não analisáveis são ignorados em vez de desativar silenciosamente a aplicação.

Atualizando para v2.9.0 via HTTP: se você servir o Vibe Check em um hostname não-loopback (Docker, proxy reverso, implantação hospedada), defina MCP_ALLOWED_HOSTS para esse hostname — ou * — ou as solicitações serão rejeitadas com HTTP 403.

Configuração

Consulte docs/TESTING.md para instruções sobre como executar testes.

Docker

O repositório inclui um script auxiliar para configuração em um comando.

bash scripts/docker-setup.sh

Consulte Configuração Automática do Docker para detalhes completos.

Chaves de provedor

Consulte Chaves de API e Gerenciamento de Segredos para provedores suportados, ordem de resolução, locais de armazenamento e orientações de segurança.

Seleção de transporte

A CLI suporta transportes stdio e HTTP. A resolução de transporte segue esta ordem: flags explícitas (--stdio/--http) → MCP_TRANSPORT → padrão stdio. Ao usar HTTP, especifique --port (ou defina MCP_HTTP_PORT); a porta padrão é 2091. As entradas geradas adicionam --stdio ou --http --port <n> de acordo, e clientes compatíveis com HTTP também recebem um endpoint http://127.0.0.1:<port>.

Instaladores de cliente

Cada instalador é idempotente e marca entradas com "managedBy": "vibe-check-mcp-cli". Backups são gravados uma vez por execução antes que as alterações sejam aplicadas, e as mesclagens são atômicas (arquivos *.bak facilitam a reversão). Consulte docs/clients.md para referências mais aprofundadas específicas de clientes.

Claude Desktop

• Caminho de configuração: claude_desktop_config.json (descoberto automaticamente por plataforma).
• Transporte padrão: stdio (npx … start --stdio).
• Reinicie o Claude Desktop após a instalação para carregar o novo servidor MCP.
• Se uma entrada não gerenciada já existir para vibe-check-mcp, a CLI a deixa intacta e exibe um aviso.

Cursor

• Caminho de configuração: ~/.cursor/mcp.json (forneça --config se você o armazenar em outro lugar).
• O esquema espelha o layout mcpServers do Claude.
• Se o arquivo estiver ausente, a CLI imprime um bloco JSON pronto para colar no painel de configurações do Cursor em vez de falhar.

Windsurf (Cascade)

• Caminho de configuração: legado ~/.codeium/windsurf/mcp_config.json, novas versões usam ~/.codeium/mcp_config.json.
• Passe --http para emitir uma entrada com serverUrl para o cliente HTTP do Windsurf.
• Entradas existentes gerenciadas por sentinela serverUrl são preservadas e atualizadas no local.

Visual Studio Code

• A configuração do workspace fica em .vscode/mcp.json; os perfis também armazenam mcp.json no diretório de dados do usuário do VS Code.
• Forneça --config <path> para direcionar um arquivo de workspace. Sem --config, a CLI imprime um trecho JSON e um link vscode:mcp/install?... que você pode abrir diretamente do terminal.
• O VS Code suporta campos de desenvolvimento opcionais; passe --dev-watch e/ou --dev-debug <value> para preencher dev.watch/dev.debug.

Desinstalação e reversão

• Restaure o backup gerado durante a instalação (o *.bak mais recente ao lado da sua configuração) para reverter imediatamente.
• Para remover o servidor manualmente, exclua a entrada vibe-check-mcp em mcpServers (Claude/Windsurf/Cursor) ou servers (VS Code), desde que ainda esteja marcada com "managedBy": "vibe-check-mcp-cli".

Pesquisa e Filosofia

CPI (Interrupção por Padrão de Cadeia) é o método de supervisão baseado em pesquisa por trás do Vibe Check. Ele injeta "pontos de pausa" breves e bem cronometrados em momentos de inflexão de risco para realinhar o agente à prioridade real do usuário, prevenindo cascatas destrutivas e bloqueio de raciocínio (RLI). Em avaliação agrupada em 153 execuções, o CPI quase dobra o sucesso (~27%→54%) e reduz aproximadamente pela metade as ações prejudiciais (~83%→42%). A dosagem ideal de interrupção é de ~10–20% dos passos. O Vibe Check MCP implementa o CPI como uma camada de mentoria externa em tempo de teste.

Links:

• 📄 Artigo CPI (ResearchGate) — http://dx.doi.org/10.13140/RG.2.2.18237.93922
• 📘 Implementação de Referência CPI (GitHub): https://github.com/PV-Bhat/cpi
• 📚 DOI Zenodo MURST (arquivo RSRC): https://doi.org/10.5281/zenodo.14851363

flowchart TD
  A[Agent Phase] --> B{Monitor Progress}
  B -- high risk --> C[CPI Interrupt]
  C --> D[Reflect & Adjust]
  B -- smooth --> E[Continue]

Fundamentos de Prompting para Agentes

No prompt de sistema do seu agente, deixe claro que vibe_check é uma ferramenta obrigatória para reflexão. Sempre passe a solicitação completa do usuário e outro contexto relevante. Após corrigir um erro, você pode opcionalmente registrá-lo com vibe_learn para construir um histórico para análises futuras.

Exemplo de trecho:

As an autonomous agent you will:
1. Call vibe_check after planning and before major actions.
2. Provide the full user request and your current plan.
3. Optionally, record resolved issues with vibe_learn.

Quando Usar Cada Ferramenta

Ferramenta	Finalidade
🛑 vibe_check	Desafiar suposições e evitar visão de túnel
🔄 vibe_learn	Capturar erros, preferências e sucessos
🧰 update_constitution	Definir/mesclar regras de sessão que a camada CPI aplicará
🧹 reset_constitution	Limpar regras de uma sessão
🔎 check_constitution	Inspecionar regras efetivas de uma sessão

Documentação

• Estratégias de Prompting para Agentes
• Integração CPI
• Integração Avançada
• Referência Técnica
• Configuração Automática com Docker
• Filosofia
• Estudos de Caso
• Changelog

Segurança

Este repositório inclui uma varredura de segurança baseada em CI que é executada em cada pull request. Ela verifica dependências com npm audit e examina o código-fonte em busca de padrões arriscados. Consulte SECURITY.md para detalhes e como relatar problemas.

Roadmap

Nota: Este projeto está em modo de manutenção (última versão de manutenção: v2.9.0). O roadmap abaixo é preservado para forks da comunidade que desejem continuar o desenvolvimento.

• Saída estruturada para vibe_check: Retornar um envelope JSON como { advice, riskScore, traits } para que agentes downstream possam raciocinar de forma determinística.
• Resiliência de LLM: Envolver generateResponse com tentativas e backoff exponencial.
• Sanitização de entrada: Validar e limpar argumentos de ferramentas para mitigar vetores de injeção de prompt.
• Externalização de prompts: Mover prompts codificados para arquivos de configuração para transparência e auditabilidade (veja PR #71).

Contribuidores e Comunidade

Contribuições são bem-vindas! Consulte CONTRIBUTING.md.

Links

• MSEEP
• MCP Servers
• MCP.so
• Creati.ai
• Pulse MCP
• Playbooks.com
• MCPHub.tools
• MCP Directory

Créditos e Licença

O Vibe Check MCP é distribuído sob a Licença MIT. Construído para agentes de IA confiáveis e prontos para empresas.

Créditos do Autor e Links

Vibe Check MCP criado por: Pruthvi Bhat, Iniciativa - https://murst.org/