Skip to main content
Glama

mcp-vibe-check

by vinny1575
npmGitHub
TypeScript
MIT License
12
  • Linux
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

🧠 Vibe Check MCP v2.5.1

Plug-and-play metacognitive oversight layer for autonomous AI agents – a research-backed MCP server keeping LLMs aligned, reflective and safe.

Recognition

  • Listed in Anthropic’s official Model Context Protocol repo 🔗

  • Discoverable in the official MCP Registry 🔗

  • 18k+ installs across public MCP directories/clients

Version Trust Score smithery badge Security 4.3★ on MSEEP PRs Welcome

Table of Contents

What is Vibe Check MCP?

Vibe Check MCP is a lightweight server implementing Anthropic's Model Context Protocol. It acts as an AI meta-mentor for your agents, interrupting pattern inertia with Chain-Pattern Interrupts (CPI) to prevent Reasoning Lock-In (RLI). Think of it as a rubber-duck debugger for LLMs – a quick sanity check before your agent goes down the wrong path.

Overview

Vibe Check MCP pairs a metacognitive signal layer with CPI so agents can pause when risk spikes. Vibe Check surfaces traits, uncertainty, and risk scores; CPI consumes those triggers and enforces an intervention policy before the agent resumes. See the CPI integration guide and the CPI repo at https://github.com/PV-Bhat/cpi for wiring details.

Architecture

Vibe Check runs alongside your agent workflow, emitting signals that downstream overseers like CPI or human reviewers can act on. The high-level component map lives in docs/architecture.md, while the CPI handoff diagram and example shim are captured in docs/integrations/cpi.md.

The Problem: Pattern Inertia & Reasoning Lock-In

Large language models can confidently follow flawed plans. Without an external nudge they may spiral into overengineering or misalignment. Vibe Check provides that nudge through short reflective pauses, improving reliability and safety.

Key Features

Feature

Description

Benefits

CPI Adaptive Interrupts

Phase-aware prompts that challenge assumptions

alignment, robustness

Multi-provider LLM

Gemini, OpenAI and OpenRouter support

flexibility

History Continuity

Summarizes prior advice when

sessionId

is supplied

context retention

Optional vibe_learn

Log mistakes and fixes for future reflection

self-improvement

What's New in v2.5.1

Session Constitution (per-session rules)

Use a lightweight “constitution” to enforce rules per sessionId that CPI will honor. Typical uses: “no external network calls,” “prefer unit tests before refactors,” “never write secrets to disk.”

API (tools):

  • update_constitution({ sessionId, rules }) → merges/sets rule set for the session

  • reset_constitution({ sessionId }) → clears session rules

  • check_constitution({ sessionId }) → returns effective rules for the session as a JSON string in text format for broad MCP client compatibility

Response Format Note: The check_constitution tool returns its data with type: 'text' containing a JSON string (rather than type: 'json') to ensure compatibility with the widest range of MCP clients. Clients will need to parse the text field to access the JSON data.

Quickstart & Installation

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

This project targets Node 20+. If you see a TypeScript error about a duplicate require declaration when building with Node 20.19.3, ensure your dependencies are up to date (npm install) or use the Docker setup below which handles the build automatically.

Create a .env file with the API keys you plan to use:

# Gemini (default) GEMINI_API_KEY=your_gemini_api_key # Optional providers OPENAI_API_KEY=your_openai_api_key OPENROUTER_API_KEY=your_openrouter_api_key # Optional overrides DEFAULT_LLM_PROVIDER=gemini DEFAULT_MODEL=gemini-2.5-pro

Start the server:

npm start

See docs/TESTING.md for instructions on how to run tests.

Docker

The repository includes a helper script for one-command setup. It builds the image, saves your GEMINI_API_KEY and configures the container to start automatically whenever you log in:

bash scripts/docker-setup.sh

This script:

  • Creates ~/vibe-check-mcp for persistent data

  • Builds the Docker image and sets up docker-compose.yml

  • Prompts for your API key and writes ~/vibe-check-mcp/.env

  • Installs a systemd service (Linux) or LaunchAgent (macOS) so the container starts at login

  • Generates vibe-check-tcp-wrapper.sh which proxies Cursor IDE to the server After running it, open Cursor IDE → Settings → MCP and add a new server of type Command pointing to:

