vibecheck-ai 2.0.2 → 5.0.1

package/bin/runners/runMcp.js

@@ -0,0 +1,1875 @@
+/**
+ * Vibecheck MCP Server CLI - HARDENED v4.1.0
+ * 
+ * "My IDE is now VibeCheck-powered"
+ * 
+ * HARDENING FEATURES:
+ * - Comprehensive error codes and structured error handling
+ * - Retry logic with exponential backoff
+ * - Input validation and sanitization
+ * - Lock file to prevent multiple instances
+ * - Startup verification with health probe
+ * - Structured logging with log levels
+ * - Connection testing and verification
+ * - Graceful degradation and recovery
+ * - Signal handling and cleanup
+ * - Timeout management
+ * - Secret redaction
+ * 
+ * Subcommands:
+ *   serve    - Start the MCP server (default)
+ *   doctor   - Health check with self-healing
+ *   config   - Print IDE-specific connection configs
+ *   manifest - Machine-readable tool manifest for IDEs
+ *   status   - Check server health
+ *   test     - Test MCP server connection
+ * 
+ * @version 4.1.0
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const net = require("net");
+const crypto = require("crypto");
+const { spawn, execSync } = require("child_process");
+const { EXIT } = require("./lib/exit-codes");
+const { parseGlobalFlags, shouldSuppressOutput, isJsonMode } = require("./lib/global-flags");
+
+// ============================================================================
+// CONSTANTS & CONFIGURATION
+// ============================================================================
+const VERSION = "4.1.0";
+const DEFAULT_PORT = 3847;
+const PORT_RANGE = { min: 3847, max: 3867 };
+const FALLBACK_PORTS = [8000, 8080, 9000, 9999, 3000];
+const SERVER_NAME = "vibecheck-mcp";
+const LOCK_FILE_NAME = ".vibecheck-mcp.lock";
+const LOG_FILE_NAME = "mcp-server.log";
+const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
+
+// Timeouts (ms)
+const TIMEOUTS = {
+  STARTUP: 10000,       // Max time to wait for server startup
+  HEALTH_PROBE: 3000,   // Health check timeout
+  SHUTDOWN: 5000,       // Graceful shutdown timeout
+  RETRY_BASE: 1000,     // Base retry delay
+  RETRY_MAX: 30000,     // Max retry delay
+  PORT_CHECK: 1000,     // Port availability check
+};
+
+// Retry configuration
+const RETRY_CONFIG = {
+  maxAttempts: 3,
+  backoffMultiplier: 2,
+  jitter: 0.1,
+};
+
+// Error codes
+const ERROR_CODES = {
+  SUCCESS: 0,
+  VALIDATION_ERROR: 1,
+  SERVER_NOT_FOUND: 2,
+  PORT_UNAVAILABLE: 3,
+  STARTUP_FAILED: 4,
+  ALREADY_RUNNING: 5,
+  CONFIG_ERROR: 6,
+  PERMISSION_DENIED: 7,
+  NETWORK_ERROR: 8,
+  TIMEOUT: 9,
+  INTERNAL_ERROR: 10,
+  NOT_CONFIGURED: 11,
+  HEALTH_CHECK_FAILED: 12,
+};
+
+// ============================================================================
+// ANSI STYLING (Safe for non-TTY)
+// ============================================================================
+const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = SUPPORTS_COLOR ? {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  italic: "\x1b[3m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  magenta: "\x1b[35m",
+  blue: "\x1b[34m",
+  gray: "\x1b[90m",
+  bgGreen: "\x1b[42m",
+  bgRed: "\x1b[41m",
+  bgYellow: "\x1b[43m",
+  bgBlue: "\x1b[44m",
+} : Object.fromEntries([
+  "reset", "bold", "dim", "italic", "cyan", "green", "yellow", "red",
+  "magenta", "blue", "gray", "bgGreen", "bgRed", "bgYellow", "bgBlue"
+].map(k => [k, ""]));
+
+const sym = {
+  check: SUPPORTS_COLOR ? "✓" : "[OK]",
+  cross: SUPPORTS_COLOR ? "✗" : "[FAIL]",
+  warn: SUPPORTS_COLOR ? "⚠" : "[WARN]",
+  info: SUPPORTS_COLOR ? "ℹ" : "[INFO]",
+  arrow: SUPPORTS_COLOR ? "→" : "->",
+  box: SUPPORTS_COLOR ? "█" : "#",
+  dot: SUPPORTS_COLOR ? "•" : "-",
+  rocket: SUPPORTS_COLOR ? "🚀" : "[*]",
+  plug: SUPPORTS_COLOR ? "🔌" : "[PLUG]",
+  wrench: SUPPORTS_COLOR ? "🔧" : "[FIX]",
+  heart: SUPPORTS_COLOR ? "💚" : "[OK]",
+  shield: SUPPORTS_COLOR ? "🛡️" : "[SHIELD]",
+  brain: SUPPORTS_COLOR ? "🧠" : "[AI]",
+  clipboard: SUPPORTS_COLOR ? "📋" : "[COPY]",
+  folder: SUPPORTS_COLOR ? "📁" : "[DIR]",
+  lock: SUPPORTS_COLOR ? "🔒" : "[LOCK]",
+  key: SUPPORTS_COLOR ? "🔑" : "[KEY]",
+  timer: SUPPORTS_COLOR ? "⏱️" : "[TIME]",
+  retry: SUPPORTS_COLOR ? "🔄" : "[RETRY]",
+};
+
+// ============================================================================
+// STRUCTURED LOGGING
+// ============================================================================
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+let currentLogLevel = LOG_LEVELS.info;
+let logFile = null;
+
+function setLogLevel(level) {
+  currentLogLevel = LOG_LEVELS[level] ?? LOG_LEVELS.info;
+}
+
+function getLogFilePath(projectPath) {
+  const logDir = path.join(projectPath, ".vibecheck", "logs");
+  return path.join(logDir, LOG_FILE_NAME);
+}
+
+function initLogFile(projectPath) {
+  try {
+    const logPath = getLogFilePath(projectPath);
+    const logDir = path.dirname(logPath);
+    
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    
+    // Rotate log if too large
+    if (fs.existsSync(logPath)) {
+      const stats = fs.statSync(logPath);
+      if (stats.size > MAX_LOG_SIZE) {
+        const backupPath = `${logPath}.1`;
+        if (fs.existsSync(backupPath)) {
+          fs.unlinkSync(backupPath);
+        }
+        fs.renameSync(logPath, backupPath);
+      }
+    }
+    
+    logFile = fs.createWriteStream(logPath, { flags: "a" });
+  } catch {
+    // Logging is best-effort
+  }
+}
+
+function log(level, message, meta = {}) {
+  if (LOG_LEVELS[level] < currentLogLevel) return;
+  
+  const timestamp = new Date().toISOString();
+  const entry = {
+    timestamp,
+    level,
+    message,
+    ...meta,
+  };
+  
+  // Write to log file
+  if (logFile) {
+    try {
+      logFile.write(JSON.stringify(entry) + "\n");
+    } catch {
+      // Best effort
+    }
+  }
+  
+  // Console output (only for warn/error or if debug mode)
+  if (level === "error") {
+    console.error(`${c.red}[ERROR]${c.reset} ${message}`);
+  } else if (level === "warn" && currentLogLevel <= LOG_LEVELS.warn) {
+    console.error(`${c.yellow}[WARN]${c.reset} ${message}`);
+  } else if (level === "debug" && currentLogLevel === LOG_LEVELS.debug) {
+    console.error(`${c.gray}[DEBUG]${c.reset} ${message}`);
+  }
+}
+
+// ============================================================================
+// INPUT VALIDATION & SANITIZATION
+// ============================================================================
+
+/**
+ * Validate and sanitize a file path
+ */
+function validatePath(inputPath, basePath = process.cwd()) {
+  if (!inputPath || typeof inputPath !== "string") {
+    return { valid: false, error: "Path must be a non-empty string", code: ERROR_CODES.VALIDATION_ERROR };
+  }
+  
+  // Length check
+  if (inputPath.length > 4096) {
+    return { valid: false, error: "Path too long (max 4096 chars)", code: ERROR_CODES.VALIDATION_ERROR };
+  }
+  
+  // Null byte check
+  if (inputPath.includes("\0")) {
+    return { valid: false, error: "Path contains invalid characters", code: ERROR_CODES.VALIDATION_ERROR };
+  }
+  
+  try {
+    const resolved = path.resolve(basePath, inputPath);
+    const normalizedBase = path.resolve(basePath).replace(/\\/g, "/").toLowerCase();
+    const normalizedPath = resolved.replace(/\\/g, "/").toLowerCase();
+    
+    // Path traversal check
+    const baseWithSep = normalizedBase.endsWith("/") ? normalizedBase : normalizedBase + "/";
+    if (!normalizedPath.startsWith(baseWithSep) && normalizedPath !== normalizedBase) {
+      // Allow if it's the base path itself or a child
+      if (!normalizedPath.startsWith(normalizedBase)) {
+        return { valid: false, error: "Path traversal detected", code: ERROR_CODES.VALIDATION_ERROR };
+      }
+    }
+    
+    return { valid: true, path: resolved };
+  } catch (err) {
+    return { valid: false, error: `Invalid path: ${err.message}`, code: ERROR_CODES.VALIDATION_ERROR };
+  }
+}
+
+/**
+ * Validate port number
+ */
+function validatePort(port) {
+  const num = parseInt(port, 10);
+  if (isNaN(num) || num < 1 || num > 65535) {
+    return { valid: false, error: `Invalid port: ${port} (must be 1-65535)`, code: ERROR_CODES.VALIDATION_ERROR };
+  }
+  return { valid: true, port: num };
+}
+
+/**
+ * Validate IDE name
+ */
+function validateIde(ide) {
+  const validIdes = ["cursor", "windsurf", "claude", "vscode", "all"];
+  const normalized = (ide || "all").toLowerCase();
+  if (!validIdes.includes(normalized)) {
+    return { valid: false, error: `Invalid IDE: ${ide}. Valid options: ${validIdes.join(", ")}`, code: ERROR_CODES.VALIDATION_ERROR };
+  }
+  return { valid: true, ide: normalized };
+}
+
+/**
+ * Redact sensitive values from output
+ */
+function redactSecrets(text) {
+  if (typeof text !== "string") return text;
+  
+  const patterns = [
+    [/(?:sk_live_|sk_test_)[a-zA-Z0-9]{24,}/g, "[STRIPE_KEY_REDACTED]"],
+    [/(?:AKIA|ASIA)[A-Z0-9]{16}/g, "[AWS_KEY_REDACTED]"],
+    [/ghp_[a-zA-Z0-9]{36}/g, "[GITHUB_TOKEN_REDACTED]"],
+    [/xox[baprs]-[0-9A-Za-z\-]{10,}/g, "[SLACK_TOKEN_REDACTED]"],
+    [/eyJ[a-zA-Z0-9_-]*\.eyJ[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*/g, "[JWT_REDACTED]"],
+    [/(?:password|secret|token|apikey|api_key)["']?\s*[:=]\s*["'][^"']{8,}["']/gi, "[SECRET_REDACTED]"],
+    [/VIBECHECK_API_KEY=\S+/g, "VIBECHECK_API_KEY=[REDACTED]"],
+  ];
+  
+  let result = text;
+  for (const [pattern, replacement] of patterns) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+// ============================================================================
+// LOCK FILE MANAGEMENT
+// ============================================================================
+
+function getLockFilePath(projectPath) {
+  return path.join(projectPath, ".vibecheck", LOCK_FILE_NAME);
+}
+
+function createLockFile(projectPath, pid, port) {
+  const lockPath = getLockFilePath(projectPath);
+  const lockDir = path.dirname(lockPath);
+  
+  try {
+    if (!fs.existsSync(lockDir)) {
+      fs.mkdirSync(lockDir, { recursive: true });
+    }
+    
+    const lockData = {
+      pid,
+      port,
+      startedAt: new Date().toISOString(),
+      hostname: os.hostname(),
+      nodeVersion: process.version,
+    };
+    
+    fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2));
+    log("debug", "Lock file created", { lockPath, pid, port });
+    return { success: true };
+  } catch (err) {
+    log("error", "Failed to create lock file", { error: err.message });
+    return { success: false, error: err.message };
+  }
+}
+
+function readLockFile(projectPath) {
+  const lockPath = getLockFilePath(projectPath);
+  
+  try {
+    if (!fs.existsSync(lockPath)) {
+      return { exists: false };
+    }
+    
+    const data = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    return { exists: true, data };
+  } catch {
+    return { exists: false };
+  }
+}
+
+function removeLockFile(projectPath) {
+  const lockPath = getLockFilePath(projectPath);
+  
+  try {
+    if (fs.existsSync(lockPath)) {
+      fs.unlinkSync(lockPath);
+      log("debug", "Lock file removed", { lockPath });
+    }
+    return { success: true };
+  } catch (err) {
+    log("warn", "Failed to remove lock file", { error: err.message });
+    return { success: false, error: err.message };
+  }
+}
+
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function checkExistingInstance(projectPath) {
+  const lock = readLockFile(projectPath);
+  
+  if (!lock.exists) {
+    return { running: false };
+  }
+  
+  const { pid, port, startedAt } = lock.data;
+  
+  if (isProcessRunning(pid)) {
+    return {
+      running: true,
+      pid,
+      port,
+      startedAt,
+      message: `MCP server already running (PID: ${pid}, Port: ${port})`,
+    };
+  }
+  
+  // Stale lock file - remove it
+  log("info", "Removing stale lock file", { pid });
+  removeLockFile(projectPath);
+  return { running: false, wasStale: true };
+}
+
+// ============================================================================
+// RETRY LOGIC WITH EXPONENTIAL BACKOFF
+// ============================================================================
+
+async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function calculateBackoff(attempt, config = RETRY_CONFIG) {
+  const baseDelay = TIMEOUTS.RETRY_BASE * Math.pow(config.backoffMultiplier, attempt);
+  const jitter = baseDelay * config.jitter * (Math.random() * 2 - 1);
+  return Math.min(baseDelay + jitter, TIMEOUTS.RETRY_MAX);
+}
+
+async function withRetry(fn, options = {}) {
+  const { maxAttempts = RETRY_CONFIG.maxAttempts, onRetry, shouldRetry } = options;
+  
+  let lastError;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+      
+      if (shouldRetry && !shouldRetry(err, attempt)) {
+        throw err;
+      }
+      
+      if (attempt < maxAttempts - 1) {
+        const delay = calculateBackoff(attempt);
+        log("debug", `Retry ${attempt + 1}/${maxAttempts} after ${delay}ms`, { error: err.message });
+        
+        if (onRetry) {
+          onRetry(err, attempt, delay);
+        }
+        
+        await sleep(delay);
+      }
+    }
+  }
+  
+  throw lastError;
+}
+
+// ============================================================================
+// PORT MANAGEMENT
+// ============================================================================
+
+async function isPortAvailable(port, timeout = TIMEOUTS.PORT_CHECK) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    const timeoutId = setTimeout(() => {
+      server.close();
+      resolve(false);
+    }, timeout);
+    
+    server.once("error", () => {
+      clearTimeout(timeoutId);
+      resolve(false);
+    });
+    
+    server.once("listening", () => {
+      clearTimeout(timeoutId);
+      server.close();
+      resolve(true);
+    });
+    
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+async function findAvailablePort(startPort = DEFAULT_PORT) {
+  // Try primary range
+  for (let port = startPort; port <= PORT_RANGE.max; port++) {
+    if (await isPortAvailable(port)) {
+      return { port, source: "primary" };
+    }
+  }
+  
+  // Try fallback ports
+  for (const port of FALLBACK_PORTS) {
+    if (await isPortAvailable(port)) {
+      return { port, source: "fallback" };
+    }
+  }
+  
+  return { port: null, error: "No available ports found" };
+}
+
+function findPortProcess(port) {
+  try {
+    if (process.platform === "win32") {
+      const result = execSync(`netstat -ano | findstr :${port}`, { 
+        encoding: "utf8", 
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      const lines = result.trim().split("\n").filter(l => l.includes("LISTENING"));
+      if (lines.length > 0) {
+        const pid = lines[0].trim().split(/\s+/).pop();
+        try {
+          const taskResult = execSync(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, { encoding: "utf8" });
+          const name = taskResult.split(",")[0]?.replace(/"/g, "");
+          return { pid: parseInt(pid), name };
+        } catch {
+          return { pid: parseInt(pid), name: "unknown" };
+        }
+      }
+    } else {
+      const result = execSync(`lsof -i :${port} -t 2>/dev/null | head -1`, { 
+        encoding: "utf8", 
+        timeout: 5000,
+      });
+      const pid = result.trim();
+      if (pid) {
+        try {
+          const name = execSync(`ps -p ${pid} -o comm= 2>/dev/null`, { encoding: "utf8" }).trim();
+          return { pid: parseInt(pid), name };
+        } catch {
+          return { pid: parseInt(pid), name: "unknown" };
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+// ============================================================================
+// PATH UTILITIES
+// ============================================================================
+
+function getProjectPath(inputPath) {
+  const result = validatePath(inputPath || process.cwd());
+  if (!result.valid) {
+    return process.cwd();
+  }
+  return result.path;
+}
+
+function getMcpServerPath() {
+  return path.join(__dirname, "..", "..", "mcp-server", "index.js");
+}
+
+function mcpServerExists() {
+  const serverPath = getMcpServerPath();
+  return fs.existsSync(serverPath);
+}
+
+function getCliBinPath() {
+  return path.join(__dirname, "..", "vibecheck.js");
+}
+
+function getManifestPath() {
+  return path.join(__dirname, "..", "..", "mcp-server", "manifest.json");
+}
+
+// ============================================================================
+// TOOL REGISTRY
+// ============================================================================
+const TOOL_CATEGORIES = {
+  setup: { name: "Setup", icon: "🔧", description: "Project initialization and health" },
+  analysis: { name: "Analysis", icon: "🔍", description: "Code analysis and auditing" },
+  truth: { name: "Truth", icon: "📜", description: "Ground truth and context generation" },
+  enforcement: { name: "Enforcement", icon: "🛡️", description: "Agent firewall and intent tracking" },
+  proof: { name: "Proof", icon: "✅", description: "Verification and evidence" },
+  automation: { name: "Automation", icon: "🤖", description: "CI/CD and deployment" },
+  output: { name: "Output", icon: "📦", description: "Reports and artifacts" },
+  config: { name: "Config", icon: "⚙️", description: "Configuration management" },
+  account: { name: "Account", icon: "👤", description: "Authentication and billing" },
+};
+
+const CANONICAL_TOOLS = [
+  { name: "vibecheck.link", cli: "link", category: "setup", tier: "free", description: "One-time project setup: config, contracts, scripts" },
+  { name: "vibecheck.kickoff", cli: "kickoff", category: "setup", tier: "free", description: "Interactive guided onboarding experience" },
+  { name: "vibecheck.doctor", cli: "doctor", category: "setup", tier: "free", description: "Environment, dependency, and configuration health check" },
+  { name: "vibecheck.audit", cli: "audit", category: "analysis", tier: "free", description: "Analyze codebase for issues (routes, env, auth, security, dead code)" },
+  { name: "vibecheck.forge", cli: "forge", category: "truth", tier: "free", description: "Generate IDE rules and AI context (.cursorrules, MDC, Copilot)" },
+  { name: "vibecheck.shield", cli: "shield", category: "enforcement", tier: "free", description: "Agent Firewall - intercept, validate, enforce AI actions", proOptions: ["enforce", "lock", "install", "check"] },
+  { name: "vibecheck.intent", cli: "intent", category: "enforcement", tier: "free", description: "Declare and manage AI session intent for enforcement" },
+  { name: "vibecheck.ship", cli: "ship", category: "proof", tier: "pro", description: "Verdict engine - SHIP/WARN/BLOCK with evidence-backed decision" },
+  { name: "vibecheck.fix", cli: "fix", category: "proof", tier: "pro", description: "AI-powered auto-fix for detected findings" },
+  { name: "vibecheck.prove", cli: "prove", category: "proof", tier: "pro", description: "Full proof loop with runtime verification" },
+  { name: "vibecheck.reality", cli: "reality", category: "proof", tier: "pro", description: "Browser-based runtime verification with auth boundary testing" },
+  { name: "vibecheck.checkpoint", cli: "checkpoint", category: "proof", tier: "pro", description: "Compare baseline vs current state" },
+  { name: "vibecheck.launch", cli: "launch", category: "automation", tier: "pro", description: "CI/CD enforcement - preflight checks and deploy gates" },
+  { name: "vibecheck.packs", cli: "packs", category: "output", tier: "free", description: "Generate shareable artifact packs: reports, evidence, proof graphs" },
+  { name: "vibecheck.seal", cli: "seal", category: "output", tier: "pro", description: "Generate verification seal/badge with cryptographic attestation" },
+  { name: "vibecheck.safelist", cli: "safelist", category: "config", tier: "free", description: "Manage finding safelist for false positives" },
+  { name: "vibecheck.auth", cli: "auth", category: "account", tier: "free", description: "Authentication management: login, logout, whoami" },
+  { name: "vibecheck.approve", cli: "approve", category: "proof", tier: "pro", description: "Authority verdicts - PROCEED/STOP/DEFER with proofs" },
+  { name: "vibecheck.polish", cli: "polish", category: "proof", tier: "pro", description: "Code polish and cleanup" },
+  { name: "vibecheck.labs", cli: "labs", category: "setup", tier: "free", description: "Access experimental features" },
+  { name: "vibecheck.health", cli: "health", category: "setup", tier: "free", description: "MCP server health check" },
+  { name: "vibecheck.manifest", cli: "manifest", category: "setup", tier: "free", description: "Get tool manifest" },
+];
+
+// ============================================================================
+// IDE CONFIGURATIONS
+// ============================================================================
+const IDE_CONFIGS = {
+  cursor: {
+    name: "Cursor",
+    icon: "⌘",
+    configPath: {
+      win32: path.join(os.homedir(), ".cursor", "mcp.json"),
+      darwin: path.join(os.homedir(), ".cursor", "mcp.json"),
+      linux: path.join(os.homedir(), ".cursor", "mcp.json"),
+    },
+    format: "json",
+    instructions: "Add to Cursor Settings → MCP, or create ~/.cursor/mcp.json",
+  },
+  windsurf: {
+    name: "Windsurf",
+    icon: "🏄",
+    configPath: { win32: null, darwin: null, linux: null },
+    format: "json",
+    instructions: "Open Command Palette → 'Windsurf: Open MCP Config'",
+  },
+  claude: {
+    name: "Claude Desktop",
+    icon: "🤖",
+    configPath: {
+      win32: path.join(process.env.APPDATA || "", "Claude", "claude_desktop_config.json"),
+      darwin: path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+      linux: path.join(os.homedir(), ".config", "claude", "claude_desktop_config.json"),
+    },
+    format: "json",
+    instructions: "Edit claude_desktop_config.json in your Claude config directory",
+  },
+  vscode: {
+    name: "VS Code (Continue)",
+    icon: "💻",
+    configPath: {
+      win32: path.join(os.homedir(), ".continue", "config.json"),
+      darwin: path.join(os.homedir(), ".continue", "config.json"),
+      linux: path.join(os.homedir(), ".continue", "config.json"),
+    },
+    format: "continue",
+    instructions: "Add to ~/.continue/config.json if using Continue extension",
+  },
+};
+
+// ============================================================================
+// STRUCTURED ERROR RESPONSES
+// ============================================================================
+
+function createError(code, message, details = {}) {
+  return {
+    success: false,
+    error: {
+      code,
+      message,
+      ...details,
+    },
+  };
+}
+
+function createSuccess(data, meta = {}) {
+  return {
+    success: true,
+    data,
+    meta: {
+      version: VERSION,
+      timestamp: new Date().toISOString(),
+      ...meta,
+    },
+  };
+}
+
+// ============================================================================
+// DOCTOR - Health Check with Self-Healing
+// ============================================================================
+
+async function runDoctor(opts, globalFlags) {
+  const json = isJsonMode(globalFlags);
+  const quiet = shouldSuppressOutput(globalFlags);
+  const checks = [];
+  const fixes = [];
+  const projectPath = getProjectPath(opts.path);
+  
+  if (!quiet && !json) {
+    console.log(`\n${c.bold}${sym.wrench} VibeCheck MCP Doctor v${VERSION}${c.reset}\n`);
+    console.log(`${c.dim}Running comprehensive health checks...${c.reset}\n`);
+  }
+  
+  // Check 1: Node.js version
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0]);
+  const nodeOk = nodeMajor >= 18;
+  checks.push({
+    id: "node-version",
+    name: "Node.js Version",
+    status: nodeOk ? "pass" : "fail",
+    current: nodeVersion,
+    required: ">=18.0.0",
+    message: nodeOk ? `Node.js ${nodeVersion}` : `Node.js ${nodeVersion} too old`,
+    fix: nodeOk ? null : "Install Node.js 18+ from https://nodejs.org",
+    critical: true,
+  });
+  
+  // Check 2: MCP Server exists
+  const serverPath = getMcpServerPath();
+  const serverExists = mcpServerExists();
+  checks.push({
+    id: "mcp-server",
+    name: "MCP Server",
+    status: serverExists ? "pass" : "fail",
+    path: serverPath,
+    message: serverExists ? "Server module found" : "Server module not found",
+    fix: serverExists ? null : "Run 'npm install' in vibecheck directory",
+    critical: true,
+  });
+  
+  // Check 3: Port availability
+  const portAvailable = await isPortAvailable(DEFAULT_PORT);
+  let portMessage = portAvailable ? `Port ${DEFAULT_PORT} available` : `Port ${DEFAULT_PORT} in use`;
+  let portFix = null;
+  let portProcess = null;
+  
+  if (!portAvailable) {
+    portProcess = findPortProcess(DEFAULT_PORT);
+    if (portProcess) {
+      portMessage = `Port ${DEFAULT_PORT} in use by ${portProcess.name} (PID: ${portProcess.pid})`;
+      portFix = `Kill process ${portProcess.pid} or use --port flag`;
+    }
+  }
+  
+  checks.push({
+    id: "port-available",
+    name: "Default Port",
+    status: portAvailable ? "pass" : "warn",
+    port: DEFAULT_PORT,
+    process: portProcess,
+    message: portMessage,
+    fix: portFix,
+    critical: false,
+  });
+  
+  // Check 4: Existing instance
+  const existingInstance = checkExistingInstance(projectPath);
+  checks.push({
+    id: "no-existing-instance",
+    name: "No Existing Instance",
+    status: existingInstance.running ? "warn" : "pass",
+    message: existingInstance.running 
+      ? `Server running (PID: ${existingInstance.pid})`
+      : existingInstance.wasStale ? "Cleaned stale lock" : "No instance running",
+    pid: existingInstance.pid,
+    fix: existingInstance.running ? `Stop existing server or use different port` : null,
+    critical: false,
+  });
+  
+  // Check 5: Project config
+  const configPaths = [
+    path.join(projectPath, ".vibecheckrc"),
+    path.join(projectPath, "vibecheck.config.json"),
+    path.join(projectPath, ".vibecheck", "config.json"),
+  ];
+  const configExists = configPaths.some(p => fs.existsSync(p));
+  const configPath = configPaths.find(p => fs.existsSync(p));
+  checks.push({
+    id: "project-config",
+    name: "Project Config",
+    status: configExists ? "pass" : "warn",
+    path: configPath || projectPath,
+    message: configExists ? `Config found: ${path.basename(configPath)}` : "No config (run 'vibecheck link')",
+    fix: configExists ? null : "Run 'vibecheck link' to initialize",
+    critical: false,
+  });
+  
+  // Check 6: Environment variables
+  const apiKey = process.env.VIBECHECK_API_KEY;
+  checks.push({
+    id: "api-key",
+    name: "API Key",
+    status: apiKey ? "pass" : "info",
+    message: apiKey ? "VIBECHECK_API_KEY configured" : "No API key (free tier)",
+    fix: apiKey ? null : "Set VIBECHECK_API_KEY for PRO features",
+    critical: false,
+  });
+  
+  // Check 7: Write permissions
+  let canWrite = false;
+  try {
+    const testFile = path.join(projectPath, ".vibecheck", ".write-test");
+    const testDir = path.dirname(testFile);
+    if (!fs.existsSync(testDir)) {
+      fs.mkdirSync(testDir, { recursive: true });
+    }
+    fs.writeFileSync(testFile, "test");
+    fs.unlinkSync(testFile);
+    canWrite = true;
+  } catch {
+    canWrite = false;
+  }
+  
+  checks.push({
+    id: "write-permissions",
+    name: "Write Permissions",
+    status: canWrite ? "pass" : "fail",
+    path: path.join(projectPath, ".vibecheck"),
+    message: canWrite ? "Can write to .vibecheck/" : "Cannot write to project directory",
+    fix: canWrite ? null : "Check directory permissions",
+    critical: true,
+  });
+  
+  // Check 8: IDE integrations
+  const platform = process.platform;
+  const ideChecks = [];
+  
+  for (const [ide, config] of Object.entries(IDE_CONFIGS)) {
+    const configPath = config.configPath[platform];
+    if (configPath) {
+      const exists = fs.existsSync(configPath);
+      let hasVibecheck = false;
+      let parseError = null;
+      
+      if (exists) {
+        try {
+          const content = JSON.parse(fs.readFileSync(configPath, "utf8"));
+          hasVibecheck = !!(content.mcpServers?.vibecheck || content.mcpServers?.["vibecheck-local"]);
+        } catch (err) {
+          parseError = err.message;
+        }
+      }
+      
+      ideChecks.push({
+        ide: config.name,
+        key: ide,
+        configExists: exists,
+        vibecheckConfigured: hasVibecheck,
+        parseError,
+        path: configPath,
+      });
+    }
+  }
+  
+  const configuredIdes = ideChecks.filter(c => c.vibecheckConfigured);
+  checks.push({
+    id: "ide-integration",
+    name: "IDE Integration",
+    status: configuredIdes.length > 0 ? "pass" : "warn",
+    message: configuredIdes.length > 0
+      ? `Configured: ${configuredIdes.map(c => c.ide).join(", ")}`
+      : "No IDE configured",
+    fix: configuredIdes.length > 0 ? null : "Run 'vibecheck mcp config --ide cursor --write'",
+    details: ideChecks,
+    critical: false,
+  });
+  
+  // Check 9: Manifest file
+  const manifestPath = getManifestPath();
+  const manifestExists = fs.existsSync(manifestPath);
+  checks.push({
+    id: "manifest",
+    name: "Tool Manifest",
+    status: manifestExists ? "pass" : "warn",
+    path: manifestPath,
+    message: manifestExists ? "Manifest available" : "Manifest not found",
+    fix: manifestExists ? null : "Manifest will be generated on server start",
+    critical: false,
+  });
+  
+  // Self-healing
+  if (opts.fix) {
+    for (const check of checks) {
+      if (check.status !== "pass" && check.fix && !check.critical) {
+        // Auto-fix: Create project config
+        if (check.id === "project-config" && !configExists) {
+          try {
+            const configDir = path.join(projectPath, ".vibecheck");
+            if (!fs.existsSync(configDir)) {
+              fs.mkdirSync(configDir, { recursive: true });
+            }
+            const rcPath = path.join(projectPath, ".vibecheckrc");
+            fs.writeFileSync(rcPath, JSON.stringify({ 
+              version: "1.0.0", 
+              created: new Date().toISOString(),
+              mcp: { autoStart: false },
+            }, null, 2));
+            fixes.push({ id: check.id, action: "Created .vibecheckrc" });
+            check.status = "fixed";
+          } catch (err) {
+            fixes.push({ id: check.id, action: `Failed: ${err.message}`, success: false });
+          }
+        }
+        
+        // Auto-fix: Remove stale lock
+        if (check.id === "no-existing-instance" && existingInstance.wasStale) {
+          fixes.push({ id: check.id, action: "Removed stale lock file" });
+          check.status = "fixed";
+        }
+      }
+    }
+  }
+  
+  // Calculate summary
+  const summary = {
+    pass: checks.filter(c => c.status === "pass").length,
+    warn: checks.filter(c => c.status === "warn").length,
+    fail: checks.filter(c => c.status === "fail").length,
+    info: checks.filter(c => c.status === "info").length,
+    fixed: checks.filter(c => c.status === "fixed").length,
+  };
+  
+  const healthy = summary.fail === 0;
+  const hasWarnings = summary.warn > 0;
+  const criticalFail = checks.some(c => c.status === "fail" && c.critical);
+  
+  // Output
+  if (json) {
+    console.log(JSON.stringify(createSuccess({
+      healthy,
+      criticalFail,
+      checks,
+      fixes: fixes.length > 0 ? fixes : undefined,
+      summary,
+    }), null, 2));
+    return healthy ? EXIT.SUCCESS : EXIT.INTERNAL_ERROR;
+  }
+  
+  // Pretty output
+  for (const check of checks) {
+    const icon = check.status === "pass" ? `${c.green}${sym.check}${c.reset}` :
+                 check.status === "fail" ? `${c.red}${sym.cross}${c.reset}` :
+                 check.status === "warn" ? `${c.yellow}${sym.warn}${c.reset}` :
+                 check.status === "fixed" ? `${c.cyan}${sym.wrench}${c.reset}` :
+                 `${c.blue}${sym.info}${c.reset}`;
+    
+    const critical = check.critical && check.status === "fail" ? ` ${c.red}(CRITICAL)${c.reset}` : "";
+    
+    console.log(`  ${icon} ${c.bold}${check.name}${c.reset}${critical}`);
+    console.log(`    ${c.dim}${check.message}${c.reset}`);
+    
+    if (check.fix && check.status !== "fixed" && check.status !== "pass") {
+      console.log(`    ${c.yellow}${sym.arrow} ${check.fix}${c.reset}`);
+    }
+    console.log();
+  }
+  
+  // Summary
+  console.log(`${c.dim}${"─".repeat(55)}${c.reset}\n`);
+  
+  if (healthy && !hasWarnings) {
+    console.log(`${c.green}${sym.heart} All checks passed!${c.reset}\n`);
+    console.log(`${c.dim}Your MCP setup is bulletproof. Start with:${c.reset}`);
+    console.log(`  ${c.cyan}vibecheck mcp serve${c.reset}\n`);
+  } else if (criticalFail) {
+    console.log(`${c.red}${sym.cross} Critical issues found${c.reset}\n`);
+    console.log(`${c.dim}Fix critical issues before starting the server.${c.reset}\n`);
+  } else if (summary.fail > 0) {
+    console.log(`${c.red}${sym.cross} ${summary.fail} check(s) failed${c.reset}\n`);
+    console.log(`${c.dim}Fix issues above, then run:${c.reset}`);
+    console.log(`  ${c.cyan}vibecheck mcp doctor --fix${c.reset}\n`);
+  } else {
+    console.log(`${c.yellow}${sym.warn} ${summary.warn} warning(s)${c.reset}\n`);
+    console.log(`${c.dim}Server will work, but consider fixing warnings.${c.reset}`);
+    console.log(`  ${c.cyan}vibecheck mcp serve${c.reset}\n`);
+  }
+  
+  if (fixes.length > 0) {
+    console.log(`${c.cyan}${sym.wrench} Auto-fixed ${fixes.length} issue(s)${c.reset}\n`);
+  }
+  
+  return healthy ? EXIT.SUCCESS : (criticalFail ? ERROR_CODES.HEALTH_CHECK_FAILED : EXIT.SUCCESS);
+}
+
+// ============================================================================
+// CONFIG - Generate IDE-specific Configurations
+// ============================================================================
+
+function generateConfig(ide, opts) {
+  const projectPath = getProjectPath(opts.path);
+  const mcpServerPath = getMcpServerPath();
+  const cliBinPath = getCliBinPath();
+  
+  const useNpx = opts.npx || !fs.existsSync(mcpServerPath);
+  const useCli = opts.cli;
+  
+  let command, args, cwd;
+  
+  if (useNpx) {
+    command = "npx";
+    args = ["-y", "@vibecheck/mcp-server"];
+  } else if (useCli) {
+    command = "node";
+    args = [cliBinPath, "mcp", "serve"];
+    cwd = projectPath;
+  } else {
+    command = "node";
+    args = [mcpServerPath];
+    cwd = projectPath;
+  }
+  
+  const env = {};
+  if (opts.apiKey || process.env.VIBECHECK_API_KEY) {
+    env.VIBECHECK_API_KEY = opts.apiKey || "${VIBECHECK_API_KEY}";
+  }
+  env.VIBECHECK_PROJECT_PATH = projectPath;
+  
+  if (ide === "vscode") {
+    return {
+      mcpServers: [{
+        name: "vibecheck",
+        command,
+        args,
+        ...(cwd ? { cwd } : {}),
+        env: Object.keys(env).length > 0 ? env : undefined,
+      }],
+    };
+  }
+  
+  return {
+    mcpServers: {
+      vibecheck: {
+        command,
+        args,
+        ...(cwd ? { cwd } : {}),
+        env: Object.keys(env).length > 0 ? env : undefined,
+      },
+    },
+  };
+}
+
+async function runConfig(opts, globalFlags) {
+  const json = isJsonMode(globalFlags);
+  const quiet = shouldSuppressOutput(globalFlags);
+  
+  // Validate IDE
+  const ideValidation = validateIde(opts.ide);
+  if (!ideValidation.valid) {
+    if (json) {
+      console.log(JSON.stringify(createError(ideValidation.code, ideValidation.error)));
+    } else {
+      console.error(`${c.red}${sym.cross} ${ideValidation.error}${c.reset}`);
+    }
+    return ERROR_CODES.VALIDATION_ERROR;
+  }
+  
+  const ide = ideValidation.ide;
+  
+  if (!quiet && !json) {
+    console.log(`\n${c.bold}${sym.plug} VibeCheck MCP Configuration${c.reset}\n`);
+  }
+  
+  const configs = {};
+  const ides = ide === "all" ? Object.keys(IDE_CONFIGS) : [ide];
+  
+  for (const ideKey of ides) {
+    const ideConfig = IDE_CONFIGS[ideKey];
+    if (!ideConfig) continue;
+    
+    const config = generateConfig(ideKey, opts);
+    configs[ideKey] = config;
+    
+    if (!json && !quiet) {
+      const configPath = ideConfig.configPath[process.platform];
+      
+      console.log(`${c.cyan}${ideConfig.icon} ${ideConfig.name}${c.reset}`);
+      console.log(`${c.dim}${ideConfig.instructions}${c.reset}`);
+      if (configPath) {
+        console.log(`${c.dim}Path: ${configPath}${c.reset}`);
+      }
+      console.log();
+      console.log(`${c.green}┌${"─".repeat(53)}┐${c.reset}`);
+      const configLines = JSON.stringify(config, null, 2).split("\n");
+      for (const line of configLines) {
+        console.log(`${c.green}│${c.reset} ${line}`);
+      }
+      console.log(`${c.green}└${"─".repeat(53)}┘${c.reset}`);
+      console.log();
+    }
+  }
+  
+  if (json) {
+    console.log(JSON.stringify(createSuccess(ide === "all" ? configs : configs[ide])));
+    return EXIT.SUCCESS;
+  }
+  
+  if (!quiet) {
+    console.log(`${c.dim}${"─".repeat(55)}${c.reset}\n`);
+    console.log(`${c.bold}Quick Setup:${c.reset}`);
+    console.log(`  1. Copy the config above to your IDE's MCP settings`);
+    console.log(`  2. Restart your IDE`);
+    console.log(`  3. Ask: "${c.cyan}What vibecheck tools are available?${c.reset}"\n`);
+    
+    // Auto-write
+    if (opts.write && ide !== "all") {
+      const ideConfig = IDE_CONFIGS[ide];
+      const configPath = ideConfig?.configPath[process.platform];
+      
+      if (configPath) {
+        try {
+          const dir = path.dirname(configPath);
+          if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+          }
+          
+          let existingConfig = {};
+          if (fs.existsSync(configPath)) {
+            try {
+              existingConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            } catch {
+              // Start fresh
+            }
+          }
+          
+          const newConfig = generateConfig(ide, opts);
+          const merged = {
+            ...existingConfig,
+            mcpServers: {
+              ...(existingConfig.mcpServers || {}),
+              ...(newConfig.mcpServers || {}),
+            },
+          };
+          
+          fs.writeFileSync(configPath, JSON.stringify(merged, null, 2));
+          console.log(`${c.green}${sym.check} Config written to: ${configPath}${c.reset}\n`);
+        } catch (err) {
+          console.log(`${c.red}${sym.cross} Write failed: ${err.message}${c.reset}\n`);
+          return ERROR_CODES.PERMISSION_DENIED;
+        }
+      } else {
+        console.log(`${c.yellow}${sym.warn} No config path for ${ide} on ${process.platform}${c.reset}\n`);
+      }
+    }
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+// ============================================================================
+// MANIFEST - Machine-readable Tool Manifest
+// ============================================================================
+
+async function runManifest(opts, globalFlags) {
+  const json = isJsonMode(globalFlags) || opts.format === "json";
+  const format = opts.format || "json";
+  
+  // Try to read from file first
+  const manifestPath = getManifestPath();
+  let manifest;
+  
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    } catch {
+      // Fall back to generated
+    }
+  }
+  
+  if (!manifest) {
+    manifest = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      name: "vibecheck-mcp",
+      version: VERSION,
+      description: "VibeCheck MCP Server - AI-powered code verification",
+      tools: CANONICAL_TOOLS,
+      categories: TOOL_CATEGORIES,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+  
+  if (format === "summary") {
+    const output = {
+      name: manifest.name,
+      version: manifest.version,
+      toolCount: manifest.tools?.length || CANONICAL_TOOLS.length,
+      categories: Object.keys(manifest.categories || TOOL_CATEGORIES),
+      tiers: {
+        free: (manifest.tools || CANONICAL_TOOLS).filter(t => t.tier === "free").length,
+        pro: (manifest.tools || CANONICAL_TOOLS).filter(t => t.tier === "pro").length,
+      },
+    };
+    console.log(JSON.stringify(createSuccess(output), null, 2));
+  } else {
+    console.log(JSON.stringify(json ? createSuccess(manifest) : manifest, null, 2));
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+// ============================================================================
+// SERVE - Start the MCP Server (HARDENED)
+// ============================================================================
+
+async function runServe(opts, globalFlags) {
+  const json = isJsonMode(globalFlags);
+  const quiet = shouldSuppressOutput(globalFlags);
+  const projectPath = getProjectPath(opts.path);
+  
+  // Initialize logging
+  if (opts.debug) {
+    setLogLevel("debug");
+  }
+  initLogFile(projectPath);
+  
+  log("info", "Starting MCP server", { projectPath, version: VERSION });
+  
+  // Validate server exists
+  const serverPath = getMcpServerPath();
+  if (!fs.existsSync(serverPath)) {
+    const error = createError(ERROR_CODES.SERVER_NOT_FOUND, "MCP server not found", { path: serverPath });
+    if (json) {
+      console.log(JSON.stringify(error));
+    } else {
+      console.error(`${c.red}${sym.cross} MCP server not found: ${serverPath}${c.reset}`);
+      console.error(`${c.dim}Run 'npm install' in vibecheck directory${c.reset}`);
+    }
+    log("error", "Server not found", { serverPath });
+    return ERROR_CODES.SERVER_NOT_FOUND;
+  }
+  
+  // Check for existing instance
+  const existingInstance = checkExistingInstance(projectPath);
+  if (existingInstance.running) {
+    if (opts.force) {
+      log("warn", "Force-starting despite existing instance", { pid: existingInstance.pid });
+      try {
+        process.kill(existingInstance.pid, "SIGTERM");
+        await sleep(1000);
+      } catch {
+        // Process may already be dead
+      }
+      removeLockFile(projectPath);
+    } else {
+      const error = createError(ERROR_CODES.ALREADY_RUNNING, existingInstance.message, {
+        pid: existingInstance.pid,
+        port: existingInstance.port,
+      });
+      if (json) {
+        console.log(JSON.stringify(error));
+      } else {
+        console.error(`${c.red}${sym.lock} ${existingInstance.message}${c.reset}`);
+        console.error(`${c.dim}Use --force to override${c.reset}`);
+      }
+      return ERROR_CODES.ALREADY_RUNNING;
+    }
+  }
+  
+  // Port handling with retry
+  let port = opts.port || DEFAULT_PORT;
+  let portInfo = null;
+  
+  const portResult = await withRetry(
+    async (attempt) => {
+      if (await isPortAvailable(port)) {
+        return { port, available: true };
+      }
+      
+      if (opts.autoPort !== false) {
+        const available = await findAvailablePort(port + 1);
+        if (available.port) {
+          return { port: available.port, available: true, source: available.source };
+        }
+      }
+      
+      throw new Error(`Port ${port} unavailable`);
+    },
+    {
+      maxAttempts: 2,
+      onRetry: (err, attempt) => {
+        log("debug", `Port retry ${attempt + 1}`, { error: err.message });
+      },
+    }
+  ).catch(err => ({ available: false, error: err.message }));
+  
+  if (!portResult.available) {
+    portInfo = findPortProcess(port);
+    const error = createError(ERROR_CODES.PORT_UNAVAILABLE, `No available ports`, {
+      requestedPort: port,
+      blockedBy: portInfo,
+    });
+    if (json) {
+      console.log(JSON.stringify(error));
+    } else {
+      console.error(`${c.red}${sym.cross} Port ${port} unavailable${portInfo ? ` (${portInfo.name})` : ""}${c.reset}`);
+    }
+    log("error", "No available ports", { port, portInfo });
+    return ERROR_CODES.PORT_UNAVAILABLE;
+  }
+  
+  if (portResult.port !== port) {
+    if (!quiet && !json) {
+      console.log(`${c.yellow}${sym.warn} Port ${port} in use, using ${portResult.port}${c.reset}\n`);
+    }
+    log("info", "Using alternate port", { requested: port, actual: portResult.port });
+    port = portResult.port;
+  }
+  
+  // Banner
+  if (!quiet && !json) {
+    console.log(`
+${c.cyan}${c.bold}╔════════════════════════════════════════════════════════════════╗
+║                                                                ║
+║   ${sym.brain} VibeCheck MCP Server v${VERSION}                             ║
+║   Your IDE is now VibeCheck-powered                            ║
+║                                                                ║
+║   ${c.dim}Hardened Build - Production Ready${c.reset}${c.cyan}${c.bold}                          ║
+║                                                                ║
+╚════════════════════════════════════════════════════════════════╝${c.reset}
+`);
+  }
+  
+  // Environment setup
+  const env = {
+    ...process.env,
+    VIBECHECK_PROJECT_PATH: projectPath,
+    VIBECHECK_MCP_PORT: String(port),
+    VIBECHECK_MCP_VERSION: VERSION,
+    NODE_ENV: process.env.NODE_ENV || "production",
+  };
+  
+  if (opts.debug) {
+    env.VIBECHECK_DEBUG = "true";
+    env.DEBUG = "vibecheck:*";
+  }
+  
+  // Spawn server process
+  const server = spawn("node", [serverPath], {
+    cwd: projectPath,
+    env,
+    stdio: opts.stdio ? "inherit" : ["pipe", "pipe", "pipe"],
+    detached: false,
+  });
+  
+  if (!server.pid) {
+    const error = createError(ERROR_CODES.STARTUP_FAILED, "Failed to spawn server process");
+    if (json) {
+      console.log(JSON.stringify(error));
+    } else {
+      console.error(`${c.red}${sym.cross} Failed to start server${c.reset}`);
+    }
+    log("error", "Spawn failed");
+    return ERROR_CODES.STARTUP_FAILED;
+  }
+  
+  // Create lock file
+  createLockFile(projectPath, server.pid, port);
+  
+  // Track server state
+  let serverReady = false;
+  let serverError = null;
+  let outputBuffer = "";
+  
+  // Handle server output
+  if (!opts.stdio) {
+    server.stdout.on("data", (data) => {
+      const text = data.toString();
+      outputBuffer += text;
+      
+      // Check for ready signal
+      if (text.includes("Server running") || text.includes("MCP server started")) {
+        serverReady = true;
+      }
+      
+      if (!quiet) {
+        process.stdout.write(redactSecrets(text));
+      }
+      
+      log("debug", "stdout", { data: redactSecrets(text.trim()) });
+    });
+    
+    server.stderr.on("data", (data) => {
+      const text = data.toString();
+      
+      // Check for errors
+      if (text.includes("Error") || text.includes("EADDRINUSE")) {
+        serverError = text.trim();
+      }
+      
+      if (!quiet) {
+        process.stderr.write(redactSecrets(text));
+      }
+      
+      log("warn", "stderr", { data: redactSecrets(text.trim()) });
+    });
+  }
+  
+  // Server error handler
+  server.on("error", (err) => {
+    serverError = err.message;
+    log("error", "Server error", { error: err.message });
+    
+    if (json) {
+      console.log(JSON.stringify(createError(ERROR_CODES.STARTUP_FAILED, err.message)));
+    } else {
+      console.error(`${c.red}${sym.cross} Server error: ${err.message}${c.reset}`);
+    }
+  });
+  
+  // Wait for server startup with timeout
+  const startupResult = await Promise.race([
+    new Promise((resolve) => {
+      const checkInterval = setInterval(() => {
+        if (serverReady) {
+          clearInterval(checkInterval);
+          resolve({ ready: true });
+        }
+        if (serverError) {
+          clearInterval(checkInterval);
+          resolve({ ready: false, error: serverError });
+        }
+      }, 100);
+    }),
+    sleep(TIMEOUTS.STARTUP).then(() => ({ ready: false, error: "Startup timeout" })),
+  ]);
+  
+  if (!startupResult.ready && !opts.stdio) {
+    // Server didn't signal ready, but may still be running
+    // Check if process is alive
+    if (!isProcessRunning(server.pid)) {
+      removeLockFile(projectPath);
+      const error = createError(ERROR_CODES.STARTUP_FAILED, startupResult.error || "Server exited unexpectedly");
+      if (json) {
+        console.log(JSON.stringify(error));
+      }
+      return ERROR_CODES.STARTUP_FAILED;
+    }
+    // Process is running, assume it's okay
+    serverReady = true;
+  }
+  
+  // Success output
+  if (!quiet && !json) {
+    console.log(`${c.green}${sym.rocket} Server started successfully${c.reset}`);
+    console.log(`${c.dim}├─ PID: ${server.pid}${c.reset}`);
+    console.log(`${c.dim}├─ Port: ${port}${c.reset}`);
+    console.log(`${c.dim}├─ Project: ${projectPath}${c.reset}`);
+    console.log(`${c.dim}└─ Lock: ${getLockFilePath(projectPath)}${c.reset}`);
+    console.log();
+    
+    // Tool summary
+    const freeTools = CANONICAL_TOOLS.filter(t => t.tier === "free");
+    const proTools = CANONICAL_TOOLS.filter(t => t.tier === "pro");
+    
+    console.log(`${c.bold}Available Tools (${CANONICAL_TOOLS.length}):${c.reset}`);
+    console.log(`  ${c.green}FREE${c.reset} (${freeTools.length}): ${freeTools.slice(0, 6).map(t => t.cli).join(", ")}...`);
+    console.log(`  ${c.magenta}PRO${c.reset}  (${proTools.length}): ${proTools.slice(0, 6).map(t => t.cli).join(", ")}...`);
+    console.log();
+    
+    console.log(`${c.dim}${"─".repeat(60)}${c.reset}`);
+    console.log(`${c.dim}Press Ctrl+C for graceful shutdown${c.reset}`);
+    console.log(`${c.dim}${"─".repeat(60)}${c.reset}\n`);
+  }
+  
+  log("info", "Server started", { pid: server.pid, port });
+  
+  // Graceful shutdown handler
+  let shuttingDown = false;
+  
+  const cleanup = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    
+    log("info", "Shutdown initiated", { signal });
+    
+    if (!quiet && !json) {
+      console.log(`\n${c.dim}${sym.timer} Shutting down gracefully...${c.reset}`);
+    }
+    
+    // Send SIGTERM first
+    server.kill("SIGTERM");
+    
+    // Wait for graceful shutdown
+    const shutdownResult = await Promise.race([
+      new Promise((resolve) => {
+        server.once("close", () => resolve({ clean: true }));
+      }),
+      sleep(TIMEOUTS.SHUTDOWN).then(() => ({ clean: false })),
+    ]);
+    
+    if (!shutdownResult.clean) {
+      log("warn", "Force killing server");
+      server.kill("SIGKILL");
+    }
+    
+    // Cleanup
+    removeLockFile(projectPath);
+    
+    if (logFile) {
+      logFile.end();
+    }
+    
+    if (!quiet && !json) {
+      console.log(`${c.green}${sym.check} Server stopped${c.reset}\n`);
+    }
+    
+    log("info", "Server stopped", { clean: shutdownResult.clean });
+  };
+  
+  // Register signal handlers
+  process.on("SIGINT", () => cleanup("SIGINT").then(() => process.exit(0)));
+  process.on("SIGTERM", () => cleanup("SIGTERM").then(() => process.exit(0)));
+  
+  // Handle uncaught errors
+  process.on("uncaughtException", (err) => {
+    log("error", "Uncaught exception", { error: err.message, stack: err.stack });
+    cleanup("uncaughtException").then(() => process.exit(1));
+  });
+  
+  // Server close handler
+  server.on("close", (code, signal) => {
+    if (!shuttingDown) {
+      log("warn", "Server exited unexpectedly", { code, signal });
+      removeLockFile(projectPath);
+      
+      if (!quiet && !json) {
+        if (code === 0) {
+          console.log(`\n${c.green}${sym.check} Server exited cleanly${c.reset}`);
+        } else {
+          console.log(`\n${c.yellow}${sym.warn} Server exited (code: ${code}, signal: ${signal})${c.reset}`);
+        }
+      }
+    }
+  });
+  
+  // Keep process alive
+  return new Promise((resolve) => {
+    server.on("close", (code) => {
+      resolve(code === 0 ? EXIT.SUCCESS : ERROR_CODES.INTERNAL_ERROR);
+    });
+  });
+}
+
+// ============================================================================
+// STATUS - Quick Status Check
+// ============================================================================
+
+async function runStatus(opts, globalFlags) {
+  const json = isJsonMode(globalFlags);
+  const quiet = shouldSuppressOutput(globalFlags);
+  const projectPath = getProjectPath(opts.path);
+  
+  const status = {
+    version: VERSION,
+    node: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    projectPath,
+    serverPath: getMcpServerPath(),
+    serverExists: mcpServerExists(),
+    manifestPath: getManifestPath(),
+    manifestExists: fs.existsSync(getManifestPath()),
+    lockFile: getLockFilePath(projectPath),
+    defaultPort: DEFAULT_PORT,
+  };
+  
+  // Check running instance
+  const instance = checkExistingInstance(projectPath);
+  status.running = instance.running;
+  if (instance.running) {
+    status.pid = instance.pid;
+    status.runningPort = instance.port;
+    status.startedAt = instance.startedAt;
+  }
+  
+  // Check port
+  status.portAvailable = await isPortAvailable(DEFAULT_PORT);
+  if (!status.portAvailable) {
+    const proc = findPortProcess(DEFAULT_PORT);
+    if (proc) {
+      status.portBlockedBy = proc;
+    }
+  }
+  
+  // Check config
+  const configPaths = [
+    path.join(projectPath, ".vibecheckrc"),
+    path.join(projectPath, "vibecheck.config.json"),
+  ];
+  status.projectConfigured = configPaths.some(p => fs.existsSync(p));
+  status.apiKeySet = !!process.env.VIBECHECK_API_KEY;
+  
+  if (json) {
+    console.log(JSON.stringify(createSuccess(status), null, 2));
+    return EXIT.SUCCESS;
+  }
+  
+  if (!quiet) {
+    console.log(`\n${c.bold}${sym.info} VibeCheck MCP Status${c.reset}\n`);
+    
+    const check = (v) => v ? `${c.green}${sym.check}${c.reset}` : `${c.red}${sym.cross}${c.reset}`;
+    const warn = (v) => v ? `${c.green}${sym.check}${c.reset}` : `${c.yellow}${sym.warn}${c.reset}`;
+    
+    console.log(`  ${c.dim}Version:${c.reset}        ${status.version}`);
+    console.log(`  ${c.dim}Node.js:${c.reset}        ${status.node}`);
+    console.log(`  ${c.dim}Platform:${c.reset}       ${status.platform}/${status.arch}`);
+    console.log();
+    console.log(`  ${c.dim}Server:${c.reset}         ${check(status.serverExists)} ${status.serverExists ? "Found" : "Not found"}`);
+    console.log(`  ${c.dim}Running:${c.reset}        ${status.running ? `${c.green}Yes${c.reset} (PID: ${status.pid})` : `${c.dim}No${c.reset}`}`);
+    console.log(`  ${c.dim}Port ${DEFAULT_PORT}:${c.reset}       ${warn(status.portAvailable)} ${status.portAvailable ? "Available" : `In use${status.portBlockedBy ? ` (${status.portBlockedBy.name})` : ""}`}`);
+    console.log();
+    console.log(`  ${c.dim}Project:${c.reset}        ${warn(status.projectConfigured)} ${status.projectConfigured ? "Configured" : "Not configured"}`);
+    console.log(`  ${c.dim}API Key:${c.reset}        ${status.apiKeySet ? `${c.green}${sym.check}${c.reset} Set` : `${c.dim}Not set${c.reset}`}`);
+    console.log();
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+// ============================================================================
+// TEST - Test MCP Connection
+// ============================================================================
+
+async function runTest(opts, globalFlags) {
+  const json = isJsonMode(globalFlags);
+  const quiet = shouldSuppressOutput(globalFlags);
+  const projectPath = getProjectPath(opts.path);
+  
+  if (!quiet && !json) {
+    console.log(`\n${c.bold}${sym.plug} Testing MCP Connection${c.reset}\n`);
+  }
+  
+  const results = {
+    serverExists: mcpServerExists(),
+    manifestExists: fs.existsSync(getManifestPath()),
+    nodeVersion: process.version,
+    nodeMajor: parseInt(process.version.slice(1).split(".")[0]),
+  };
+  
+  results.nodeOk = results.nodeMajor >= 18;
+  
+  // Check running instance
+  const instance = checkExistingInstance(projectPath);
+  results.instanceRunning = instance.running;
+  
+  // Calculate overall status
+  results.ready = results.serverExists && results.nodeOk;
+  results.canStart = results.ready && !instance.running;
+  
+  if (json) {
+    console.log(JSON.stringify(createSuccess(results), null, 2));
+    return results.ready ? EXIT.SUCCESS : ERROR_CODES.HEALTH_CHECK_FAILED;
+  }
+  
+  if (!quiet) {
+    const check = (v) => v ? `${c.green}${sym.check}${c.reset}` : `${c.red}${sym.cross}${c.reset}`;
+    
+    console.log(`  ${check(results.nodeOk)} Node.js ${results.nodeVersion} ${results.nodeOk ? "" : "(need >=18)"}`);
+    console.log(`  ${check(results.serverExists)} MCP server module`);
+    console.log(`  ${check(results.manifestExists)} Tool manifest`);
+    console.log(`  ${check(!results.instanceRunning)} No existing instance`);
+    console.log();
+    
+    if (results.ready) {
+      console.log(`${c.green}${sym.heart} Ready to start!${c.reset}`);
+      console.log(`${c.dim}Run: vibecheck mcp serve${c.reset}\n`);
+    } else {
+      console.log(`${c.red}${sym.cross} Not ready - fix issues above${c.reset}\n`);
+    }
+  }
+  
+  return results.ready ? EXIT.SUCCESS : ERROR_CODES.HEALTH_CHECK_FAILED;
+}
+
+// ============================================================================
+// HELP
+// ============================================================================
+
+function printHelp() {
+  console.log(`
+${c.cyan}${c.bold}vibecheck mcp${c.reset} - Hardened MCP Server for AI-Powered IDEs
+
+${c.bold}VERSION${c.reset}
+  ${VERSION} (Hardened Build)
+
+${c.bold}USAGE${c.reset}
+  vibecheck mcp [command] [options]
+
+${c.bold}COMMANDS${c.reset}
+  ${c.cyan}serve${c.reset}      Start the MCP server (default)
+  ${c.cyan}doctor${c.reset}     Comprehensive health check with auto-healing
+  ${c.cyan}config${c.reset}     Generate IDE-specific connection configs
+  ${c.cyan}manifest${c.reset}   Export machine-readable tool manifest
+  ${c.cyan}status${c.reset}     Quick status check
+  ${c.cyan}test${c.reset}       Test MCP readiness
+
+${c.bold}SERVE OPTIONS${c.reset}
+  --port <port>       Port number (default: ${DEFAULT_PORT})
+  --path <path>       Project path (default: cwd)
+  --no-auto-port      Don't auto-select port if blocked
+  --force             Force start (kill existing instance)
+  --debug             Enable debug logging
+  --stdio             Use stdio mode (inherit streams)
+
+${c.bold}DOCTOR OPTIONS${c.reset}
+  --fix               Auto-fix issues where possible
+  --path <path>       Project to check
+
+${c.bold}CONFIG OPTIONS${c.reset}
+  --ide <ide>         Target IDE (cursor, windsurf, claude, vscode, all)
+  --write             Write config to IDE config file
+  --npx               Use npx command
+  --cli               Use CLI wrapper
+  --api-key <key>     Include API key
+
+${c.bold}MANIFEST OPTIONS${c.reset}
+  --format <fmt>      Output format (json, summary)
+
+${c.bold}GLOBAL OPTIONS${c.reset}
+  --json              JSON output mode
+  --quiet             Suppress non-essential output
+
+${c.bold}HARDENING FEATURES${c.reset}
+  ${sym.lock} Lock file prevents multiple instances
+  ${sym.retry} Retry logic with exponential backoff
+  ${sym.shield} Input validation and sanitization
+  ${sym.key} Secret redaction in logs
+  ${sym.timer} Timeout management
+  ${sym.heart} Health probes and self-healing
+
+${c.bold}EXAMPLES${c.reset}
+  ${c.dim}# Full health check with auto-fix${c.reset}
+  vibecheck mcp doctor --fix
+
+  ${c.dim}# Start server with debug logging${c.reset}
+  vibecheck mcp serve --debug
+
+  ${c.dim}# Generate and write Cursor config${c.reset}
+  vibecheck mcp config --ide cursor --write
+
+  ${c.dim}# Quick status check${c.reset}
+  vibecheck mcp status --json
+
+${c.bold}ERROR CODES${c.reset}
+  0   Success
+  1   Validation error
+  2   Server not found
+  3   Port unavailable
+  4   Startup failed
+  5   Already running
+  12  Health check failed
+
+${c.bold}DOCUMENTATION${c.reset}
+  https://vibecheckai.dev/docs/mcp
+`);
+}
+
+// ============================================================================
+// ARGUMENT PARSING
+// ============================================================================
+
+function parseArgs(args) {
+  const opts = {
+    command: null,
+    port: null,
+    path: null,
+    autoPort: true,
+    force: false,
+    debug: false,
+    stdio: false,
+    fix: false,
+    ide: "all",
+    write: false,
+    npx: false,
+    cli: false,
+    apiKey: null,
+    format: "json",
+    help: false,
+  };
+  
+  const commands = ["serve", "doctor", "config", "manifest", "status", "test"];
+  
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    
+    if (commands.includes(a) && !opts.command) {
+      opts.command = a;
+      continue;
+    }
+    
+    switch (a) {
+      case "--port":
+        opts.port = parseInt(args[++i]);
+        break;
+      case "--path":
+        opts.path = args[++i];
+        break;
+      case "--no-auto-port":
+        opts.autoPort = false;
+        break;
+      case "--force":
+        opts.force = true;
+        break;
+      case "--debug":
+        opts.debug = true;
+        break;
+      case "--stdio":
+        opts.stdio = true;
+        break;
+      case "--fix":
+        opts.fix = true;
+        break;
+      case "--ide":
+        opts.ide = args[++i];
+        break;
+      case "--write":
+        opts.write = true;
+        break;
+      case "--npx":
+        opts.npx = true;
+        break;
+      case "--cli":
+        opts.cli = true;
+        break;
+      case "--api-key":
+        opts.apiKey = args[++i];
+        break;
+      case "--format":
+        opts.format = args[++i];
+        break;
+      case "--help":
+      case "-h":
+        opts.help = true;
+        break;
+      default:
+        if (a.startsWith("--port=")) opts.port = parseInt(a.split("=")[1]);
+        else if (a.startsWith("--path=")) opts.path = a.split("=")[1];
+        else if (a.startsWith("--ide=")) opts.ide = a.split("=")[1];
+        else if (a.startsWith("--api-key=")) opts.apiKey = a.split("=")[1];
+        else if (a.startsWith("--format=")) opts.format = a.split("=")[1];
+    }
+  }
+  
+  // Default command
+  if (!opts.command) {
+    opts.command = "serve";
+  }
+  
+  return opts;
+}
+
+// ============================================================================
+// MAIN ENTRY POINT
+// ============================================================================
+
+async function runMcp(args) {
+  const opts = parseArgs(args);
+  const { flags: globalFlags } = parseGlobalFlags(args);
+  
+  if (opts.help) {
+    printHelp();
+    return EXIT.SUCCESS;
+  }
+  
+  try {
+    switch (opts.command) {
+      case "serve":
+        return await runServe(opts, globalFlags);
+      case "doctor":
+        return await runDoctor(opts, globalFlags);
+      case "config":
+        return await runConfig(opts, globalFlags);
+      case "manifest":
+        return await runManifest(opts, globalFlags);
+      case "status":
+        return await runStatus(opts, globalFlags);
+      case "test":
+        return await runTest(opts, globalFlags);
+      default:
+        printHelp();
+        return ERROR_CODES.VALIDATION_ERROR;
+    }
+  } catch (err) {
+    log("error", "Unhandled error", { error: err.message, stack: err.stack });
+    
+    if (isJsonMode(globalFlags)) {
+      console.log(JSON.stringify(createError(ERROR_CODES.INTERNAL_ERROR, err.message)));
+    } else {
+      console.error(`${c.red}${sym.cross} Error: ${err.message}${c.reset}`);
+      if (opts.debug) {
+        console.error(err.stack);
+      }
+    }
+    
+    return ERROR_CODES.INTERNAL_ERROR;
+  }
+}
+
+module.exports = { runMcp, ERROR_CODES };