@vibecheckai/cli 3.0.10 → 3.1.0

package/bin/runners/runMcp.js

@@ -1,14 +1,807 @@
+/**
+ * Vibecheck MCP Server
+ * 
+ * Secure, tier-gated access to Vibecheck's truth analysis
+ * for IDE agents and AI assistants.
+ */
+
 const path = require("path");
-const { execSync } = require("child_process");
+const http = require("http");
+const { URL } = require("url");
+
+// Import Vibecheck modules
+const { buildTruthpack, writeTruthpack } = require("./lib/truth");
+const { shipCore } = require("./runShip");
+const { generateRunId } = require("./lib/cli-output");
+const { enforceLimit, enforceFeature, trackUsage } = require("./lib/entitlements");
+
+// MCP Server class
+class VibecheckMCPServer {
+  constructor(options = {}) {
+    this.host = options.host || "127.0.0.1";
+    this.port = options.port || 3000;
+    this.allowRemote = options.allowRemote || false;
+    this.requireApiKey = options.requireApiKey !== false;
+    this.apiKey = options.apiKey || process.env.VIBECHECK_API_KEY;
+    this.logLevel = options.logLevel || "info";
+    this.auditLog = options.auditLog || path.join(process.cwd(), ".vibecheck", "mcp-audit.log");
+    
+    // Rate limiting (in-memory for now)
+    this.rateLimits = new Map();
+    this.tiers = {
+      free: { rpm: 10, burst: 20, daily: 100 },
+      starter: { rpm: 30, burst: 60, daily: 500 },
+      pro: { rpm: 100, burst: 200, daily: 2000 },
+      enterprise: { rpm: 500, burst: 1000, daily: Infinity }
+    };
+    
+    // Tool definitions
+    this.tools = this.defineTools();
+    
+    // Ensure audit directory exists
+    require("fs").mkdirSync(path.dirname(this.auditLog), { recursive: true });
+  }
+
+  defineTools() {
+    return {
+      // Free tier tools
+      repo_map: {
+        description: "Map repository structure and detect project type",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", default: ".", description: "Repository path" },
+            includeTests: { type: "boolean", default: false, description: "Include test files" }
+          }
+        },
+        tier: "free"
+      },
+      
+      routes_list: {
+        description: "List server and client routes with metadata",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", default: ".", description: "Project path" },
+            source: { type: "string", enum: ["server", "client", "both"], default: "both" }
+          }
+        },
+        tier: "free"
+      },
+      
+      truthpack_get: {
+        description: "Retrieve the latest truthpack for the project",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", default: ".", description: "Project path" },
+            refresh: { type: "boolean", default: false, description: "Force refresh" }
+          }
+        },
+        tier: "free"
+      },
+      
+      findings_latest: {
+        description: "Retrieve findings from the latest ship check",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", default: ".", description: "Project path" },
+            severity: { type: "string", enum: ["all", "BLOCK", "WARN", "INFO"], default: "all" }
+          }
+        },
+        tier: "free"
+      },
+      
+      // Pro tier tools
+      run_ship: {
+        description: "Execute a comprehensive ship check",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", default: ".", description: "Project path" },
+            strict: { type: "boolean", default: false, description: "Fail on warnings" },
+            saveReport: { type: "boolean", default: true, description: "Save report" }
+          }
+        },
+        tier: "pro"
+      },
+      
+      // Enterprise tier tools
+      policy_check: {
+        description: "Validate project against custom compliance policies",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", default: ".", description: "Project path" },
+            policyFile: { type: "string", default: ".vibecheck/policy.yml", description: "Policy file" },
+            reportFormat: { type: "string", enum: ["json", "sarif", "markdown"], default: "json" }
+          }
+        },
+        tier: "enterprise"
+      }
+    };
+  }
+
+  // Authentication and tier checking
+  async authenticate(req) {
+    const authHeader = req.headers["authorization"];
+    const apiKey = authHeader?.replace("Bearer ", "");
+    
+    // Check if API key is required for paid tools
+    if (this.requireApiKey && !apiKey) {
+      return { tier: "free", error: "API key required for paid features" };
+    }
+    
+    // TODO: Implement actual API key validation against Vibecheck API
+    // For now, return pro tier if API key provided
+    const tier = apiKey ? "pro" : "free";
+    
+    return { tier };
+  }
+
+  // Rate limiting check
+  checkRateLimit(clientId, tier) {
+    const now = Date.now();
+    const limits = this.tiers[tier];
+    
+    if (!this.rateLimits.has(clientId)) {
+      this.rateLimits.set(clientId, {
+        requests: [],
+        dailyCount: 0,
+        dailyReset: new Date().setHours(0, 0, 0, 0) + 24 * 60 * 60 * 1000
+      });
+    }
+    
+    const client = this.rateLimits.get(clientId);
+    
+    // Reset daily counter if needed
+    if (now > client.dailyReset) {
+      client.dailyCount = 0;
+      client.dailyReset = new Date().setHours(0, 0, 0, 0) + 24 * 60 * 60 * 1000;
+    }
+    
+    // Clean old requests (older than 1 minute)
+    client.requests = client.requests.filter(time => now - time < 60000);
+    
+    // Check limits
+    if (client.requests.length >= limits.rpm) {
+      return { allowed: false, error: "Rate limit exceeded", resetAt: now + 60000 };
+    }
+    
+    if (client.dailyCount >= limits.daily) {
+      return { allowed: false, error: "Daily quota exceeded" };
+    }
+    
+    // Record request
+    client.requests.push(now);
+    client.dailyCount++;
+    
+    return { allowed: true, remaining: limits.rpm - client.requests.length };
+  }
+
+  // Audit logging
+  async logAudit(event) {
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      ...event
+    };
+    
+    try {
+      require("fs").appendFileSync(this.auditLog, JSON.stringify(logEntry) + "\n");
+    } catch (err) {
+      console.error("Failed to write audit log:", err);
+    }
+  }
 
