Vibe Check

El definitivo servidor MCP de verificación de cordura para Vibe Coder: Previene errores en cascada al llamar a un agente "Vibe-check" para asegurar la alineación y evitar la expansión del alcance.

GitHub
503
Prueba este MCPPatrocinado

Documentación

Vibe Check MCP

Este proyecto está en modo de mantenimiento. El desarrollo activo de funciones ha terminado; solo se publican parches de mantenimiento (correcciones de seguridad y errores). v2.9.0 es la última versión de mantenimiento. El servidor sigue siendo totalmente funcional. Las bifurcaciones comunitarias y las contribuciones son bienvenidas bajo la licencia MIT.

Di adiós a los agentes demasiado entusiastas. Herramienta de supervisión de agentes plug & play.

Basado en investigación:
En nuestro estudio, los agentes que llaman a Vibe Check mejoraron el éxito en +27% y redujeron a la mitad las acciones dañinas -41%

CPI Research Anthropic MCP: listed MCP Registry PulseMCP: Most Popular (this week) CI passing MIT License

Destacado en PulseMCP "Más Popular (Esta Semana)" • Más de 5k llamadas mensuales en Smithery.ai • supervisión respaldada por investigación • transporte STDIO + HTTP streamable

Gemini_Generated_Image_kvdvp4kvdvp4kvdv

Version Trust Score PRs Welcome

Capa de mentor plug-and-play que evita que los agentes sobre-ingeniericen y los mantiene en el camino mínimo viable: servidor MCP respaldado por investigación que mantiene a los LLM alineados, reflexivos y seguros.

GitHub    Anthropic MCP Registry    Smithery    PulseMCP
Con la confianza de desarrolladores en plataformas y registros MCP

Inicio rápido (npx)

Ejecuta el servidor directamente desde npm sin instalación local. Requiere Node >=20. Elige un transporte:

Opción 1 – Cliente MCP sobre STDIO

npx -y @pv-bhat/vibe-check-mcp start --stdio
  • Inicia desde un cliente compatible con MCP (Claude Desktop, Cursor, Windsurf, etc.).
  • [MCP] stdio transport connected indica que el proceso está esperando al cliente.
  • Añade este bloque a la configuración de tu cliente para que ejecute el comando:
{
  "mcpServers": {
    "vibe-check-mcp": {
      "command": "npx",
      "args": ["-y", "@pv-bhat/vibe-check-mcp", "start", "--stdio"]
    }
  }
}

Opción 2 – Inspección HTTP manual

npx -y @pv-bhat/vibe-check-mcp start --http --port 2091
  • curl http://127.0.0.1:2091/healthz para confirmar que el servicio está activo.
  • Envía solicitudes JSON-RPC a http://127.0.0.1:2091/mcp.

npx descarga el paquete bajo demanda para ambas opciones. Para una configuración detallada del cliente y otros comandos como install y doctor, consulta la documentación a continuación.

Star History Chart

Reconocimiento

  • Destacado en la portada de PulseMCP "Más Popular (Esta Semana)" (semana del 13 de octubre de 2025) 🔗
  • Listado en el repositorio oficial de Model Context Protocol de Anthropic 🔗
  • Descubrible en el Registro MCP oficial 🔗
  • Destacado en el Top 9 de servidores MCP de Sean Kochel para codificadores de vibraciones 🔗

Tabla de contenidos

¿Qué es Vibe Check MCP?

Vibe Check MCP mantiene a los agentes en el camino mínimo viable y aumenta la complejidad solo cuando la evidencia lo exige. Vibe Check MCP es un servidor ligero que implementa el Protocolo de Contexto de Modelo de Anthropic. Actúa como un meta-mentor de IA para tus agentes, interrumpiendo la inercia de patrones con Interrupciones de Cadena de Patrones (CPI) para prevenir el Bloqueo de Razonamiento (RLI). Piénsalo como un depurador de pato de goma para LLMs: una verificación rápida de cordura antes de que tu agente tome el camino equivocado.

Descripción general

