@vibecheckdev/vibecheck-mcp

@vibecheck/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

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

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

# yarn
yarn global add @vibecheck/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 @vibecheck/mcp-server build

# Run tests
pnpm --filter @vibecheck/mcp-server test

# Start in dev mode
pnpm --filter @vibecheck/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

Website • Twitter