-const c = {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
-  dim: "\x1b[2m",
-  cyan: "\x1b[36m",
-};
+  // Tool implementations
+  async handleRepoMap(args) {
+    const projectPath = path.resolve(args.path || ".");
+    
+    // Detect project type
+    const pkgPath = path.join(projectPath, "package.json");
+    let projectType = "unknown";
+    let structure = { routes: [], components: [], config: [] };
+    let metadata = {};
+    
+    if (require("fs").existsSync(pkgPath)) {
+      const pkg = JSON.parse(require("fs").readFileSync(pkgPath, "utf8"));
+      metadata.packageManager = this.detectPackageManager(projectPath);
+      metadata.hasTypeScript = require("fs").existsSync(path.join(projectPath, "tsconfig.json"));
+      metadata.frameworks = [];
+      
+      if (pkg.dependencies?.next) {
+        projectType = "nextjs";
+        metadata.frameworks.push("nextjs");
+        structure = this.scanNextProject(projectPath, args.includeTests);
+      } else if (pkg.dependencies?.fastify) {
+        projectType = "fastify";
+        metadata.frameworks.push("fastify");
+        structure = this.scanFastifyProject(projectPath, args.includeTests);
+      } else {
+        projectType = "mixed";
+        structure = this.scanGenericProject(projectPath, args.includeTests);
+      }
+    }
+    
+    return {
+      type: projectType,
+      structure,
+      metadata
+    };
+  }
+
+  async handleRoutesList(args) {
+    const projectPath = path.resolve(args.path || ".");
+    const source = args.source || "both";
+    
+    // Get truthpack
+    const truthpack = await buildTruthpack({ repoRoot: projectPath });
+    
+    const result = {};
+    
+    if (source === "server" || source === "both") {
+      result.server = truthpack.routes?.server || [];
+    }
+    
+    if (source === "client" || source === "both") {
+      result.client = truthpack.routes?.clientRefs || [];
+    }
+    
+    result.gaps = truthpack.routes?.gaps || [];
+    
+    return result;
+  }
+
+  async handleTruthpackGet(args) {
+    const projectPath = path.resolve(args.path || ".");
+    let truthpack;
+    
+    if (args.refresh) {
+      truthpack = await buildTruthpack({ repoRoot: projectPath });
+      writeTruthpack(projectPath, truthpack);
+    } else {
+      // Try to read existing truthpack
+      const truthpackPath = path.join(projectPath, ".vibecheck", "truth", "truthpack.json");
+      if (require("fs").existsSync(truthpackPath)) {
+        truthpack = JSON.parse(require("fs").readFileSync(truthpackPath, "utf8"));
+      } else {
+        truthpack = await buildTruthpack({ repoRoot: projectPath });
+        writeTruthpack(projectPath, truthpack);
+      }
+    }
+    
+    // Sanitize sensitive data
+    const sanitized = {
+      ...truthpack,
+      env: truthpack.env ? {
+        ...truthpack.env,
+        vars: truthpack.env.vars?.map(v => ({
+          ...v,
+          value: undefined // Never expose actual values
+        }))
+      } : undefined
+    };
+    
+    return sanitized;
+  }
+
+  async handleFindingsLatest(args) {
+    const projectPath = path.resolve(args.path || ".");
+    const severity = args.severity || "all";
+    
+    // Try to read latest ship report
+    const reportPath = path.join(projectPath, ".vibecheck", "last_ship.json");
+    
+    if (!require("fs").existsSync(reportPath)) {
+      throw new Error("No ship report found. Run 'vibecheck ship' first.");
+    }
+    
+    const report = JSON.parse(require("fs").readFileSync(reportPath, "utf8"));
+    
+    let findings = report.findings || [];
+    
+    if (severity !== "all") {
+      findings = findings.filter(f => f.severity === severity);
+    }
+    
+    const summary = {
+      total: findings.length,
+      blockers: findings.filter(f => f.severity === "BLOCK").length,
+      warnings: findings.filter(f => f.severity === "WARN").length,
+      info: findings.filter(f => f.severity === "INFO").length
+    };
+    
+    return {
+      verdict: report.verdict,
+      score: report.score || 0,
+      findings,
+      summary,
+      runId: report.runId,
+      timestamp: report.timestamp
+    };
+  }
 
