npm package: @shipgateisl/vibecheck-mcp
Description: VibeCheck — AI Code Firewall | MCP Server for hallucination prevention in AI-assisted development
Author: VibeCheck Team
Latest version: 1.0.0

# @vibecheck/mcp-server

<p align="center">
  <strong>VibeCheck — AI Code Firewall</strong><br/>
  MCP Server for hallucination prevention in AI-assisted development
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@vibecheck/mcp-server"><img alt="npm version" src="https://img.shields.io/npm/v/@vibecheck/mcp-server?style=flat-square&color=CB3837&logo=npm" /></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
</p>

---

## 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 @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`):

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

### Claude Desktop

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

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

### CLI Usage

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

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

```bash
# 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](https://www.npmjs.com/package/vibecheck-ai) - CLI tool
- [VibeCheck VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Vibecheck-AI.vibecheck-ai) - 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

---

<p align="center">
  <a href="https://vibecheckai.dev">Website</a> •
  <a href="https://x.com/VibeCheck_AI">Twitter</a>
</p>