Vibe Check MCP combina una capa de señal metacognitiva con CPI para que los agentes puedan pausarse cuando el riesgo aumenta. Vibe Check muestra rasgos, incertidumbre y puntuaciones de riesgo; CPI consume esos desencadenantes y aplica una política de intervención antes de que el agente continúe. Consulta la guía de integración de CPI y el repositorio de CPI en https://github.com/PV-Bhat/cpi para detalles de conexión.

Vibe Check invoca un segundo LLM para dar retroalimentación metacognitiva a tu agente principal. Integrar llamadas de vibe_check en los indicaciones del sistema del agente e instruir llamadas a herramientas antes de acciones irreversibles mejora significativamente la alineación y el sentido común del agente. El mapa de componentes de alto nivel: docs/architecture.md, mientras que el diagrama de transferencia de CPI y el ejemplo de shim están capturados en docs/integrations/cpi.md.

El problema: inercia de patrones y bloqueo de razonamiento

Los modelos de lenguaje grandes pueden seguir con confianza planes defectuosos. Sin un empujón externo, pueden caer en espirales de sobreingeniería o desalineación. Vibe Check proporciona ese empujón a través de breves pausas reflexivas, mejorando la fiabilidad y la seguridad.

Características clave

CaracterísticaDescripciónBeneficios
Interrupciones adaptativas CPIIndicaciones conscientes de fase que desafían suposicionesalineación, robustez
LLM multiproveedorCompatibilidad con Gemini 3.6, Claude 5, GPT-5.6 y OpenRouterflexibilidad
Continuidad de historialResume consejos anteriores cuando se proporciona sessionIdretención de contexto
vibe_learn opcionalRegistra errores y correcciones para reflexión futuraautomejora

Novedades en v2.9.0 (Actualización de seguridad y modelos)

Aviso de mantenimiento: Este proyecto está en modo de mantenimiento y ya no está en desarrollo activo de funciones. Sigue siendo totalmente funcional y está disponible bajo la licencia MIT. Las bifurcaciones comunitarias son bienvenidas. Para más detalles, consulta el Registro de cambios.

  • Modelos actuales: Gemini 3.6 Flash, Claude Sonnet 5 / Opus 5 / Fable 5 y GPT-5.6 Sol / Terra / Luna son ahora los valores predeterminados compatibles, definidos en un solo registro (src/utils/models.ts)
  • Google AI Studio nativo: migrado del paquete retirado @google/generative-ai al SDK unificado @google/genai
  • Refuerzo HTTP: CORS ahora predeterminado a orígenes de loopback en lugar de *, los encabezados Host se validan para bloquear el rebinding de DNS, y el límite del cuerpo JSON es explícito y validado
  • Seguridad: npm audit está limpio: 10 avisos resueltos en axios, la pila Hono del SDK de MCP, form-data, fast-uri, postcss y el conjunto de herramientas de prueba
  • Dependencias: MCP SDK 1.29, axios 1.18, OpenAI SDK 6.x, vitest 4.x; se eliminó la dependencia directa no utilizada body-parser

Constitución de sesión (reglas por sesión)

Usa una "constitución" ligera para aplicar reglas por sessionId que CPI respetará. Ejemplo de reglas de constitución: "sin llamadas de red externas", "preferir pruebas unitarias antes de refactorizaciones", "nunca escribir secretos en disco".

API (herramientas):

  • update_constitution({ sessionId, rules }) → fusiona/establece el conjunto de reglas para la sesión
  • reset_constitution({ sessionId }) → limpia las reglas de la sesión
  • check_constitution({ sessionId }) → devuelve las reglas efectivas para la sesión

Configuración de desarrollo

# 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

Usa npm para todos los flujos de trabajo (npm ci, npm run build, npm test). Este proyecto requiere Node >=20.

Crea un archivo .env con las claves de API que planeas 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

Proveedores y modelos

Gemini se ejecuta de forma nativa contra Google AI Studio (la API de desarrollador de Gemini) a través del SDK unificado @google/genai. Cualquier ID de modelo que el proveedor acepte funcionará: la tabla enumera los valores predeterminados y las sugerencias que se muestran a los agentes en el esquema de la herramienta vibe_check.

