@vibecheckai/cli 3.9.1 → 4.0.1

package/mcp-server/README.md

@@ -1,211 +1,501 @@
-# vibecheck MCP Server v4.0
+# VibeCheck MCP Standard
 
-Professional Model Context Protocol server for vibecheck AI.
+<p align="center">
+  <strong>The Official Model Context Protocol Implementation for AI Agent Security</strong>
+</p>
 
-> "Stop shipping pretend features."
+<p align="center">
+  <a href="https://npmjs.com/package/@vibecheck/mcp-standard"><img src="https://img.shields.io/npm/v/@vibecheck/mcp-standard?style=flat-square" alt="npm version"></a>
+  <a href="https://npmjs.com/package/@vibecheck/mcp-standard"><img src="https://img.shields.io/npm/dm/@vibecheck/mcp-standard?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/guardiavault-oss/VIBEYCHECK/blob/main/mcp-server/SPEC.md"><img src="https://img.shields.io/badge/MCP-Standard%20v1.0-blue?style=flat-square" alt="MCP Standard"></a>
+</p>
 
-## Installation
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="./SPEC.md">Protocol Specification</a> •
+  <a href="#integrations">Integrations</a> •
+  <a href="#available-tools">Tools</a>
+</p>
 
-```bash
-npm install -g @vibecheckai/cli
-```
+---
 
-## Configuration
+## What is MCP Standard?
 
-Add to your AI IDE's MCP configuration:
+**VibeCheck MCP Standard** is the official, production-ready implementation of the Model Context Protocol for AI agent security. It provides:
 
-```json
-{
-  "mcpServers": {
-    "vibecheck": {
-      "command": "npx",
-      "args": ["@vibecheckai/cli", "mcp"]
-    }
-  }
-}
-```
-
-See [MCP-QUICK-START.md](../docs/MCP-QUICK-START.md) for editor-specific setup.
+- **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
 
-## Development
+### Integrations
 
-```bash
-cd mcp-server
-npm install
-npm start
-```
+| 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 |
 
 ---
 
-## Core MCP Tools (v4.0)
+## Why VibeCheck MCP Standard Exists
 
-These are the primary tools available via MCP:
+**LLMs hallucinate tools, APIs, routes, and success states.**
 
-| Tool | Description |
-|------|-------------|
-| `vibecheck_audit` | 🔍 Static analysis - routes, secrets, contracts |
-| `vibecheck_ship` | 🚀 Verdict engine - SHIP / WARN / BLOCK |
-| `vibecheck_prove` | 🔬 Full proof loop: audit → reality → ship |
-| `vibecheck_fix` | 🛠️ Mission-based auto-fix with safety gates |
-| `vibecheck_reality` | 🧪 Browser-based runtime verification |
-| `vibecheck_forge` | 📝 Generate AI IDE rules (.cursorrules, .windsurf) |
-| `vibecheck_shield` | 🛡️ Agent Firewall controls |
-| `vibecheck_doctor` | 🏥 Environment health check |
-| `vibecheck_checkpoint` | 📍 Snapshot & restore, baseline comparison |
-| `vibecheck_polish` | ✨ Production polish - final cleanup |
+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        │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-## Shield (Agent Firewall) Tools
+---
 
-Control the Agent Firewall via MCP:
+## Architecture
 
-| Tool | Description |
-|------|-------------|
-| `vibecheck_shield_status` | Get firewall status |
-| `vibecheck_shield_enforce` | Enable enforcement mode |
-| `vibecheck_shield_observe` | Enable observe-only mode |
-| `vibecheck_shield_lock` | Hard lockdown (all rules enforced) |
-| `vibecheck_shield_unlock` | Release lock |
-| `vibecheck_shield_verify` | Verify claims/prompts |
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         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)         │
+└──────────────────────────────────────────────────────────────────┘
+```
 
 ---
 
-## Intent & Approval Tools
-
-For declaring AI intent and approving changes:
+## Used in Production
 
-| Tool | Description |
-|------|-------------|
-| `vibecheck_intent_start` | 🎯 Declare intent before making changes |
-| `vibecheck_intent_check` | ✅ Check if changes align with stated intent |
-| `vibecheck_intent_complete` | ✅ Complete step and generate proof artifact |
-| `vibecheck_approve` | 👍 Review and approve session changes |
+- **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
 
 ---
 
-## Checkpoint Tools
+## 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
 
-Pre-write validation and time machine:
+## Installation
 
-| Tool | Description |
-|------|-------------|
-| `vibecheck_checkpoint` | 🛡️ Validate code before writing - blocks on issues |
-| `vibecheck_checkpoint_status` | 📊 Get current checkpoint status |
-| `vibecheck_checkpoint_restore` | ⏪ Restore to a previous checkpoint |
-| `vibecheck_checkpoint_compare` | 📈 Compare baseline vs current |
+```bash
+npm install @vibecheck/mcp-standard
+```
 
----
+Or run directly with npx:
 
-## Report & Artifact Tools
+```bash
+npx @vibecheck/mcp-standard
+```
 
-Generate outputs and evidence:
+### Quick Start for CI/CD
 
-| Tool | Description |
-|------|-------------|
-| `vibecheck_packs_evidence` | 📦 Bundle videos, traces, screenshots |
-| `vibecheck_packs_report` | 📄 Generate HTML/MD/SARIF reports |
-| `vibecheck_packs_graph` | 📊 Proof graph visualization |
-| `vibecheck_seal` | 🏆 Generate ship badge and attestation |
+```bash
+# 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
 
