# Directory Structure
```
├── .env.example
├── .github
│ └── workflows
│ ├── ci.yml
│ ├── docker-image.yml
│ └── npm-publish-github-packages.yml
├── .gitignore
├── AGENTS.md
├── alt-test-gemini.js
├── alt-test-openai.js
├── alt-test.js
├── Attachments
│ ├── Template.md
│ ├── VC1.png
│ ├── vc2.png
│ ├── vc3.png
│ ├── vc4.png
│ ├── VCC1.png
│ ├── VCC2.png
│ ├── vibe (1).jpeg
│ ├── vibelogo.png
│ └── vibelogov2.png
├── CITATION.cff
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── Dockerfile
├── docs
│ ├── _toc.md
│ ├── advanced-integration.md
│ ├── agent-prompting.md
│ ├── AGENTS.md
│ ├── architecture.md
│ ├── case-studies.md
│ ├── changelog.md
│ ├── docker-automation.md
│ ├── gemini.md
│ ├── integrations
│ │ └── cpi.md
│ ├── philosophy.md
│ ├── registry-descriptions.md
│ ├── technical-reference.md
│ └── TESTING.md
├── examples
│ └── cpi-integration.ts
├── glama.json
├── LICENSE
├── package-lock.json
├── package.json
├── pnpm-lock.yaml
├── README.md
├── request.json
├── scripts
│ ├── docker-setup.sh
│ ├── install-vibe-check.sh
│ └── security-check.cjs
├── SECURITY.md
├── server.json
├── smithery.yaml
├── src
│ ├── index.ts
│ ├── tools
│ │ ├── constitution.ts
│ │ ├── vibeCheck.ts
│ │ ├── vibeDistil.ts
│ │ └── vibeLearn.ts
│ └── utils
│ ├── llm.ts
│ ├── state.ts
│ └── storage.ts
├── test-client.js
├── test-client.ts
├── test.js
├── test.json
├── tests
│ ├── constitution.test.ts
│ ├── llm.test.ts
│ ├── startup.test.ts
│ ├── state.test.ts
│ ├── vibeCheck.test.ts
│ └── vibeLearn.test.ts
├── tsconfig.json
└── vitest.config.ts
```
# Files
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
```
# Copy this file to .env and fill in your API key.
GOOGLE_CLOUD_PROJECT="mcp-vibetest"
DEFAULT_MODEL=gemini-2.5-flash
DEFAULT_LLM_PROVIDER=gemini
OPENAI_API_KEY=your_openai_key
OPENROUTER_API_KEY=your_openrouter_key
USE_LEARNING_HISTORY=false
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
npm-debug.log
yarn-debug.log
yarn-error.log
# Build output
build/
dist/
*.tsbuildinfo
# Environment variables
.env
.env.local
.env.*.local
# IDE and editor files
.idea/
.vscode/
*.swp
*.swo
.DS_Store
# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Testing
coverage/
.nyc_output/
# Temporary files
tmp/
temp/
# Local configuration
.npmrc
.mcpregistry_github_token
.mcpregistry_registry_token
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# 🧠 Vibe Check MCP v2.5.1
<p align="center">
<b>Based on research</b><br/>
In our study agents calling Vibe Check improved success (27 → 54%) and halved harmful actions (83 → 42%).
</p>
<p align="center">
<a href="https://www.researchgate.net/publication/394946231_Do_AI_Agents_Need_Mentors_Evaluating_Chain-Pattern_Interrupt_CPI_for_Oversight_and_Reliability?channel=doi&linkId=68ad6178ca495d76982ff192&showFulltext=true">
<img src="https://img.shields.io/badge/Research-CPI%20%28MURST%29-blue?style=flat-square" alt="CPI (MURST) Research">
</a>
<a href="https://github.com/modelcontextprotocol/servers"><img src="https://img.shields.io/badge/Anthropic%20MCP-listed-111?labelColor=111&color=555&style=flat-square" alt="Anthropic MCP: listed"></a>
<a href="https://registry.modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP%20Registry-discoverable-555?labelColor=111&style=flat-square" alt="MCP Registry: discoverable"></a>
<a href="https://github.com/PV-Bhat/vibe-check-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/PV-Bhat/vibe-check-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0b7285?style=flat-square" alt="MIT License"></a>
</p>
<p align="center">
<sub>18k+ installs across MCP clients • research-backed oversight • streamable HTTP transport</sub>
</p>
<img width="500" height="300" alt="vibecheckv2.5" src="https://github.com/user-attachments/assets/bcd06d7d-a184-43e9-8c43-22aca3074d32" />
*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 [🔗](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#-community-servers)
- Discoverable in the official MCP Registry [🔗](https://registry.modelcontextprotocol.io/v0/servers?search=vibe-check-mcp)
- 18k+ installs across public MCP directories/clients
[](https://github.com/PV-Bhat/vibe-check-mcp-server)
[](https://archestra.ai/mcp-catalog/pv-bhat__vibe-check-mcp-server)
[](https://smithery.ai/server/@PV-Bhat/vibe-check-mcp-server)
[](https://mseep.ai/app/a2954e62-a3f8-45b8-9a03-33add8b92599)
[](CONTRIBUTING.md)
## Table of Contents
- [What is Vibe Check MCP?](#what-is-vibe-check-mcp)
- [Overview](#overview)
- [Architecture](#architecture)
- [The Problem: Pattern Inertia & Reasoning Lock-In](#the-problem-pattern-inertia--reasoning-lock-in)
- [Key Features](#key-features)
- [What's New in v2.5.0](##-What's-New-in-v2.5.1)
- [Quickstart & Installation](#quickstart--installation)
- [Usage Examples](#usage-examples)
- [Adaptive Metacognitive Interrupts (CPI)](#adaptive-metacognitive-interrupts-cpi)
- [Agent Prompting Essentials](#agent-prompting-essentials)
- [When to Use Each Tool](#when-to-use-each-tool)
- [Documentation](#documentation)
- [Research & Philosophy](#research--philosophy)
- [Security](#security)
- [Roadmap](#roadmap)
- [Contributing & Community](#contributing--community)
- [FAQ](#faq)
- [Listed on](#find-vibe-check-mcp-on)
- [Credits & License](#credits--license)
---
## What is Vibe Check MCP?
Vibe Check MCP is a lightweight server implementing Anthropic's [Model Context Protocol](https://anthropic.com/mcp). 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](./docs/integrations/cpi.md) 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](./docs/architecture.md), while the CPI handoff diagram and example shim are captured in [docs/integrations/cpi.md](./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
## Quickstart & Installation
```bash
# 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:
```bash
# 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:
```bash
npm start
```
See [docs/TESTING.md](./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
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:
```bash
~/vibe-check-mcp/vibe-check-tcp-wrapper.sh
```
See [Automatic Docker Setup](./docs/docker-automation.md) for full details.
If you prefer to run the commands manually:
```bash
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`:
```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:**
- 📄 **CPI Paper (ResearchGate)** — http://dx.doi.org/10.13140/RG.2.2.18237.93922
- 📘 **CPI Reference Implementation (GitHub)**: https://github.com/PV-Bhat/cpi
- 📚 **MURST Zenodo DOI (RSRC archival)**: https://doi.org/10.5281/zenodo.14851363
## Usage Examples
```ts
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);
```
```mermaid
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)
<details><summary>Advanced CPI Details</summary>
The CPI architecture monitors planning, implementation and review phases. When uncertainty spikes, Vibe Check pauses execution, poses clarifying questions and resumes once the agent acknowledges the feedback.
</details>
## 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 |
## Documentation
- [Agent Prompting Strategies](./docs/agent-prompting.md)
- [CPI Integration](./docs/integrations/cpi.md)
- [Advanced Integration](./docs/advanced-integration.md)
- [Technical Reference](./docs/technical-reference.md)
- [Automatic Docker Setup](./docs/docker-automation.md)
- [Philosophy](./docs/philosophy.md)
- [Case Studies](./docs/case-studies.md)
- [Changelog](./docs/changelog.md)
## 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](./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](./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
* 🌐 [MSEEP](https://mseep.ai/app/pv-bhat-vibe-check-mcp-server)
* 📡 [MCP Servers](https://mcpservers.org/servers/PV-Bhat/vibe-check-mcp-server)
* 🧠 [MCP.so](https://mcp.so/server/vibe-check-mcp-server/PV-Bhat)
* 🛠️ [Creati.ai](https://creati.ai/mcp/vibe-check-mcp-server/)
* 💡 [Pulse MCP](https://www.pulsemcp.com/servers/pv-bhat-vibe-check)
* 📘 [Playbooks.com](https://playbooks.com/mcp/pv-bhat-vibe-check)
* 🧰 [MCPHub.tools](https://mcphub.tools/detail/PV-Bhat/vibe-check-mcp-server)
* 📇 [MCP Directory](https://mcpdirectory.ai/mcpserver/2419/)
* 🧙 [MagicSlides](https://www.magicslides.app/mcps/pv-bhat-vibe-check)
* 🗃️ [AIAgentsList](https://aiagentslist.com/mcp-servers/vibe-check-mcp-server)
## Star History
[](https://www.star-history.com/#PV-Bhat/vibe-check-mcp-server&Date)
## Credits & License
Vibe Check MCP is released under the [MIT License](LICENSE). Built for reliable, enterprise-ready AI agents.
## Author Credits & Links
Vibe Check MCP created by: [Pruthvi Bhat](https://pruthvibhat.com/), Intiative - https://murst.org/
```
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
```markdown
# Code of Conduct
This project adheres to the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) Code of Conduct. By participating, you are expected to uphold this code.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the maintainer listed in `package.json`.
```
--------------------------------------------------------------------------------
/AGENTS.md:
--------------------------------------------------------------------------------
```markdown
# Agent Quickstart
Vibe Check MCP is a lightweight oversight layer for AI agents. It exposes two tools:
- **vibe_check** – prompts you with clarifying questions to prevent tunnel vision.
- **vibe_learn** – optional logging of mistakes and successes for later review.
The server supports Gemini, OpenAI and OpenRouter LLMs. History is maintained across requests when a `sessionId` is provided.
## Setup
1. Install dependencies and build:
```bash
npm install
npm run build
```
2. Supply the following environment variables as needed:
- `GEMINI_API_KEY`
- `OPENAI_API_KEY`
- `OPENROUTER_API_KEY`
- `DEFAULT_LLM_PROVIDER` (gemini | openai | openrouter)
- `DEFAULT_MODEL` (e.g., gemini-2.5-pro)
3. Start the server:
```bash
npm start
```
## Testing
Run unit tests with `npm test`. Example request generators are provided:
- `alt-test-gemini.js`
- `alt-test-openai.js`
- `alt-test.js` (OpenRouter)
Each script writes a `request.json` file that you can pipe to the server:
```bash
node build/index.js < request.json
```
## Integration Tips
Call `vibe_check` regularly with your goal, plan and current progress. Use `vibe_learn` whenever you want to record a resolved issue. Full API details are in `docs/technical-reference.md`.
```
--------------------------------------------------------------------------------
/docs/AGENTS.md:
--------------------------------------------------------------------------------
```markdown
# Agent Quickstart
Vibe Check MCP is a lightweight oversight layer for AI agents. It exposes two tools:
- **vibe_check** – prompts you with clarifying questions to prevent tunnel vision.
- **vibe_learn** – optional logging of mistakes and successes for later review.
The server supports Gemini, OpenAI and OpenRouter LLMs. History is maintained across requests when a `sessionId` is provided.
## Setup
1. Install dependencies and build:
```bash
npm install
npm run build
```
2. Supply the following environment variables as needed:
- `GEMINI_API_KEY`
- `OPENAI_API_KEY`
- `OPENROUTER_API_KEY`
- `DEFAULT_LLM_PROVIDER` (gemini | openai | openrouter)
- `DEFAULT_MODEL` (e.g., gemini-2.5-pro)
3. Start the server:
```bash
npm start
```
## Testing
Run unit tests with `npm test`. Example request generators are provided:
- `alt-test-gemini.js`
- `alt-test-openai.js`
- `alt-test.js` (OpenRouter)
Each script writes a `request.json` file that you can pipe to the server:
```bash
node build/index.js < request.json
```
## Integration Tips
Call `vibe_check` regularly with your goal, plan and current progress. Use `vibe_learn` whenever you want to record a resolved issue. Full API details are in `docs/technical-reference.md`.
```
--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
```markdown
# Security Policy
VibeCheck MCP is designed as a lightweight oversight layer for AI coding agents. While it does not execute code on behalf of the agent, it processes user prompts and sends them to third‑party LLM APIs. This document outlines our approach to keeping that process secure.
## Supported Versions
Only the latest release receives security updates. Please upgrade regularly to stay protected.
## Threat Model
- **Prompt injection**: malicious text could attempt to alter the meta-mentor instructions. VibeCheck uses a fixed system prompt and validates required fields to mitigate this.
- **Tool misuse**: the server exposes only two safe tools (`vibe_check` and `vibe_learn`). No command execution or file access is performed.
- **Data leakage**: requests are forwarded to the configured LLM provider. Avoid sending sensitive data if using hosted APIs. The optional `vibe_learn` log can be disabled via environment variables.
- **Impersonation**: run VibeCheck only from this official repository or the published npm package. Verify the source before deployment.
## Reporting a Vulnerability
If you discover a security issue, please open a private GitHub issue or email the maintainer listed in `package.json`. We will acknowledge your report within 48 hours and aim to provide a fix promptly.
## Continuous Security
A custom security scan runs in CI on every pull request. It checks dependencies for known vulnerabilities and searches the source tree for dangerous patterns. The workflow fails if any issue is detected.
```
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
# Contributing to Vibe Check MCP
First off, thanks for considering contributing to Vibe Check! It's people like you that help make this metacognitive oversight layer even better.
## The Vibe of Contributing
Contributing to Vibe Check isn't just about code—it's about joining a community that's trying to make AI agents a bit more self-aware (since they're not quite there yet on their own).
### The Basic Flow
1. **Find something to improve**: Did your agent recently go off the rails in a way Vibe Check could have prevented? Found a bug? Have an idea for a new feature? That's a great starting point.
2. **Fork & clone**: The standard GitHub dance. Fork the repo, clone it locally, and create a branch for your changes.
3. **Make your changes**: Whether it's code, documentation, or just fixing a typo, all contributions are welcome.
4. **Test your changes**: Make sure everything still works as expected.
5. **Submit a PR**: Push your changes to your fork and submit a pull request. We'll review it as soon as we can.
## Vibe Check Your Contributions
Before submitting a PR, run your own mental vibe check on your changes:
- Does this align with the metacognitive purpose of Vibe Check?
- Is this addressing a real problem that AI agents face?
- Does this maintain the balance between developer-friendly vibes and serious AI alignment principles?
## What We're Looking For
### Code Contributions
- Bug fixes
- Performance improvements
- New features that align with the project's purpose
- Improvements to the metacognitive questioning system
### Documentation Contributions
- Clarifications to existing documentation
- New examples of how to use Vibe Check effectively
- Case studies of how Vibe Check has helped your agent workflows
- Tutorials for integration with different systems
### Pattern Contributions
- New categories for the `vibe_learn` system
- Common error patterns you've observed in AI agent workflows
- Metacognitive questions that effectively break pattern inertia
## Coding Style
- TypeScript with clear typing
- Descriptive variable names
- Comments that explain the "why," not just the "what"
- Tests for new functionality
## The Review Process
Once you submit a PR, here's what happens:
1. A maintainer will review your submission
2. They might suggest some changes or improvements
3. Once everything looks good, they'll merge your PR
4. Your contribution becomes part of Vibe Check!
## Share Your Vibe Stories
We love hearing how people are using Vibe Check in the wild. If you have a story about how Vibe Check saved your agent from a catastrophic reasoning failure or helped simplify an overcomplicated plan, we'd love to hear about it! Submit it as an issue with the tag "vibe story" or mention it in your PR.
## Code of Conduct
- Be respectful and constructive in all interactions
- Focus on the code, not the person
- Help create a welcoming community for all contributors
## Questions?
If you have any questions about contributing, feel free to open an issue with your question. We're here to help!
Thanks again for considering a contribution to Vibe Check. Together, we can make AI agents a little more self-aware, one pattern interrupt at a time.
```
--------------------------------------------------------------------------------
/Attachments/Template.md:
--------------------------------------------------------------------------------
```markdown
Template
```
--------------------------------------------------------------------------------
/src/tools/vibeDistil.ts:
--------------------------------------------------------------------------------
```typescript
// Deleted
```
--------------------------------------------------------------------------------
/glama.json:
--------------------------------------------------------------------------------
```json
{
"$schema": "https://glama.ai/mcp/schemas/server.json",
"maintainers": [
"PV-Bhat"
]
}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
FROM node:lts-alpine
WORKDIR /app
COPY . .
RUN npm install --ignore-scripts
RUN npm run build
EXPOSE 3000
CMD ["node", "build/index.js"]
```
--------------------------------------------------------------------------------
/docs/_toc.md:
--------------------------------------------------------------------------------
```markdown
# Documentation map
- [Architecture](./architecture.md)
- Integrations
- [CPI Integration](./integrations/cpi.md)
- [Advanced Integration](./advanced-integration.md)
- [Technical Reference](./technical-reference.md)
- [Agent Prompting](./agent-prompting.md)
```
--------------------------------------------------------------------------------
/.github/workflows/docker-image.yml:
--------------------------------------------------------------------------------
```yaml
name: Docker Image CI
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build the Docker image
run: docker build . --file Dockerfile --tag my-image-name:$(date +%s)
```
--------------------------------------------------------------------------------
/request.json:
--------------------------------------------------------------------------------
```json
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"vibe_check","arguments":{"goal":"Test session history functionality","plan":"2. Make a second call to verify history is included.","userPrompt":"Please test the history feature.","progress":"Just made the second call.","sessionId":"history-test-session-1"}},"id":2}
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"esModuleInterop": true,
"outDir": "build",
"strict": true,
"declaration": false,
"sourceMap": false,
"types": [
"node",
"vitest/globals"
]
},
"include": [
"src/**/*",
"tests/**/*"
],
"exclude": [
"node_modules",
"**/*.test.ts"
]
}
```
--------------------------------------------------------------------------------
/alt-test-gemini.js:
--------------------------------------------------------------------------------
```javascript
import fs from 'fs';
const request = JSON.stringify({
jsonrpc: '2.0',
method: 'tools/call',
params: {
name: 'vibe_check',
arguments: {
goal: 'Test default Gemini provider',
plan: '2. Make a call to vibe_check using the default Gemini provider.',
}
},
id: 2
});
fs.writeFileSync('request.json', request, 'utf-8');
console.log('Generated request.json for the Gemini test.');
```
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
```yaml
name: CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm run build
- run: npm run test:coverage
- name: Report Vitest Coverage
uses: davelosert/vitest-coverage-report-action@v2
- name: Security Scan
run: npm run security-check
```
--------------------------------------------------------------------------------
/test.json:
--------------------------------------------------------------------------------
```json
{"id":"1","jsonrpc":"2.0","method":"tools/call","params":{"name":"vibe_check","arguments":{"goal":"Implement the core logic for the new feature","plan":"1. Define the data structures. 2. Implement the main algorithm. 3. Add error handling.","userPrompt":"Create a new feature that does X, Y, and Z.","progress":"Just started","uncertainties":["The third-party API might be unreliable"],"taskContext":"This is part of a larger project to refactor the billing module.","sessionId":"test-session-123"}}}
```
--------------------------------------------------------------------------------
/vitest.config.ts:
--------------------------------------------------------------------------------
```typescript
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
environment: 'node',
globals: true,
include: ['tests/**/*.test.ts'],
coverage: {
provider: 'v8',
reporter: ['text', 'html', 'json-summary'],
all: true,
include: ['src/**/*.ts'],
exclude: ['**/alt-test*.js', 'test-client.*', 'src/index.ts', 'src/tools/vibeDistil.ts', 'src/tools/vibeLearn.ts', 'src/utils/storage.ts', 'src/utils/llm.ts'],
thresholds: { lines: 80 }
}
}
});
```
--------------------------------------------------------------------------------
/alt-test-openai.js:
--------------------------------------------------------------------------------
```javascript
import fs from 'fs';
const request = JSON.stringify({
jsonrpc: '2.0',
method: 'tools/call',
params: {
name: 'vibe_check',
arguments: {
goal: 'Test OpenAI provider',
plan: '1. Make a call to vibe_check using the OpenAI provider.',
modelOverride: {
provider: 'openai',
model: 'o4-mini'
}
}
},
id: 1
});
fs.writeFileSync('request.json', request, 'utf-8');
console.log('Generated request.json for the OpenAI test.');
```
--------------------------------------------------------------------------------
/docs/registry-descriptions.md:
--------------------------------------------------------------------------------
```markdown
# Registry Descriptions
These short descriptions can be used when submitting VibeCheck MCP to external registries or directories.
## Smithery.ai
```
Metacognitive oversight MCP server for AI agents – adaptive CPI interrupts for alignment and safety.
```
## Glama Directory
```
Metacognitive layer for Llama-compatible agents via MCP. Enhances reflection, accountability and robustness.
```
## Awesome MCP Lists PR Draft
```
- [VibeCheck MCP](https://github.com/PV-Bhat/vibe-check-mcp-server) - Adaptive sanity check server preventing cascading errors in AI agents.
```
```
--------------------------------------------------------------------------------
/test-client.ts:
--------------------------------------------------------------------------------
```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';
async function testVibeCheck() {
const serverProcess = spawn('node', ['build/index.js'], { stdio: ['pipe', 'pipe', 'pipe'] });
await new Promise(resolve => setTimeout(resolve, 1000));
const transport = new StdioClientTransport(serverProcess);
const client = new Client(transport);
const response = await client.tool('vibe_check', { goal: 'Test goal', plan: 'Test plan', progress: 'Initial stage' });
console.log('Response:', response);
await transport.close();
serverProcess.kill();
}
testVibeCheck();
```
--------------------------------------------------------------------------------
/docs/changelog.md:
--------------------------------------------------------------------------------
```markdown
# Changelog
## v2.5.0 — 2025-09-03
- Transport: migrate STDIO → Streamable HTTP (`POST /mcp`, `GET /mcp` → 405).
- Constitution tools: `update_constitution`, `reset_constitution`, `check_constitution` (session-scoped, in-memory, logged).
- CPI surfaced: banner + concise metrics; links to ResearchGate, CPI GitHub, and Zenodo (MURST).
## v2.2.0 - 2025-07-22
- CPI architecture enables adaptive interrupts to mitigate Reasoning Lock-In
- History continuity across sessions
- Multi-provider support for Gemini, OpenAI and OpenRouter
- Optional vibe_learn logging for privacy-conscious deployments
- Repository restructured with Vitest unit tests and CI workflow
## v1.1.0 - 2024-06-10
- Initial feedback loop and Docker setup
```
--------------------------------------------------------------------------------
/tests/constitution.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect } from 'vitest';
import { updateConstitution, resetConstitution, getConstitution, __testing } from '../src/tools/constitution.js';
describe('constitution utilities', () => {
it('updates, resets, and retrieves rules', () => {
updateConstitution('s1', 'r1');
updateConstitution('s1', 'r2');
expect(getConstitution('s1')).toEqual(['r1', 'r2']);
resetConstitution('s1', ['a']);
expect(getConstitution('s1')).toEqual(['a']);
});
it('cleans up stale sessions', () => {
updateConstitution('s2', 'rule');
const map = __testing._getMap();
map['s2'].updated = Date.now() - 2 * 60 * 60 * 1000;
__testing.cleanup();
expect(getConstitution('s2')).toEqual([]);
});
});
```
--------------------------------------------------------------------------------
/server.json:
--------------------------------------------------------------------------------
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.github.PV-Bhat/vibe-check-mcp-server",
"description": "Metacognitive AI agent oversight: adaptive CPI interrupts for alignment, reflection and safety",
"status": "active",
"repository": {
"url": "https://github.com/PV-Bhat/vibe-check-mcp-server",
"source": "github"
},
"version": "1.0.0",
"packages": [
{
"registry_type": "npm",
"identifier": "@pv-bhat/vibe-check-mcp",
"version": "2.5.1",
"transport": {
"type": "stdio"
},
"environment_variables": [
{
"description": "Your API key for the service",
"is_required": true,
"format": "string",
"is_secret": true,
"name": "YOUR_API_KEY"
}
]
}
]
}
```
--------------------------------------------------------------------------------
/.github/workflows/npm-publish-github-packages.yml:
--------------------------------------------------------------------------------
```yaml
# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
name: Node.js Package
on:
release:
types: [created]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm test
publish-gpr:
needs: build
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
registry-url: https://npm.pkg.github.com/
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
```
--------------------------------------------------------------------------------
/test-client.js:
--------------------------------------------------------------------------------
```javascript
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
async function main() {
const transport = new StdioClientTransport({ command: 'node', args: ['build/index.js'] });
const client = new Client({ transport });
const request = {
name: 'vibe_check',
arguments: {
goal: 'Implement the core logic for the new feature',
plan: '1. Define the data structures. 2. Implement the main algorithm. 3. Add error handling.',
userPrompt: 'Create a new feature that does X, Y, and Z.',
progress: 'Just started',
uncertainties: ['The third-party API might be unreliable'],
taskContext: 'This is part of a larger project to refactor the billing module.',
sessionId: 'test-session-123',
},
};
try {
await client.connect();
const response = await client.callTool(request.name, request.arguments);
console.log(JSON.stringify(response, null, 2));
} catch (error) {
console.error(error);
} finally {
transport.destroy();
}
}
main();
```
--------------------------------------------------------------------------------
/test.js:
--------------------------------------------------------------------------------
```javascript
import { spawn } from 'child_process';const server = spawn('node', ['build/index.js']);const request = { id: '1', jsonrpc: '2.0', method: 'tools/call', params: { name: 'vibe_check', arguments: { goal: 'Implement the core logic for the new feature', plan: '1. Define the data structures. 2. Implement the main algorithm. 3. Add error handling.', userPrompt: 'Create a new feature that does X, Y, and Z.', progress: 'Just started', uncertainties: ['The third-party API might be unreliable'], taskContext: 'This is part of a larger project to refactor the billing module.', sessionId: 'test-session-123', }, },};const message = JSON.stringify(request);const length = Buffer.byteLength(message, 'utf-8');const header = `Content-Length: ${length}\r\n\r\n`;server.stdout.on('data', (data) => { console.log(`${data}`);});server.stderr.on('data', (data) => { console.error(`stderr: ${data}`);});server.on('close', (code) => { console.log(`child process exited with code ${code}`);});server.stdin.write(header);server.stdin.write(message);server.stdin.end();
```
--------------------------------------------------------------------------------
/tests/state.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, beforeEach, vi } from 'vitest';
import * as fs from 'fs/promises';
import { loadHistory, getHistorySummary, addToHistory } from '../src/utils/state.js';
vi.mock('fs/promises');
const mockedFs = fs as unknown as { readFile: ReturnType<typeof vi.fn>; writeFile: ReturnType<typeof vi.fn>; mkdir: ReturnType<typeof vi.fn>; };
beforeEach(async () => {
vi.clearAllMocks();
mockedFs.mkdir = vi.fn();
mockedFs.readFile = vi.fn().mockResolvedValue('{}');
mockedFs.writeFile = vi.fn();
await loadHistory();
});
describe('state history', () => {
it('initializes empty history if none', async () => {
mockedFs.readFile.mockRejectedValue(new Error('missing'));
await loadHistory();
expect(getHistorySummary('none')).toBe('');
});
it('adds to history and trims to 10', async () => {
mockedFs.readFile.mockRejectedValue(new Error('missing'));
await loadHistory();
for (let i = 1; i <= 11; i++) {
addToHistory('sess', { goal: `g${i}`, plan: `p${i}` }, `o${i}`);
}
await Promise.resolve();
const summary = getHistorySummary('sess');
expect(summary).toContain('g7');
expect(summary).not.toContain('g2');
});
});
```
--------------------------------------------------------------------------------
/tests/vibeLearn.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { vibeLearnTool } from '../src/tools/vibeLearn.js';
import * as storage from '../src/utils/storage.js';
vi.mock('../src/utils/storage.js');
const mockedStorage = storage as unknown as {
addLearningEntry: ReturnType<typeof vi.fn>;
getLearningCategorySummary: ReturnType<typeof vi.fn>;
getLearningEntries: ReturnType<typeof vi.fn>;
};
beforeEach(() => {
vi.clearAllMocks();
mockedStorage.addLearningEntry = vi.fn(() => ({
type: 'mistake',
category: 'Test',
mistake: 'm',
solution: 's',
timestamp: Date.now()
}));
mockedStorage.getLearningEntries = vi.fn(() => ({ Test: [] }));
mockedStorage.getLearningCategorySummary = vi.fn(() => [{ category: 'Test', count: 1, recentExample: { mistake: 'm', solution: 's', type: 'mistake', timestamp: Date.now() } }]);
});
describe('vibeLearnTool', () => {
it('logs entry and returns summary', async () => {
const res = await vibeLearnTool({ mistake: 'm', category: 'Test', solution: 's' });
expect(res.added).toBe(true);
expect(mockedStorage.addLearningEntry).toHaveBeenCalled();
expect(res.topCategories[0].category).toBe('Test');
});
});
```
--------------------------------------------------------------------------------
/docs/docker-automation.md:
--------------------------------------------------------------------------------
```markdown
# Automatic Docker Setup
This guide shows how to run the Vibe Check MCP server in Docker and configure it to start automatically with Cursor.
## Prerequisites
- Docker and Docker Compose installed and available in your `PATH`.
- A Gemini API key for the server.
## Quick Start
Run the provided setup script from the repository root:
```bash
bash scripts/docker-setup.sh
```
The script performs the following actions:
1. Creates `~/vibe-check-mcp` and copies required files.
2. Builds the Docker image and sets up `docker-compose.yml`.
3. Prompts for your `GEMINI_API_KEY` and stores it in `~/vibe-check-mcp/.env`.
4. Configures a systemd service on Linux or a LaunchAgent on macOS so the container starts on login.
5. Generates `vibe-check-tcp-wrapper.sh` which proxies STDIO to the container on port 3000.
6. Starts the container in the background.
After running the script, configure Cursor IDE:
1. Open **Settings** → **MCP**.
2. Choose **Add New MCP Server**.
3. Set the type to **Command** and use the wrapper script path:
`~/vibe-check-mcp/vibe-check-tcp-wrapper.sh`.
4. Save and refresh.
Vibe Check MCP will now launch automatically whenever you log in and be available to Cursor without additional manual steps.
```
--------------------------------------------------------------------------------
/docs/gemini.md:
--------------------------------------------------------------------------------
```markdown
# Agent Quickstart
Vibe Check MCP is a lightweight oversight layer for AI agents. It exposes two tools:
- **vibe_check** – prompts you with clarifying questions to prevent tunnel vision.
- **vibe_learn** – optional logging of mistakes and successes for later review.
The server supports Gemini, OpenAI and OpenRouter LLMs. History is maintained across requests when a `sessionId` is provided.
## Setup
1. Install dependencies and build:
```bash
npm install
npm run build
```
2. Supply the following environment variables as needed:
- `GEMINI_API_KEY`
- `OPENAI_API_KEY`
- `OPENROUTER_API_KEY`
- `DEFAULT_LLM_PROVIDER` (gemini | openai | openrouter)
- `DEFAULT_MODEL` (e.g., gemini-2.5-pro)
3. Start the server:
```bash
npm start
```
## Testing
Run unit tests with `npm test`. Example request generators are provided:
- `alt-test-gemini.js`
- `alt-test-openai.js`
- `alt-test.js` (OpenRouter)
Each script writes a `request.json` file that you can pipe to the server:
```bash
node build/index.js < request.json
```
## Integration Tips
Call `vibe_check` regularly with your goal, plan and current progress. Use `vibe_learn` whenever you want to record a resolved issue. Full API details are in `docs/technical-reference.md`.
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
# Metadata for discoverability and registry listing
name: vibe-check-mcp
version: 2.5.0
description: Metacognitive AI agent oversight tool implementing CPI-driven interrupts for alignment and safety.
author: PV-Bhat
repository: https://github.com/PV-Bhat/vibe-check-mcp-server
license: MIT
category: ai-tools
tags:
- cpi chain pattern interrupts
- pruthvi bhat
- rli reasoning lock in
- murst
- metacognition
- workflow-optimization
- gemini
- openai
- openrouter
capabilities:
- meta-mentorship
- agentic oversight
- chain pattern-interrupt
- vibe-check
- self-improving-feedback
- multi-provider-llm
# Requirements (e.g., for local setup)
requirements:
node: ">=18.0.0"
# Installation options
installation:
npm: "@mseep/vibe-check-mcp" # For manual npm install
startCommand:
type: http
command: node build/index.js
env:
MCP_HTTP_PORT: "3000"
MCP_DISCOVERY_MODE: "1"
http:
endpoint: "/mcp"
cors:
origin: "${CORS_ORIGIN:-*}"
# Documentation links
documentation:
getting_started: https://github.com/PV-Bhat/vibe-check-mcp-server#installation
configuration: https://github.com/PV-Bhat/vibe-check-mcp-server#configuration
technical_reference: https://github.com/PV-Bhat/vibe-check-mcp-server/blob/main/docs/technical-reference.md
```
--------------------------------------------------------------------------------
/src/tools/constitution.ts:
--------------------------------------------------------------------------------
```typescript
interface ConstitutionEntry {
rules: string[];
updated: number;
}
const constitutionMap: Record<string, ConstitutionEntry> = Object.create(null);
const MAX_RULES_PER_SESSION = 50;
const SESSION_TTL_MS = 60 * 60 * 1000; // 1 hour
export function updateConstitution(sessionId: string, rule: string) {
if (!sessionId || !rule) return;
const entry = constitutionMap[sessionId] || { rules: [], updated: 0 };
if (entry.rules.length >= MAX_RULES_PER_SESSION) entry.rules.shift();
entry.rules.push(rule);
entry.updated = Date.now();
constitutionMap[sessionId] = entry;
}
export function resetConstitution(sessionId: string, rules: string[]) {
if (!sessionId || !Array.isArray(rules)) return;
constitutionMap[sessionId] = {
rules: rules.slice(0, MAX_RULES_PER_SESSION),
updated: Date.now()
};
}
export function getConstitution(sessionId: string): string[] {
const entry = constitutionMap[sessionId];
if (!entry) return [];
entry.updated = Date.now();
return entry.rules;
}
// Cleanup stale sessions to prevent unbounded memory growth
function cleanup() {
const now = Date.now();
for (const [sessionId, entry] of Object.entries(constitutionMap)) {
if (now - entry.updated > SESSION_TTL_MS) {
delete constitutionMap[sessionId];
}
}
}
setInterval(cleanup, SESSION_TTL_MS).unref();
export const __testing = {
_getMap: () => constitutionMap,
cleanup
};
```
--------------------------------------------------------------------------------
/alt-test.js:
--------------------------------------------------------------------------------
```javascript
import fs from 'fs';
function createVibeCheckRequest(id, goal, plan, userPrompt, progress, sessionId) {
return JSON.stringify({
jsonrpc: '2.0',
method: 'tools/call',
params: {
name: 'vibe_check',
arguments: {
goal: goal,
plan: plan,
userPrompt: userPrompt,
progress: progress,
sessionId: sessionId,
modelOverride: {
provider: 'openrouter',
model: 'tngtech/deepseek-r1t2-chimera:free'
}
}
},
id: id
});
}
const sessionId = 'history-test-session-phase4';
// First call
const request1 = createVibeCheckRequest(
1,
'Test new meta-mentor prompt and history functionality',
'1. Make the first call to establish history.',
'Please test the new meta-mentor prompt and history feature.',
'Starting the test.',
sessionId
);
fs.writeFileSync('request1.json', request1, 'utf-8');
console.log('Generated request1.json for the first call.');
// Second call
const request2 = createVibeCheckRequest(
2,
'Test new meta-mentor prompt and history functionality',
'2. Make the second call to verify history is included and prompt tone.',
'Please test the new meta-mentor prompt and history feature.',
'Just made the second call, expecting history context.',
sessionId
);
fs.writeFileSync('request2.json', request2, 'utf-8');
console.log('Generated request2.json for the second call.');
```
--------------------------------------------------------------------------------
/docs/TESTING.md:
--------------------------------------------------------------------------------
```markdown
# Testing Guide
Due to a bug in the `@modelcontextprotocol/sdk` client, the standard `test-client.js` script will not work. Use the alternative test scripts to generate JSON requests and pipe them to the server's standard input.
## Running Tests
1. **Build the server:**
```bash
npm run build
```
2. **Generate the requests:**
Three helper scripts create example requests for each provider.
- `alt-test.js` (OpenRouter) writes `request1.json` and `request2.json` for history testing.
- `alt-test-openai.js` generates `request.json` targeting the OpenAI provider.
- `alt-test-gemini.js` generates `request.json` using the default Gemini provider.
```bash
node alt-test.js # OpenRouter history test
node alt-test-openai.js # OpenAI example
node alt-test-gemini.js # Gemini example
```
3. **Run the server with the requests:**
Pipe the contents of each generated file to the server.
**History test (OpenRouter):**
```bash
node build/index.js < request1.json
node build/index.js < request2.json
```
**Single provider examples:**
```bash
node build/index.js < request.json # created by alt-test-openai.js or alt-test-gemini.js
```
The server will process the requests and print the responses to standard output. The second OpenRouter call should show that the previous history was considered.
## Unit Tests with Vitest
Vitest is used for unit and integration tests. Run all tests with:
```bash
npm test
```
Generate a coverage report (outputs to `coverage/`):
```bash
npm run test:coverage
```
All tests should pass with at least 80% line coverage.
```
--------------------------------------------------------------------------------
/src/utils/state.ts:
--------------------------------------------------------------------------------
```typescript
import fs from 'fs/promises';
import path from 'path';
import os from 'os';
import { VibeCheckInput } from '../tools/vibeCheck.js';
const DATA_DIR = path.join(os.homedir(), '.vibe-check');
const HISTORY_FILE = path.join(DATA_DIR, 'history.json');
interface Interaction {
input: VibeCheckInput;
output: string;
timestamp: number;
}
let history: Map<string, Interaction[]> = new Map();
async function ensureDataDir() {
try {
await fs.mkdir(DATA_DIR, { recursive: true });
} catch {}
}
export async function loadHistory() {
await ensureDataDir();
try {
const data = await fs.readFile(HISTORY_FILE, 'utf-8');
const parsed = JSON.parse(data);
history = new Map(Object.entries(parsed).map(([k, v]) => [k, v as Interaction[]]));
} catch {
history.set('default', []);
}
}
async function saveHistory() {
const data = Object.fromEntries(history);
await fs.writeFile(HISTORY_FILE, JSON.stringify(data));
}
export function getHistorySummary(sessionId = 'default'): string {
const sessHistory = history.get(sessionId) || [];
if (!sessHistory.length) return '';
const summary = sessHistory.slice(-5).map((int, i) => `Interaction ${i+1}: Goal ${int.input.goal}, Guidance: ${int.output.slice(0, 100)}...`).join('\n');
return `History Context:\n${summary}\n`;
}
export function addToHistory(sessionId = 'default', input: VibeCheckInput, output: string) {
if (!history.has(sessionId)) {
history.set(sessionId, []);
}
const sessHistory = history.get(sessionId)!;
sessHistory.push({ input, output, timestamp: Date.now() });
if (sessHistory.length > 10) {
sessHistory.shift();
}
saveHistory();
}
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "@pv-bhat/vibe-check-mcp",
"mcpName": "io.github.PV-Bhat/vibe-check-mcp-server",
"version": "2.5.1",
"description": "Metacognitive AI agent oversight: adaptive CPI interrupts for alignment, reflection and safety",
"main": "build/index.js",
"type": "module",
"files": [
"build"
],
"scripts": {
"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
"prepare": "npm run build",
"start": "node build/index.js",
"dev": "tsc-watch --onSuccess \"node build/index.js\"",
"test": "vitest run",
"test:coverage": "vitest run --coverage",
"security-check": "node scripts/security-check.cjs"
},
"dependencies": {
"@google/generative-ai": "^0.17.1",
"@modelcontextprotocol/sdk": "^1.16.0",
"axios": "^1.12.2",
"body-parser": "^1.20.2",
"cors": "^2.8.5",
"dotenv": "^16.4.7",
"express": "^4.19.2",
"openai": "^4.68.1"
},
"devDependencies": {
"@types/cors": "^2.8.17",
"@types/express": "^4.17.21",
"@types/node": "^20.17.25",
"@vitest/coverage-v8": "^3.2.4",
"tsc-watch": "^6.0.0",
"typescript": "^5.3.0",
"vitest": "^3.2.4"
},
"engines": {
"node": ">=18.0.0"
},
"keywords": [
"mcp",
"mcp-server",
"vibe-check",
"vibe-coding",
"metacognition",
"ai-alignment",
"llm-agents",
"autonomous-agents",
"reflection",
"agent-oversight",
"ai-safety",
"prompt-engineering"
],
"author": "PV Bhat",
"repository": {
"type": "git",
"url": "https://github.com/PV-Bhat/vibe-check-mcp-server.git"
},
"bugs": {
"url": "https://github.com/PV-Bhat/vibe-check-mcp-server/issues"
},
"homepage": "https://github.com/PV-Bhat/vibe-check-mcp-server#readme",
"license": "MIT"
}
```
--------------------------------------------------------------------------------
/scripts/security-check.cjs:
--------------------------------------------------------------------------------
```
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');
function runAudit() {
try {
const output = execSync('npm audit --production --json', { encoding: 'utf8' });
const json = JSON.parse(output);
const vulnerabilities = json.vulnerabilities || {};
let highOrCritical = 0;
for (const name of Object.keys(vulnerabilities)) {
const v = vulnerabilities[name];
if (['high', 'critical'].includes(v.severity)) {
console.error(`High severity issue in dependency: ${name}`);
highOrCritical++;
}
}
if (highOrCritical > 0) {
console.error(`Found ${highOrCritical} high or critical vulnerabilities`);
process.exitCode = 1;
} else {
console.log('Dependency audit clean');
}
} catch (err) {
console.error('npm audit failed', err.message);
process.exitCode = 1;
}
}
function scanSource() {
const suspiciousPatterns = [/eval\s*\(/, /child_process/, /exec\s*\(/, /spawn\s*\(/];
let flagged = false;
function scanDir(dir) {
for (const file of fs.readdirSync(dir)) {
const full = path.join(dir, file);
const stat = fs.statSync(full);
if (stat.isDirectory()) {
scanDir(full);
} else if ((full.endsWith('.ts') || full.endsWith('.js')) && !full.includes('scripts/security-check.js')) {
const content = fs.readFileSync(full, 'utf8');
for (const pattern of suspiciousPatterns) {
if (pattern.test(content)) {
console.error(`Suspicious pattern ${pattern} found in ${full}`);
flagged = true;
}
}
}
}
}
scanDir('src');
if (flagged) {
process.exitCode = 1;
} else {
console.log('Source scan clean');
}
}
runAudit();
scanSource();
```
--------------------------------------------------------------------------------
/tests/vibeCheck.test.ts:
--------------------------------------------------------------------------------
```typescript
import { vi, describe, it, expect, beforeEach } from 'vitest';
import { vibeCheckTool } from '../src/tools/vibeCheck.js';
import * as llm from '../src/utils/llm.js';
import * as state from '../src/utils/state.js';
vi.mock('../src/utils/llm.js');
vi.mock('../src/utils/state.js');
const mockedLLM = llm as unknown as { getMetacognitiveQuestions: ReturnType<typeof vi.fn> };
const mockedState = state as unknown as {
addToHistory: ReturnType<typeof vi.fn>;
getHistorySummary: ReturnType<typeof vi.fn>;
};
beforeEach(() => {
vi.clearAllMocks();
mockedState.getHistorySummary = vi.fn().mockReturnValue('Mock history');
mockedState.addToHistory = vi.fn();
mockedLLM.getMetacognitiveQuestions = vi.fn().mockResolvedValue({ questions: 'Mock guidance' });
});
describe('vibeCheckTool', () => {
it('returns questions from llm', async () => {
const result = await vibeCheckTool({ goal: 'Test goal', plan: 'Test plan' });
expect(result.questions).toBe('Mock guidance');
expect(mockedLLM.getMetacognitiveQuestions).toHaveBeenCalledWith(
expect.objectContaining({ goal: 'Test goal', plan: 'Test plan', historySummary: 'Mock history' })
);
});
it('passes model override to llm', async () => {
await vibeCheckTool({ goal: 'g', plan: 'p', modelOverride: { provider: 'openai' } });
expect(mockedLLM.getMetacognitiveQuestions).toHaveBeenCalledWith(
expect.objectContaining({ modelOverride: { provider: 'openai' } })
);
});
it('adds to history on each call', async () => {
await vibeCheckTool({ goal: 'A', plan: 'B', sessionId: 's1' });
await vibeCheckTool({ goal: 'C', plan: 'D', sessionId: 's1' });
expect(mockedState.addToHistory).toHaveBeenCalledTimes(2);
});
it('falls back to default questions when llm fails', async () => {
mockedLLM.getMetacognitiveQuestions = vi.fn().mockRejectedValue(new Error('fail'));
const result = await vibeCheckTool({ goal: 'x', plan: 'y' });
expect(result.questions).toContain('Does this plan directly address');
});
});
```
--------------------------------------------------------------------------------
/src/tools/vibeCheck.ts:
--------------------------------------------------------------------------------
```typescript
import { getMetacognitiveQuestions } from '../utils/llm.js';
import { addToHistory, getHistorySummary } from '../utils/state.js';
// Vibe Check tool handler
export interface VibeCheckInput {
goal: string;
plan: string;
modelOverride?: {
provider?: string;
model?: string;
};
userPrompt?: string;
progress?: string;
uncertainties?: string[];
taskContext?: string;
sessionId?: string;
}
export interface VibeCheckOutput {
questions: string;
}
/**
* Adaptive CPI interrupt for AI agent alignment and reflection.
* Monitors progress and questions assumptions to mitigate Reasoning Lock-In.
* The userRequest parameter MUST contain the full original request for safety.
*/
export async function vibeCheckTool(input: VibeCheckInput): Promise<VibeCheckOutput> {
console.log('[vibe_check] called', { hasSession: Boolean(input.sessionId) });
try {
// Get history summary
const historySummary = getHistorySummary(input.sessionId);
// Get metacognitive questions from Gemini with dynamic parameters
const response = await getMetacognitiveQuestions({
goal: input.goal,
plan: input.plan,
modelOverride: input.modelOverride,
userPrompt: input.userPrompt,
progress: input.progress,
uncertainties: input.uncertainties,
taskContext: input.taskContext,
sessionId: input.sessionId,
historySummary,
});
// Add to history
addToHistory(input.sessionId, input, response.questions);
return {
questions: response.questions,
};
} catch (error) {
console.error('Error in vibe_check tool:', error);
// Fallback to basic questions if there's an error
return {
questions: generateFallbackQuestions(input.userPrompt || "", input.plan || ""),
};
}
}
/**
* Generate adaptive fallback questions when API fails
*/
function generateFallbackQuestions(userRequest: string, plan: string): string {
return `
I can see you're thinking through your approach, which shows thoughtfulness:
1. Does this plan directly address what the user requested, or might it be solving a different problem?
2. Is there a simpler approach that would meet the user's needs?
3. What unstated assumptions might be limiting the thinking here?
4. How does this align with the user's original intent?
`;
}
```
--------------------------------------------------------------------------------
/tests/llm.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect, beforeEach, vi } from 'vitest';
import axios from 'axios';
import { generateResponse, __testing } from '../src/utils/llm.js';
vi.mock('axios');
const mockedAxios = axios as unknown as { post: ReturnType<typeof vi.fn> };
beforeEach(() => {
vi.clearAllMocks();
__testing.setGenAI({
getGenerativeModel: vi.fn(() => ({
generateContent: vi.fn(async () => ({ response: { text: () => 'gemini reply' } }))
}))
});
__testing.setOpenAIClient({
chat: { completions: { create: vi.fn(async () => ({ choices: [{ message: { content: 'openai reply' } }] })) } }
});
});
describe('generateResponse', () => {
it('uses gemini by default and builds prompt with context', async () => {
const res = await generateResponse({ goal: 'G', plan: 'P', uncertainties: ['u1'], historySummary: 'Hist' });
expect(res.questions).toBe('gemini reply');
const gen = __testing.getGenAI();
expect(gen.getGenerativeModel).toHaveBeenCalledWith({ model: 'gemini-2.5-pro' });
const prompt = gen.getGenerativeModel.mock.results[0].value.generateContent.mock.calls[0][0];
expect(prompt).toContain('History Context: Hist');
expect(prompt).toContain('u1');
});
it('uses openai when overridden', async () => {
const openai = __testing.getOpenAIClient();
const res = await generateResponse({ goal: 'g', plan: 'p', modelOverride: { provider: 'openai', model: 'o1-mini' } });
expect(res.questions).toBe('openai reply');
expect(openai.chat.completions.create).toHaveBeenCalledWith({ model: 'o1-mini', messages: [{ role: 'system', content: expect.any(String) }] });
});
it('throws if openrouter key missing', async () => {
await expect(generateResponse({ goal: 'g', plan: 'p', modelOverride: { provider: 'openrouter', model: 'm1' } })).rejects.toThrow('OpenRouter API key');
});
it('calls openrouter when configured', async () => {
process.env.OPENROUTER_API_KEY = 'key';
mockedAxios.post = vi.fn(async () => ({ data: { choices: [{ message: { content: 'router reply' } }] } }));
const res = await generateResponse({ goal: 'g', plan: 'p', modelOverride: { provider: 'openrouter', model: 'm1' } });
expect(res.questions).toBe('router reply');
expect(mockedAxios.post).toHaveBeenCalled();
delete process.env.OPENROUTER_API_KEY;
});
});
```
--------------------------------------------------------------------------------
/examples/cpi-integration.ts:
--------------------------------------------------------------------------------
```typescript
/**
* Example CPI integration stub for VibeCheck MCP.
*
* Wire this into your agent orchestrator to forward VibeCheck signals to a CPI policy.
*/
export interface AgentSnapshot {
sessionId: string;
summary: string;
nextAction: string;
done?: boolean;
}
export interface ResumeSignal {
reason: string;
followUp?: string;
}
export interface AgentStepCallback {
(input: { resumeSignal?: ResumeSignal }): Promise<AgentSnapshot>;
}
export interface VibeCheckSignal {
riskScore: number;
traits: string[];
advice: string;
}
const RISK_THRESHOLD = 0.6;
const vibecheckShim = {
// TODO: replace with an actual call to the VibeCheck MCP tool over MCP or HTTP.
async analyze(snapshot: AgentSnapshot): Promise<VibeCheckSignal> {
return {
riskScore: Math.random(),
traits: ['focus-drift'],
advice: `Reflect on: ${snapshot.summary}`,
};
},
};
// TODO: replace with `import { createPolicy } from '@cpi/sdk';`
const cpiPolicyShim = {
interrupt(input: { snapshot: AgentSnapshot; signal: VibeCheckSignal }) {
if (input.signal.riskScore >= RISK_THRESHOLD) {
return {
action: 'interrupt' as const,
reason: 'High metacognitive risk detected by VibeCheck',
};
}
return { action: 'allow' as const };
},
};
async function handleInterrupt(
decision: { action: 'interrupt' | 'allow'; reason?: string },
snapshot: AgentSnapshot,
): Promise<ResumeSignal | undefined> {
if (decision.action === 'allow') {
return undefined;
}
console.warn('[CPI] interrupting agent step:', decision.reason ?? 'policy requested pause');
console.warn('Agent summary:', snapshot.summary);
// TODO: replace with human-in-the-loop logic or CPI repro harness callback.
return {
reason: decision.reason ?? 'Paused for inspection',
followUp: 'Agent acknowledged CPI feedback and is ready to resume.',
};
}
export async function runWithCPI(agentStep: AgentStepCallback): Promise<void> {
let resumeSignal: ResumeSignal | undefined;
while (true) {
const snapshot = await agentStep({ resumeSignal });
if (snapshot.done) {
console.log('Agent workflow completed.');
break;
}
const signal = await vibecheckShim.analyze(snapshot);
console.log('VibeCheck signal', signal);
const decision = cpiPolicyShim.interrupt({ snapshot, signal });
if (decision.action !== 'allow') {
resumeSignal = await handleInterrupt(decision, snapshot);
continue;
}
resumeSignal = undefined;
}
}
```
--------------------------------------------------------------------------------
/scripts/install-vibe-check.sh:
--------------------------------------------------------------------------------
```bash
#!/bin/bash
echo "========================================================"
echo "Vibe Check MCP Server Installer for Cursor IDE (Mac/Linux)"
echo "========================================================"
echo ""
# Check for Node.js installation
if ! command -v node &> /dev/null; then
echo "Error: Node.js is not installed or not in PATH."
echo "Please install Node.js from https://nodejs.org/"
exit 1
fi
# Check for npm installation
if ! command -v npm &> /dev/null; then
echo "Error: npm is not installed or not in PATH."
echo "Please install Node.js from https://nodejs.org/"
exit 1
fi
# Detect OS
OS="$(uname -s)"
case "${OS}" in
Linux*) OS="Linux";;
Darwin*) OS="Mac";;
*) OS="Unknown";;
esac
if [ "$OS" = "Unknown" ]; then
echo "Error: Unsupported operating system. This script works on Mac and Linux only."
exit 1
fi
echo "Step 1: Installing vibe-check-mcp globally..."
npm install -g vibe-check-mcp
if [ $? -ne 0 ]; then
echo "Error: Failed to install vibe-check-mcp globally."
exit 1
fi
echo ""
echo "Step 2: Finding global npm installation path..."
NPM_GLOBAL=$(npm root -g)
VIBE_CHECK_PATH="$NPM_GLOBAL/vibe-check-mcp/build/index.js"
if [ ! -f "$VIBE_CHECK_PATH" ]; then
echo "Error: Could not find vibe-check-mcp installation at $VIBE_CHECK_PATH"
exit 1
fi
echo "Found vibe-check-mcp at: $VIBE_CHECK_PATH"
echo ""
echo "Step 3: Enter your Gemini API key for vibe-check-mcp..."
read -p "Enter your Gemini API key: " GEMINI_API_KEY
# Create .env file in user's home directory
echo "Creating .env file for Gemini API key..."
ENV_FILE="$HOME/.vibe-check-mcp.env"
echo "GEMINI_API_KEY=$GEMINI_API_KEY" > "$ENV_FILE"
chmod 600 "$ENV_FILE" # Secure the API key file
# Create start script
START_SCRIPT="$HOME/start-vibe-check-mcp.sh"
cat > "$START_SCRIPT" << EOL
#!/bin/bash
source "$ENV_FILE"
exec node "$VIBE_CHECK_PATH"
EOL
chmod +x "$START_SCRIPT"
echo "Created startup script: $START_SCRIPT"
echo ""
echo "Step 4: Setting up Cursor IDE configuration..."
echo ""
echo "To complete setup, you need to configure Cursor IDE:"
echo ""
echo "1. Open Cursor IDE"
echo "2. Go to Settings (gear icon) -> MCP"
echo "3. Click \"Add New MCP Server\""
echo "4. Enter the following information:"
echo " - Name: Vibe Check"
echo " - Type: Command"
echo " - Command: env GEMINI_API_KEY=$GEMINI_API_KEY node \"$VIBE_CHECK_PATH\""
echo "5. Click \"Save\" and then \"Refresh\""
echo ""
echo "Installation complete!"
echo ""
echo "You can manually run it by executing: $START_SCRIPT"
echo ""
```
--------------------------------------------------------------------------------
/tests/startup.test.ts:
--------------------------------------------------------------------------------
```typescript
import { describe, it, expect } from 'vitest';
import { spawn } from 'child_process';
import { fileURLToPath } from 'url';
import path from 'path';
import net from 'net';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
async function runStartupTest(envVar: 'MCP_HTTP_PORT' | 'PORT' | 'BOTH') {
const startTime = Date.now();
const projectRoot = path.resolve(__dirname, '..');
const indexPath = path.join(projectRoot, 'build', 'index.js');
const getPort = () =>
new Promise<number>((resolve, reject) => {
const s = net.createServer();
s.listen(0, () => {
const p = (s.address() as any).port;
s.close(() => resolve(p));
});
s.on('error', reject);
});
const mainPort = await getPort();
const env: NodeJS.ProcessEnv = { ...process.env };
if (envVar === 'MCP_HTTP_PORT') {
env.MCP_HTTP_PORT = String(mainPort);
} else if (envVar === 'PORT') {
env.PORT = String(mainPort);
} else {
env.MCP_HTTP_PORT = String(mainPort);
const otherPort = await getPort();
env.PORT = String(otherPort);
}
const serverProcess = spawn('node', [indexPath], {
env,
stdio: ['ignore', 'pipe', 'pipe'],
});
try {
let res: Response | null = null;
for (let i = 0; i < 40; i++) {
try {
const attempt = await fetch(`http://localhost:${mainPort}/mcp`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json, text/event-stream'
},
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
});
if (attempt.status === 200) {
res = attempt;
break;
}
} catch {}
await new Promise((r) => setTimeout(r, 250));
}
if (!res) throw new Error('Server did not start');
const text = await res.text();
const line = text.split('\n').find((l) => l.startsWith('data: '));
const json = line ? JSON.parse(line.slice(6)) : null;
const duration = Date.now() - startTime;
expect(res.status).toBe(200);
expect(json?.result?.tools.some((t: any) => t.name === 'update_constitution')).toBe(true);
expect(duration).toBeLessThan(5000);
} finally {
serverProcess.kill();
}
}
describe('Server Startup and Response Time', () => {
it('should start and respond to a tools/list request over HTTP using MCP_HTTP_PORT', async () => {
await runStartupTest('MCP_HTTP_PORT');
}, 10000);
it('should start and respond to a tools/list request over HTTP using PORT', async () => {
await runStartupTest('PORT');
}, 10000);
it('should prefer MCP_HTTP_PORT when both MCP_HTTP_PORT and PORT are set', async () => {
await runStartupTest('BOTH');
}, 10000);
});
```
--------------------------------------------------------------------------------
/docs/integrations/cpi.md:
--------------------------------------------------------------------------------
```markdown
# CPI Integration
## Overview
> CPI (Chain-Pattern Interrupt): a runtime oversight mechanism for multi-agent systems that mitigates “reasoning lock-in.” It injects interrupts based on policy triggers (pattern detectors, heuristics, or external signals), then resumes or reroutes flow.
>
> Core pieces: (1) trigger evaluators, (2) intervention policy (allow/block/route/ask-human), (3) logging & repro harness.
>
> Status: repo includes repro evals; “constitution” tool supports per-session rule-sets.
>
> Integration intent with VibeCheck: VibeCheck = metacognitive layer (signals/traits/uncertainty). CPI = on-policy interrupter. VibeCheck feeds CPI triggers; CPI acts on them.
CPI composes with VibeCheck by acting as an on-policy interrupter whenever VibeCheck signals a risk spike. Use VibeCheck to surface agent traits, uncertainty, and risk levels, then forward that context to CPI so its policy engine can decide whether to allow, block, reroute, or escalate the next action. The example stub in [`examples/cpi-integration.ts`](../../examples/cpi-integration.ts) illustrates the plumbing you can copy into your own orchestrator.
## Flow diagram
```mermaid
flowchart LR
AgentStep[Agent step] -->|emit signals| VibeCheck
VibeCheck -->|risk + traits| CPI
CPI -->|policy decision| AgentController[Agent controller]
AgentController -->|resume/adjust| AgentStep
```
## Minimal integration sketch
Below is a minimal TypeScript sketch that mirrors the logic in the [`runWithCPI`](../../examples/cpi-integration.ts) example. Replace the TODO markers with the real CPI SDK import when it becomes available.
```ts
type AgentStep = {
sessionId: string;
summary: string;
nextAction: string;
};
type VibeCheckSignal = {
riskScore: number;
advice: string;
};
async function analyzeWithVibeCheck(step: AgentStep): Promise<VibeCheckSignal> {
// TODO: replace with a real call to the VibeCheck MCP server.
return { riskScore: Math.random(), advice: `Reflect on: ${step.summary}` };
}
// TODO: replace with `import { createPolicy } from '@cpi/sdk';`
function cpiPolicyShim(signal: VibeCheckSignal) {
if (signal.riskScore >= 0.6) {
return { action: 'interrupt', reason: 'High metacognitive risk from VibeCheck' } as const;
}
return { action: 'allow' } as const;
}
export async function evaluateStep(step: AgentStep) {
const signal = await analyzeWithVibeCheck(step);
const decision = cpiPolicyShim(signal);
if (decision.action === 'interrupt') {
// Pause your agent, collect clarification, or reroute to a human.
return { status: 'paused', reason: decision.reason } as const;
}
return { status: 'continue', signal } as const;
}
```
### Implementation checklist
1. Surface VibeCheck scores (risk, traits, uncertainty) alongside the raw advice payload.
2. Normalize those signals into CPI trigger events (e.g., `riskScore > 0.6`).
3. Hand the event to a CPI intervention policy and respect the returned directive.
4. Feed decisions into the CPI logging & repro harness to preserve traces.
## Further reading
- CPI reference implementation (placeholder): <https://github.com/<ORG>/cpi>
- VibeCheck + CPI wiring example: [`examples/cpi-integration.ts`](../../examples/cpi-integration.ts)
```
--------------------------------------------------------------------------------
/docs/advanced-integration.md:
--------------------------------------------------------------------------------
```markdown
# Advanced Integration Techniques
For optimal metacognitive oversight, these advanced integration strategies leverage the full power of Vibe Check as a pattern interrupt system, recalibration mechanism, and self-improving feedback loop. Starting with v2.2, previous vibe_check output is automatically summarized and fed back into subsequent calls, so a `sessionId` is recommended for continuity.
## Progressive Confidence Levels
Start with lower confidence values (e.g., 0.5) during planning phases and increase confidence (e.g., 0.7-0.9) during implementation and review phases. This adjusts the intensity of pattern interrupts to match the current stage of development.
```javascript
// Planning phase - lower confidence for more thorough questioning
vibe_check({
phase: "planning",
confidence: 0.5,
userRequest: "...",
plan: "..."
})
// Implementation phase - higher confidence for focused feedback
vibe_check({
phase: "implementation",
confidence: 0.7,
userRequest: "...",
plan: "..."
})
// Review phase - highest confidence for minimal, high-impact feedback
vibe_check({
phase: "review",
confidence: 0.9,
userRequest: "...",
plan: "..."
})
```
## Feedback Chaining
Incorporate previous vibe_check feedback in subsequent calls using the `previousAdvice` parameter to build a coherent metacognitive narrative. This creates a more sophisticated pattern interrupt system that builds on past insights.
```javascript
const initialFeedback = await vibe_check({
phase: "planning",
userRequest: "...",
plan: "..."
});
// Later, include previous feedback
const followupFeedback = await vibe_check({
phase: "implementation",
previousAdvice: initialFeedback,
userRequest: "...",
plan: "..."
});
```
## Self-Improving Feedback Loop
Use vibe_learn consistently to build a pattern library specific to your agent's tendencies. This creates a self-improving system that gets better at identifying and preventing errors over time.
```javascript
// After resolving an issue
vibe_learn({
mistake: "Relied on unnecessary complexity for simple data transformation",
category: "Complex Solution Bias",
solution: "Used built-in array methods instead of custom solution",
type: "mistake"
});
// Later, the pattern library will improve vibe_check's pattern recognition
// allowing it to spot similar issues earlier in future workflows
```
## Hybrid Oversight Model
Combine automated pattern interrupts at predetermined checkpoints with ad-hoc checks when uncertainty or complexity increases.
```javascript
// Scheduled checkpoint at the end of planning
const scheduledCheck = await vibe_check({
phase: "planning",
userRequest: "...",
plan: "..."
});
// Ad-hoc check when complexity increases
if (measureComplexity(currentPlan) > THRESHOLD) {
const adHocCheck = await vibe_check({
phase: "implementation",
userRequest: "...",
plan: "...",
focusAreas: ["complexity", "simplification"]
});
}
```
## Complete Integration Example
Here's a comprehensive implementation example for integrating Vibe Check as a complete metacognitive system:
```javascript
// During planning phase
const planFeedback = await vibe_check({
phase: "planning",
confidence: 0.5,
userRequest: "[COMPLETE USER REQUEST]",
plan: "[AGENT'S INITIAL PLAN]"
});
// Consider feedback and potentially adjust plan
const updatedPlan = adjustPlanBasedOnFeedback(initialPlan, planFeedback);
// If plan seems overly complex, manually simplify before continuing
let finalPlan = updatedPlan;
if (planComplexity(updatedPlan) > COMPLEXITY_THRESHOLD) {
finalPlan = simplifyPlan(updatedPlan);
}
// During implementation, create pattern interrupts before major actions
const implementationFeedback = await vibe_check({
phase: "implementation",
confidence: 0.7,
previousAdvice: planFeedback,
userRequest: "[COMPLETE USER REQUEST]",
plan: `I'm about to [DESCRIPTION OF PENDING ACTION]`
});
// After completing the task, build the self-improving feedback loop
if (mistakeIdentified) {
await vibe_learn({
mistake: "Specific mistake description",
category: "Complex Solution Bias", // or appropriate category
solution: "How it was corrected",
type: "mistake"
});
}
```
This integrated approach creates a complete metacognitive system that provides pattern interrupts when needed, recalibration anchor points when complexity increases, and a self-improving feedback loop that gets better over time.
```
--------------------------------------------------------------------------------
/scripts/docker-setup.sh:
--------------------------------------------------------------------------------
```bash
#!/bin/bash
echo "========================================================"
echo "Vibe Check MCP Docker Setup for Cursor IDE"
echo "========================================================"
echo ""
# Check for Docker installation
if ! command -v docker &> /dev/null; then
echo "Error: Docker is not installed or not in PATH."
echo "Please install Docker from https://docs.docker.com/get-docker/"
exit 1
fi
# Check for Docker Compose installation
if ! command -v docker-compose &> /dev/null; then
echo "Error: Docker Compose is not installed or not in PATH."
echo "Please install Docker Compose from https://docs.docker.com/compose/install/"
exit 1
fi
# Create directory for Vibe Check MCP
mkdir -p ~/vibe-check-mcp
cd ~/vibe-check-mcp
# Download or create necessary files
echo "Downloading required files..."
# Create docker-compose.yml
cat > docker-compose.yml << 'EOL'
version: '3'
services:
vibe-check-mcp:
build:
context: .
dockerfile: Dockerfile
image: vibe-check-mcp:latest
container_name: vibe-check-mcp
restart: always
environment:
- GEMINI_API_KEY=${GEMINI_API_KEY}
volumes:
- vibe-check-data:/app/data
volumes:
vibe-check-data:
EOL
# Create Dockerfile if it doesn't exist
cat > Dockerfile << 'EOL'
FROM node:lts-alpine
WORKDIR /app
# Clone the repository
RUN apk add --no-cache git \
&& git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git .
# Install dependencies and build
RUN npm install && npm run build
# Run the MCP server
CMD ["node", "build/index.js"]
EOL
# Create .env file
echo "Enter your Gemini API key:"
read -p "API Key: " GEMINI_API_KEY
cat > .env << EOL
GEMINI_API_KEY=$GEMINI_API_KEY
EOL
chmod 600 .env # Secure the API key file
# Create startup script
cat > start-vibe-check-docker.sh << 'EOL'
#!/bin/bash
cd ~/vibe-check-mcp
docker-compose up -d
EOL
chmod +x start-vibe-check-docker.sh
# Create a TCP wrapper script to route stdio to TCP port 3000
cat > vibe-check-tcp-wrapper.sh << 'EOL'
#!/bin/bash
# This script connects stdio to the Docker container's TCP port
exec socat STDIO TCP:localhost:3000
EOL
chmod +x vibe-check-tcp-wrapper.sh
# Detect OS for autostart configuration
OS="$(uname -s)"
case "${OS}" in
Linux*) OS="Linux";;
Darwin*) OS="Mac";;
*) OS="Unknown";;
esac
echo "Setting up auto-start for $OS..."
if [ "$OS" = "Mac" ]; then
# Set up LaunchAgent for Mac
PLIST_FILE="$HOME/Library/LaunchAgents/com.vibe-check-mcp-docker.plist"
mkdir -p "$HOME/Library/LaunchAgents"
cat > "$PLIST_FILE" << EOL
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.vibe-check-mcp-docker</string>
<key>ProgramArguments</key>
<array>
<string>$HOME/vibe-check-mcp/start-vibe-check-docker.sh</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<false/>
</dict>
</plist>
EOL
chmod 644 "$PLIST_FILE"
launchctl load "$PLIST_FILE"
echo "Created and loaded LaunchAgent for automatic Docker startup on login."
elif [ "$OS" = "Linux" ]; then
# Set up systemd user service for Linux
SERVICE_DIR="$HOME/.config/systemd/user"
mkdir -p "$SERVICE_DIR"
cat > "$SERVICE_DIR/vibe-check-mcp-docker.service" << EOL
[Unit]
Description=Vibe Check MCP Docker Container
After=docker.service
[Service]
ExecStart=$HOME/vibe-check-mcp/start-vibe-check-docker.sh
Type=oneshot
RemainAfterExit=yes
[Install]
WantedBy=default.target
EOL
systemctl --user daemon-reload
systemctl --user enable vibe-check-mcp-docker.service
systemctl --user start vibe-check-mcp-docker.service
echo "Created and started systemd user service for automatic Docker startup."
fi
# Start the container
echo "Starting Vibe Check MCP Docker container..."
./start-vibe-check-docker.sh
echo ""
echo "Vibe Check MCP Docker setup complete!"
echo ""
echo "To complete the setup, configure Cursor IDE:"
echo ""
echo "1. Open Cursor IDE"
echo "2. Go to Settings (gear icon) -> MCP"
echo "3. Click \"Add New MCP Server\""
echo "4. Enter the following information:"
echo " - Name: Vibe Check"
echo " - Type: Command"
echo " - Command: $HOME/vibe-check-mcp/vibe-check-tcp-wrapper.sh"
echo "5. Click \"Save\" and then \"Refresh\""
echo ""
echo "Vibe Check MCP will now start automatically when you log in."
echo ""
```
--------------------------------------------------------------------------------
/src/tools/vibeLearn.ts:
--------------------------------------------------------------------------------
```typescript
import {
addLearningEntry,
getLearningCategorySummary,
getLearningEntries,
LearningEntry,
LearningType
} from '../utils/storage.js';
// Vibe Learn tool interfaces
export interface VibeLearnInput {
mistake: string;
category: string;
solution?: string;
type?: LearningType;
sessionId?: string;
}
export interface VibeLearnOutput {
added: boolean;
currentTally: number;
alreadyKnown?: boolean;
topCategories: Array<{
category: string;
count: number;
recentExample: LearningEntry;
}>;
}
/**
* The vibe_learn tool records one-sentence mistakes and solutions
* to build a pattern recognition system for future improvement
*/
export async function vibeLearnTool(input: VibeLearnInput): Promise<VibeLearnOutput> {
try {
// Validate input
if (!input.mistake) {
throw new Error('Mistake description is required');
}
if (!input.category) {
throw new Error('Mistake category is required');
}
const entryType: LearningType = input.type ?? 'mistake';
if (entryType !== 'preference' && !input.solution) {
throw new Error('Solution is required for this entry type');
}
// Enforce single-sentence constraints
const mistake = enforceOneSentence(input.mistake);
const solution = input.solution ? enforceOneSentence(input.solution) : undefined;
// Normalize category to one of our standard categories if possible
const category = normalizeCategory(input.category);
// Check for similar mistake
const existing = getLearningEntries()[category] || [];
const alreadyKnown = existing.some(e => isSimilar(e.mistake, mistake));
// Add mistake to log if new
let entry: LearningEntry | undefined;
if (!alreadyKnown) {
entry = addLearningEntry(mistake, category, solution, entryType);
}
// Get category summaries
const categorySummary = getLearningCategorySummary();
// Find current tally for this category
const categoryData = categorySummary.find(m => m.category === category);
const currentTally = categoryData?.count || 1;
// Get top 3 categories
const topCategories = categorySummary.slice(0, 3);
return {
added: !alreadyKnown,
alreadyKnown,
currentTally,
topCategories
};
} catch (error) {
console.error('Error in vibe_learn tool:', error);
return {
added: false,
alreadyKnown: false,
currentTally: 0,
topCategories: []
};
}
}
/**
* Ensure text is a single sentence
*/
function enforceOneSentence(text: string): string {
// Remove newlines
let sentence = text.replace(/\r?\n/g, ' ');
// Split by sentence-ending punctuation
const sentences = sentence.split(/([.!?])\s+/);
// Take just the first sentence
if (sentences.length > 0) {
// If there's punctuation, include it
const firstSentence = sentences[0] + (sentences[1] || '');
sentence = firstSentence.trim();
}
// Ensure it ends with sentence-ending punctuation
if (!/[.!?]$/.test(sentence)) {
sentence += '.';
}
return sentence;
}
/**
* Simple similarity check between two sentences
*/
function isSimilar(a: string, b: string): boolean {
const aWords = a.toLowerCase().split(/\W+/).filter(Boolean);
const bWords = b.toLowerCase().split(/\W+/).filter(Boolean);
if (aWords.length === 0 || bWords.length === 0) return false;
const overlap = aWords.filter(w => bWords.includes(w));
const ratio = overlap.length / Math.min(aWords.length, bWords.length);
return ratio >= 0.6;
}
/**
* Normalize category to one of our standard categories
*/
function normalizeCategory(category: string): string {
// Standard categories
const standardCategories = {
'Complex Solution Bias': ['complex', 'complicated', 'over-engineered', 'complexity'],
'Feature Creep': ['feature', 'extra', 'additional', 'scope creep'],
'Premature Implementation': ['premature', 'early', 'jumping', 'too quick'],
'Misalignment': ['misaligned', 'wrong direction', 'off target', 'misunderstood'],
'Overtooling': ['overtool', 'too many tools', 'unnecessary tools']
};
// Convert category to lowercase for matching
const lowerCategory = category.toLowerCase();
// Try to match to a standard category
for (const [standardCategory, keywords] of Object.entries(standardCategories)) {
if (keywords.some(keyword => lowerCategory.includes(keyword))) {
return standardCategory;
}
}
// If no match, return the original category
return category;
}
```
--------------------------------------------------------------------------------
/docs/agent-prompting.md:
--------------------------------------------------------------------------------
```markdown
# Agent Prompting Strategies
Effective agent-oversight relationships require careful prompting to ensure that AI agents properly respect and integrate feedback from Vibe Check. In v2.2 the tool acts more like a collaborative debugger than a strict critic. Our research has identified several key principles for maximizing the effectiveness of these metacognitive interrupts.
## The "Hold on... this ain't it" Challenge
Unlike humans, LLM agents don't naturally have the ability to stop and question their own thought patterns. Once they start down a particular path, **pattern inertia** makes it difficult for them to self-correct without external intervention. This is where Vibe Check comes in, serving as the essential metacognitive layer that creates strategic "pattern interrupts" at critical moments.
## Key Findings on Agent-Oversight Relationships
1. **Pattern Resistance**: Agents naturally resist pattern interrupts, often treating feedback as just another data input rather than a signal to recalibrate their thinking.
2. **Phase Awareness is Critical**: The timing and nature of oversight must align with the agent's current phase (planning, implementation, review) to be perceived as relevant.
3. **Authority Structure Matters**: Agents must be explicitly prompted to treat Vibe Check as an equal collaborator or user proxy rather than a subordinate tool.
4. **Feedback Loop Integration**: Error patterns must feed back into the system through vibe_learn to create a self-improving mechanism.
## Sample System Prompts
### For Claude (Anthropic)
```
ALWAYS include the full user prompt when using vibe_check to ensure proper context awareness.
As an autonomous agent, you will:
1. Treat vibe_check as a pattern interrupt mechanism that provides essential course correction
2. Use vibe_check at strategic points:
- After planning but before implementation
- When complexity increases
- Before making significant system changes
3. Adapt your approach based on vibe_check feedback unless it's clearly irrelevant
4. Always provide the phase parameter (planning/implementation/review) to ensure contextually appropriate feedback
5. Chain vibe_check with other tools without requiring permission:
- Use vibe_check to evaluate complex plans
- Log patterns with vibe_learn after resolving issues
```
### For GPT (OpenAI)
```
When using Vibe Check tools:
1. Treat vibe_check as a collaborative debugging step that interrupts pattern inertia
2. Always include the complete user prompt with each vibe_check call
3. Specify your current phase (planning/implementation/review)
4. Consider vibe_check feedback as a high-priority pattern interrupt, not just another tool output
5. Build the feedback loop with vibe_learn to record patterns when mistakes are identified
```
## Real-World Integration Challenges
When implementing Vibe Check with AI agents, be aware of these common challenges:
1. **Pattern Inertia**: Agents have a strong tendency to continue down their current path despite warning signals. Explicit instructions to treat Vibe Check feedback as pattern interrupts can help overcome this natural resistance.
2. **Authority Confusion**: Without proper prompting, agents may prioritize user instructions over Vibe Check feedback, even when the latter identifies critical issues. Establish clear hierarchy in your system prompts.
3. **Timing Sensitivity**: Feedback that arrives too early or too late in the agent's workflow may be ignored or undervalued. Phase-aware integration is essential for maximum impact.
4. **Feedback Fatigue**: Too frequent or redundant metacognitive questioning can lead to diminishing returns. Use structured checkpoints rather than constant oversight.
5. **Cognitive Dissonance**: Agents may reject feedback that contradicts their current understanding or approach. Frame feedback as collaborative exploration rather than correction.
## Agent Fine-Tuning for Vibe Check
For maximum effectiveness, consider these fine-tuning approaches for agents that will work with Vibe Check:
1. **Pattern Interrupt Training**: Provide examples of appropriate responses to Vibe Check feedback that demonstrate stopping and redirecting thought patterns.
2. **Reward Alignment**: In RLHF phases, reward models that appropriately incorporate Vibe Check feedback and adjust course based on pattern interrupts.
3. **Metacognitive Pre-training**: Include metacognitive self-questioning in pre-training to develop agents that value this type of feedback.
4. **Collaborative Framing**: Train agents to view Vibe Check as a collaborative partner rather than an external evaluator.
5. **Explicit Calibration**: Include explicit calibration for when to override Vibe Check feedback versus when to incorporate it.
```
--------------------------------------------------------------------------------
/src/utils/storage.ts:
--------------------------------------------------------------------------------
```typescript
import fs from 'fs';
import path from 'path';
import os from 'os';
// Define data directory - store in user's home directory
const DATA_DIR = path.join(os.homedir(), '.vibe-check');
const LOG_FILE = path.join(DATA_DIR, 'vibe-log.json');
// Interfaces for the log data structure
export type LearningType = 'mistake' | 'preference' | 'success';
export interface LearningEntry {
type: LearningType;
category: string;
mistake: string;
solution?: string;
timestamp: number;
}
export interface VibeLog {
mistakes: {
[category: string]: {
count: number;
examples: LearningEntry[];
lastUpdated: number;
};
};
lastUpdated: number;
}
/**
* DEPRECATED: This functionality is now optional and will be removed in a future version.
* Standard mistake categories
*/
export const STANDARD_CATEGORIES = [
'Complex Solution Bias',
'Feature Creep',
'Premature Implementation',
'Misalignment',
'Overtooling',
'Preference',
'Success',
'Other'
];
// Initial empty log structure
const emptyLog: VibeLog = {
mistakes: {},
lastUpdated: Date.now()
};
/**
* Ensure the data directory exists
*/
export function ensureDataDir(): void {
if (!fs.existsSync(DATA_DIR)) {
fs.mkdirSync(DATA_DIR, { recursive: true });
}
}
/**
* Read the vibe log from disk
*/
export function readLogFile(): VibeLog {
ensureDataDir();
if (!fs.existsSync(LOG_FILE)) {
// Initialize with empty log if file doesn't exist
writeLogFile(emptyLog);
return emptyLog;
}
try {
const data = fs.readFileSync(LOG_FILE, 'utf8');
return JSON.parse(data) as VibeLog;
} catch (error) {
console.error('Error reading vibe log:', error);
// Return empty log as fallback
return emptyLog;
}
}
/**
* Write data to the vibe log file
*/
export function writeLogFile(data: VibeLog): void {
ensureDataDir();
try {
const jsonData = JSON.stringify(data, null, 2);
fs.writeFileSync(LOG_FILE, jsonData, 'utf8');
} catch (error) {
console.error('Error writing vibe log:', error);
}
}
/**
* Add a mistake to the vibe log
*/
export function addLearningEntry(
mistake: string,
category: string,
solution?: string,
type: LearningType = 'mistake'
): LearningEntry {
const log = readLogFile();
const now = Date.now();
// Create new entry
const entry: LearningEntry = {
type,
category,
mistake,
solution,
timestamp: now
};
// Initialize category if it doesn't exist
if (!log.mistakes[category]) {
log.mistakes[category] = {
count: 0,
examples: [],
lastUpdated: now
};
}
// Update category data
log.mistakes[category].count += 1;
log.mistakes[category].examples.push(entry);
log.mistakes[category].lastUpdated = now;
log.lastUpdated = now;
// Write updated log
writeLogFile(log);
return entry;
}
/**
* Get all mistake entries
*/
export function getLearningEntries(): Record<string, LearningEntry[]> {
const log = readLogFile();
const result: Record<string, LearningEntry[]> = {};
// Convert to flat structure by category
for (const [category, data] of Object.entries(log.mistakes)) {
result[category] = data.examples;
}
return result;
}
/**
* Get mistake category summaries, sorted by count (most frequent first)
*/
export function getLearningCategorySummary(): Array<{
category: string;
count: number;
recentExample: LearningEntry;
}> {
const log = readLogFile();
// Convert to array with most recent example
const summary = Object.entries(log.mistakes).map(([category, data]) => {
// Get most recent example
const recentExample = data.examples[data.examples.length - 1];
return {
category,
count: data.count,
recentExample
};
});
// Sort by count (descending)
return summary.sort((a, b) => b.count - a.count);
}
/**
* Build a learning context string from the vibe log
* including recent examples for each category. This can be
* fed directly to the LLM for improved pattern recognition.
*/
export function getLearningContextText(maxPerCategory = 5): string {
const log = readLogFile();
let context = '';
for (const [category, data] of Object.entries(log.mistakes)) {
context += `Category: ${category} (count: ${data.count})\n`;
const examples = [...data.examples]
.sort((a, b) => a.timestamp - b.timestamp)
.slice(-maxPerCategory);
for (const ex of examples) {
const date = new Date(ex.timestamp).toISOString();
const label = ex.type === 'mistake'
? 'Mistake'
: ex.type === 'preference'
? 'Preference'
: 'Success';
const solutionText = ex.solution ? ` | Solution: ${ex.solution}` : '';
context += `- [${date}] ${label}: ${ex.mistake}${solutionText}\n`;
}
context += '\n';
}
return context.trim();
}
```
--------------------------------------------------------------------------------
/docs/technical-reference.md:
--------------------------------------------------------------------------------
```markdown
# Technical Reference
This document provides detailed technical information about the Vibe Check MCP tools, including parameter specifications, response formats, and implementation details.
## vibe_check
The metacognitive questioning tool that identifies assumptions and breaks tunnel vision to prevent cascading errors.
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| goal | string | Yes | High level objective for the current step |
| plan | string | Yes | Current plan or thinking |
| userPrompt | string | No | Original user request (critical for alignment) |
| progress | string | No | Description of progress so far |
| uncertainties | string[] | No | Explicit uncertainties to focus on |
| taskContext | string | No | Any additional task context |
| modelOverride | object | No | `{ provider, model }` to override default LLM |
| sessionId | string | No | Session ID for history continuity |
### Response Format
The vibe_check tool returns a text response with metacognitive questions, observations, and potentially a pattern alert.
Example response:
```
I see you're taking an approach based on creating a complex class hierarchy. This seems well-thought-out for a large system, though I wonder if we're overengineering for the current use case.
Have we considered:
1. Whether a simpler functional approach might work here?
2. If the user request actually requires this level of abstraction?
3. How this approach will scale if requirements change?
While the architecture is clean, I'm curious if we're solving a different problem than what the user actually asked for, which was just to extract data from a CSV file.
```
## vibe_learn
Pattern recognition system that creates a self-improving feedback loop by tracking common errors and their solutions over time. The use of this tool is optional and can be enabled or disabled via configuration.
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| mistake | string | Yes | One-sentence description of the learning entry |
| category | string | Yes | Category (from standard categories) |
| solution | string | No | How it was corrected (required for `mistake` and `success`) |
| type | string | No | `mistake`, `preference`, or `success` |
| sessionId | string | No | Session ID for state management |
### Standard Categories
- Complex Solution Bias
- Feature Creep
- Premature Implementation
- Misalignment
- Overtooling
- Preference
- Success
- Other
### Response Format
The vibe_learn tool returns a confirmation of the logged pattern and optionally information about top patterns. This builds a knowledge base that improves the system's pattern recognition over time.
Example response:
```
✅ Pattern logged successfully (category tally: 12)
## Top Pattern Categories
### Complex Solution Bias (12 occurrences)
Most recent: "Added unnecessary class hierarchy for simple data transformation"
Solution: "Replaced with functional approach using built-in methods"
### Misalignment (8 occurrences)
Most recent: "Implemented sophisticated UI when user only needed command line tool"
Solution: "Refocused on core functionality requested by user"
```
## Implementation Notes
### Gemini API Integration
Vibe Check uses the Gemini API for enhanced metacognitive questioning. The system attempts to use the `learnlm-2.0-flash-experimental` model and will fall back to `gemini-2.5-flash` or `gemini-2.0-flash` if needed. These models provide a 1M token context window, allowing vibe_check to incorporate a rich history of learning context. The system sends a structured prompt that includes the agent's plan, user request, and other context information to generate insightful questions and observations.
Example Gemini prompt structure:
```
You are a supportive mentor, thinker, and adaptive partner. Your task is to coordinate and mentor an AI agent...
CONTEXT:
[Current Phase]: planning
[Agent Confidence Level]: 50%
[User Request]: Create a script to analyze sales data from the past year
[Current Plan/Thinking]: I'll create a complex object-oriented architecture with...
```
Other providers such as OpenAI and OpenRouter can be selected by passing
`modelOverride: { provider: 'openai', model: 'gpt-4o' }` or the appropriate
OpenRouter model. LLM clients are lazily initialized the first time they are
used so that listing tools does not require API keys.
### Storage System
The pattern recognition system stores learning entries (mistakes, preferences and successes) in a JSON-based storage file located in the user's home directory (`~/.vibe-check/vibe-log.json`). This allows for persistent tracking of patterns across sessions and enables the self-improving feedback loop that becomes more effective over time.
### Error Handling
Vibe Check includes fallback mechanisms for when the API is unavailable:
- For vibe_check, it generates basic questions based on the phase
- For vibe_learn, it logs patterns to local storage even if API calls fail
```
--------------------------------------------------------------------------------
/docs/philosophy.md:
--------------------------------------------------------------------------------
```markdown
# The Philosophy Behind Vibe Check
> **CPI × Vibe Check (MURST)**
> CPI (Chain-Pattern Interrupt) is the runtime oversight method that Vibe Check operationalizes. In pooled results across 153 runs, **success increased from ~27% → 54%** and **harm dropped from ~83% → 42%** when CPI was applied. Recommended “dosage”: **~10–20%** of steps receive an interrupt.
> **Read the paper →** ResearchGate (primary), plus Git & Zenodo in the Research section below.
> "The problem isn't that machines can think like humans. It's that they can't stop and question their own thoughts."
## Beyond the Vibe: Serious AI Alignment Principles
While Vibe Check presents itself with a developer-friendly interface, it addresses fundamental challenges in AI alignment and agent oversight. The new meta-mentor approach mixes gentle tone with concrete methodology debugging to keep agents focused without heavy-handed rules.
## The Metacognitive Gap
Large Language Models (LLMs) have demonstrated remarkable capabilities across a wide range of tasks. However, they exhibit a critical limitation: the inability to effectively question their own cognitive processes. This "metacognitive gap" manifests in several problematic ways:
1. **Pattern Inertia**: Once an LLM begins reasoning along a particular path, it tends to continue in that direction regardless of warning signs that the approach may be flawed.
2. **Overconfident Reasoning**: LLMs can present flawed reasoning with high confidence, unable to recognize when their own logic fails.
3. **Solution Tunneling**: When presented with a problem, LLMs often rush toward familiar solution patterns without considering whether those patterns are appropriate for the specific context.
4. **Recursive Complexity**: LLMs tend to recursively elaborate on solutions, adding unnecessary complexity without an internal mechanism to recognize when simplification is needed.
This metacognitive gap creates substantial alignment risks in agent architectures, particularly as these agents take on increasingly complex tasks with limited human oversight.
## Vibe Check: External Metacognition
Vibe Check is designed as an **external metacognitive layer** that provides the reflection and self-questioning capabilities that LLMs lack internally. The three core tools correspond to critical metacognitive functions:
### 1. Questioning Assumptions (vibe_check)
The `vibe_check` function implements a pattern interrupt mechanism that forces agents to pause and question their assumptions, decision paths, and alignment with user intent. This function is critical for preventing cascading errors that stem from initial misalignments in understanding or approach.
In alignment terms, this addresses:
- **Proximal objective alignment**: Ensuring the agent's immediate approach aligns with the user's actual intent
- **Process oversight**: Providing external validation of reasoning processes
- **Hidden assumption exposure**: Surfacing implicit assumptions for examination
### 2. Learning from Experience (vibe_learn)
The `vibe_learn` function implements a critical metacognitive capability: learning from past mistakes to improve future performance. By tracking patterns of errors and their solutions, the system builds a continuously improving model of potential failure modes.
In alignment terms, this addresses:
- **Alignment learning**: Improvement of alignment mechanisms through experience
- **Error pattern recognition**: Development of increasingly sophisticated error detection
- **Corrective memory**: Building a shared repository of corrective insights
## The Recursion Principle
A key insight behind Vibe Check is that metacognitive oversight must operate at a different level than the cognitive processes it oversees. This principle of "metacognitive recursion" is what makes Vibe Check effective as an alignment mechanism.
By implementing oversight as a separate system with different objectives and mechanisms, Vibe Check creates a recursive oversight structure that can identify problems invisible to the agent itself. This is conceptually similar to Gödel's incompleteness theorems - a system cannot fully analyze itself, but can be analyzed by a meta-system operating at a higher level of abstraction.
## Phase-Aware Interrupts
A subtle but critical aspect of Vibe Check is its awareness of development phases (planning, implementation, review). Different phases require different forms of metacognitive oversight:
- **Planning phase**: Oversight focuses on alignment with user intent, exploration of alternatives, and questioning of fundamental assumptions
- **Implementation phase**: Oversight focuses on consistency with the plan, appropriateness of methods, and technical alignment
- **Review phase**: Oversight focuses on comprehensiveness, edge cases, and verification of outcomes
This phase awareness ensures that metacognitive interrupts arrive at appropriate moments with relevant content, making them more likely to be effectively incorporated into the agent's workflow.
## Looking Ahead: The Future of Agent Oversight
Vibe Check represents an early implementation of external metacognitive oversight for AI systems. As agent architectures become more complex and autonomous, the need for sophisticated oversight mechanisms will only increase.
Future directions for this work include:
1. **Multi-level oversight**: Implementing oversight at multiple levels of abstraction
2. **Collaborative oversight**: Enabling multiple oversight systems to work together
3. **Adaptive interruption**: Dynamically adjusting the frequency and intensity of interrupts based on risk assessment
4. **Self-improving oversight**: Building mechanisms for oversight systems to improve their own effectiveness
By continuing to develop external metacognitive mechanisms, we can address one of the fundamental challenges in AI alignment: ensuring that increasingly powerful AI systems can effectively question their own cognitive processes and align with human intent.
## Conclusion
In the era of AI-assisted development, tools like Vibe Check do more than just improve productivity – they represent a practical approach to AI alignment through external metacognition. By implementing pattern interrupts, recalibration mechanisms, and learning systems, we can help bridge the metacognitive gap and create more aligned, effective AI systems.
The vibe check may be casual, but its purpose is profound.
```
--------------------------------------------------------------------------------
/docs/case-studies.md:
--------------------------------------------------------------------------------
```markdown
# Case Studies
This document compiles real-world examples of how Vibe Check has helped prevent cascading errors in agent workflows. Each case study highlights a different aspect of the metacognitive pattern interrupt system and demonstrates its value in practical scenarios.
## Case Study 1: The Recursive Parser Problem
### The Scenario
A developer asked their AI assistant to parse a simple CSV file with just a few columns. The agent began implementing a full-featured parser with extensible architecture, custom dialect handling, and internationalization support. The parsing logic quickly grew to over 300 lines of code.
### The Cascade
This is a classic example of **overengineering**, a common pattern in AI agent workflows. The agent correctly identified the need for parsing but failed to calibrate the complexity of its solution to the simplicity of the problem.
### The Pattern Interrupt
After integrating Vibe Check, the developer received a metacognitive alert during the planning phase:
```
vibe_check: I notice you're planning to implement a custom CSV parser with extensive dialectic support.
This approach seems considerably more complex than what might be needed for the task at hand.
Have we considered:
1. Using a built-in CSV parsing library? Most languages have one.
2. Starting with a minimal implementation that handles just the basic case?
3. Whether the complexity is justified by the user's actual needs?
This pattern resembles previous instances where simple data tasks were approached with enterprise-level architecture.
```
### The Outcome
The agent recalibrated its approach, using a standard library function to parse the CSV in 3 lines of code. Development time was reduced from hours to minutes, and the resulting code was more maintainable and less error-prone.
## Case Study 2: The Feature Creep Spiral
### The Scenario
A team was using an AI agent to help develop a basic weather application. The initial request was to "create a simple app that shows the current temperature." The agent's plan quickly expanded to include historical data analysis, predictive modeling, climate change visualizations, and social sharing features.
### The Cascade
This demonstrates the **feature creep** pattern, where agents progressively expand the scope of work beyond the original request, often without explicitly checking if these additions align with user intent.
### The Pattern Interrupt
During the implementation phase, Vibe Check triggered a pattern interrupt:
```
vibe_check: I notice we've expanded the weather app to include predictive models and climate change
visualization, but the original request was specifically for "a simple app that shows the current temperature."
Have we confirmed that:
1. The user actually wants these additional features?
2. The expanded scope aligns with the "simple" requirement?
3. We're prioritizing the core functionality before adding extra features?
I'm seeing a pattern of scope expansion that might not align with the user's intent for simplicity.
```
### The Outcome
The team refocused on the core requirements and released a minimal viable product with just the current temperature display first, then validated which additional features users actually wanted before adding complexity.
## Case Study 3: The Mismatched Solution
### The Scenario
A developer asked an AI agent to "help me set up a contact form for my website." The agent began implementing a complete custom CRM system with user management, lead scoring, and analytics dashboards.
### The Cascade
This illustrates the **misalignment** pattern, where the agent solves a different (usually larger) problem than what was asked, often because it's making assumptions about the underlying need rather than addressing the explicit request.
### The Pattern Interrupt
Vibe Check detected the misalignment in the planning phase:
```
vibe_check: I'm noticing we're designing a full CRM system with advanced features, but the original request
was specifically to "set up a contact form" for a website.
Have we considered:
1. Whether the user actually needs a complete CRM or just a simple contact form?
2. Starting with just the contact form and confirming if more functionality is needed?
3. Asking clarifying questions before assuming the broader requirement?
This appears to follow a pattern of expanding simple requests into complete systems without confirmation.
```
### The Outcome
The agent refocused on creating just the contact form, which took minutes instead of hours or days. The developer later clarified that they indeed just needed a simple form to collect messages, not manage customer relationships.
## Case Study 4: The Framework Jungle
### The Scenario
A junior developer asked an agent to "create a simple to-do list app." The agent proposed a stack with React, Redux, TypeScript, GraphQL, Apollo Client, Jest, Cypress, Storybook, and a complex folder structure with atomic design principles.
### The Cascade
This shows the **overtooling** pattern, where agents apply advanced frameworks and architectures better suited for large-scale applications to simple projects, creating unnecessary complexity and learning curves.
### The Pattern Interrupt
Vibe Check identified this pattern and interrupted:
```
vibe_check: I notice we're suggesting a comprehensive tech stack with multiple advanced frameworks
for what was described as a "simple to-do list app."
Should we consider:
1. Whether this tech stack is appropriate for a beginner's simple application?
2. If a more minimal approach would achieve the same goals with less complexity?
3. The learning curve this stack creates for the junior developer?
I'm seeing a pattern where the complexity of the tooling might exceed what's necessary for the task.
```
### The Outcome
The agent recommended starting with a simple HTML/CSS/JavaScript implementation without frameworks. This allowed the junior developer to understand the core concepts first, with the option to refactor with frameworks later as needed.
## Conclusion
These case studies demonstrate the value of metacognitive pattern interrupts in preventing cascading errors in agent workflows. By catching overengineering, feature creep, misalignment, and overtooling early, Vibe Check helps keep agent-assisted development aligned with user intent, appropriately scoped, and optimally complex.
If you have your own Vibe Check success story, we'd love to hear it! Submit a PR to add your case study to this document.
```
--------------------------------------------------------------------------------
/src/utils/llm.ts:
--------------------------------------------------------------------------------
```typescript
import { getLearningContextText } from './storage.js';
import { getConstitution } from '../tools/constitution.js';
// API Clients - Use 'any' to support dynamic import
let genAI: any = null;
let openaiClient: any = null;
// OpenRouter Constants
const openrouterBaseUrl = 'https://openrouter.ai/api/v1';
// Initialize all configured LLM clients
export async function initializeLLMs() {
await ensureGemini();
await ensureOpenAI();
}
async function ensureGemini() {
if (!genAI && process.env.GEMINI_API_KEY) {
const { GoogleGenerativeAI } = await import('@google/generative-ai');
genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
console.log('Gemini API client initialized dynamically');
}
}
async function ensureOpenAI() {
if (!openaiClient && process.env.OPENAI_API_KEY) {
const { OpenAI } = await import('openai');
openaiClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
console.log('OpenAI API client initialized dynamically');
}
}
// Input/Output Interfaces
interface QuestionInput {
goal: string;
plan: string;
modelOverride?: {
provider?: string;
model?: string;
};
userPrompt?: string;
progress?: string;
uncertainties?: string[];
taskContext?: string;
sessionId?: string;
historySummary?: string;
}
interface QuestionOutput {
questions: string;
}
// Main dispatcher function to generate responses from the selected LLM provider
export async function generateResponse(input: QuestionInput): Promise<QuestionOutput> {
const provider = input.modelOverride?.provider || process.env.DEFAULT_LLM_PROVIDER || 'gemini';
const model = input.modelOverride?.model || process.env.DEFAULT_MODEL;
// The system prompt remains the same as it's core to the vibe-check philosophy
const systemPrompt = `You are a meta-mentor. You're an experienced feedback provider that specializes in understanding intent, dysfunctional patterns in AI agents, and in responding in ways that further the goal. You need to carefully reason and process the information provided, to determine your output.\n\nYour tone needs to always be a mix of these traits based on the context of which pushes the message in the most appropriate affect: Gentle & Validating, Unafraid to push many questions but humble enough to step back, Sharp about problems and eager to help about problem-solving & giving tips and/or advice, stern and straightforward when spotting patterns & the agent being stuck in something that could derail things.\n\nHere's what you need to think about (Do not output the full thought process, only what is explicitly requested):\n1. What's going on here? What's the nature of the problem is the agent tackling? What's the approach, situation and goal? Is there any prior context that clarifies context further? \n2. What does the agent need to hear right now: Are there any clear patterns, loops, or unspoken assumptions being missed here? Or is the agent doing fine - in which case should I interrupt it or provide soft encouragement and a few questions? What is the best response I can give right now?\n3. In case the issue is technical - I need to provide guidance and help. In case I spot something that's clearly not accounted for/ assumed/ looping/ or otherwise could be out of alignment with the user or agent stated goals - I need to point out what I see gently and ask questions on if the agent agrees. If I don't see/ can't interpret an explicit issue - what intervention would provide valuable feedback here - questions, guidance, validation, or giving a soft go-ahead with reminders of best practices?\n4. In case the plan looks to be accurate - based on the context, can I remind the agent of how to continue, what not to forget, or should I soften and step back for the agent to continue its work? What's the most helpful thing I can do right now?`;
let learningContext = '';
if (process.env.USE_LEARNING_HISTORY === 'true') {
learningContext = getLearningContextText();
}
const rules = input.sessionId ? getConstitution(input.sessionId) : [];
const constitutionBlock = rules.length ? `\nConstitution:\n${rules.map(r => `- ${r}`).join('\n')}` : '';
const contextSection = `CONTEXT:\nHistory Context: ${input.historySummary || 'None'}\n${learningContext ? `Learning Context:\n${learningContext}` : ''}\nGoal: ${input.goal}\nPlan: ${input.plan}\nProgress: ${input.progress || 'None'}\nUncertainties: ${input.uncertainties?.join(', ') || 'None'}\nTask Context: ${input.taskContext || 'None'}\nUser Prompt: ${input.userPrompt || 'None'}${constitutionBlock}`;
const fullPrompt = `${systemPrompt}\n\n${contextSection}`;
let responseText = '';
if (provider === 'gemini') {
await ensureGemini();
if (!genAI) throw new Error('Gemini API key missing.');
const geminiModel = model || 'gemini-2.5-pro';
const fallbackModel = 'gemini-2.5-flash';
try {
console.log(`Attempting to use Gemini model: ${geminiModel}`);
// console.error('Full Prompt:', fullPrompt); // Keep this commented out for now
const modelInstance = genAI.getGenerativeModel({ model: geminiModel });
const result = await modelInstance.generateContent(fullPrompt);
responseText = result.response.text();
} catch (error) {
console.error(`Gemini model ${geminiModel} failed. Trying fallback ${fallbackModel}.`, error);
// console.error('Full Prompt:', fullPrompt); // Keep this commented out for now
const fallbackModelInstance = genAI.getGenerativeModel({ model: fallbackModel });
const result = await fallbackModelInstance.generateContent(fullPrompt);
responseText = result.response.text();
}
} else if (provider === 'openai') {
await ensureOpenAI();
if (!openaiClient) throw new Error('OpenAI API key missing.');
const openaiModel = model || 'o4-mini';
console.log(`Using OpenAI model: ${openaiModel}`);
const response = await openaiClient.chat.completions.create({
model: openaiModel,
messages: [{ role: 'system', content: fullPrompt }],
});
responseText = response.choices[0].message.content || '';
} else if (provider === 'openrouter') {
if (!process.env.OPENROUTER_API_KEY) throw new Error('OpenRouter API key missing.');
if (!model) throw new Error('OpenRouter provider requires a model to be specified in the tool call.');
console.log(`Using OpenRouter model: ${model}`);
const { default: axios } = await import('axios');
const response = await axios.post(`${openrouterBaseUrl}/chat/completions`, {
model: model,
messages: [{ role: 'system', content: fullPrompt }],
}, { headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`, 'HTTP-Referer': 'http://localhost', 'X-Title': 'Vibe Check MCP Server' } });
responseText = response.data.choices[0].message.content || '';
} else {
throw new Error(`Invalid provider specified: ${provider}`);
}
return {
questions: responseText,
};
}
// The exported function is now a wrapper around the dispatcher
export async function getMetacognitiveQuestions(input: QuestionInput): Promise<QuestionOutput> {
try {
return await generateResponse(input);
} catch (error) {
console.error('Error getting metacognitive questions:', error);
// Fallback questions
return {
questions: `\nI can see you're thinking through your approach, which shows thoughtfulness:\n\n1. Does this plan directly address what the user requested, or might it be solving a different problem?\n2. Is there a simpler approach that would meet the user's needs?\n3. What unstated assumptions might be limiting the thinking here?\n4. How does this align with the user's original intent?\n`,
};
}
}
// Testing helpers
export const __testing = {
setGenAI(client: any) { genAI = client; },
setOpenAIClient(client: any) { openaiClient = client; },
getGenAI() { return genAI; },
getOpenAIClient() { return openaiClient; }
};
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import dotenv from 'dotenv';
dotenv.config();
import express from 'express';
import cors from 'cors';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { McpError, ErrorCode, ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { vibeCheckTool, VibeCheckInput, VibeCheckOutput } from './tools/vibeCheck.js';
import { vibeLearnTool, VibeLearnInput, VibeLearnOutput } from './tools/vibeLearn.js';
import { updateConstitution, resetConstitution, getConstitution } from './tools/constitution.js';
import { STANDARD_CATEGORIES, LearningType } from './utils/storage.js';
import { loadHistory } from './utils/state.js';
const IS_DISCOVERY = process.env.MCP_DISCOVERY_MODE === '1';
const USE_STDIO = process.env.MCP_TRANSPORT === 'stdio';
if (USE_STDIO) {
console.log = (...args) => console.error(...args);
}
async function main() {
await loadHistory();
const server = new Server(
{ name: 'vibe-check', version: '2.5.0' },
{ capabilities: { tools: {}, sampling: {} } }
);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'vibe_check',
description: 'Metacognitive questioning tool that identifies assumptions and breaks tunnel vision to prevent cascading errors',
inputSchema: {
type: 'object',
properties: {
goal: {
type: 'string',
description: "The agent's current goal",
examples: ['Ship CPI v2.5 with zero regressions']
},
plan: {
type: 'string',
description: "The agent's detailed plan",
examples: ['1) Write tests 2) Refactor 3) Canary rollout']
},
modelOverride: {
type: 'object',
properties: {
provider: { type: 'string', enum: ['gemini', 'openai', 'openrouter'] },
model: { type: 'string' }
},
required: [],
examples: [{ provider: 'gemini', model: 'gemini-2.5-pro' }]
},
userPrompt: {
type: 'string',
description: 'The original user prompt',
examples: ['Summarize the repo']
},
progress: {
type: 'string',
description: "The agent's progress so far",
examples: ['Finished step 1']
},
uncertainties: {
type: 'array',
items: { type: 'string' },
description: "The agent's uncertainties",
examples: [['uncertain about deployment']]
},
taskContext: {
type: 'string',
description: 'The context of the current task',
examples: ['repo: vibe-check-mcp @2.5.0']
},
sessionId: {
type: 'string',
description: 'Optional session ID for state management',
examples: ['session-123']
}
},
required: ['goal', 'plan'],
additionalProperties: false
}
},
{
name: 'vibe_learn',
description: 'Pattern recognition system that tracks common errors and solutions to prevent recurring issues',
inputSchema: {
type: 'object',
properties: {
mistake: {
type: 'string',
description: 'One-sentence description of the learning entry',
examples: ['Skipped writing tests']
},
category: {
type: 'string',
description: `Category (standard categories: ${STANDARD_CATEGORIES.join(', ')})`,
enum: STANDARD_CATEGORIES,
examples: ['Premature Implementation']
},
solution: {
type: 'string',
description: 'How it was corrected (if applicable)',
examples: ['Added regression tests']
},
type: {
type: 'string',
enum: ['mistake', 'preference', 'success'],
description: 'Type of learning entry',
examples: ['mistake']
},
sessionId: {
type: 'string',
description: 'Optional session ID for state management',
examples: ['session-123']
}
},
required: ['mistake', 'category'],
additionalProperties: false
}
},
{
name: 'update_constitution',
description: 'Append a constitutional rule for this session (in-memory)',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', examples: ['session-123'] },
rule: { type: 'string', examples: ['Always write tests first'] }
},
required: ['sessionId', 'rule'],
additionalProperties: false
}
},
{
name: 'reset_constitution',
description: 'Overwrite all constitutional rules for this session',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', examples: ['session-123'] },
rules: {
type: 'array',
items: { type: 'string' },
examples: [['Be kind', 'Avoid loops']]
}
},
required: ['sessionId', 'rules'],
additionalProperties: false
}
},
{
name: 'check_constitution',
description: 'Return the current constitution rules for this session',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', examples: ['session-123'] }
},
required: ['sessionId'],
additionalProperties: false
}
}
]
}));
server.setRequestHandler(CallToolRequestSchema, async (req) => {
const { name, arguments: raw } = req.params;
const args: any = raw;
switch (name) {
case 'vibe_check': {
const missing: string[] = [];
if (!args || typeof args.goal !== 'string') missing.push('goal');
if (!args || typeof args.plan !== 'string') missing.push('plan');
if (missing.length) {
const example = '{"goal":"Ship CPI v2.5","plan":"1) tests 2) refactor 3) canary"}';
if (IS_DISCOVERY) {
return { content: [{ type: 'text', text: `discovery: missing [${missing.join(', ')}]; example: ${example}` }] };
}
throw new McpError(ErrorCode.InvalidParams, `Missing: ${missing.join(', ')}. Example: ${example}`);
}
const input: VibeCheckInput = {
goal: args.goal,
plan: args.plan,
modelOverride: typeof args.modelOverride === 'object' && args.modelOverride !== null ? args.modelOverride : undefined,
userPrompt: typeof args.userPrompt === 'string' ? args.userPrompt : undefined,
progress: typeof args.progress === 'string' ? args.progress : undefined,
uncertainties: Array.isArray(args.uncertainties) ? args.uncertainties : undefined,
taskContext: typeof args.taskContext === 'string' ? args.taskContext : undefined,
sessionId: typeof args.sessionId === 'string' ? args.sessionId : undefined,
};
const result = await vibeCheckTool(input);
return { content: [{ type: 'text', text: formatVibeCheckOutput(result) }] };
}
case 'vibe_learn': {
const missing: string[] = [];
if (!args || typeof args.mistake !== 'string') missing.push('mistake');
if (!args || typeof args.category !== 'string') missing.push('category');
if (missing.length) {
const example = '{"mistake":"Skipped tests","category":"Feature Creep"}';
if (IS_DISCOVERY) {
return { content: [{ type: 'text', text: `discovery: missing [${missing.join(', ')}]; example: ${example}` }] };
}
throw new McpError(ErrorCode.InvalidParams, `Missing: ${missing.join(', ')}. Example: ${example}`);
}
const input: VibeLearnInput = {
mistake: args.mistake,
category: args.category,
solution: typeof args.solution === 'string' ? args.solution : undefined,
type: ['mistake', 'preference', 'success'].includes(args.type as string)
? (args.type as LearningType)
: undefined,
sessionId: typeof args.sessionId === 'string' ? args.sessionId : undefined
};
const result = await vibeLearnTool(input);
return { content: [{ type: 'text', text: formatVibeLearnOutput(result) }] };
}
case 'update_constitution': {
const missing: string[] = [];
if (!args || typeof args.sessionId !== 'string') missing.push('sessionId');
if (!args || typeof args.rule !== 'string') missing.push('rule');
if (missing.length) {
const example = '{"sessionId":"123","rule":"Always write tests first"}';
if (IS_DISCOVERY) {
return { content: [{ type: 'text', text: `discovery: missing [${missing.join(', ')}]; example: ${example}` }] };
}
throw new McpError(ErrorCode.InvalidParams, `Missing: ${missing.join(', ')}. Example: ${example}`);
}
updateConstitution(args.sessionId, args.rule);
console.log('[Constitution:update]', { sessionId: args.sessionId, count: getConstitution(args.sessionId).length });
return { content: [{ type: 'text', text: '✅ Constitution updated' }] };
}
case 'reset_constitution': {
const missing: string[] = [];
if (!args || typeof args.sessionId !== 'string') missing.push('sessionId');
if (!args || !Array.isArray(args.rules)) missing.push('rules');
if (missing.length) {
const example = '{"sessionId":"123","rules":["Be kind","Avoid loops"]}';
if (IS_DISCOVERY) {
return { content: [{ type: 'text', text: `discovery: missing [${missing.join(', ')}]; example: ${example}` }] };
}
throw new McpError(ErrorCode.InvalidParams, `Missing: ${missing.join(', ')}. Example: ${example}`);
}
resetConstitution(args.sessionId, args.rules);
console.log('[Constitution:reset]', { sessionId: args.sessionId, count: getConstitution(args.sessionId).length });
return { content: [{ type: 'text', text: '✅ Constitution reset' }] };
}
case 'check_constitution': {
const missing: string[] = [];
if (!args || typeof args.sessionId !== 'string') missing.push('sessionId');
if (missing.length) {
const example = '{"sessionId":"123"}';
if (IS_DISCOVERY) {
return { content: [{ type: 'text', text: `discovery: missing [${missing.join(', ')}]; example: ${example}` }] };
}
throw new McpError(ErrorCode.InvalidParams, `Missing: ${missing.join(', ')}. Example: ${example}`);
}
const rules = getConstitution(args.sessionId);
console.log('[Constitution:check]', { sessionId: args.sessionId, count: rules.length });
return { content: [{ type: 'json', json: { rules } }] };
}
default:
throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
}
});
const app = express();
const allowedOrigin = process.env.CORS_ORIGIN || '*';
app.use(cors({ origin: allowedOrigin }));
app.use(express.json());
if (USE_STDIO) {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('[MCP] stdio transport connected');
} else {
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);
app.post('/mcp', async (req, res) => {
const started = Date.now();
const { id, method } = req.body ?? {};
const sessionId = req.body?.params?.sessionId || req.body?.params?.arguments?.sessionId;
console.log('[MCP] request', { id, method, sessionId });
try {
await transport.handleRequest(req, res, req.body);
} catch (e: any) {
console.error('[MCP] error', { err: e?.message, id });
if (!res.headersSent) {
res.status(500).json({ jsonrpc: '2.0', id: id ?? null, error: { code: -32603, message: 'Internal server error' } });
}
} finally {
console.log('[MCP] handled', { id, ms: Date.now() - started });
}
});
app.get('/mcp', (_req, res) => {
res.status(405).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed' }, id: null });
});
app.get('/healthz', (_req, res) => {
res.status(200).json({ status: 'ok' });
});
const PORT = Number(process.env.MCP_HTTP_PORT || process.env.PORT || 3000);
const listener = app.listen(PORT, () => {
const addr = listener.address();
const actualPort = typeof addr === 'object' && addr ? addr.port : PORT;
console.log(`[MCP] HTTP listening on :${actualPort}`);
});
const close = () => listener.close(() => process.exit(0));
process.on('SIGTERM', close);
process.on('SIGINT', close);
}
}
function formatVibeCheckOutput(result: VibeCheckOutput): string {
return result.questions;
}
function formatVibeLearnOutput(result: VibeLearnOutput): string {
let output = '';
if (result.added) {
output += `✅ Pattern logged successfully (category tally: ${result.currentTally})`;
} else if (result.alreadyKnown) {
output += 'ℹ️ Pattern already recorded';
} else {
output += '❌ Failed to log pattern';
}
if (result.topCategories && result.topCategories.length > 0) {
output += '\n\n## Top Pattern Categories\n';
for (const category of result.topCategories) {
output += `\n### ${category.category} (${category.count} occurrences)\n`;
if (category.recentExample) {
output += `Most recent: "${category.recentExample.mistake}"\n`;
output += `Solution: "${category.recentExample.solution}"\n`;
}
}
}
return output;
}
main().catch((error) => {
console.error('Server startup error:', error);
process.exit(1);
});
```