ProveedorModelo predeterminadoTambién compatible
geminigemini-3.6-flashgemini-3.5-flash, gemini-3.5-flash-lite, gemini-2.5-pro, gemini-2.5-flash
anthropicclaude-sonnet-5claude-opus-5, claude-fable-5, claude-haiku-4-5-20251001
openaigpt-5.6-terragpt-5.6-sol, gpt-5.6-luna
openrouter(ninguno — requerido)cualquier slug de OpenRouter, p. ej. google/gemini-3.6-flash

Establece el valor predeterminado globalmente con DEFAULT_LLM_PROVIDER / DEFAULT_MODEL, o por llamada con modelOverride. DEFAULT_MODEL nombra un modelo de DEFAULT_LLM_PROVIDER; una llamada que anula el proveedor sin nombrar un modelo recurre al valor predeterminado de ese proveedor en lugar de reutilizarlo.

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

Si una llamada a Gemini falla, el servidor reintenta una vez contra gemini-3.5-flash-lite antes de recurrir a preguntas estáticas.

Refuerzo del transporte HTTP

Estos se aplican solo al modo --http; stdio no se ve afectado.

VariablePredeterminadoPropósito
CORS_ORIGINsolo orígenes de loopbackLista de orígenes de navegador permitidos separados por comas. * restaura el comodín anterior a 2.9.
MCP_ALLOWED_HOSTSlocalhost, 127.0.0.1, ::1Lista de encabezados permitidos Host (protección contra rebinding de DNS). * desactiva la verificación.
MCP_MAX_BODY_SIZE100kbLímite del cuerpo JSON. Los valores no analizables se ignoran en lugar de desactivar silenciosamente la aplicación.

Actualización a v2.9.0 sobre HTTP: si sirves Vibe Check en un nombre de host que no sea de loopback (Docker, un proxy inverso, una implementación alojada), establece MCP_ALLOWED_HOSTS a ese nombre de host — o * — o las solicitudes serán rechazadas con HTTP 403.

Configuración

Consulta docs/TESTING.md para instrucciones sobre cómo ejecutar pruebas.

Docker

El repositorio incluye un script auxiliar para la configuración con un solo comando.

bash scripts/docker-setup.sh

Consulta Configuración automática de Docker para más detalles.

Claves de proveedor

Consulta Claves de API y gestión de secretos para proveedores compatibles, orden de resolución, ubicaciones de almacenamiento y guía de seguridad.

Selección de transporte

La CLI admite transportes stdio y HTTP. La resolución del transporte sigue este orden: banderas explícitas (--stdio/--http) → MCP_TRANSPORT → predeterminado stdio. Al usar HTTP, especifica --port (o establece MCP_HTTP_PORT); el puerto predeterminado es 2091. Las entradas generadas añaden --stdio o --http --port <n> según corresponda, y los clientes compatibles con HTTP también reciben un endpoint http://127.0.0.1:<port>.

Instaladores de cliente

Cada instalador es idempotente y etiqueta las entradas con "managedBy": "vibe-check-mcp-cli". Las copias de seguridad se escriben una vez por ejecución antes de aplicar los cambios, y las fusiones son atómicas (los archivos *.bak facilitan la reversión). Consulta docs/clients.md para referencias más profundas específicas del cliente.

Claude Desktop

  • Ruta de configuración: claude_desktop_config.json (auto-descubierta por plataforma).
  • Transporte predeterminado: stdio (npx … start --stdio).
  • Reinicia Claude Desktop después de la instalación para cargar el nuevo servidor MCP.
  • Si ya existe una entrada no gestionada para vibe-check-mcp, la CLI la deja intacta e imprime una advertencia.

Cursor

  • Ruta de configuración: ~/.cursor/mcp.json (proporciona --config si lo almacenas en otro lugar).
  • El esquema refleja el diseño mcpServers de Claude.
  • Si el archivo falta, la CLI imprime un bloque JSON listo para pegar en el panel de configuración de Cursor en lugar de fallar.