+  async handleRunShip(args) {
+    const projectPath = path.resolve(args.path || ".");
+    
+    // Check entitlements
+    try {
+      await enforceLimit("scans");
+      await enforceFeature("ship");
+    } catch (err) {
+      throw new Error(`Access denied: ${err.message}`);
+    }
+    
+    // Run ship check
+    const result = await shipCore({ 
+      repoRoot: projectPath, 
+      noWrite: !args.saveReport,
+      strict: args.strict 
+    });
+    
+    // Track usage
+    await trackUsage("scans");
+    
+    return result;
+  }
+
+  async handlePolicyCheck(args) {
+    const projectPath = path.resolve(args.path || ".");
+    const policyFile = path.resolve(args.policyFile || ".vibecheck/policy.yml");
+    
+    if (!require("fs").existsSync(policyFile)) {
+      throw new Error("Policy file not found");
+    }
+    
+    // TODO: Implement actual policy checking
+    // For now, return a mock response
+    return {
+      compliant: true,
+      violations: [],
+      score: 100,
+      report: "Policy check passed"
+    };
+  }
+
+  // Helper methods
+  detectPackageManager(projectPath) {
+    if (require("fs").existsSync(path.join(projectPath, "pnpm-lock.yaml"))) return "pnpm";
+    if (require("fs").existsSync(path.join(projectPath, "yarn.lock"))) return "yarn";
+    if (require("fs").existsSync(path.join(projectPath, "package-lock.json"))) return "npm";
+    return "unknown";
+  }
+
+  scanNextProject(projectPath, includeTests = false) {
+    const structure = { routes: [], components: [], config: [] };
+    
+    // Scan app directory
+    const appDir = path.join(projectPath, "app");
+    if (require("fs").existsSync(appDir)) {
+      this.scanDirectory(appDir, structure, includeTests, "app");
+    }
+    
+    // Scan pages directory
+    const pagesDir = path.join(projectPath, "pages");
+    if (require("fs").existsSync(pagesDir)) {
+      this.scanDirectory(pagesDir, structure, includeTests, "pages");
+    }
+    
+    // Scan components
+    const componentsDir = path.join(projectPath, "components");
+    if (require("fs").existsSync(componentsDir)) {
+      this.scanDirectory(componentsDir, structure, includeTests, "components");
+    }
+    
+    return structure;
+  }
+
+  scanFastifyProject(projectPath, includeTests = false) {
+    const structure = { routes: [], components: [], config: [] };
+    
+    // Find main entry file
+    const possibleEntries = ["index.js", "server.js", "app.js", "main.js"];
+    for (const entry of possibleEntries) {
+      const entryPath = path.join(projectPath, entry);
+      if (require("fs").existsSync(entryPath)) {
+        this.scanFile(entryPath, structure, "server");
+        break;
+      }
+    }
+    
+    return structure;
+  }
+
+  scanGenericProject(projectPath, includeTests = false) {
+    const structure = { routes: [], components: [], config: [] };
+    this.scanDirectory(projectPath, structure, includeTests, "root");
+    return structure;
+  }
+
+  scanDirectory(dir, structure, includeTests, type) {
+    if (!require("fs").existsSync(dir)) return;
+    
+    const items = require("fs").readdirSync(dir);
+    
+    for (const item of items) {
+      if (item.startsWith(".") || item === "node_modules") continue;
+      if (!includeTests && (item.includes(".test.") || item.includes(".spec."))) continue;
+      
+      const itemPath = path.join(dir, item);
+      const stat = require("fs").statSync(itemPath);
+      
+      if (stat.isDirectory()) {
+        this.scanDirectory(itemPath, structure, includeTests, type);
+      } else if (stat.isFile() && (item.endsWith(".js") || item.endsWith(".ts") || item.endsWith(".jsx") || item.endsWith(".tsx"))) {
+        this.scanFile(itemPath, structure, type);
+      }
+    }
+  }
+
+  scanFile(filePath, structure, type) {
+    const relative = path.relative(process.cwd(), filePath);
+    
+    if (type === "components" || relative.includes("components")) {
+      structure.components.push(relative);
+    } else if (type === "server" || relative.includes("routes") || relative.includes("api")) {
+      structure.routes.push(relative);
+    } else if (relative.includes("config") || relative.endsWith(".config.js") || relative.endsWith(".config.ts")) {
+      structure.config.push(relative);
+    }
+  }
+
+  // HTTP request handler
+  async handleRequest(req, res) {
+    const startTime = Date.now();
+    let clientId = req.headers["x-client-id"] || "unknown";
+    
+    try {
+      // Parse URL
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      
+      // Handle different endpoints
+      if (url.pathname === "/tools") {
+        // List available tools
+        const auth = await this.authenticate(req);
+        const availableTools = Object.entries(this.tools)
+          .filter(([_, tool]) => this.checkTierAccess(tool.tier, auth.tier))
+          .map(([name, tool]) => ({
+            name,
+            description: tool.description,
+            inputSchema: tool.inputSchema
+          }));
+        
+        this.sendJson(res, { tools: availableTools });
+        return;
+      }
+      
+      if (url.pathname === "/call" && req.method === "POST") {
+        // Tool execution
+        const body = await this.parseBody(req);
+        const { tool, arguments: args } = body;
+        
+        if (!tool || !this.tools[tool]) {
+          this.sendError(res, 400, "Unknown tool");
+          return;
+        }
+        
+        // Authenticate
+        const auth = await this.authenticate(req);
+        if (auth.error) {
+          this.sendError(res, 401, auth.error);
+          return;
+        }
+        
+        // Check tier access
+        if (!this.checkTierAccess(this.tools[tool].tier, auth.tier)) {
+          this.sendError(res, 403, `Tool '${tool}' requires ${this.tools[tool].tier} tier`);
+          return;
+        }
+        
+        // Rate limit
+        const rateLimit = this.checkRateLimit(clientId, auth.tier);
+        if (!rateLimit.allowed) {
+          this.sendError(res, 429, rateLimit.error);
+          return;
+        }
+        
+        // Execute tool
+        const runId = generateRunId();
+        const result = await this.executeTool(tool, args);
+        const duration = Date.now() - startTime;
+        
+        // Log audit
+        await this.logAudit({
+          clientId,
+          tier: auth.tier,
+          tool,
+          duration,
+          success: true,
+          runId
+        });
+        
+        // Send response
+        this.sendJson(res, {
+          success: true,
+          data: result,
+          meta: {
+            runId,
+            duration,
+            tier: auth.tier,
+            rateLimit: {
+              remaining: rateLimit.remaining
+            }
+          }
+        });
+        
+        return;
+      }
+      
+      if (url.pathname === "/status") {
+        // Server status
+        this.sendJson(res, {
+          status: "running",
+          version: require("../../package.json").version,
+          uptime: process.uptime(),
+          activeClients: this.rateLimits.size
+        });
+        return;
+      }
+      
+      // Unknown endpoint
+      this.sendError(res, 404, "Not found");
+      
+    } catch (error) {
+      console.error("MCP Server Error:", error);
+      
+      // Log audit
+      await this.logAudit({
+        clientId,
+        error: error.message,
+        success: false
+      });
+      
+      this.sendError(res, 500, "Internal server error");
+    }
+  }
+
+  async executeTool(toolName, args) {
+    switch (toolName) {
+      case "repo_map":
+        return await this.handleRepoMap(args);
+      case "routes_list":
+        return await this.handleRoutesList(args);
+      case "truthpack_get":
+        return await this.handleTruthpackGet(args);
+      case "findings_latest":
+        return await this.handleFindingsLatest(args);
+      case "run_ship":
+        return await this.handleRunShip(args);
+      case "policy_check":
+        return await this.handlePolicyCheck(args);
+      default:
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  }
+
+  checkTierAccess(requiredTier, userTier) {
+    const tierOrder = ["free", "starter", "pro", "enterprise"];
+    const requiredIndex = tierOrder.indexOf(requiredTier);
+    const userIndex = tierOrder.indexOf(userTier);
+    
+    return userIndex >= requiredIndex;
+  }
+
+  parseBody(req) {
+    return new Promise((resolve, reject) => {
+      let body = "";
+      req.on("data", chunk => body += chunk);
+      req.on("end", () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch (err) {
+          reject(err);
+        }
+      });
+      req.on("error", reject);
+    });
+  }
+
+  sendJson(res, data) {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(data, null, 2));
+  }
+
+  sendError(res, code, message) {
+    res.writeHead(code, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+      error: {
+        code,
+        message
+      }
+    }, null, 2));
+  }
+
+  // Start server
+  start() {
+    this.server = http.createServer((req, res) => {
+      // Check remote access
+      if (!this.allowRemote && req.socket.remoteAddress !== "127.0.0.1" && req.socket.remoteAddress !== "::1") {
+        this.sendError(res, 403, "Remote access not allowed");
+        return;
+      }
+      
+      this.handleRequest(req, res);
+    });
+    
+    this.server.listen(this.port, this.host, () => {
+      console.log(`🚀 Vibecheck MCP Server running on http://${this.host}:${this.port}`);
+      console.log(`📋 Tools available: ${Object.keys(this.tools).length}`);
+      console.log(`🔐 Remote access: ${this.allowRemote ? "enabled" : "disabled"}`);
+      console.log(`🔑 API key required: ${this.requireApiKey ? "yes" : "no"}`);
+    });
+    
+    this.server.on("error", err => {
+      console.error("MCP Server failed to start:", err);
+      process.exit(1);
+    });
+  }
+
+  stop() {
+    if (this.server) {
+      this.server.close();
+      console.log("MCP Server stopped");
+    }
+  }
+}
+
+// CLI handler
+async function runMcp(args) {
+  const opts = parseArgs(args);
+  
+  // Check if we're in free tier and only showing help/config
+  const isFreeTier = process.env.VIBECHECK_TIER === "free" || !process.env.VIBECHECK_API_KEY;
+  const isHelpOrConfig = opts.help || opts.printConfig || opts.status || opts.test;
+  
+  if (isFreeTier && !isHelpOrConfig) {
+    // This will be handled by entitlements system
+    // But we can show a helpful message
+    console.log("\n🔌 MCP Server requires STARTER plan or higher");
+    console.log("Use --help to see available options or");
+    console.log("Upgrade: https://vibecheckai.dev/pricing\n");
+    return 3; // EXIT_FEATURE_NOT_ALLOWED
+  }
+  
+  if (opts.help) {
+    printHelp();
+    return 0;
+  }
+  
+  if (opts.printConfig) {
+    printClientConfig(opts);
+    return 0;
+  }
+  
+  if (opts.status) {
+    // Check server status
+    try {
+      const response = await fetch(`http://${opts.host}:${opts.port}/status`);
+      const status = await response.json();
+      console.log(JSON.stringify(status, null, 2));
+      return 0;
+    } catch (err) {
+      console.error("Server not running or not reachable");
+      return 1;
+    }
+  }
+  
+  if (opts.test) {
+    // Test connection
+    try {
+      const response = await fetch(`http://${opts.host}:${opts.port}/tools`);
+      const tools = await response.json();
+      console.log("✅ Connection successful");
+      console.log(`📋 Available tools: ${tools.tools.length}`);
+      return 0;
+    } catch (err) {
+      console.error("❌ Connection failed:", err.message);
+      return 1;
+    }
+  }
+  
+  // Load config if provided
+  let config = {};
+  if (opts.config) {
+    const configPath = path.resolve(opts.config);
+    if (require("fs").existsSync(configPath)) {
+      config = JSON.parse(require("fs").readFileSync(configPath, "utf8"));
+    } else {
+      console.error(`Config file not found: ${configPath}`);
+      return 1;
+    }
+  }
+  
+  // Create and start server
+  const server = new VibecheckMCPServer({
+    host: opts.host || config.server?.host || "127.0.0.1",
+    port: opts.port || config.server?.port || 3000,
+    allowRemote: opts.allowRemote || config.server?.allowRemote || false,
+    requireApiKey: opts.requireApiKey !== false,
+    apiKey: opts.apiKey || config.auth?.apiKey,
+    logLevel: opts.logLevel || config.logging?.level || "info",
+    auditLog: opts.auditLog || config.logging?.auditFile
+  });
+  
+  server.start();
+  
+  // Handle shutdown
+  process.on("SIGINT", () => {
+    console.log("\nShutting down MCP server...");
+    server.stop();
+    process.exit(0);
+  });
+  
+  process.on("SIGTERM", () => {
+    console.log("\nShutting down MCP server...");
+    server.stop();
+    process.exit(0);
+  });
+  
+  // Keep process alive
+  return new Promise(() => {});
+}
+
+// Argument parsing
+function parseArgs(args) {
+  const opts = {
+    host: null,
+    port: null,
+    allowRemote: false,
+    requireApiKey: true,
+    apiKey: null,
+    config: null,
+    logLevel: null,
+    auditLog: null,
+    printConfig: false,
+    status: false,
+    test: false,
+    help: false
+  };
+  
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--host") opts.host = args[++i];
+    else if (a.startsWith("--host=")) opts.host = a.split("=")[1];
+    else if (a === "--port") opts.port = parseInt(args[++i]);
+    else if (a.startsWith("--port=")) opts.port = parseInt(a.split("=")[1]);
+    else if (a === "--allow-remote") opts.allowRemote = true;
+    else if (a === "--no-api-key") opts.requireApiKey = false;
+    else if (a === "--api-key") opts.apiKey = args[++i];
+    else if (a.startsWith("--api-key=")) opts.apiKey = a.split("=")[1];
+    else if (a === "--config") opts.config = args[++i];
+    else if (a.startsWith("--config=")) opts.config = a.split("=")[1];
+    else if (a === "--log-level") opts.logLevel = args[++i];
+    else if (a.startsWith("--log-level=")) opts.logLevel = a.split("=")[1];
+    else if (a === "--audit-log") opts.auditLog = args[++i];
+    else if (a.startsWith("--audit-log=")) opts.auditLog = a.split("=")[1];
+    else if (a === "--print-config") opts.printConfig = true;
+    else if (a === "--status") opts.status = true;
+    else if (a === "--test") opts.test = true;
+    else if (a === "--help" || a === "-h") opts.help = true;
+  }
+  
+  return opts;
+}
+
+// Help text
 function printHelp() {
+  const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+  };
+  
   console.log(`
 ${c.cyan}${c.bold}vibecheck mcp${c.reset} - MCP Server for AI Agents
 
@@ -16,62 +809,92 @@ ${c.bold}USAGE${c.reset}
   vibecheck mcp [options]
 
 ${c.bold}OPTIONS${c.reset}
-  --help, -h    Show this help
-
-${c.bold}WHAT IT DOES${c.reset}
-  Starts a Model Context Protocol (MCP) server that allows AI agents
-  (like Claude, Cursor, Windsurf) to interact with vibecheck tools.
+  --host <host>           Server host (default: 127.0.0.1)
+  --port <port>           Server port (default: 3000)
+  --allow-remote          Allow remote connections
+  --no-api-key           Don't require API key for paid features
+  --api-key <key>        API key for authentication
+  --config <file>        Configuration file path
+  --log-level <level>    Log level (debug, info, warn, error)
+  --audit-log <file>     Audit log file path
+  --print-config         Print client configuration
+  --status              Check server status
+  --test                Test connection
+  --help, -h            Show this help
 
 ${c.bold}MCP TOOLS AVAILABLE${c.reset}
-  • vibecheck.scan           Run static analysis
-  • vibecheck.ship           Get ship verdict
-  • vibecheck.validate_claim Verify code claims
-  • vibecheck.get_truthpack  Get ground truth
-  • vibecheck.list_findings  List current findings
+  ${c.dim}Free Tier:${c.reset}
+  • repo_map           Map repository structure
+  • routes_list        List server/client routes
+  • truthpack_get      Get project truthpack
+  • findings_latest    Get latest scan findings
+  
+  ${c.dim}Pro Tier:${c.reset}
+  • run_ship           Execute ship check
+  
+  ${c.dim}Enterprise Tier:${c.reset}
+  • policy_check       Validate against policies
 
 ${c.bold}CONFIGURATION${c.reset}
   Add to your AI IDE's MCP config:
   
-  ${c.dim}// cursor/windsurf settings${c.reset}
+  ${c.dim}// Claude Desktop config${c.reset}
   {
     "mcpServers": {
       "vibecheck": {
-        "command": "npx",
-        "args": ["vibecheck", "mcp"]
+        "command": "node",
+        "args": ["./bin/vibecheck.js", "mcp"],
+        "env": {
+          "VIBECHECK_API_KEY": "your-key-here"
+        }
       }
     }
   }
 
+${c.bold}SECURITY${c.reset}
+  • Local-only by default (127.0.0.1)
+  • API key authentication for paid tiers
+  • Rate limiting per client
+  • Full audit logging
+  • No secret exposure
+
+${c.bold}EXAMPLES${c.reset}
+  vibecheck mcp                          # Start server with defaults
+  vibecheck mcp --port 8080              # Custom port
+  vibecheck mcp --allow-remote           # Allow remote connections
+  vibecheck mcp --print-config           # Print client config
+  vibecheck mcp --status                 # Check if running
+  vibecheck mcp --test                   # Test connection
+
 ${c.bold}NOTE${c.reset}
   This command starts a long-running server process.
   Press Ctrl+C to stop.
-
-${c.bold}EXAMPLES${c.reset}
-  vibecheck mcp    # Start MCP server
 `);
 }
 
