@vibecheckai/mcp-standard

v4.0.0

Published

21 days ago

VibeCheck MCP Standard - The official Model Context Protocol implementation for AI agent security, firewall enforcement, and intent-based development

VibeCheck MCP Standard

What is MCP Standard?

VibeCheck MCP Standard is the official, production-ready implementation of the Model Context Protocol for AI agent security. It provides:

Intent-Based Security: Agents declare intent before making changes
Hallucination Detection: Catch fake APIs, phantom methods, and invented routes
Claim Verification: Verify what AI agents claim they did
Firewall Enforcement: Block unauthorized actions in real-time

Integrations

| Platform | Package | Status | |----------|---------|--------| | GitHub Actions | vibecheck/vibecheck-action | Production | | CI Pipelines | @vibecheck/ci-sdk | Production | | Cursor IDE | Native MCP | Production | | Claude Desktop | Native MCP | Production | | Windsurf | Native MCP | Production |

Why VibeCheck MCP Standard Exists

LLMs hallucinate tools, APIs, routes, and success states.

Traditional linters run after the damage is done. By the time you catch a fake API call or phantom library method, the code is already committed.

VibeCheck MCP intercepts AI actions BEFORE execution and requires proof before allowing writes, commits, or tool calls.

┌─────────────────────────────────────────────────────────────────┐
│                    THE HALLUCINATION PROBLEM                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   AI Agent: "I'll call the /api/v2/users endpoint"              │
│                                                                  │
│   Reality:  That endpoint doesn't exist.                         │
│             The AI made it up.                                   │
│             It will fail at runtime.                             │
│                                                                  │
│   Traditional Tools: ✗ Catch this AFTER code is written         │
│   VibeCheck MCP:     ✓ Block this BEFORE code is written        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                         AI IDE / Agent                           │
│                  (Cursor, Claude, Windsurf, etc.)                │
└────────────────────────────┬─────────────────────────────────────┘
                             │ MCP Protocol
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│                      VibeCheck MCP Server                        │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐     │
│  │ Agent Firewall │  │  Proof Engine  │  │ Context Manager│     │
│  │  (Intent-based │  │  (Reality Mode │  │  (Smart file   │     │
│  │   gating)      │  │   + Audit)     │  │   selection)   │     │
│  └───────┬────────┘  └───────┬────────┘  └───────┬────────┘     │
│          │                   │                   │               │
│          ▼                   ▼                   ▼               │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    VibeCheck CLI Engine                      ││
│  │   audit · ship · prove · fix · reality · forge · checkpoint  ││
│  └─────────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│                        Your Codebase                             │
│         (Protected by intent verification & proof gates)         │
└──────────────────────────────────────────────────────────────────┘

Used in Production

Cursor IDE - Deep MCP integration with Agent Firewall
Claude Desktop - Intent-based code generation workflows
Windsurf - Real-time hallucination detection
CI/CD Pipelines - Automated proof generation and blocking

Tier Model v4.0

| Tier | Price | Commands | Focus | |------|-------|----------|-------| | FREE | $0/mo | 11 | Inspect & Observe | | PRO | $49/mo | 12 | Fix, Prove & Enforce |

FREE Tier ($0/mo)

100 scans/month
1,000 files/scan max
Report formats: HTML, MD, JSON
Agent Firewall: observe mode only

PRO Tier ($49/mo)

Unlimited scans
Unlimited files
All report formats: HTML, MD, JSON, SARIF, CSV, PDF
Agent Firewall: enforce mode
Full MCP server access

World-Class Features

Session Management

Complete agent session tracking with:

Trust Scoring: Dynamic trust score based on behavior (0-100)
Metrics Tracking: Success rates, latency, call counts by category
Health Monitoring: Automatic issue detection and reporting
Audit Trail: Complete history of all tool calls and state changes

Git Integration

Deep git integration for code change analysis:

Status Tracking: Staged, unstaged, untracked files with ahead/behind counts
Diff Analysis: Risk assessment for changes with pattern detection
Intent Verification: Check if changes match declared intent (PRO)
Snapshot Creation: Quick stash for saving work (PRO)
File History: Track changes to specific files

Context Management

Intelligent context handling for large codebases:

Project Analysis: Framework, language, structure detection
Smart Context Windows: Relevance-scored file selection for queries
Import Tracing: Find related files based on dependencies
File Categorization: Automatic categorization (api, component, config, etc.)

Performance & Caching

Built for speed with:

