@vibecheckai/cli 3.9.1 → 4.0.1

package/mcp-server/src/server.ts

@@ -0,0 +1,1933 @@
+/**
+ * VibeCheck MCP Server
+ * Provides tools for Agent Firewall, Prompt Builder, and CLI integration
+ * 
+ * Tier Model v4.0:
+ * - FREE ($0/mo): Inspect & Observe - 11 commands
+ * - PRO ($49/mo): Fix, Prove & Enforce - 12 commands
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ErrorCode,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import {
+  CliService,
+  FirewallService,
+  PromptBuilderService,
+  TierService,
+  SessionService,
+  GitService,
+  CacheService,
+  ContextManager,
+} from './services/index.js';
+import type { McpServerConfig, McpServerState, FirewallMode } from './types.js';
+
+export class VibecheckMcpServer {
+  private server: Server;
+  private cliService: CliService;
+  private firewallService: FirewallService;
+  private promptBuilderService: PromptBuilderService;
+  private tierService: TierService;
+  private sessionService: SessionService;
+  private gitService: GitService;
+  private cacheService: CacheService;
+  private contextManager: ContextManager;
+  private config: McpServerConfig;
+  private state: McpServerState;
+
+  constructor(config: McpServerConfig = {}) {
+    this.config = config;
+    const workspacePath = config.workspacePath || process.cwd();
+
+    // Initialize core services
+    this.cliService = new CliService(workspacePath, config.cliPath);
+    this.firewallService = new FirewallService(this.cliService);
+    this.promptBuilderService = new PromptBuilderService(workspacePath);
+    this.tierService = new TierService();
+
+    // Initialize enhanced services
+    this.sessionService = new SessionService(workspacePath);
+    this.gitService = new GitService(workspacePath);
+    this.cacheService = new CacheService({ persistToDisk: true });
+    this.contextManager = new ContextManager(workspacePath);
+
+    // Initialize state
+    this.state = {
+      initialized: false,
+      cliAvailable: false,
+      firewallMode: config.defaultFirewallMode || 'off',
+      sessionId: `mcp_${Date.now()}`,
+      startTime: new Date().toISOString(),
+    };
+
+    // Create MCP server
+    this.server = new Server(
+      {
+        name: 'vibecheck-mcp-server',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+          resources: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  /**
+   * Check if a tool is allowed for the current tier
+   * Returns error response if not allowed
+   */
+  private checkTierAccess(toolName: string): { allowed: boolean; errorResponse?: { content: { type: 'text'; text: string }[]; isError: boolean } } {
+    const result = this.tierService.checkToolAccess(toolName);
+
+    if (result.allowed) {
+      return { allowed: true };
+    }
+
+    return {
+      allowed: false,
+      errorResponse: {
+        content: [{
+          type: 'text' as const,
+          text: this.tierService.formatTierError(result),
+        }],
+        isError: true,
+      },
+    };
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        // ═══════════════════════════════════════════════════════════════════════
+        // CLI Tools
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'vibecheck_doctor',
+          description: '[FREE] Run health check on the project. Checks CLI installation, environment, and project setup.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'vibecheck_audit',
+          description: '[FREE] Run a comprehensive security audit on the codebase. Returns findings with severity levels. FREE: 100 scans/month, 1000 files/scan. PRO: unlimited.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              path: {
+                type: 'string',
+                description: 'Optional path to audit (defaults to workspace root)',
+              },
+              severity: {
+                type: 'string',
+                enum: ['critical', 'high', 'medium', 'low'],
+                description: 'Minimum severity level to report',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'vibecheck_ship',
+          description: '[PRO] Get a ship verdict - whether the code is ready to deploy. Returns SHIP, WARN, or BLOCK.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'vibecheck_forge',
+          description: '[FREE] Generate AI rules (.cursorrules, CLAUDE.md) from the codebase analysis.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              output: {
+                type: 'string',
+                description: 'Output path for generated rules',
+              },
+              format: {
+                type: 'string',
+                enum: ['cursor', 'claude', 'all'],
+                description: 'Format of rules to generate',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'vibecheck_fix',
+          description: '[PRO] Plan or apply fixes for security findings. Use plan mode first to preview changes.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              mode: {
+                type: 'string',
+                enum: ['plan', 'apply'],
+                description: 'Whether to plan or apply fixes',
+              },
+              missionId: {
+                type: 'string',
+                description: 'Specific finding ID to fix',
+              },
+            },
+            required: ['mode'],
+          },
+        },
+        {
+          name: 'vibecheck_checkpoint',
+          description: '[PRO] Create, restore, or list code checkpoints (snapshots).',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              action: {
+                type: 'string',
+                enum: ['create', 'restore', 'list'],
+                description: 'Checkpoint action',
+              },
+              id: {
+                type: 'string',
+                description: 'Checkpoint ID (for restore)',
+              },
+            },
+            required: ['action'],
+          },
+        },
+        {
+          name: 'vibecheck_packs',
+          description: '[FREE] Generate report bundle. FREE: HTML, MD, JSON. PRO: + SARIF, CSV, PDF.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              format: {
+                type: 'string',
+                enum: ['html', 'zip', 'json', 'sarif', 'csv', 'pdf'],
+                description: 'Output format (sarif, csv, pdf require PRO)',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'vibecheck_reality',
+          description: '[PRO] Run browser-based reality testing on a URL.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              url: {
+                type: 'string',
+                description: 'URL to test',
+              },
+              headless: {
+                type: 'boolean',
+                description: 'Run in headless mode',
+              },
+            },
+            required: ['url'],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Firewall Tools
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'firewall_status',
+          description: '[FREE] Get current firewall status including mode, violation count, and current intent.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'firewall_set_mode',
+          description: '[FREE/PRO] Set firewall mode. "off" and "observe" are FREE. "enforce" requires PRO subscription.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              mode: {
+                type: 'string',
+                enum: ['off', 'observe', 'enforce'],
+                description: 'Firewall mode (enforce requires PRO)',
+              },
+            },
+            required: ['mode'],
+          },
+        },
+        {
+          name: 'firewall_set_intent',
+          description: '[PRO] Set the current intent before making code changes. Required in enforce mode.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              summary: {
+                type: 'string',
+                description: 'Brief description of what you intend to do',
+              },
+              constraints: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of constraints/boundaries for this intent',
+              },
+              template: {
+                type: 'string',
+                description: 'Use a predefined template instead of custom summary',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'firewall_get_intent',
+          description: '[PRO] Get the current intent that was set.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'firewall_clear_intent',
+          description: '[PRO] Clear the current intent.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'firewall_check',
+          description: '[PRO] Run a comprehensive shield check on the codebase.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'firewall_verify_claim',
+          description: '[PRO] Verify an AI claim against the current codebase state and intent.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              claim: {
+                type: 'string',
+                description: 'The claim to verify (e.g., "I only added a new route")',
+              },
+              context: {
+                type: 'string',
+                description: 'Additional context about the claim',
+              },
+              files: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Files involved in the claim',
+              },
+            },
+            required: ['claim'],
+          },
+        },
+        {
+          name: 'firewall_gate_action',
+          description: '[PRO] Check if an action is allowed by the firewall. Use before performing sensitive operations.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              action: {
+                type: 'string',
+                description: 'Description of the action to perform',
+              },
+              category: {
+                type: 'string',
+                enum: ['read', 'write', 'execute', 'network', 'sensitive'],
+                description: 'Category of the action',
+              },
+            },
+            required: ['action', 'category'],
+          },
+        },
+        {
+          name: 'firewall_get_templates',
+          description: '[PRO] Get available intent templates for common tasks.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Prompt Builder Tools (FREE)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'prompt_get_templates',
+          description: '[FREE] Get all available prompt templates, optionally filtered by category.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              category: {
+                type: 'string',
+                description: 'Filter by category (authentication, api, frontend, etc.)',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'prompt_get_categories',
+          description: '[FREE] Get all prompt categories with template counts.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'prompt_detect_template',
+          description: '[FREE] Detect the best template for a given user input.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              input: {
+                type: 'string',
+                description: 'User input to analyze',
+              },
+            },
+            required: ['input'],
+          },
+        },
+        {
+          name: 'prompt_build',
+          description: '[FREE] Build a production-ready prompt from a template.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              templateId: {
+                type: 'string',
+                description: 'Template ID to use',
+              },
+              userInput: {
+                type: 'string',
+                description: 'Original user request',
+              },
+              answers: {
+                type: 'object',
+                description: 'Answers to template context questions',
+              },
+            },
+            required: ['templateId', 'userInput'],
+          },
+        },
+        {
+          name: 'prompt_get_context',
+          description: '[FREE] Detect workspace context (framework, database, etc.) from project files.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'prompt_get_suggestions',
+          description: '[FREE] Get smart suggestions for improving a prompt.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              input: {
+                type: 'string',
+                description: 'Current prompt or user input',
+              },
+            },
+            required: ['input'],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Tier Info Tool (FREE)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'vibecheck_tier',
+          description: 'Get current subscription tier info, usage limits, and available features. FREE tier includes 11 commands for inspect & observe. PRO tier ($49/mo) includes 12 additional commands for fix, prove & enforce.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Session Management Tools (FREE)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'session_info',
+          description: '[FREE] Get current session information including metrics, trust score, and activity history.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'session_metrics',
+          description: '[FREE] Get detailed session metrics including tool call statistics, latency, and success rates.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'session_history',
+          description: '[FREE] Get recent tool call history for the current session.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              limit: {
+                type: 'number',
+                description: 'Maximum number of entries to return (default: 20)',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'session_health',
+          description: '[FREE] Check session health status including trust score and any issues.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Git Integration Tools (FREE)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'git_status',
+          description: '[FREE] Get comprehensive git status including branch, staged/unstaged changes, and ahead/behind counts.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'git_diff',
+          description: '[FREE] Get diff of current changes with risk analysis.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              staged: {
+                type: 'boolean',
+                description: 'Get staged changes only (default: false)',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'git_diff_intent_check',
+          description: '[PRO] Check if current git changes match the declared intent. Identifies constraint violations.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              staged: {
+                type: 'boolean',
+                description: 'Check staged changes only (default: false)',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'git_commits',
+          description: '[FREE] Get recent commit history.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              count: {
+                type: 'number',
+                description: 'Number of commits to retrieve (default: 10)',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'git_branches',
+          description: '[FREE] List all git branches.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'git_file_history',
+          description: '[FREE] Get commit history for a specific file.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              file: {
+                type: 'string',
+                description: 'File path (relative to workspace)',
+              },
+              count: {
+                type: 'number',
+                description: 'Number of commits to retrieve (default: 10)',
+              },
+            },
+            required: ['file'],
+          },
+        },
+        {
+          name: 'git_snapshot',
+          description: '[PRO] Create a git stash snapshot of current changes.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              message: {
+                type: 'string',
+                description: 'Optional message for the snapshot',
+              },
+            },
+            required: [],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Context Management Tools (FREE)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'context_project',
+          description: '[FREE] Get comprehensive project structure analysis including framework, language, directories, and statistics.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'context_window',
+          description: '[FREE] Get a smart context window of relevant files for a given query or task.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              query: {
+                type: 'string',
+                description: 'Query or task description to find relevant files',
+              },
+              maxFiles: {
+                type: 'number',
+                description: 'Maximum number of files (default: 50)',
+              },
+              categories: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter by categories: config, entry, api, component, utility, test, style, documentation',
+              },
+              includeContent: {
+                type: 'boolean',
+                description: 'Include file contents (default: false)',
+              },
+            },
+            required: [],
+          },
+        },
+        {
+          name: 'context_find_files',
+          description: '[FREE] Find files matching a pattern in the workspace.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              pattern: {
+                type: 'string',
+                description: 'Regex pattern to match file paths',
+              },
+            },
+            required: ['pattern'],
+          },
+        },
+        {
+          name: 'context_related_files',
+          description: '[FREE] Find files related to a given file based on imports and dependencies.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              file: {
+                type: 'string',
+                description: 'File path (relative to workspace)',
+              },
+              depth: {
+                type: 'number',
+                description: 'Depth of dependency traversal (default: 1)',
+              },
+            },
+            required: ['file'],
+          },
+        },
+        {
+          name: 'context_file_info',
+          description: '[FREE] Get detailed information about a specific file including category, relevance, and optionally content.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              file: {
+                type: 'string',
+                description: 'File path (relative to workspace)',
+              },
+              includeContent: {
+                type: 'boolean',
+                description: 'Include file content (default: false)',
+              },
+            },
+            required: ['file'],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Cache & Performance Tools (FREE)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'cache_stats',
+          description: '[FREE] Get cache statistics including hit rate, size, and entry count.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+        {
+          name: 'cache_clear',
+          description: '[FREE] Clear the cache. Use tag to clear specific entries.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              tag: {
+                type: 'string',
+                description: 'Optional tag to clear specific cache entries',
+              },
+            },
+            required: [],
+          },
+        },
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Health & Diagnostics Tools (FREE)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+          name: 'health_check',
+          description: '[FREE] Run comprehensive health check on the MCP server and all services.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+      ],
+    }));
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        // ═══════════════════════════════════════════════════════════════════════
+        // TIER CHECK - Enforce FREE/PRO tiers
+        // ═══════════════════════════════════════════════════════════════════════
+        const tierCheck = this.checkTierAccess(name);
+        if (!tierCheck.allowed && tierCheck.errorResponse) {
+          return tierCheck.errorResponse;
+        }
+
+        switch (name) {
+          // ═══════════════════════════════════════════════════════════════════════
+          // CLI Tools
+          // ═══════════════════════════════════════════════════════════════════════
+
+          // FREE: doctor, audit, forge, packs
+          case 'vibecheck_doctor':
+            return this.handleDoctor();
+          case 'vibecheck_audit':
+            return this.handleAudit(args as { path?: string; severity?: string });
+          case 'vibecheck_forge':
+            return this.handleForge(args as { output?: string; format?: string });
+          case 'vibecheck_packs':
+            return this.handlePacks(args as { format?: string });
+
+          // PRO: ship, fix, checkpoint, reality
+          case 'vibecheck_ship':
+            return this.handleShip();
+          case 'vibecheck_fix':
+            return this.handleFix(args as { mode: string; missionId?: string });
+          case 'vibecheck_checkpoint':
+            return this.handleCheckpoint(args as { action: string; id?: string });
+          case 'vibecheck_reality':
+            return this.handleReality(args as { url: string; headless?: boolean });
+
+          // ═══════════════════════════════════════════════════════════════════════
+          // Firewall Tools (PRO for enforce mode, FREE for observe)
+          // ═══════════════════════════════════════════════════════════════════════
+          case 'firewall_status':
+            return this.handleFirewallStatus();
+          case 'firewall_set_mode':
+            return this.handleFirewallSetMode(args as { mode: string });
+          case 'firewall_set_intent':
+            return this.handleFirewallSetIntent(args as { summary?: string; constraints?: string[]; template?: string });
+          case 'firewall_get_intent':
+            return this.handleFirewallGetIntent();
+          case 'firewall_clear_intent':
+            return this.handleFirewallClearIntent();
+          case 'firewall_check':
+            return this.handleFirewallCheck();
+          case 'firewall_verify_claim':
+            return this.handleFirewallVerifyClaim(args as { claim: string; context?: string; files?: string[] });
+          case 'firewall_gate_action':
+            return this.handleFirewallGateAction(args as { action: string; category: string });
+          case 'firewall_get_templates':
+            return this.handleFirewallGetTemplates();
+
+          // ═══════════════════════════════════════════════════════════════════════
+          // Prompt Builder Tools (FREE - helpers for forge)
+          // ═══════════════════════════════════════════════════════════════════════
+          case 'prompt_get_templates':
+            return this.handlePromptGetTemplates(args as { category?: string });
+          case 'prompt_get_categories':
+            return this.handlePromptGetCategories();
+          case 'prompt_detect_template':
+            return this.handlePromptDetectTemplate(args as { input: string });
+          case 'prompt_build':
+            return this.handlePromptBuild(args as { templateId: string; userInput: string; answers?: Record<string, unknown> });
+          case 'prompt_get_context':
+            return this.handlePromptGetContext();
+          case 'prompt_get_suggestions':
+            return this.handlePromptGetSuggestions(args as { input: string });
+
+          // ═══════════════════════════════════════════════════════════════════════
+          // Tier Info Tool (FREE)
+          // ═══════════════════════════════════════════════════════════════════════
+          case 'vibecheck_tier':
+            return this.handleTierInfo();
+
+          // ═══════════════════════════════════════════════════════════════════════
+          // Session Management Tools
+          // ═══════════════════════════════════════════════════════════════════════
+          case 'session_info':
+            return this.handleSessionInfo();
+          case 'session_metrics':
+            return this.handleSessionMetrics();
+          case 'session_history':
+            return this.handleSessionHistory(args as { limit?: number });
+          case 'session_health':
+            return this.handleSessionHealth();
+
+          // ═══════════════════════════════════════════════════════════════════════
+          // Git Integration Tools
+          // ═══════════════════════════════════════════════════════════════════════
+          case 'git_status':
+            return this.handleGitStatus();
+          case 'git_diff':
+            return this.handleGitDiff(args as { staged?: boolean });
+          case 'git_diff_intent_check':
+            return this.handleGitDiffIntentCheck(args as { staged?: boolean });
+          case 'git_commits':
+            return this.handleGitCommits(args as { count?: number });
+          case 'git_branches':
+            return this.handleGitBranches();
+          case 'git_file_history':
+            return this.handleGitFileHistory(args as { file: string; count?: number });
+          case 'git_snapshot':
+            return this.handleGitSnapshot(args as { message?: string });
+
+          // ═══════════════════════════════════════════════════════════════════════
+          // Context Management Tools
+          // ═══════════════════════════════════════════════════════════════════════
+          case 'context_project':
+            return this.handleContextProject();
+          case 'context_window':
+            return this.handleContextWindow(args as { query?: string; maxFiles?: number; categories?: string[]; includeContent?: boolean });
+          case 'context_find_files':
+            return this.handleContextFindFiles(args as { pattern: string });
+          case 'context_related_files':
+            return this.handleContextRelatedFiles(args as { file: string; depth?: number });
+          case 'context_file_info':
+            return this.handleContextFileInfo(args as { file: string; includeContent?: boolean });
+
+          // ═══════════════════════════════════════════════════════════════════════
+          // Cache & Health Tools
+          // ═══════════════════════════════════════════════════════════════════════
+          case 'cache_stats':
+            return this.handleCacheStats();
+          case 'cache_clear':
+            return this.handleCacheClear(args as { tag?: string });
+          case 'health_check':
+            return this.handleHealthCheck();
+
+          default:
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        if (error instanceof McpError) throw error;
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+          content: [{ type: 'text', text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    });
+
+    // List resources
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: [
+        {
+          uri: 'vibecheck://status',
+          name: 'Server Status',
+          description: 'Current MCP server status and configuration',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://tier',
+          name: 'Subscription Tier',
+          description: 'Current subscription tier, limits, and usage',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://session',
+          name: 'Session Info',
+          description: 'Current session information, metrics, and trust score',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://firewall/stats',
+          name: 'Firewall Statistics',
+          description: 'Firewall violation and action statistics',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://firewall/log',
+          name: 'Firewall Action Log',
+          description: 'Recent firewall action log entries',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://git/status',
+          name: 'Git Status',
+          description: 'Current git repository status',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://context',
+          name: 'Workspace Context',
+          description: 'Detected workspace context (framework, database, etc.)',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://project',
+          name: 'Project Structure',
+          description: 'Comprehensive project structure analysis',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://health',
+          name: 'Health Status',
+          description: 'MCP server health check status',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'vibecheck://cache',
+          name: 'Cache Statistics',
+          description: 'Cache hit rate and statistics',
+          mimeType: 'application/json',
+        },
+      ],
+    }));
+
+    // Read resources
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const { uri } = request.params;
+
+      switch (uri) {
+        case 'vibecheck://status':
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify({
+                ...this.state,
+                tier: this.tierService.getTier(),
+              }, null, 2),
+            }],
+          };
+
+        case 'vibecheck://tier':
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(this.tierService.getTierInfo(), null, 2),
+            }],
+          };
+
+        case 'vibecheck://firewall/stats':
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(this.firewallService.getStats(), null, 2),
+            }],
+          };
+
+        case 'vibecheck://firewall/log':
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(this.firewallService.getActionLog(50), null, 2),
+            }],
+          };
+
+        case 'vibecheck://context':
+          const context = await this.promptBuilderService.detectWorkspaceContext();
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(context, null, 2),
+            }],
+          };
+
+        case 'vibecheck://session':
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(this.sessionService.getSessionSummary(), null, 2),
+            }],
+          };
+
+        case 'vibecheck://git/status':
+          const gitStatus = await this.gitService.getStatus();
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(gitStatus, null, 2),
+            }],
+          };
+
+        case 'vibecheck://project':
+          const project = await this.contextManager.getProjectStructure();
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(project, null, 2),
+            }],
+          };
+
+        case 'vibecheck://health':
+          const checks = [];
+          checks.push({ name: 'CLI', available: await this.cliService.isAvailable() });
+          checks.push({ name: 'Git', available: await this.gitService.isRepo() });
+          checks.push({ name: 'Session', healthy: this.sessionService.isSessionHealthy().healthy });
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify({ checks, timestamp: new Date().toISOString() }, null, 2),
+            }],
+          };
+
+        case 'vibecheck://cache':
+          return {
+            contents: [{
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(this.cacheService.getStats(), null, 2),
+            }],
+          };
+
+        default:
+          throw new McpError(ErrorCode.InvalidRequest, `Unknown resource: ${uri}`);
+      }
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // CLI Tool Handlers
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private async handleDoctor() {
+    const result = await this.cliService.doctor();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Doctor check failed: ${result.error}`,
+      }],
+    };
+  }
+
+  private async handleAudit(args: { path?: string; severity?: string }) {
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TIER CHECK: Check scan limit for FREE tier
+    // ═══════════════════════════════════════════════════════════════════════════
+    const scanLimit = this.tierService.checkScanLimit();
+    if (!scanLimit.allowed) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: this.tierService.formatTierError(scanLimit),
+        }],
+        isError: true,
+      };
+    }
+
+    const result = await this.cliService.audit(args);
+
+    // Increment scan count on successful audit
+    if (result.success) {
+      this.tierService.incrementScanCount();
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Audit failed: ${result.error}`,
+      }],
+    };
+  }
+
+  private async handleShip() {
+    const result = await this.cliService.ship();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Ship check failed: ${result.error}`,
+      }],
+    };
+  }
+
+  private async handleForge(args: { output?: string; format?: string }) {
+    const result = await this.cliService.forge(args);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Forge failed: ${result.error}`,
+      }],
+    };
+  }
+
+  private async handleFix(args: { mode: string; missionId?: string }) {
+    const result = args.mode === 'plan'
+      ? await this.cliService.fixPlan()
+      : await this.cliService.fixApply({ missionId: args.missionId });
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Fix ${args.mode} failed: ${result.error}`,
+      }],
+    };
+  }
+
+  private async handleCheckpoint(args: { action: string; id?: string }) {
+    const result = await this.cliService.checkpoint(
+      args.action as 'create' | 'restore' | 'list',
+      args.id
+    );
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Checkpoint ${args.action} failed: ${result.error}`,
+      }],
+    };
+  }
+
+  private async handlePacks(args: { format?: string }) {
+    const format = (args.format as 'html' | 'zip' | 'json' | 'sarif' | 'csv' | 'pdf') || 'html';
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TIER CHECK: Check report format for FREE tier
+    // ═══════════════════════════════════════════════════════════════════════════
+    const formatCheck = this.tierService.checkReportFormat(format);
+    if (!formatCheck.allowed) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: this.tierService.formatTierError(formatCheck),
+        }],
+        isError: true,
+      };
+    }
+
+    const result = await this.cliService.packs(format as 'html' | 'zip' | 'json');
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Packs generation failed: ${result.error}`,
+      }],
+    };
+  }
+
+  private async handleReality(args: { url: string; headless?: boolean }) {
+    const result = await this.cliService.reality(args.url, { headless: args.headless });
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result.success
+          ? JSON.stringify(result.data, null, 2)
+          : `Reality test failed: ${result.error}`,
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Firewall Tool Handlers
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private async handleFirewallStatus() {
+    const status = await this.firewallService.getStatus();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(status, null, 2),
+      }],
+    };
+  }
+
+  private async handleFirewallSetMode(args: { mode: string }) {
+    const mode = args.mode as FirewallMode;
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TIER CHECK: Enforce mode requires PRO subscription
+    // ═══════════════════════════════════════════════════════════════════════════
+    if (mode === 'enforce') {
+      const tierCheck = this.tierService.checkFirewallEnforceMode();
+      if (!tierCheck.allowed) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: this.tierService.formatTierError(tierCheck) +
+              '\n\n💡 FREE tier supports "observe" mode, which logs actions without blocking.',
+          }],
+          isError: true,
+        };
+      }
+    }
+
+    const success = await this.firewallService.setMode(mode);
+    this.state.firewallMode = mode;
+    return {
+      content: [{
+        type: 'text' as const,
+        text: success
+          ? `Firewall mode set to: ${mode}` +
+          (mode === 'enforce' ? ' (PRO feature)' : '')
+          : `Failed to set firewall mode to: ${mode}`,
+      }],
+    };
+  }
+
+  private async handleFirewallSetIntent(args: { summary?: string; constraints?: string[]; template?: string }) {
+    let success: boolean;
+
+    if (args.template) {
+      success = await this.firewallService.setIntentFromTemplate(args.template, args.summary);
+    } else if (args.summary) {
+      success = await this.firewallService.setIntent(args.summary, args.constraints || []);
+    } else {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: 'Error: Either summary or template is required',
+        }],
+        isError: true,
+      };
+    }
+
+    const intent = this.firewallService.getCurrentIntent();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: success
+          ? `Intent set:\n${JSON.stringify(intent, null, 2)}`
+          : 'Failed to set intent',
+      }],
+    };
+  }
+
+  private async handleFirewallGetIntent() {
+    const intent = await this.firewallService.getIntent();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: intent
+          ? JSON.stringify(intent, null, 2)
+          : 'No intent is currently set',
+      }],
+    };
+  }
+
+  private async handleFirewallClearIntent() {
+    const success = await this.firewallService.clearIntent();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: success ? 'Intent cleared' : 'Failed to clear intent',
+      }],
+    };
+  }
+
+  private async handleFirewallCheck() {
+    const result = await this.firewallService.check();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result
+          ? JSON.stringify(result, null, 2)
+          : 'Shield check failed',
+      }],
+    };
+  }
+
+  private async handleFirewallVerifyClaim(args: { claim: string; context?: string; files?: string[] }) {
+    const result = await this.firewallService.verifyClaim({
+      claim: args.claim,
+      context: args.context,
+      files: args.files,
+    });
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(result, null, 2),
+      }],
+    };
+  }
+
+  private handleFirewallGateAction(args: { action: string; category: string }) {
+    const result = this.firewallService.gateAction(
+      args.action,
+      args.category as 'read' | 'write' | 'execute' | 'network' | 'sensitive'
+    );
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(result, null, 2),
+      }],
+    };
+  }
+
+  private handleFirewallGetTemplates() {
+    const templates = this.firewallService.getTemplates();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(templates, null, 2),
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Prompt Builder Tool Handlers
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private handlePromptGetTemplates(args: { category?: string }) {
+    const templates = args.category
+      ? this.promptBuilderService.getTemplatesByCategory(args.category as any)
+      : this.promptBuilderService.getTemplates();
+
+    // Return simplified template info
+    const simplified = templates.map(t => ({
+      id: t.id,
+      name: t.name,
+      category: t.category,
+      description: t.description,
+      icon: t.icon,
+      popularity: t.popularity,
+      contextQuestions: t.contextQuestions.map(q => ({
+        id: q.id,
+        label: q.label,
+        type: q.type,
+        required: q.required,
+      })),
+    }));
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(simplified, null, 2),
+      }],
+    };
+  }
+
+  private handlePromptGetCategories() {
+    const categories = this.promptBuilderService.getCategories();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(categories, null, 2),
+      }],
+    };
+  }
+
+  private handlePromptDetectTemplate(args: { input: string }) {
+    const template = this.promptBuilderService.detectTemplate(args.input);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: template
+          ? JSON.stringify({
+            id: template.id,
+            name: template.name,
+            description: template.description,
+            category: template.category,
+            contextQuestions: template.contextQuestions,
+          }, null, 2)
+          : 'No matching template found',
+      }],
+    };
+  }
+
+  private async handlePromptBuild(args: { templateId: string; userInput: string; answers?: Record<string, unknown> }) {
+    const result = await this.promptBuilderService.buildPrompt(
+      args.templateId,
+      args.userInput,
+      (args.answers || {}) as Record<string, string | string[]>
+    );
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: result
+          ? JSON.stringify({
+            id: result.id,
+            quality: result.quality,
+            expandedPrompt: result.expandedPrompt,
+          }, null, 2)
+          : `Template not found: ${args.templateId}`,
+      }],
+    };
+  }
+
+  private async handlePromptGetContext() {
+    const context = await this.promptBuilderService.detectWorkspaceContext();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(context, null, 2),
+      }],
+    };
+  }
+
+  private handlePromptGetSuggestions(args: { input: string }) {
+    const suggestions = this.promptBuilderService.getSmartSuggestions(args.input);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(suggestions, null, 2),
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tier Info Handler
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private handleTierInfo() {
+    const tierInfo = this.tierService.getTierInfo();
+    const isPro = tierInfo.isPro;
+
+    const freeCommands = [
+      'link', 'kickoff', 'doctor', 'watch', 'forge',
+      'audit', 'auth', 'safelist', 'labs', 'packs', 'ci'
+    ];
+
+    const proCommands = [
+      'intent', 'approve', 'shield', 'launch', 'reality',
+      'prove', 'ship', 'seal', 'fix', 'polish', 'mcp', 'checkpoint'
+    ];
+
+    const output = {
+      currentTier: tierInfo.tier.toUpperCase(),
+      isPro,
+      pricing: isPro ? '$49/mo (active)' : '$0/mo (FREE)',
+
+      limits: {
+        scansPerMonth: tierInfo.limits.scansPerMonth === Infinity ? 'Unlimited' : tierInfo.limits.scansPerMonth,
+        filesPerScan: tierInfo.limits.filesPerScan === Infinity ? 'Unlimited' : tierInfo.limits.filesPerScan,
+        reportFormats: tierInfo.limits.reportFormats,
+        firewallMode: tierInfo.limits.firewallMode,
+      },
+
+      usage: {
+        scansThisMonth: tierInfo.usage.scans,
+        scanLimit: tierInfo.usage.limit === Infinity ? 'Unlimited' : tierInfo.usage.limit,
+        resetsAt: tierInfo.usage.resetsAt,
+      },
+
+      commands: {
+        free: {
+          count: freeCommands.length,
+          focus: 'Inspect & Observe',
+          list: freeCommands,
+        },
+        pro: {
+          count: proCommands.length,
+          focus: 'Fix, Prove & Enforce',
+          list: proCommands,
+          available: isPro,
+        },
+      },
+
+      upgradeUrl: isPro ? null : 'https://vibecheckai.dev/pricing',
+    };
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(output, null, 2),
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Session Management Handlers
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private handleSessionInfo() {
+    const summary = this.sessionService.getSessionSummary();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: summary
+          ? JSON.stringify(summary, null, 2)
+          : 'No active session',
+      }],
+    };
+  }
+
+  private handleSessionMetrics() {
+    const metrics = this.sessionService.getDetailedMetrics();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: metrics
+          ? JSON.stringify(metrics, null, 2)
+          : 'No metrics available',
+      }],
+    };
+  }
+
+  private handleSessionHistory(args: { limit?: number }) {
+    const history = this.sessionService.getToolCallHistory(args.limit || 20);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(history, null, 2),
+      }],
+    };
+  }
+
+  private handleSessionHealth() {
+    const health = this.sessionService.isSessionHealthy();
+    const session = this.sessionService.getSession();
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          healthy: health.healthy,
+          issues: health.issues,
+          trustScore: session?.securityContext.trustScore || 0,
+          status: session?.status || 'unknown',
+        }, null, 2),
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Git Integration Handlers
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private async handleGitStatus() {
+    const status = await this.gitService.getStatus();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(status, null, 2),
+      }],
+    };
+  }
+
+  private async handleGitDiff(args: { staged?: boolean }) {
+    const analysis = await this.gitService.analyzeDiff(args.staged || false);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(analysis, null, 2),
+      }],
+    };
+  }
+
+  private async handleGitDiffIntentCheck(args: { staged?: boolean }) {
+    const intent = this.firewallService.getCurrentIntent();
+
+    if (!intent) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            error: 'No intent set. Set an intent first using firewall_set_intent.',
+            suggestion: 'Use firewall_get_templates to see available intent templates.',
+          }, null, 2),
+        }],
+        isError: true,
+      };
+    }
+
+    const check = await this.gitService.checkDiffAgainstIntent(
+      { summary: intent.summary, constraints: intent.constraints },
+      args.staged || false
+    );
+
+    // Record in session
+    this.sessionService.recordClaimVerification(check.matches);
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          intent: intent.summary,
+          constraints: intent.constraints,
+          result: check,
+        }, null, 2),
+      }],
+    };
+  }
+
+  private async handleGitCommits(args: { count?: number }) {
+    const commits = await this.gitService.getRecentCommits(args.count || 10);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(commits, null, 2),
+      }],
+    };
+  }
+
+  private async handleGitBranches() {
+    const branches = await this.gitService.getBranches();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(branches, null, 2),
+      }],
+    };
+  }
+
+  private async handleGitFileHistory(args: { file: string; count?: number }) {
+    const history = await this.gitService.getFileHistory(args.file, args.count || 10);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(history, null, 2),
+      }],
+    };
+  }
+
+  private async handleGitSnapshot(args: { message?: string }) {
+    const result = await this.gitService.createSnapshot(args.message);
+
+    if (result.success) {
+      this.sessionService.recordStateChange({
+        type: 'checkpoint_created',
+        before: 'working',
+        after: result.stashId || 'stash',
+        metadata: { message: args.message },
+      });
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(result, null, 2),
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Context Management Handlers
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private async handleContextProject() {
+    const structure = await this.contextManager.getProjectStructure();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(structure, null, 2),
+      }],
+    };
+  }
+
+  private async handleContextWindow(args: {
+    query?: string;
+    maxFiles?: number;
+    categories?: string[];
+    includeContent?: boolean;
+  }) {
+    const window = await this.contextManager.getContextWindow({
+      query: args.query,
+      maxFiles: args.maxFiles,
+      categories: args.categories as any,
+      includeContent: args.includeContent,
+    });
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          totalFiles: window.files.length,
+          totalSize: window.totalSize,
+          totalTokensEstimate: window.totalTokensEstimate,
+          truncated: window.truncated,
+          files: window.files.map(f => ({
+            path: f.relativePath,
+            category: f.category,
+            language: f.language,
+            relevanceScore: f.relevanceScore,
+            size: f.size,
+            ...(f.content ? { contentPreview: f.content.substring(0, 200) + '...' } : {}),
+          })),
+        }, null, 2),
+      }],
+    };
+  }
+
+  private async handleContextFindFiles(args: { pattern: string }) {
+    const files = await this.contextManager.findFiles(args.pattern);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(files.map(f => ({
+          path: f.relativePath,
+          category: f.category,
+          language: f.language,
+          size: f.size,
+        })), null, 2),
+      }],
+    };
+  }
+
+  private async handleContextRelatedFiles(args: { file: string; depth?: number }) {
+    const related = await this.contextManager.getRelatedFiles(args.file, args.depth || 1);
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(related.map(f => ({
+          path: f.relativePath,
+          category: f.category,
+          language: f.language,
+          relevanceScore: f.relevanceScore,
+        })), null, 2),
+      }],
+    };
+  }
+
+  private async handleContextFileInfo(args: { file: string; includeContent?: boolean }) {
+    const info = await this.contextManager.getFileContext(args.file, args.includeContent);
+
+    if (!info) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: `File not found: ${args.file}`,
+        }],
+        isError: true,
+      };
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          path: info.relativePath,
+          category: info.category,
+          language: info.language,
+          size: info.size,
+          lastModified: info.lastModified,
+          relevanceScore: info.relevanceScore,
+          ...(info.content ? { content: info.content } : {}),
+        }, null, 2),
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Cache & Health Handlers
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  private handleCacheStats() {
+    const stats = this.cacheService.getStats();
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(stats, null, 2),
+      }],
+    };
+  }
+
+  private handleCacheClear(args: { tag?: string }) {
+    let count = 0;
+
+    if (args.tag) {
+      count = this.cacheService.invalidateByTag(args.tag);
+    } else {
+      this.cacheService.clear();
+      count = -1; // All cleared
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: count === -1
+          ? 'Cache cleared completely'
+          : `Cleared ${count} cache entries with tag: ${args.tag}`,
+      }],
+    };
+  }
+
+  private async handleHealthCheck() {
+    const checks: { name: string; status: 'pass' | 'warn' | 'fail'; message: string }[] = [];
+
+    // Check CLI
+    const cliAvailable = await this.cliService.isAvailable();
+    checks.push({
+      name: 'CLI',
+      status: cliAvailable ? 'pass' : 'warn',
+      message: cliAvailable ? 'VibeCheck CLI is available' : 'CLI not found (some features limited)',
+    });
+
+    // Check Git
+    const isGitRepo = await this.gitService.isRepo();
+    checks.push({
+      name: 'Git',
+      status: isGitRepo ? 'pass' : 'warn',
+      message: isGitRepo ? 'Git repository detected' : 'Not a git repository',
+    });
+
+    // Check Session
+    const sessionHealth = this.sessionService.isSessionHealthy();
+    checks.push({
+      name: 'Session',
+      status: sessionHealth.healthy ? 'pass' : 'warn',
+      message: sessionHealth.healthy
+        ? 'Session is healthy'
+        : `Issues: ${sessionHealth.issues.join(', ')}`,
+    });
+
+    // Check Cache
+    const cacheStats = this.cacheService.getStats();
+    checks.push({
+      name: 'Cache',
+      status: 'pass',
+      message: `Hit rate: ${cacheStats.hitRate}, entries: ${cacheStats.totalEntries}`,
+    });
+
+    // Check Tier
+    const tierInfo = this.tierService.getTierInfo();
+    checks.push({
+      name: 'Tier',
+      status: 'pass',
+      message: `${tierInfo.tier.toUpperCase()} tier - ${tierInfo.usage.scans}/${tierInfo.usage.limit} scans used`,
+    });
+
+    // Check Firewall
+    const firewallStatus = await this.firewallService.getStatus();
+    checks.push({
+      name: 'Firewall',
+      status: 'pass',
+      message: `Mode: ${firewallStatus.mode}, Intent: ${firewallStatus.currentIntent ? 'set' : 'not set'}`,
+    });
+
+    const allPassing = checks.every(c => c.status === 'pass');
+    const hasFailures = checks.some(c => c.status === 'fail');
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          overall: hasFailures ? 'unhealthy' : (allPassing ? 'healthy' : 'degraded'),
+          checks,
+          timestamp: new Date().toISOString(),
+        }, null, 2),
+      }],
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Server Lifecycle
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  async initialize(): Promise<void> {
+    // Check CLI availability
+    this.state.cliAvailable = await this.cliService.isAvailable();
+    if (this.state.cliAvailable) {
+      this.state.cliVersion = await this.cliService.getVersion() || undefined;
+    }
+
+    // Get initial firewall status
+    const status = await this.firewallService.getStatus();
+    this.state.firewallMode = status.mode;
+    this.state.currentIntent = status.currentIntent;
+
+    this.state.initialized = true;
+  }
+
+  async run(): Promise<void> {
+    await this.initialize();
+
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    // Log to stderr (not stdout which is used for MCP protocol)
+    console.error('VibeCheck MCP Server running on stdio');
+    console.error(`CLI available: ${this.state.cliAvailable}`);
+    if (this.state.cliVersion) {
+      console.error(`CLI version: ${this.state.cliVersion}`);
+    }
+  }
+
+  getState(): McpServerState {
+    return this.state;
+  }
+}