-function runMcp(args) {
-  // Handle array args from CLI
-  if (Array.isArray(args)) {
-    if (args.includes("--help") || args.includes("-h")) {
-      printHelp();
-      return 0;
+// Print client configuration
+function printClientConfig(opts) {
+  const config = {
+    mcpServers: {
+      vibecheck: {
+        command: "node",
+        args: ["./bin/vibecheck.js", "mcp"],
+        env: {}
+      }
     }
+  };
+  
+  if (opts.apiKey) {
+    config.mcpServers.vibecheck.env.VIBECHECK_API_KEY = opts.apiKey;
   }
-
-  console.log("\n  🔌 Starting vibecheck MCP Server...\n");
-
-  const mcpServer = path.join(__dirname, "../../mcp-server/index.js");
-
-  try {
-    execSync(`node "${mcpServer}"`, { stdio: "inherit" });
-  } catch (error) {
-    console.error("  ❌ MCP Server failed to start");
-    return 1;
+  
+  if (opts.port && opts.port !== 3000) {
+    config.mcpServers.vibecheck.args.push("--port", opts.port.toString());
   }
-
-  return 0;
+  
+  console.log("Client configuration for Claude Desktop:");
+  console.log(JSON.stringify(config, null, 2));
+  console.log("\nAdd this to your claude_desktop_config.json file");
 }
 
-module.exports = { runMcp };
+module.exports = { runMcp, VibecheckMCPServer };