general MCP Server
Vibe Check is a tool that provides mentor-like feedback to AI Agents, preventing tunnel-vision, over-engineering and reasoning lock-in for complex and long-horizon agent workflows. KISS your over-eager AI Agents goodbye! Effective for: Coding, Ambiguous Tasks, High-Risk tasks
Discovered via unknown and last synced 2mo ago.
1. Install the package
npx -y @pv-bhat/vibe-check-mcp start --stdio
2. Add to claude_desktop_config.json
{
"mcpServers": {
"-pv-bhat-vibe-check-mcp": {
"command": "npx",
"args": [
"@pv-bhat/vibe-check-mcp"
]
}
}
}Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
anthropic DEFAULT_LLM_PROVIDER=gemini DEFAULT_MODEL=gemini-2.5-pro ``` #### Configuration See [docs/TESTING.md]() for instructions on how to run tests. ### Docker The repository includes a helper script for one-command setup. ```bash bash scripts/docker-setup.sh ``` See [Automatic Docker Setup](./docs/docker-automation.md) for full details. ### Provider keys See [API Keys & Secret Management](./docs/api-keys.md) for supported providers, resolution order, storage locations, and security guidance. ### Transport selection The CLI supports stdio and HTTP transports. Transport resolution follows this order: explicit flags (`--stdio`/`--http`) → `MCP_TRANSPORT` → default `stdio`. When using HTTP, specify `--port` (or set `MCP_HTTP_PORT`); the default port is **2091**. The generated entries add `--stdio` or `--http --port <n>` accordingly, and HTTP-capable clients also receive a `http://127.0.0.1:<port>` endpoint. ### Client installers Each installer is idempotent and tags entries with `"managedBy": "vibe-check-mcp-cli"`. Backups are written once per run before changes are applied, and merges are atomic (`*.bak` files make rollback easy). See [docs/clients.md](./docs/clients.md) for deeper client-specific references. #### Claude Desktop - Config path: `claude_desktop_config.json` (auto-discovered per platform). - Default transport: stdio (`npx … start --stdio`). - Restart Claude Desktop after installation to load the new MCP server. - If an unmanaged entry already exists for `vibe-check-mcp`, the CLI leaves it untouched and prints a warning. #### Cursor - Config path: `~/.cursor/mcp.json` (provide `--config` if you store it elsewhere). - Schema mirrors Claude’s `mcpServers` layout. - If the file is missing, the CLI prints a ready-to-paste JSON block for Cursor’s settings panel instead of failing. #### Windsurf (Cascade) - Config path: legacy `~/.codeium/windsurf/mcp_config.json`, new builds use `~/.codeium/mcp_config.json`. - Pass `--http` to emit an entry with `serverUrl` for Windsurf’s HTTP client. - Existing sentinel-managed `serverUrl` entries are preserved and updated in place. #### Visual Studio Code - Workspace config lives at `.vscode/mcp.json`; profiles also store `mcp.json` in your VS Code user data directory. - Provide `--config <path>` to target a workspace file. Without `--config`, the CLI prints a JSON snippet and a `vscode:mcp/install?...` link you can open directly from the terminal. - VS Code supports optional dev fields; pass `--dev-watch` and/or `--dev-debug <value>` to populate `dev.watch`/`dev.debug`. ### Uninstall & rollback - Restore the backup generated during installation (the newest `*.bak` next to your config) to revert immediately. - To remove the server manually, delete the `vibe-check-mcp` entry under `mcpServers` (Claude/Windsurf/Cursor) or `servers` (VS Code) as long as it is still tagged with `"managedBy": "vibe-check-mcp-cli"`. ## 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 ```mermaid flowchart TD A[Agent Phase] --> B{Monitor Progress} B -- high risk --> C[CPI Interrupt] C --> D[Reflect & Adjust] B -- smooth --> E[Continue] ``` ## 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
Description
## What's New in v2.8.1 (Maintenance Release) > **Maintenance Notice:** This project is in maintenance mode and is no longer under active feature development. It remains fully functional and available under the MIT license. Community forks are welcome. For details, see the [Changelog](./docs/changelog.md). - **npm release:** v2.8.0 was never published to npm; v2.8.1 ships all of its fixes to the registry, including everything below - **Bug fix (v2.8.0):** `check_constitution` now returns valid MCP content types (fixes #84) - **Security (v2.8.0):** All dependencies updated — resolves 14 npm audit vulnerabilities (axios, MCP SDK, diff, express, and transitive deps) - **MCP SDK 1.26 (v2.8.0):** Updated to latest SDK with critical cross-client data leakage fix; HTTP transport adapter updated for compatibility - **Housekeeping:** registry metadata (`server.json`, `smithery.yaml`, `CITATION.cff`) re-synced to the release version, dev-only vitest advisory cleared, GitHub Releases automated on tag push ## Session Constitution (per-session rules) Use a lightweight “constitution” to enforce rules per `sessionId` that CPI will honor. Eg. constitution rules: “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 ## Development Setup ```bash # Clone and install git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git cd vibe-check-mcp-server npm ci npm run build npm test ``` Use **npm** for all workflows (`npm ci`, `npm run build`, `npm test`). This project targets Node **>=20**. Create a `.env` file with the API keys you plan to use: ```bash # Gemini (default) GEMINI_API_KEY=your_gemini_api_key # Optional providers / Anthropic-compatible endpoints OPENAI_API_KEY=your_openai_api_key OPENROUTER_API_KEY=your_openrouter_api_key ANTHROPIC_API_KEY=your_anthropic_api_key ANTHROPIC_AUTH_TOKEN=your_proxy_bearer_token ANTHROPIC_BASE_URL=https://api.anthropic.com ANTHROPIC_VERSION=2023-06-01 # Optional overrides # DEFAULT_LLM_PROVIDER accepts gemini