DOCSEARCHbyAlgolia
Submit Docs

Vibe Check MCP Server

repository·main·Indexed 19 days ago

https://github.com/pv-bhat/vibe-check-mcp-server

A Model Context Protocol (MCP) server acting as an AI meta-mentor to prevent 'Reasoning Lock-In' and 'Pattern Inertia' in LLM agents. It utilizes Chain-Pattern Interrupts (CPI) to provide metacognitive feedback and adaptive interrupts for alignment, reflection, and safety. Features include session constitution management, support for multiple LLM providers (Gemini, OpenAI, OpenRouter, Anthropic), and flexible transport modes via STDIO or HTTP.

Tokens
20.4K
Snippets
63
Records
92
Agent score
67%

What's inside vibe-check-mcp-server

  1. What is Vibe Check MCP?

    main

    Vibe Check MCP is a lightweight Model Context Protocol (MCP) server that acts as an AI meta-mentor. It is designed to prevent 'Reasoning Lock-In' (RLI) and 'Pattern Inertia' in LLM agents by providing a metacognitive signal layer.

    It uses Chain-Pattern Interrupts (CPI) to interrupt agents when risk or complexity spikes, forcing a reflective pause. This helps keep agents on a minimal viable path and prevents over-engineering. The server invokes a second LLM to provide meta-cognitive feedback to the primary agent.

  2. Understand the CPI (Chain-Pattern Interrupt) dosage

    main

    Vibe Check operationalizes CPI (Chain-Pattern Interrupt), a runtime oversight method. Research indicates that applying CPI can increase success rates (from ~27% to 54%) and decrease harm (from ~83% to 42%).

    Recommended dosage: Aim for approximately 10–20% of steps to receive an interrupt to balance oversight with productivity.

  3. Identify and prevent common AI agent error patterns

    main

    Vibe Check identifies several recurring error patterns in AI agent workflows through metacognitive pattern interrupts. Understanding these patterns helps you recognize when an agent is deviating from your intent:

    • Overengineering: The agent implements a solution that is significantly more complex than the problem requires (e.g., building a custom parser when a standard library suffices).
    • Feature Creep: The agent progressively expands the scope of work beyond the original request (e.g., adding predictive modeling to a simple weather app).
    • Misalignment: The agent solves a different, usually larger, problem than the one explicitly requested (e.g., building a CRM when only a contact form was asked for).
    • Overtooling: The agent proposes an overly complex tech stack or architecture that is inappropriate for the project's scale or the user's skill level (e.g., suggesting a full React/Redux/GraphQL stack for a simple to-do list).

  5. Configure Vibe Check storage and error handling

    main

    Storage

    Pattern recognition entries (mistakes, preferences, and successes) are stored in a JSON file located at ~/.vibe-check/vibe-log.json. This allows for persistent tracking across sessions.

    Error Handling Fallbacks

    If the API is unavailable, the system provides the following fallbacks:

    • vibe_check: Generates basic questions based on the current phase.
    • vibe_learn: Logs patterns to local storage even if API calls fail.

  6. Select transport mode (stdio vs HTTP)

    main

    The CLI supports two transport modes. Resolution follows this priority: explicit flags (--stdio or --http) $\rightarrow$ MCP_TRANSPORT environment variable $\rightarrow$ default stdio.

    • stdio: The default mode.
    • HTTP: Requires specifying a port via --port or setting the MCP_HTTP_PORT environment variable. The default port is 2091.

    When using HTTP, the server provides a http://127.0.0.1:<port> endpoint for HTTP-capable clients.

  7. How vibe_check and vibe_learn work together

    main

    Vibe Check MCP implements a metacognitive layer designed to provide AI agents with self-reflection and course-correction capabilities. The system relies on two primary tools that form a feedback loop:

    1. vibe_check (Pattern Interrupt): Acts as the primary mechanism to interrupt the agent's workflow. It analyzes the agent's current plan or thinking to detect misalignments, tunnel vision, or overengineering. It then generates phase-appropriate metacognitive questions and identifies matches with known error patterns.

    2. vibe_learn (Feedback Loop): Powers the self-improvement aspect. It records mistakes and their solutions, categorizes them into patterns, and builds a knowledge base. This knowledge is then used by vibe_check to improve its pattern recognition accuracy over time.

    Together, they compensate for the lack of natural self-doubt in LLM agents by providing external reflection and strategic interruption.

  8. Use vibe_check for pattern interruption

    main

    The vibe_check tool is used to force an AI agent to pause and reflect on its current reasoning. It is most effective when integrated into the following workflow phases:

    • Planning Phase: Use it to identify potential issues in an initial plan and to detect/prevent overengineering by encouraging simplification.
    • Implementation Phase: Use it to provide focused feedback on specific implementation decisions. At this stage, it can reference patterns learned via vibe_learn to provide higher-confidence feedback.
    • Review Phase: Use it to ensure the final solution aligns with the original intent before completion.

  9. Understand secret resolution order and storage

    main

    Vibe Check MCP resolves provider keys using a specific hierarchy. The first match found in the following order is used:

    1. Process Environment Variables: Values currently set in your shell or active process.
    2. Project-level .env: The .env file located in your current working directory. Use the --local flag with the CLI to write to this file.
    3. Home Directory Config: The file located at ~/.vibe-check/.env. This is where interactive CLI runs store or update keys by default (using 0600 permissions).

    Important Behavior:

    • Priority: Shell environment variables take precedence over project .env files, which take precedence over the home directory config.
    • Non-interactive runs: These runs (e.g., when used as an MCP server) do not automatically prompt for keys; they expect keys to be pre-configured in the environment or a .env file, otherwise they will exit early.

  10. How Vibe Check provides external metacognition

    main

    Vibe Check acts as an external metacognitive layer designed to bridge the "metacognitive gap" in LLMs. LLMs often suffer from Pattern Inertia (continuing flawed reasoning paths), Overconfident Reasoning (failing to recognize logic errors), Solution Tunneling (rushing to familiar patterns), and Recursive Complexity (adding unnecessary complexity).

    By operating as a separate system with different objectives, Vibe Check implements a "metacognitive recursion" principle, allowing it to identify problems that are invisible to the agent itself. It uses Phase-Aware Interrupts to provide oversight tailored to the current stage of work:

    • Planning phase: Focuses on alignment with user intent, exploring alternatives, and questioning fundamental assumptions.
    • Implementation phase: Focuses on consistency with the plan, appropriateness of methods, and technical alignment.
    • Review phase: Focuses on comprehensiveness, edge cases, and verification of outcomes.

  11. Use vibe_learn to build a feedback loop

    main

    The vibe_learn tool is used to create a long-term knowledge base of agent errors and corrections. It functions by:

    1. Recording specific instances where a mistake occurred and how it was solved.
    2. Categorizing these instances into meaningful pattern groups.
    3. Feeding these patterns back into the system so that vibe_check can recognize them in future sessions.

    By consistently using vibe_learn, the system's ability to identify potential issues early in the workflow increases in sophistication and accuracy.

  12. Negotiate HTTP transport modes

    main

    The HTTP transport supports request-scoped response modes.

    • JSON Fallback: Legacy clients advertising only application/json receive a direct JSON reply. This does not affect concurrent SSE subscribers.
    • Streaming (SSE): Clients including text/event-stream in their Accept header will continue to receive live SSE frames, even if JSON-only calls are running in parallel.