-## Example Usage
+### Cursor IDE
 
-### Run Analysis
+Add to your `.cursor/mcp.json`:
 
 ```json
 {
-  "tool": "vibecheck_audit",
-  "arguments": {
-    "path": ".",
-    "profile": "full"
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["@vibecheck/mcp-standard"],
+      "env": {}
+    }
   }
 }
 ```
 
-### Get Ship Verdict
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
-  "tool": "vibecheck_ship",
-  "arguments": {
-    "path": "."
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["@vibecheck/mcp-standard"],
+      "env": {}
+    }
   }
 }
 ```
 
-### Full Proof Loop
+### With Workspace Path
 
 ```json
 {
-  "tool": "vibecheck_prove",
-  "arguments": {
-    "url": "http://localhost:3000",
-    "maxFixRounds": 3
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["@vibecheck/mcp-standard", "--workspace", "/path/to/project"],
+      "env": {}
+    }
   }
 }
 ```
 
-### Runtime Verification
+### With Firewall Mode
 
 ```json
 {
-  "tool": "vibecheck_reality",
-  "arguments": {
-    "url": "http://localhost:3000",
-    "headed": false,
-    "maxPages": 18,
-    "maxDepth": 2
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["@vibecheck/mcp-standard", "--firewall-mode", "observe"],
+      "env": {}
+    }
   }
 }
 ```
 
-### AI-Powered Fixes
+## 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
 
-```json
-{
-  "tool": "vibecheck_fix",
-  "arguments": {
-    "apply": true,
-    "autopilot": false,
-    "maxMissions": 8
-  }
-}
 ```
+Agent: I'll set an intent first before making changes.
 
-### Generate IDE Rules
+[Calls firewall_set_intent with template="Bug Fix"]
 
-```json
-{
-  "tool": "vibecheck_forge",
-  "arguments": {
-    "format": "cursor",
-    "enhanced": true
-  }
-}
+Now I can make minimal changes to fix the bug.
 ```
 
----
+### Building Enhanced Prompts
 
-## Resources
+```
+User: I need to add OAuth login with Google and GitHub
 
-- `vibecheck://rules` - Generated AI rules
-- `vibecheck://truthpack` - Repo reality index
-- `vibecheck://status` - Server status and health
+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]
 
-## Documentation
+Here's your production-ready implementation plan...
+```
 
-- [MCP Quick Start](../docs/MCP-QUICK-START.md)
-- [Full CLI Documentation](../docs/CLI-REFERENCE.md)
-- [Agent Firewall Spec](../docs/AGENT_FIREWALL_V2_SPEC.md)
+### 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
+
+```typescript
+import { VibecheckMcpServer } from '@vibecheck/mcp-standard';
+
+const server = new VibecheckMcpServer({
+  workspacePath: '/path/to/project',
+  defaultFirewallMode: 'observe',
+  logLevel: 'info',
+});
+
+await server.run();
+```
+
+### Using Services Directly
+
+```typescript
+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):
+
+```bash
+VIBECHECK_DEV_PRO=1 NODE_ENV=development npx @vibecheck/mcp-standard
+```
+
+**Security:** This bypass is blocked when:
+- `NODE_ENV=production`
+- `CI=true`
+
+## Upgrading
+
+```bash
+vibecheck auth login
+# Then visit: https://vibecheckai.dev/pricing
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- VibeCheck CLI (optional, for full functionality)
 
-## Privacy & Trust
+## License
 
-- Runs locally
-- Artifacts saved to `.vibecheck/`
-- No upload unless you explicitly export/share
+MIT