@vibecheckai/mcp-server

VibeCheck — AI Code Firewall

MCP Server for hallucination prevention in AI-assisted development

---

What is this?

The VibeCheck MCP Server provides AI agents (like Claude, Cursor, Windsurf) with tools to prevent hallucinations in generated code. It integrates directly with MCP-compatible clients to:

- Block ghost routes - Prevent AI from referencing API endpoints that don't exist
- Validate environment variables - Ensure env vars exist before they're used
- Enforce file locks - Protect critical files from AI modification
- Generate truthpacks - Create a source of truth from your codebase
- Provide smart context - Give AI accurate information about your project

---

Installation

``bash


npm

npm install -g @vibecheckai/mcp-server

pnpm

pnpm add -g @vibecheckai/mcp-server

yarn

yarn global add @vibecheckai/mcp-server
`

---

Quick Start

$3

Add to your Cursor MCP settings (~/.cursor/mcp.json):

`json
{
"mcpServers": {
"vibecheck": {
"command": "vibecheck-mcp"
}
}
}
`

$3

Add to your Claude MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json):

`json
{
"mcpServers": {
"vibecheck": {
"command": "vibecheck-mcp"
}
}
}
`

$3

`bash


Start with stdio (default, for Cursor/Claude)

vibecheck-mcp

Start HTTP server (for custom integrations)

vibecheck-mcp --http --port 3001

Start WebSocket server (for real-time connections)

vibecheck-mcp --websocket --port 3002

Show help

vibecheck-mcp --help
`

---

Available Tools

$3

| Tool | Description |
|------|-------------|
| truthpack_generate | Scan codebase and generate truthpack (routes, env, auth, contracts) |
| truthpack_query | Query truthpack for specific information |
| truthpack_validate | Validate truthpack against current codebase |
| truthpack_routes | Get API routes with filtering |
| truthpack_env | Get environment variables (required/optional) |

$3

| Tool | Description |
|------|-------------|
| firewall_evaluate | Full evaluation with evidence resolution |
| firewall_quick_check | Fast hallucination check |
| firewall_get_tier | Get confidence tier for a rule |
| firewall_should_block | Check if tier should block |
| firewall_tier_stats | Get statistics by confidence tier |
| firewall_set_mode | Set mode (observe/enforce/lockdown) |

$3

| Tool | Description |
|------|-------------|
| context_gather | Gather AI context for a coding task |
| context_file | Get context for a specific file |
| context_smart | Smart context based on task description |

$3

| Tool | Description |
|------|-------------|
| validate_code | Validate generated code against truthpack |
| validate_imports | Check import statements |
| validate_api_calls | Verify API endpoint usage |

$3

| Tool | Description |
|------|-------------|
| intent_set | Set current coding intent/spec |
| intent_get | Get active intent |
| intent_clear | Clear current intent |
| intent_validate | Validate code against intent |

$3

| Tool | Description |
|------|-------------|
| hook_pre_generation | Pre-generation checks with enhanced context |
| hook_post_generation | Validate generated code for issues |
| hook_file_write | Validate file write operations |

$3

| Tool | Description |
|------|-------------|
| lock_check | Check if file/folder is locked |
| lock_list | Get all locked files/folders |

$3

| Tool | Description |
|------|-------------|
| forge_generate | Generate AI context rules for .cursor/rules |
| forge_scan | Scan codebase for rule generation |

$3

| Tool | Description |
|------|-------------|
| docguard_check | Check documentation quality |
| docguard_validate | Validate docs against code |

$3

| Tool | Description |
|------|-------------|
| translate_nl_to_isl | Convert natural language to ISL spec |
| translate_isl_to_checks | Convert ISL to validation checks |

---

Confidence Tiers

The firewall uses three confidence tiers:

| Tier | Confidence | Behavior |
|------|------------|----------|
| hard_block | High | Ghost routes, missing env vars → Always blocks |
| soft_block | Medium | Dynamic routes, patterns → Blocks in enforce mode |
| warn | Low | Style issues, best practices → Warning only |

---

Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| VIBECHECK_MODE | Mode (local/cloud/hybrid) | local |
| VIBECHECK_TRANSPORT | Transport (stdio/http/websocket) | stdio |
| VIBECHECK_PORT | Port for HTTP/WS | 3001 |
| VIBECHECK_HOST | Host for HTTP/WS | localhost |
| VIBECHECK_PROJECT_ROOT | Project root path | process.cwd() |

---

Example Usage

Once the MCP server is connected, AI agents can use tools like:

`
User: Add a new API endpoint for user profiles

AI (using truthpack_routes): Let me check existing routes...
Found 15 routes. Similar patterns: GET /api/v1/users/:id

AI (using hook_pre_generation): Running pre-generation checks...
✓ No conflicts with existing routes
✓ Auth patterns identified

AI: I'll create GET /api/v1/users/:id/profile following your existing patterns...
`

---

Development

`bash


Clone the monorepo

git clone https://github.com/vibecheckai/vibecheck.git
cd vibecheck

Install dependencies

pnpm install

Build MCP server

pnpm --filter @vibecheckai/mcp-server build

Run tests

pnpm --filter @vibecheckai/mcp-server test

Start in dev mode

pnpm --filter @vibecheckai/mcp-server dev
``

---

Related Packages

- vibecheck-ai - CLI tool
- VibeCheck VS Code Extension - VS Code integration

---

Changelog

$3

- Enhanced Tool Set - All MCP tools verified and tested
- Improved Firewall - Better confidence tier evaluation
- Context Tools - Smarter context gathering for AI agents
- Performance - Faster truthpack generation and validation
- Stability - Various bug fixes and improvements

$3

- Bug fixes and stability improvements

$3

- Added confidence tiers (hard_block, soft_block, warn)
- Added tier statistics tool
- Improved firewall evaluation
- Added DocGuard and Translator tools

$3

- Initial release
- Truthpack management tools
- Firewall evaluation
- Context gathering
- ISL (Intent Specification Language) support

---

License

MIT © VibeCheck Team

---

Website •
Twitter