@vibecheckai/cli 3.9.1 → 4.0.0

package/mcp-server/SPEC.md

@@ -0,0 +1,583 @@
+# VibeCheck MCP Standard Protocol Specification
+
+**Version:** 1.0.0  
+**Status:** Production  
+**Last Updated:** 2026-01-28
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Protocol Basics](#protocol-basics)
+3. [Authentication](#authentication)
+4. [Tool Categories](#tool-categories)
+5. [Request/Response Schemas](#requestresponse-schemas)
+6. [Error Handling](#error-handling)
+7. [Firewall Protocol](#firewall-protocol)
+8. [Intent Verification](#intent-verification)
+9. [Tier System](#tier-system)
+
+---
+
+## Overview
+
+The VibeCheck MCP Standard defines a secure, intent-based protocol for AI agent interactions with development environments. It extends the Model Context Protocol (MCP) with security-first primitives for hallucination detection, claim verification, and action gating.
+
+### Design Principles
+
+1. **Intent-First**: Agents must declare intent before making changes
+2. **Verify, Don't Trust**: All AI claims are subject to verification
+3. **Fail-Safe**: Default to blocking when intent is unclear
+4. **Observable**: All actions are logged and auditable
+5. **Tiered Access**: Features are gated by subscription tier
+
+---
+
+## Protocol Basics
+
+### Transport
+
+The protocol operates over stdio transport as defined by MCP:
+
+```
+Client (IDE/Agent) <--stdio--> VibeCheck MCP Server
+```
+
+### Message Format
+
+All messages follow the MCP JSON-RPC 2.0 format:
+
+```typescript
+interface MCPRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+interface MCPResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: MCPError;
+}
+
+interface MCPError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+```
+
+---
+
+## Authentication
+
+### API Key Authentication
+
+Authentication is performed via the `VIBECHECK_API_KEY` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "vibecheck": {
+      "command": "npx",
+      "args": ["@vibecheck/mcp-standard"],
+      "env": {
+        "VIBECHECK_API_KEY": "vck_..."
+      }
+    }
+  }
+}
+```
+
+### Tier Resolution
+
+The server resolves the subscription tier at startup:
+
+```typescript
+interface TierInfo {
+  tier: "free" | "pro";
+  limits: {
+    scansPerMonth: number;      // 100 for free, unlimited for pro
+    filesPerScan: number;       // 1000 for free, unlimited for pro
+    firewallMode: FirewallMode; // "observe" for free, "enforce" for pro
+  };
+  usage: {
+    scansUsed: number;
+    resetDate: string;
+  };
+}
+```
+
+---
+
+## Tool Categories
+
+### Category: CLI Tools
+
+Tools that execute VibeCheck CLI commands.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `vibecheck_doctor` | FREE | Health check on project setup |
+| `vibecheck_audit` | FREE | Comprehensive security audit |
+| `vibecheck_forge` | FREE | Generate AI rules |
+| `vibecheck_packs` | FREE | Generate report bundles |
+| `vibecheck_tier` | FREE | Get subscription info |
+| `vibecheck_ship` | PRO | Get ship verdict |
+| `vibecheck_fix` | PRO | Plan or apply security fixes |
+| `vibecheck_checkpoint` | PRO | Create/restore code snapshots |
+| `vibecheck_reality` | PRO | Browser-based testing |
+
+### Category: Firewall Tools
+
+Tools for intent-based security enforcement.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `firewall_status` | FREE | Get current firewall status |
+| `firewall_set_mode` | FREE/PRO | Set firewall mode |
+| `firewall_set_intent` | PRO | Set intent before changes |
+| `firewall_get_intent` | PRO | Get current intent |
+| `firewall_clear_intent` | PRO | Clear current intent |
+| `firewall_check` | PRO | Run comprehensive shield check |
+| `firewall_verify_claim` | PRO | Verify an AI claim |
+| `firewall_gate_action` | PRO | Check if action is allowed |
+| `firewall_get_templates` | PRO | Get intent templates |
+
+### Category: Prompt Builder Tools
+
+Tools for enhanced prompt generation.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `prompt_get_templates` | FREE | Get available prompt templates |
+| `prompt_get_categories` | FREE | Get template categories |
+| `prompt_detect_template` | FREE | Detect template from input |
+| `prompt_build` | FREE | Build enhanced prompt |
+| `prompt_get_context` | FREE | Get workspace context |
+| `prompt_get_suggestions` | FREE | Get smart suggestions |
+
+### Category: Session Tools
+
+Tools for session management and monitoring.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `session_info` | FREE | Get session info and metrics |
+| `session_metrics` | FREE | Detailed session statistics |
+| `session_history` | FREE | Recent tool call history |
+| `session_health` | FREE | Session health and trust score |
+
+### Category: Git Tools
+
+Tools for git integration and change analysis.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `git_status` | FREE | Comprehensive git status |
+| `git_diff` | FREE | Diff analysis with risk assessment |
+| `git_diff_intent_check` | PRO | Check diff against declared intent |
+| `git_commits` | FREE | Recent commit history |
+| `git_branches` | FREE | List all branches |
+| `git_file_history` | FREE | File commit history |
+| `git_snapshot` | PRO | Create git stash snapshot |
+
+### Category: Context Tools
+
+Tools for intelligent context management.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `context_project` | FREE | Project structure analysis |
+| `context_window` | FREE | Smart context window for queries |
+| `context_find_files` | FREE | Find files by pattern |
+| `context_related_files` | FREE | Find related files by imports |
+| `context_file_info` | FREE | Detailed file information |
+
+### Category: Cache & Health Tools
+
+Tools for cache management and health monitoring.
+
+| Tool | Tier | Description |
+|------|------|-------------|
+| `cache_stats` | FREE | Cache hit rate and statistics |
+| `cache_clear` | FREE | Clear cache entries |
+| `health_check` | FREE | Comprehensive health check |
+
+---
+
+## Request/Response Schemas
+
+### vibecheck_audit
+
+**Request:**
+```typescript
+interface AuditRequest {
+  format?: "json" | "sarif" | "html" | "md";
+  severity?: "critical" | "high" | "medium" | "low";
+  category?: string;
+}
+```
+
+**Response:**
+```typescript
+interface AuditResult {
+  version: string;
+  timestamp: string;
+  attackScore: number;           // 0-100, lower is better
+  findings: AuditFinding[];
+  summary: {
+    total: number;
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+  };
+}
+
+interface AuditFinding {
+  id: string;
+  type: string;
+  severity: "critical" | "high" | "medium" | "low";
+  message: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  rule?: string;
+  howToFix?: string;
+  category?: string;
+}
+```
+
+### vibecheck_ship
+
+**Request:**
+```typescript
+interface ShipRequest {
+  mode?: "quick" | "full" | "strict";
+}
+```
+
+**Response:**
+```typescript
+interface ShipResult {
+  verdict: "SHIP" | "WARN" | "BLOCK";
+  score: number;                  // 0-100, higher is better
+  reasons: string[];
+  blockers?: string[];
+  timestamp: string;
+}
+```
+
+### firewall_set_intent
+
+**Request:**
+```typescript
+interface SetIntentRequest {
+  summary: string;                // What you intend to do
+  constraints: string[];          // Boundaries for the changes
+  templateId?: string;            // Optional: use a pre-defined template
+}
+```
+
+**Response:**
+```typescript
+interface Intent {
+  summary: string;
+  constraints: string[];
+  timestamp: string;
+  sessionId: string;
+  hash: string;                   // SHA-256 hash for verification
+}
+```
+
+### firewall_verify_claim
+
+**Request:**
+```typescript
+interface VerifyClaimRequest {
+  claim: string;                  // What the AI claims it did
+  context?: string;               // Additional context
+  files?: string[];               // Files to check
+}
+```
+
+**Response:**
+```typescript
+interface ClaimVerificationResult {
+  verified: boolean;
+  confidence: number;             // 0-100
+  verdict: "VERIFIED" | "SUSPICIOUS" | "REJECTED";
+  reasons: string[];
+  evidence?: ClaimEvidence[];
+}
+
+interface ClaimEvidence {
+  type: "file" | "code" | "behavior" | "config";
+  path?: string;
+  content?: string;
+  relevance: number;              // 0-100
+}
+```
+
+### firewall_gate_action
+
+**Request:**
+```typescript
+interface GateActionRequest {
+  action: string;                 // Description of the action
+  actionType: "read" | "write" | "execute" | "sensitive";
+  targetFiles?: string[];
+}
+```
+
+**Response:**
+```typescript
+interface FirewallVerdict {
+  allowed: boolean;
+  verdict: "ALLOW" | "WARN" | "BLOCK";
+  violations: FirewallViolation[];
+  unblockPlan?: UnblockPlan;
+}
+
+interface FirewallViolation {
+  type: string;
+  rule: string;
+  message: string;
+  file?: string;
+  severity: "critical" | "error" | "warning" | "info";
+}
+
+interface UnblockPlan {
+  reason: string;
+  steps: UnblockStep[];
+  estimatedTime?: string;
+}
+```
+
+---
+
+## Error Handling
+
+### Error Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| -32700 | Parse Error | Invalid JSON |
+| -32600 | Invalid Request | Malformed request |
+| -32601 | Method Not Found | Unknown tool |
+| -32602 | Invalid Params | Invalid parameters |
+| -32603 | Internal Error | Server error |
+| 1000 | AUTH_REQUIRED | Authentication required |
+| 1001 | AUTH_FAILED | Authentication failed |
+| 1002 | TIER_REQUIRED | Feature requires higher tier |
+| 1003 | RATE_LIMITED | Rate limit exceeded |
+| 1004 | FIREWALL_BLOCKED | Action blocked by firewall |
+| 1005 | INTENT_REQUIRED | Intent must be set first |
+| 1006 | INTENT_VIOLATION | Action violates declared intent |
+
+### Error Response Format
+
+```typescript
+interface MCPError {
+  code: number;
+  message: string;
+  data?: {
+    tier?: "free" | "pro";
+    requiredTier?: "pro";
+    unblockPlan?: UnblockPlan;
+    violations?: FirewallViolation[];
+  };
+}
+```
+
+---
+
+## Firewall Protocol
+
+### Modes
+
+| Mode | Tier | Behavior |
+|------|------|----------|
+| `off` | FREE | No enforcement, no logging |
+| `observe` | FREE | Log all actions, warn on violations |
+| `enforce` | PRO | Block actions that violate intent |
+
+### Action Types
+
+| Type | Description | Default Behavior |
+|------|-------------|------------------|
+| `read` | Reading files, querying state | Always allowed |
+| `write` | Creating or modifying files | Requires intent in enforce mode |
+| `execute` | Running commands, scripts | Requires intent in enforce mode |
+| `sensitive` | Auth, payments, env vars | Always requires intent |
+
+### Intent Flow
+
+```
+1. Agent calls firewall_set_intent with summary and constraints
+2. Server validates and stores intent with SHA-256 hash
+3. Agent performs actions
+4. Each action is checked against intent constraints
+5. In enforce mode, violating actions are blocked
+6. Agent calls firewall_clear_intent when done
+```
+
+### Intent Templates
+
+Pre-defined templates for common tasks:
+
+| Template ID | Name | Constraints |
+|-------------|------|-------------|
+| `add-auth` | Add Authentication | No new env vars, use existing middleware |
+| `add-route` | Add API Route | Follow existing patterns, no auth changes |
+| `bug-fix` | Bug Fix | Minimal changes, no new dependencies |
+| `refactor` | Refactoring | No behavior changes, preserve tests |
+| `add-feature` | Add Feature | Use existing patterns, add tests |
+| `payment-flow` | Payment Integration | No auth changes, add audit logging |
+| `db-migration` | Database Migration | Create rollback, no data deletion |
+| `dep-update` | Dependency Update | One major version, run tests |
+
+---
+
+## Intent Verification
+
+### Verification Flow
+
+```
+1. Agent makes a claim: "I only added a new API route"
+2. Server calls firewall_verify_claim
+3. Server analyzes:
+   - Git diff to see actual changes
+   - File history to detect modifications
+   - Code patterns to identify scope
+4. Server returns verdict with confidence score
+```
+
+### Verification Verdicts
+
+| Verdict | Confidence | Meaning |
+|---------|------------|---------|
+| `VERIFIED` | 80-100% | Claim matches evidence |
+| `SUSPICIOUS` | 40-79% | Partial match, review recommended |
+| `REJECTED` | 0-39% | Claim contradicts evidence |
+
+### Evidence Types
+
+| Type | Description |
+|------|-------------|
+| `file` | File was created, modified, or deleted |
+| `code` | Specific code patterns found |
+| `behavior` | Runtime behavior detected |
+| `config` | Configuration changes detected |
+
+---
+
+## Tier System
+
+### FREE Tier ($0/month)
+
+- 100 scans per month
+- 1,000 files per scan maximum
+- Observe mode firewall only
+- Report formats: HTML, MD, JSON
+- 11 CLI tools
+- Session management
+- Git integration (read-only)
+- Prompt builder
+
+### PRO Tier ($49/month)
+
+- Unlimited scans
+- Unlimited files
+- Enforce mode firewall
+- All report formats: HTML, MD, JSON, SARIF, CSV, PDF
+- 23 CLI tools (all)
+- Intent verification
+- Claim verification
+- Code checkpoints
+- Reality mode (browser testing)
+- Git snapshots
+
+### Tier Checking
+
+The server validates tier access before executing each tool:
+
+```typescript
+// Pseudo-code for tier validation
+async function validateTier(toolName: string, tier: Tier): Promise<void> {
+  const required = getRequiredTier(toolName);
+  if (required === 'pro' && tier === 'free') {
+    throw new MCPError(1002, 'This feature requires PRO tier', {
+      tier: 'free',
+      requiredTier: 'pro',
+      upgradeUrl: 'https://vibecheckai.dev/pricing'
+    });
+  }
+}
+```
+
+---
+
+## Resources
+
+MCP Resources provide read-only access to server state:
+
+| 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 |
+
+---
+
+## Appendix A: Full Type Definitions
+
+See [src/types.ts](./src/types.ts) for complete TypeScript type definitions.
+
+## Appendix B: Example Flows
+
+### Security Audit Flow
+
+```
+Client: tools/call vibecheck_audit { "severity": "high" }
+Server: { "result": { "attackScore": 23, "findings": [...] } }
+```
+
+### Intent-Based Development Flow
+
+```
+Client: tools/call firewall_set_intent { 
+  "summary": "Add user authentication with NextAuth",
+  "constraints": ["No new environment variables", "Use existing database"]
+}
+Server: { "result": { "hash": "abc123...", "timestamp": "..." } }
+
+Client: tools/call firewall_gate_action {
+  "action": "Create auth.ts file",
+  "actionType": "write"
+}
+Server: { "result": { "allowed": true, "verdict": "ALLOW" } }
+
+Client: tools/call firewall_verify_claim {
+  "claim": "I only added authentication without modifying the database schema"
+}
+Server: { "result": { "verified": true, "confidence": 95, "verdict": "VERIFIED" } }
+
+Client: tools/call firewall_clear_intent {}
+Server: { "result": { "cleared": true } }
+```
+
+---
+
+**Copyright © 2026 VibeCheck. MIT License.**