@vibecheckai/mcp-server

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

# npm
npm install -g @vibecheckai/mcp-server

# pnpm
pnpm add -g @vibecheckai/mcp-server

# yarn
yarn global add @vibecheckai/mcp-server

Quick Start

Cursor Integration

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

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

Claude Desktop

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

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

CLI Usage

# 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

Truthpack Tools

| 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) |

Firewall Tools

| 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) |

Context Tools

| 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 |

Validation Tools

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

Intent (ISL) Tools

| 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 |

Hook Tools

| 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 |

Lock Tools

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

Forge Tools

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

DocGuard Tools

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

Translator Tools

| 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

# 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

v1.2.0

• 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

v1.1.1

• Bug fixes and stability improvements

v1.1.0

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

v1.0.0

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

License

MIT © VibeCheck Team