~/vibe-check-mcp/vibe-check-tcp-wrapper.sh

See Automatic Docker Setup for full details. If you prefer to run the commands manually:

docker build -t vibe-check-mcp . docker run -e GEMINI_API_KEY=your_gemini_api_key -p 3000:3000 vibe-check-mcp

Integrating with Claude Desktop

Add to claude_desktop_config.json:

"vibe-check": { "command": "node", "args": ["/path/to/vibe-check-mcp/build/index.js"], "env": { "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY" } }

Research & Philosophy

CPI (Chain-Pattern Interrupt) is the research-backed oversight method behind Vibe Check. It injects brief, well-timed “pause points” at risk inflection moments to re-align the agent to the user’s true priority, preventing destructive cascades and reasoning lock-in (RLI). In pooled evaluation across 153 runs, CPI nearly doubles success (~27%→54%) and roughly halves harmful actions (~83%→42%). Optimal interrupt dosage is ~10–20% of steps. Vibe Check MCP implements CPI as an external mentor layer at test time.

Links:

Usage Examples

import { vibe_check } from 'vibe-check-mcp'; const result = await vibe_check({ goal: 'Write unit tests', plan: 'Use vitest for coverage', sessionId: 'demo1' }); console.log(result.questions);
flowchart TD A[Agent Phase] --> B{Monitor Progress} B -- high risk --> C[CPI Interrupt] C --> D[Reflect & Adjust] B -- smooth --> E[Continue]

Adaptive Metacognitive Interrupts (CPI)

Agent Prompting Essentials

In your agent's system prompt, make it clear that vibe_check is a mandatory tool for reflection. Always pass the full user request and other relevant context. After correcting a mistake, you can optionally log it with vibe_learn to build a history for future analysis.

Example snippet:

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.

When to Use Each Tool

Tool

Purpose

🛑

vibe_check

Challenge assumptions and prevent tunnel vision

🔄

vibe_learn

Capture mistakes, preferences, and successes

🧰

update_constitution

Set/merge session rules the CPI layer will enforce

🧹

reset_constitution

Clear rules for a session

🔎

check_constitution

Inspect effective rules for a session (returns JSON as text for MCP compatibility)

Documentation

Security

This repository includes a CI-based security scan that runs on every pull request. It checks dependencies with npm audit and scans the source for risky patterns. See SECURITY.md for details and how to report issues.

Roadmap

  1. Benchmarks and latency profiling

  2. Adaptive tuning based on agent performance

  3. Multi-agent cooperation support

  4. Optional human-in-the-loop review

Contributing & Community

Contributions are welcome! See CONTRIBUTING.md.

FAQ

  • Does it increase latency? A single CPI call typically adds ~1 second depending on the provider.

  • Can I disable logging? Yes, vibe_learn is optional.

Find Vibe Check MCP on

Star History

Star History Chart

Credits & License

Vibe Check MCP is released under the MIT License. Built for reliable, enterprise-ready AI agents.

Author Credits & Links

Vibe Check MCP created by: Pruthvi Bhat, Intiative - https://murst.org/

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Custom version of vibecheck

  1. Recognition
    1. Table of Contents
      1. What is Vibe Check MCP?
        1. Overview
          1. Architecture
            1. The Problem: Pattern Inertia & Reasoning Lock-In
              1. Key Features
                1. What's New in v2.5.1
                  1. Session Constitution (per-session rules)
                    1. Quickstart & Installation
                      1. Docker
                      2. Integrating with Claude Desktop
                    2. Research & Philosophy
                      1. Usage Examples
                        1. Adaptive Metacognitive Interrupts (CPI)
                          1. Agent Prompting Essentials
                            1. When to Use Each Tool
                              1. Documentation
                                1. Security
                                  1. Roadmap
                                    1. Contributing & Community
                                      1. FAQ
                                        1. Find Vibe Check MCP on
                                          1. Star History
                                            1. Credits & License
                                              1. Author Credits & Links

                                                New MCP Servers

                                                MCP directory API

                                                We provide all the information about MCP servers via our MCP API.

                                                curl -X GET 'https://glama.ai/api/mcp/v1/servers/vinny1575/mcp-vibe-check'

                                                If you have feedback or need assistance with the MCP directory API, please join our Discord server