LRU Caching: Intelligent caching with TTL and eviction
Disk Persistence: Optional disk cache for expensive operations
Batch Operations: Efficient handling of multiple files

Agent Firewall

Control AI agent actions with intent-based security:

Intent-First Approach: Set intent before AI writes code
Three Modes: off, observe, enforce
Claim Verification: Verify AI claims against codebase state
Action Gating: Block sensitive operations without proper intent

Prompt Builder

Intelligent prompt templates for production-ready code:

50+ Templates: Authentication, API, database, frontend, testing, etc.
Auto-Detection: Detects best template from user input
Workspace Context: Automatically detects framework, database, styling
Quality Analysis: Scores prompts for completeness, specificity, clarity

CLI Integration

Full access to VibeCheck CLI commands:

audit - Security audit
ship - Deploy readiness
forge - Generate AI rules
fix - Auto-fix findings
checkpoint - Code snapshots
packs - Report bundles
reality - Browser testing

Installation

npm install @vibecheck/mcp-standard

Or run directly with npx:

npx @vibecheck/mcp-standard

Quick Start for CI/CD

# GitHub Actions - use the official action
- uses: vibecheck/vibecheck-action@v1
  with:
    api-key: ${{ secrets.VIBECHECK_API_KEY }}

# Or use the CI SDK
npm install @vibecheck/ci-sdk

Configuration

Cursor IDE

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "vibecheck": {
      "command": "npx",
      "args": ["@vibecheck/mcp-standard"],
      "env": {}
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vibecheck": {
      "command": "npx",
      "args": ["@vibecheck/mcp-standard"],
      "env": {}
    }
  }
}

With Workspace Path

{
  "mcpServers": {
    "vibecheck": {
      "command": "npx",
      "args": ["@vibecheck/mcp-standard", "--workspace", "/path/to/project"],
      "env": {}
    }
  }
}

With Firewall Mode

{
  "mcpServers": {
    "vibecheck": {
      "command": "npx",
      "args": ["@vibecheck/mcp-standard", "--firewall-mode", "observe"],
      "env": {}
    }
  }
}

Available Tools

FREE CLI Tools (11)

| Tool | Description | Tier | |------|-------------|------| | vibecheck_doctor | Health check on project setup | FREE | | vibecheck_audit | Comprehensive security audit | FREE | | vibecheck_forge | Generate AI rules (.cursorrules, etc.) | FREE | | vibecheck_packs | Generate report bundles (HTML, MD, JSON) | FREE | | vibecheck_tier | Get subscription tier and usage info | FREE |

PRO CLI Tools (12)

| Tool | Description | Tier | |------|-------------|------| | vibecheck_ship | Get ship verdict (SHIP/WARN/BLOCK) | 🔒 PRO | | vibecheck_fix | Plan or apply security fixes | 🔒 PRO | | vibecheck_checkpoint | Create/restore code snapshots | 🔒 PRO | | vibecheck_reality | Browser-based testing | 🔒 PRO |

Firewall Tools

| Tool | Description | Tier | |------|-------------|------| | firewall_status | Get current firewall status | FREE | | firewall_set_mode | Set firewall mode (enforce = PRO only) | FREE/🔒 PRO | | firewall_set_intent | Set intent before making changes | 🔒 PRO | | firewall_get_intent | Get current intent | 🔒 PRO | | firewall_clear_intent | Clear current intent | 🔒 PRO | | firewall_check | Run comprehensive shield check | 🔒 PRO | | firewall_verify_claim | Verify an AI claim | 🔒 PRO | | firewall_gate_action | Check if action is allowed | 🔒 PRO | | firewall_get_templates | Get intent templates | 🔒 PRO |

Prompt Builder Tools (FREE)

| Tool | Description | Tier | |------|-------------|------| | prompt_get_templates | Get available prompt templates | FREE | | prompt_get_categories | Get template categories | FREE | | prompt_detect_template | Detect template from input | FREE | | prompt_build | Build enhanced prompt | FREE | | prompt_get_context | Get workspace context | FREE | | prompt_get_suggestions | Get smart suggestions | FREE |

Session Management Tools (FREE)

| Tool | Description | Tier | |------|-------------|------| | session_info | Get current session info and metrics | FREE | | session_metrics | Detailed session statistics | FREE | | session_history | Recent tool call history | FREE | | session_health | Session health and trust score | FREE |

Git Integration Tools