Windsurf (Cascade)

  • Ruta de configuración: ~/.codeium/windsurf/mcp_config.json heredado, las nuevas compilaciones usan ~/.codeium/mcp_config.json.
  • Pasa --http para emitir una entrada con serverUrl para el cliente HTTP de Windsurf.
  • Las entradas existentes gestionadas por centinela serverUrl se conservan y actualizan en su lugar.

Visual Studio Code

  • La configuración del workspace se encuentra en .vscode/mcp.json; los perfiles también almacenan mcp.json en el directorio de datos de usuario de VS Code.
  • Proporcione --config <path> para apuntar a un archivo de workspace. Sin --config, la CLI imprime un fragmento JSON y un enlace vscode:mcp/install?... que puede abrir directamente desde la terminal.
  • VS Code admite campos de desarrollo opcionales; pase --dev-watch y/o --dev-debug <value> para completar dev.watch/dev.debug.

Desinstalación y reversión

  • Restaure la copia de seguridad generada durante la instalación (la más reciente *.bak junto a su configuración) para revertir de inmediato.
  • Para eliminar el servidor manualmente, elimine la entrada vibe-check-mcp bajo mcpServers (Claude/Windsurf/Cursor) o servers (VS Code) siempre que siga etiquetada con "managedBy": "vibe-check-mcp-cli".

Investigación y filosofía

CPI (Interrupción por Patrón de Cadena) es el método de supervisión respaldado por investigación detrás de Vibe Check. Inyecta "puntos de pausa" breves y bien sincronizados en momentos de inflexión de riesgo para realinear al agente con la prioridad real del usuario, previniendo cascadas destructivas y el bloqueo de razonamiento (RLI). En una evaluación combinada de 153 ejecuciones, CPI casi duplica el éxito (~27%→54%) y reduce aproximadamente a la mitad las acciones dañinas (~83%→42%). La dosis óptima de interrupción es ~10–20% de los pasos. Vibe Check MCP implementa CPI como una capa de mentoría externa en tiempo de prueba.

Enlaces:

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

Fundamentos de indicaciones para agentes

En el prompt del sistema de su agente, deje claro que vibe_check es una herramienta obligatoria para la reflexión. Siempre pase la solicitud completa del usuario y otro contexto relevante. Después de corregir un error, puede registrarlo opcionalmente con vibe_learn para construir un historial para análisis futuros.

Fragmento de ejemplo:

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.

Cuándo usar cada herramienta

HerramientaPropósito
🛑 vibe_checkCuestionar suposiciones y prevenir visión de túnel
🔄 vibe_learnCapturar errores, preferencias y éxitos
🧰 update_constitutionEstablecer/combinar reglas de sesión que la capa CPI aplicará
🧹 reset_constitutionLimpiar reglas para una sesión
🔎 check_constitutionInspeccionar reglas efectivas para una sesión

Documentación

Seguridad

Este repositorio incluye un escaneo de seguridad basado en CI que se ejecuta en cada pull request. Verifica dependencias con npm audit y escanea el código fuente en busca de patrones riesgosos. Consulte SECURITY.md para más detalles y cómo reportar problemas.

Hoja de ruta

Nota: Este proyecto está en modo de mantenimiento (última versión de mantenimiento: v2.9.0). La hoja de ruta a continuación se conserva para forks de la comunidad que deseen continuar el desarrollo.

  • Salida estructurada para vibe_check: Devolver un envoltorio JSON como { advice, riskScore, traits } para que los agentes posteriores puedan razonar de manera determinista.
  • Resiliencia de LLM: Envolver generateResponse con reintentos y retroceso exponencial.
  • Saneamiento de entradas: Validar y limpiar los argumentos de las herramientas para mitigar vectores de inyección de prompts.
  • Externalización de prompts: Mover prompts codificados a archivos de configuración para transparencia y auditabilidad (ver PR #71).

Contribuyentes y comunidad

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md.

Contributors

Enlaces

Créditos y licencia

Vibe Check MCP se publica bajo la Licencia MIT. Construido para agentes de IA confiables y listos para empresas.

Créditos del autor y enlaces

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