| Tool | Description | Tier | |------|-------------|------| | git_status | Comprehensive git status | FREE | | git_diff | Diff analysis with risk assessment | FREE | | git_diff_intent_check | Check diff against declared intent | 🔒 PRO | | git_commits | Recent commit history | FREE | | git_branches | List all branches | FREE | | git_file_history | File commit history | FREE | | git_snapshot | Create git stash snapshot | 🔒 PRO |

Context Management Tools (FREE)

| Tool | Description | Tier | |------|-------------|------| | context_project | Project structure analysis | FREE | | context_window | Smart context window for queries | FREE | | context_find_files | Find files by pattern | FREE | | context_related_files | Find related files by imports | FREE | | context_file_info | Detailed file information | FREE |

Cache & Health Tools (FREE)

| Tool | Description | Tier | |------|-------------|------| | cache_stats | Cache hit rate and statistics | FREE | | cache_clear | Clear cache entries | FREE | | health_check | Comprehensive health check | FREE |

Available Resources

| URI | Description | |-----|-------------| | vibecheck://status | Server status and configuration | | vibecheck://tier | Subscription tier info | | vibecheck://session | Current session info | | vibecheck://firewall/stats | Firewall statistics | | vibecheck://firewall/log | Recent action log | | vibecheck://git/status | Git repository status | | vibecheck://context | Detected workspace context | | vibecheck://project | Project structure | | vibecheck://health | Health check status | | vibecheck://cache | Cache statistics |

Usage Examples

Setting Intent Before Code Changes

Agent: I'll set an intent first before making changes.

[Calls firewall_set_intent with template="Bug Fix"]

Now I can make minimal changes to fix the bug.

Building Enhanced Prompts

User: I need to add OAuth login with Google and GitHub

Agent: Let me build an enhanced prompt for that.

[Calls prompt_detect_template with input="OAuth login Google GitHub"]
[Calls prompt_build with templateId="auth-oauth" and answers]

Here's your production-ready implementation plan...

Verifying Claims

Agent: I only added a new API route, nothing else.

[Calls firewall_verify_claim with claim="I only added a new API route"]

Verification result: VERIFIED with 95% confidence

Firewall Modes

Off (FREE)

Firewall is disabled. All actions are allowed without restrictions.

Observe (FREE)

Firewall is active but permissive:

Actions are logged
Warnings are issued for sensitive operations without intent
No blocking occurs
Available on FREE tier

Enforce (🔒 PRO)

Firewall is strict:

Intent is required for write/execute/sensitive actions
Actions violating intent constraints are blocked
All actions are logged
Requires PRO subscription ($49/mo)

Intent Templates

Pre-defined templates for common tasks:

| Template | Constraints | |----------|-------------| | Add Auth | Use existing middleware, no new env vars, no billing changes | | Add Route | No new env vars, no auth changes, follow patterns | | Bug Fix | Minimal changes, no new deps, no unrelated refactoring | | Refactor | No behavior changes, preserve tests, no new features | | Add Feature | Use existing patterns, add tests, update docs | | Payment Flow | No auth changes, preserve integrations, add audit logging | | Database Migration | Create rollback, no data deletion, test in staging | | Dependency Update | One major version at a time, run tests, check breaking changes |

Programmatic Usage

import { VibecheckMcpServer } from '@vibecheck/mcp-standard';

const server = new VibecheckMcpServer({
  workspacePath: '/path/to/project',
  defaultFirewallMode: 'observe',
  logLevel: 'info',
});

await server.run();

Using Services Directly

import { CliService, FirewallService, PromptBuilderService } from '@vibecheck/mcp-standard';

// CLI Service
const cli = new CliService('/path/to/project');
const auditResult = await cli.audit();

// Firewall Service
const firewall = new FirewallService(cli);
await firewall.setIntent('Add new API route', ['No auth changes']);
const gateResult = firewall.gateAction('create file', 'write');

// Prompt Builder
const promptBuilder = new PromptBuilderService('/path/to/project');
const context = await promptBuilder.detectWorkspaceContext();
const prompt = await promptBuilder.buildPrompt('auth-oauth', 'Add OAuth', { providers: ['google'] });

Developer Mode

For local development only (blocked in production/CI):

VIBECHECK_DEV_PRO=1 NODE_ENV=development npx @vibecheck/mcp-standard

Security: This bypass is blocked when:

NODE_ENV=production
CI=true

Upgrading

vibecheck auth login
# Then visit: https://vibecheckai.dev/pricing

Requirements

Node.js >= 18.0.0
VibeCheck CLI (optional, for full functionality)

License

MIT