@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/src/lib/installers/mcp-installer.js

@@ -1,719 +1,724 @@
-/**
- * MCP Installer
- *
- * Core logic for installing and configuring MCP servers during morph-spec init
- * and via `morph-spec mcp setup`. Handles auto-installable (credential-free)
- * MCPs, prerequisite checking, credential collection, and setup guidance.
- */
-
-import { join } from 'path';
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
-import { execSync, spawn } from 'child_process';
-import { homedir } from 'os';
-import { installMcpServers } from '../../utils/claude-settings-manager.js';
-
-/**
- * Load the enhanced MCP registry (v3.0.0)
- * @returns {Object} Registry with install blocks
- */
-export function loadMcpRegistry() {
-  const registryPath = join(
-    import.meta.dirname, '..', '..', '..', 'framework', 'mcp', 'registry.json'
-  );
-  const raw = readFileSync(registryPath, 'utf-8');
-  return JSON.parse(raw);
-}
-
-/**
- * Filter MCPs by stack relevance
- * @param {Object} registry - Full MCP registry
- * @param {string} stack - Detected project stack (e.g., 'nextjs-neon', 'blazor')
- * @returns {Object} Filtered map of mcpName → mcpEntry
- */
-export function filterByStack(registry, stack) {
-  const result = {};
-  const normalizedStack = (stack || '').toLowerCase();
-
-  for (const [name, entry] of Object.entries(registry.mcps)) {
-    if (!entry.install) continue;
-    const relevance = entry.install.stackRelevance || [];
-
-    if (relevance.includes('*')) {
-      result[name] = entry;
-    } else if (normalizedStack && relevance.some(s => normalizedStack.includes(s))) {
-      result[name] = entry;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Match detected MCP servers against the registry
- * @param {Array} existingServers - From detectClaudeConfig().mcpServers
- * @param {Object} registry - MCP registry
- * @returns {Object} Map of mcpName → { installed: true, source }
- */
-export function getInstalledMcps(existingServers, registry) {
-  const installed = {};
-  const registryNames = Object.keys(registry.mcps);
-
-  for (const server of existingServers) {
-    const serverName = server.name.toLowerCase();
-    for (const regName of registryNames) {
-      if (serverName.includes(regName)) {
-        installed[regName] = { installed: true, source: server.source };
-      }
-    }
-  }
-
-  return installed;
-}
-
-/**
- * Check if prerequisites are met for an MCP entry
- * @param {Object} mcpEntry - MCP entry from registry
- * @returns {Array} Array of { name, met, installUrl } for each prerequisite
- */
-export function checkPrerequisites(mcpEntry) {
-  const prereqs = mcpEntry.install?.prerequisites || [];
-  const results = [];
-
-  for (const prereq of prereqs) {
-    let met = false;
-    try {
-      execSync(prereq.checkCommand, { stdio: 'ignore', timeout: 5000 });
-      met = true;
-    } catch {
-      // Command failed or not found
-    }
-    results.push({
-      name: prereq.name,
-      met,
-      installUrl: prereq.installUrl
-    });
-  }
-
-  return results;
-}
-
-/**
- * Check if an MCP config uses remote HTTP transport (no local process).
- * @param {Object} config - MCP server config
- * @returns {boolean}
- */
-export function isRemoteMcp(config) {
-  return config.type === 'http' || config.url != null;
-}
-
-/**
- * Patch MCP config for the current platform.
- * On Windows, npx must be invoked via `cmd /c` to avoid ENOENT errors.
- * Registry already stores cmd/c format; this handles legacy configs that still use npx directly.
- * Remote HTTP MCPs are returned as-is (no local process to patch).
- * @param {Object} config - MCP server config { command, args, env? } or { type: "http", url }
- * @returns {Object} Patched config (new object, original unmodified)
- */
-export function patchConfigForPlatform(config) {
-  // Remote MCPs need no platform patching
-  if (isRemoteMcp(config)) return config;
-  if (config.command !== 'npx') return config;
-  return {
-    ...config,
-    command: 'cmd',
-    args: ['/c', 'npx', ...(config.args || [])]
-  };
-}
-
-/**
- * Install auto-installable MCPs (no credentials, no prerequisites)
- * @param {string} targetPath - Project root directory
- * @param {Object} mcpsToInstall - Map of mcpName → mcpEntry
- * @returns {Promise<Object>} Result from installMcpServers
- */
-export async function installAutoMcps(targetPath, mcpsToInstall) {
-  const servers = {};
-
-  for (const [name, entry] of Object.entries(mcpsToInstall)) {
-    let config = { ...entry.install.config };
-    // Remote MCPs don't have env to strip
-    if (!isRemoteMcp(config)) {
-      // Only include env if it has actual values
-      if (config.env && Object.values(config.env).every(v => !v)) {
-        delete config.env;
-      }
-    }
-    servers[name] = patchConfigForPlatform(config);
-  }
-
-  return installMcpServers(targetPath, servers);
-}
-
-/**
- * Install companion skills for MCPs that define them (e.g., Stitch agent skills).
- * Reads the `companionSkills` field from registry entries and runs the install command.
- * @param {Object} mcpsInstalled - Map of mcpName → mcpEntry that were just installed
- * @param {Function} exec - execSync function (for testing)
- * @returns {Array<{name: string, repo: string, success: boolean}>}
- */
-export function installCompanionSkills(mcpsInstalled, exec = execSync) {
-  const results = [];
-
-  for (const [name, entry] of Object.entries(mcpsInstalled)) {
-    const companion = entry.companionSkills;
-    if (!companion?.installCommand) continue;
-
-    try {
-      exec(companion.installCommand, { stdio: 'inherit', timeout: 30000 });
-      results.push({ name, repo: companion.repo, success: true });
-    } catch {
-      results.push({ name, repo: companion.repo, success: false });
-    }
-  }
-
-  return results;
-}
-
-/**
- * Generate the Stitch OAuth proxy template script.
- * Cross-platform (Windows gcloud.cmd + Unix gcloud), fetch()-based,
- * with readline, session tracking, and graceful shutdown.
- * @param {string} gcpProject - GCP project ID for x-goog-user-project header
- * @returns {string} CJS proxy script content
- */
-export function getStitchProxyTemplate(gcpProject) {
-  return `#!/usr/bin/env node
-/**
- * Stitch MCP stdio-to-HTTP proxy with Google auth
- * Generated by morph-spec mcp setup stitch
- */
-const { execSync } = require('child_process');
-const { createInterface } = require('readline');
-
-const STITCH_URL = 'https://stitch.googleapis.com/mcp';
-const PROJECT_ID = '${gcpProject}';
-
-// Cross-platform gcloud path: Windows uses gcloud.cmd from Cloud SDK install
-const GCLOUD = process.platform === 'win32'
-  ? (process.env.LOCALAPPDATA || '') + '/Google/Cloud SDK/google-cloud-sdk/bin/gcloud.cmd'
-  : 'gcloud';
-
-let cachedToken = null;
-let tokenExpiry = 0;
-let pendingRequests = 0;
-let stdinClosed = false;
-let sessionId = null;
-
-function getToken() {
-  if (cachedToken && Date.now() < tokenExpiry) return cachedToken;
-  try {
-    cachedToken = execSync(\`"\${GCLOUD}" auth application-default print-access-token\`, {
-      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000
-    }).trim();
-    tokenExpiry = Date.now() + 50 * 60 * 1000; // 50-minute TTL
-    return cachedToken;
-  } catch {
-    return null;
-  }
-}
-
-function maybeExit() {
-  if (stdinClosed && pendingRequests === 0) process.exit(0);
-}
-
-async function handleMessage(line) {
-  let msg;
-  try { msg = JSON.parse(line); } catch { return; }
-
-  // Notifications (no id) don't need responses
-  if (msg.id === undefined && msg.method === 'notifications/initialized') return;
-
-  const token = getToken();
-  if (!token) {
-    if (msg.id !== undefined) {
-      process.stdout.write(JSON.stringify({
-        jsonrpc: '2.0', id: msg.id,
-        error: { code: -32000, message: 'Failed to get gcloud auth token. Run: gcloud auth application-default login' }
-      }) + '\\n');
-    }
-    return;
-  }
-
-  const headers = {
-    'Content-Type': 'application/json',
-    'Authorization': \`Bearer \${token}\`,
-    'x-goog-user-project': PROJECT_ID,
-  };
-  if (sessionId) headers['mcp-session-id'] = sessionId;
-
-  pendingRequests++;
-  try {
-    const res = await fetch(STITCH_URL, { method: 'POST', headers, body: JSON.stringify(msg) });
-
-    // Track sticky session
-    const sid = res.headers.get('mcp-session-id');
-    if (sid) sessionId = sid;
-
-    // Retry once on 401 (expired token)
-    if (res.status === 401) {
-      cachedToken = null;
-      tokenExpiry = 0;
-      const retryToken = getToken();
-      if (retryToken) {
-        headers['Authorization'] = \`Bearer \${retryToken}\`;
-        const retryRes = await fetch(STITCH_URL, { method: 'POST', headers, body: JSON.stringify(msg) });
-        const retryText = await retryRes.text();
-        if (retryText.trim()) {
-          process.stdout.write(retryText.endsWith('\\n') ? retryText : retryText + '\\n');
-        }
-        return;
-      }
-    }
-
-    const text = await res.text();
-    if (text.trim()) {
-      process.stdout.write(text.endsWith('\\n') ? text : text + '\\n');
-    }
-  } catch (err) {
-    if (msg.id !== undefined) {
-      process.stdout.write(JSON.stringify({
-        jsonrpc: '2.0', id: msg.id,
-        error: { code: -32000, message: \`Stitch API error: \${err.message}\` }
-      }) + '\\n');
-    }
-  } finally {
-    pendingRequests--;
-    maybeExit();
-  }
-}
-
-const rl = createInterface({ input: process.stdin });
-rl.on('line', handleMessage);
-rl.on('close', () => { stdinClosed = true; maybeExit(); });
-`;
-}
-
-/**
- * Generate and write the Stitch OAuth proxy script to the target project.
- * @param {string} targetPath - Project root directory
- * @param {string} gcpProject - GCP project ID
- * @returns {{ proxyPath: string }} Path to the generated proxy script
- */
-export function generateStitchProxy(targetPath, gcpProject) {
-  const claudeDir = join(targetPath, '.claude');
-  if (!existsSync(claudeDir)) {
-    mkdirSync(claudeDir, { recursive: true });
-  }
-
-  const proxyPath = join(claudeDir, 'stitch-proxy.cjs');
-  writeFileSync(proxyPath, getStitchProxyTemplate(gcpProject), 'utf-8');
-
-  return { proxyPath };
-}
-
-/**
- * Resolve the gcloud CLI binary path.
- * Checks: system PATH → bundled at ~/.stitch-mcp/ → null.
- * @param {Function} exec - execSync function (for testing)
- * @returns {{ gcloudPath: string|null, source: string }}
- */
-export function findGcloud(exec = execSync) {
-  // Try system PATH first
-  try {
-    exec('gcloud --version', { stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000 });
-    return { gcloudPath: 'gcloud', source: 'system' };
-  } catch { /* not on PATH */ }
-
-  // Windows: try Cloud SDK default install location
-  if (process.platform === 'win32') {
-    const winPath = join(process.env.LOCALAPPDATA || '', 'Google', 'Cloud SDK', 'google-cloud-sdk', 'bin', 'gcloud.cmd');
-    if (existsSync(winPath)) {
-      return { gcloudPath: winPath, source: 'windows-sdk' };
-    }
-  }
-
-  // Try bundled at ~/.stitch-mcp/
-  const bundledDir = join(homedir(), '.stitch-mcp');
-  const bundledBin = process.platform === 'win32'
-    ? join(bundledDir, 'google-cloud-sdk', 'bin', 'gcloud.cmd')
-    : join(bundledDir, 'google-cloud-sdk', 'bin', 'gcloud');
-  if (existsSync(bundledBin)) {
-    return { gcloudPath: bundledBin, source: 'bundled' };
-  }
-
-  return { gcloudPath: null, source: 'not-found' };
-}
-
-/**
- * Fully automated Stitch MCP setup orchestrator.
- *
- * Steps:
- * 1. Find gcloud CLI
- * 2. Verify ADC credentials
- * 3. Detect GCP project
- * 4. Enable stitch.googleapis.com API
- * 5. Generate proxy script
- * 6. Install MCP config in .mcp.json
- * 7. Health-check the proxy
- *
- * @param {string} targetPath - Project root directory
- * @param {Object} options
- * @param {string} [options.gcpProject] - GCP project ID (auto-detected if omitted)
- * @param {Function} [options._exec] - execSync override for testing
- * @returns {Promise<Object>} Step-by-step results
- */
-export async function setupStitch(targetPath, options = {}) {
-  const exec = options._exec || execSync;
-  const steps = [];
-
-  // Step 1: Find gcloud
-  const { gcloudPath, source: gcloudSource } = findGcloud(exec);
-  if (!gcloudPath) {
-    steps.push({ step: 'find-gcloud', success: false, error: 'gcloud CLI not found. Install from: https://cloud.google.com/sdk/docs/install' });
-    return { success: false, steps };
-  }
-  steps.push({ step: 'find-gcloud', success: true, gcloudPath, source: gcloudSource });
-
-  const gcloudCmd = gcloudPath.includes(' ') ? `"${gcloudPath}"` : gcloudPath;
-
-  // Step 2: Verify ADC credentials
-  try {
-    exec(`${gcloudCmd} auth application-default print-access-token`, {
-      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 15000
-    });
-    steps.push({ step: 'verify-adc', success: true });
-  } catch {
-    steps.push({ step: 'verify-adc', success: false, error: 'No ADC credentials. Run: gcloud auth application-default login' });
-    return { success: false, steps };
-  }
-
-  // Step 3: Detect GCP project
-  let gcpProject = options.gcpProject;
-  if (!gcpProject) {
-    // Try config.json
-    const configPath = join(targetPath, '.morph', 'config', 'config.json');
-    if (existsSync(configPath)) {
-      try {
-        const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-        gcpProject = config.gcpProject || config.project?.gcpProject;
-      } catch { /* invalid config */ }
-    }
-  }
-  if (!gcpProject) {
-    // Try gcloud config
-    try {
-      gcpProject = exec(`${gcloudCmd} config get-value project`, {
-        encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000
-      }).trim();
-      if (!gcpProject || gcpProject === '(unset)') gcpProject = null;
-    } catch { /* gcloud config failed */ }
-  }
-  if (!gcpProject) {
-    steps.push({ step: 'detect-project', success: false, error: 'Could not detect GCP project. Pass it explicitly or set via: gcloud config set project <id>' });
-    return { success: false, steps };
-  }
-  steps.push({ step: 'detect-project', success: true, gcpProject });
-
-  // Step 4: Enable Stitch API
-  try {
-    exec(`${gcloudCmd} services enable stitch.googleapis.com --project=${gcpProject}`, {
-      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000
-    });
-    steps.push({ step: 'enable-api', success: true });
-  } catch (err) {
-    steps.push({ step: 'enable-api', success: false, error: `Failed to enable stitch API: ${err.message}` });
-    // Non-fatal — API might already be enabled and user may lack permissions to re-enable
-  }
-
-  // Step 5: Generate proxy
-  const { proxyPath } = generateStitchProxy(targetPath, gcpProject);
-  steps.push({ step: 'generate-proxy', success: true, proxyPath });
-
-  // Step 6: Install MCP config in .mcp.json
-  const mcpResult = await installMcpServers(targetPath, {
-    stitch: { type: 'stdio', command: 'node', args: ['.claude/stitch-proxy.cjs'] }
-  });
-  steps.push({ step: 'install-mcp', success: true, added: mcpResult.added, skipped: mcpResult.skipped });
-
-  // Step 7: Health-check
-  const healthResult = await healthCheckStitchProxy(proxyPath);
-  steps.push({ step: 'health-check', ...healthResult });
-
-  const allCriticalPassed = steps.every(s =>
-    s.success || s.step === 'enable-api' || s.step === 'health-check'
-  );
-
-  return { success: allCriticalPassed, steps, gcpProject };
-}
-
-/**
- * Health-check the Stitch proxy by sending an MCP initialize handshake.
- * @param {string} proxyPath - Path to stitch-proxy.cjs
- * @returns {Promise<Object>} { success, protocolVersion?, error? }
- */
-export function healthCheckStitchProxy(proxyPath) {
-  return new Promise((resolve) => {
-    const initMsg = JSON.stringify({
-      jsonrpc: '2.0',
-      id: 1,
-      method: 'initialize',
-      params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'morph-spec', version: '1.0.0' } }
-    });
-
-    const child = spawn('node', [proxyPath], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 20000,
-    });
-
-    let output = '';
-    let timedOut = false;
-
-    const timer = setTimeout(() => {
-      timedOut = true;
-      child.kill();
-      resolve({ success: false, error: 'Health-check timed out after 20s' });
-    }, 20000);
-
-    child.stdout.on('data', (data) => {
-      output += data.toString();
-      // Check if we got a response
-      const lines = output.split('\n').filter(l => l.trim());
-      for (const line of lines) {
-        try {
-          const resp = JSON.parse(line);
-          if (resp.result?.protocolVersion) {
-            clearTimeout(timer);
-            child.kill();
-            resolve({ success: true, protocolVersion: resp.result.protocolVersion });
-            return;
-          }
-          if (resp.error) {
-            clearTimeout(timer);
-            child.kill();
-            resolve({ success: false, error: resp.error.message || 'MCP error' });
-            return;
-          }
-        } catch { /* not valid JSON yet */ }
-      }
-    });
-
-    child.on('error', (err) => {
-      if (!timedOut) {
-        clearTimeout(timer);
-        resolve({ success: false, error: err.message });
-      }
-    });
-
-    child.on('close', (code) => {
-      if (!timedOut) {
-        clearTimeout(timer);
-        resolve({ success: false, error: output.trim()
-          ? `Proxy exited with code ${code} — unexpected output`
-          : `Proxy exited with code ${code} and no output`
-        });
-      }
-    });
-
-    // Send the initialize message
-    child.stdin.write(initMsg + '\n');
-    child.stdin.end();
-  });
-}
-
-/**
- * Install a single MCP with provided credentials
- * @param {string} targetPath - Project root directory
- * @param {string} name - MCP name
- * @param {Object} mcpEntry - MCP entry from registry
- * @param {Object} credentialValues - Map of envVar → value
- * @returns {Promise<Object>} Result from installMcpServers
- */
-export async function installMcpWithCredentials(targetPath, name, mcpEntry, credentialValues) {
-  const config = patchConfigForPlatform({ ...mcpEntry.install.config });
-  config.env = { ...config.env, ...credentialValues };
-  return installMcpServers(targetPath, { [name]: config });
-}
-
-/**
- * Generate setup instructions for a credential-requiring MCP
- * @param {string} name - MCP name
- * @param {Object} mcpEntry - MCP entry from registry
- * @returns {Object} { configSnippet, credentialUrls, cliCommand }
- */
-export function generateSetupInstructions(name, mcpEntry) {
-  const config = mcpEntry.install.config;
-  const credentials = mcpEntry.install.credentials || [];
-  const setupGuide = mcpEntry.install.setupGuide;
-
-  // Remote HTTP MCPs — show claude mcp add command instead of config snippet
-  if (isRemoteMcp(config)) {
-    const configSnippet = JSON.stringify({ [name]: config }, null, 2);
-    const credentialUrls = credentials.map(c => ({
-      name: c.name,
-      envVar: c.envVar,
-      helpUrl: c.helpUrl
-    }));
-    return {
-      configSnippet,
-      credentialUrls,
-      cliCommand: setupGuide || `claude mcp add --transport http ${name} ${config.url}`,
-      isRemote: true
-    };
-  }
-
-  // Build the config snippet with placeholder values
-  const snippetConfig = { ...config };
-  if (credentials.length > 0) {
-    snippetConfig.env = {};
-    for (const cred of credentials) {
-      snippetConfig.env[cred.envVar] = cred.secret ? 'YOUR_KEY' : 'YOUR_VALUE';
-    }
-  }
-
-  const configSnippet = JSON.stringify({ [name]: snippetConfig }, null, 2);
-
-  const credentialUrls = credentials.map(c => ({
-    name: c.name,
-    envVar: c.envVar,
-    helpUrl: c.helpUrl
-  }));
-
-  return {
-    configSnippet,
-    credentialUrls,
-    cliCommand: `morph-spec mcp setup ${name}`
-  };
-}
-
-/**
- * Full orchestrator for MCP setup during init or `mcp setup`
- * @param {string} targetPath - Project root directory
- * @param {string} stack - Detected project stack
- * @param {Array} existingMcps - From detectClaudeConfig().mcpServers
- * @param {Object} options
- * @param {boolean} options.autoOnly - Only handle auto-installable MCPs
- * @returns {Object} { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing }
- */
-export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {}) {
-  const registry = loadMcpRegistry();
-  const relevant = filterByStack(registry, stack);
-  const installed = getInstalledMcps(existingMcps || [], registry);
-
-  const autoInstallable = {};
-  const alreadyInstalled = {};
-  const needsManualSetup = {};
-  const notRelevant = {};
-  const prerequisitesMissing = {};
-
-  // Categorize all MCPs
-  for (const [name, entry] of Object.entries(registry.mcps)) {
-    if (!entry.install) continue;
-
-    // Check if already installed
-    if (installed[name]) {
-      alreadyInstalled[name] = { entry, source: installed[name].source };
-      continue;
-    }
-
-    // Check if relevant to stack
-    if (!relevant[name]) {
-      notRelevant[name] = entry;
-      continue;
-    }
-
-    // Check prerequisites
-    const prereqResults = checkPrerequisites(entry);
-    const unmetPrereqs = prereqResults.filter(p => !p.met);
-    if (unmetPrereqs.length > 0) {
-      prerequisitesMissing[name] = { entry, unmet: unmetPrereqs };
-      continue;
-    }
-
-    // Categorize by install type
-    if (entry.install.autoInstall) {
-      autoInstallable[name] = entry;
-    } else if (!options.autoOnly) {
-      needsManualSetup[name] = entry;
-    }
-  }
-
-  return {
-    registry,
-    autoInstallable,
-    alreadyInstalled,
-    needsManualSetup,
-    notRelevant,
-    prerequisitesMissing
-  };
-}
-
-/**
- * Format MCP status table for display
- * @param {Object} orchestration - Result from orchestrateMcpSetup
- * @param {Object} justInstalled - Map of names just installed during this run
- * @returns {Array<Object>} Array of { name, status, detail }
- */
-export function formatMcpStatusTable(orchestration, justInstalled = {}) {
-  const rows = [];
-
-  const { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing, registry } = orchestration;
-
-  // Installed during this run
-  for (const [name, entry] of Object.entries(justInstalled)) {
-    const mcpEntry = registry.mcps[name];
-    rows.push({
-      name,
-      status: 'installed',
-      detail: mcpEntry ? mcpEntry.usage : ''
-    });
-  }
-
-  // Auto-installable but not yet installed (and not just-installed)
-  for (const [name, entry] of Object.entries(autoInstallable)) {
-    if (justInstalled[name]) continue;
-    rows.push({
-      name,
-      status: 'available',
-      detail: `Run: morph-spec mcp setup --auto`
-    });
-  }
-
-  // Already installed
-  for (const [name, { source }] of Object.entries(alreadyInstalled)) {
-    rows.push({
-      name,
-      status: 'already_configured',
-      detail: `(${source})`
-    });
-  }
-
-  // Needs manual setup
-  for (const [name, entry] of Object.entries(needsManualSetup)) {
-    rows.push({
-      name,
-      status: 'needs_setup',
-      detail: `Run: morph-spec mcp setup ${name}`
-    });
-  }
-
-  // Prerequisites missing
-  for (const [name, { unmet }] of Object.entries(prerequisitesMissing)) {
-    const missing = unmet.map(p => p.name).join(', ');
-    rows.push({
-      name,
-      status: 'prereq_missing',
-      detail: `Missing: ${missing}`
-    });
-  }
-
-  // Not relevant
-  for (const [name] of Object.entries(notRelevant)) {
-    rows.push({
-      name,
-      status: 'not_relevant',
-      detail: 'not relevant to stack'
-    });
-  }
-
-  return rows;
-}
+/**
+ * MCP Installer
+ *
+ * Core logic for installing and configuring MCP servers during morph-spec init
+ * and via `morph-spec mcp setup`. Handles auto-installable (credential-free)
+ * MCPs, prerequisite checking, credential collection, and setup guidance.
+ */
+
+import { join } from 'path';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { execSync, spawn } from 'child_process';
+import { homedir } from 'os';
+import { installMcpServers } from '../../utils/claude-settings-manager.js';
+
+/**
+ * Load the enhanced MCP registry (v3.0.0)
+ * @returns {Object} Registry with install blocks
+ */
+export function loadMcpRegistry() {
+  const registryPath = join(
+    import.meta.dirname, '..', '..', '..', 'framework', 'mcp', 'registry.json'
+  );
+  const raw = readFileSync(registryPath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Filter MCPs by stack relevance
+ * @param {Object} registry - Full MCP registry
+ * @param {string} stack - Detected project stack (e.g., 'nextjs-neon', 'blazor')
+ * @param {string[]} [integrations] - `project.integrations` (e.g., ['neon']). The
+ *   detectors put a database or payment provider here, never in the stack string,
+ *   so an MCP relevant to it (neon, asaas) is matched against this list too.
+ * @returns {Object} Filtered map of mcpName → mcpEntry
+ */
+export function filterByStack(registry, stack, integrations = []) {
+  const result = {};
+  const normalizedStack = (stack || '').toLowerCase();
+  const tags = integrations.map(i => String(i).toLowerCase());
+
+  for (const [name, entry] of Object.entries(registry.mcps)) {
+    if (!entry.install) continue;
+    const relevance = entry.install.stackRelevance || [];
+
+    if (relevance.includes('*')) {
+      result[name] = entry;
+    } else if (relevance.some(s => (normalizedStack && normalizedStack.includes(s)) || tags.includes(s))) {
+      result[name] = entry;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Match detected MCP servers against the registry
+ * @param {Array} existingServers - From detectClaudeConfig().mcpServers
+ * @param {Object} registry - MCP registry
+ * @returns {Object} Map of mcpName → { installed: true, source }
+ */
+export function getInstalledMcps(existingServers, registry) {
+  const installed = {};
+  const registryNames = Object.keys(registry.mcps);
+
+  for (const server of existingServers) {
+    const serverName = server.name.toLowerCase();
+    for (const regName of registryNames) {
+      if (serverName.includes(regName)) {
+        installed[regName] = { installed: true, source: server.source };
+      }
+    }
+  }
+
+  return installed;
+}
+
+/**
+ * Check if prerequisites are met for an MCP entry
+ * @param {Object} mcpEntry - MCP entry from registry
+ * @returns {Array} Array of { name, met, installUrl } for each prerequisite
+ */
+export function checkPrerequisites(mcpEntry) {
+  const prereqs = mcpEntry.install?.prerequisites || [];
+  const results = [];
+
+  for (const prereq of prereqs) {
+    let met = false;
+    try {
+      execSync(prereq.checkCommand, { stdio: 'ignore', timeout: 5000 });
+      met = true;
+    } catch {
+      // Command failed or not found
+    }
+    results.push({
+      name: prereq.name,
+      met,
+      installUrl: prereq.installUrl
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Check if an MCP config uses remote HTTP transport (no local process).
+ * @param {Object} config - MCP server config
+ * @returns {boolean}
+ */
+export function isRemoteMcp(config) {
+  return config.type === 'http' || config.url != null;
+}
+
+/**
+ * Patch MCP config for the current platform.
+ * On Windows, npx must be invoked via `cmd /c` to avoid ENOENT errors.
+ * Registry already stores cmd/c format; this handles legacy configs that still use npx directly.
+ * Remote HTTP MCPs are returned as-is (no local process to patch).
+ * @param {Object} config - MCP server config { command, args, env? } or { type: "http", url }
+ * @returns {Object} Patched config (new object, original unmodified)
+ */
+export function patchConfigForPlatform(config) {
+  // Remote MCPs need no platform patching
+  if (isRemoteMcp(config)) return config;
+  if (config.command !== 'npx') return config;
+  return {
+    ...config,
+    command: 'cmd',
+    args: ['/c', 'npx', ...(config.args || [])]
+  };
+}
+
+/**
+ * Install auto-installable MCPs (no credentials, no prerequisites)
+ * @param {string} targetPath - Project root directory
+ * @param {Object} mcpsToInstall - Map of mcpName → mcpEntry
+ * @returns {Promise<Object>} Result from installMcpServers
+ */
+export async function installAutoMcps(targetPath, mcpsToInstall) {
+  const servers = {};
+
+  for (const [name, entry] of Object.entries(mcpsToInstall)) {
+    let config = { ...entry.install.config };
+    // Remote MCPs don't have env to strip
+    if (!isRemoteMcp(config)) {
+      // Only include env if it has actual values
+      if (config.env && Object.values(config.env).every(v => !v)) {
+        delete config.env;
+      }
+    }
+    servers[name] = patchConfigForPlatform(config);
+  }
+
+  return installMcpServers(targetPath, servers);
+}
+
+/**
+ * Install companion skills for MCPs that define them (e.g., Stitch agent skills).
+ * Reads the `companionSkills` field from registry entries and runs the install command.
+ * @param {Object} mcpsInstalled - Map of mcpName → mcpEntry that were just installed
+ * @param {Function} exec - execSync function (for testing)
+ * @returns {Array<{name: string, repo: string, success: boolean}>}
+ */
+export function installCompanionSkills(mcpsInstalled, exec = execSync) {
+  const results = [];
+
+  for (const [name, entry] of Object.entries(mcpsInstalled)) {
+    const companion = entry.companionSkills;
+    if (!companion?.installCommand) continue;
+
+    try {
+      exec(companion.installCommand, { stdio: 'inherit', timeout: 30000 });
+      results.push({ name, repo: companion.repo, success: true });
+    } catch {
+      results.push({ name, repo: companion.repo, success: false });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Generate the Stitch OAuth proxy template script.
+ * Cross-platform (Windows gcloud.cmd + Unix gcloud), fetch()-based,
+ * with readline, session tracking, and graceful shutdown.
+ * @param {string} gcpProject - GCP project ID for x-goog-user-project header
+ * @returns {string} CJS proxy script content
+ */
+export function getStitchProxyTemplate(gcpProject) {
+  return `#!/usr/bin/env node
+/**
+ * Stitch MCP stdio-to-HTTP proxy with Google auth
+ * Generated by morph-spec mcp setup stitch
+ */
+const { execSync } = require('child_process');
+const { createInterface } = require('readline');
+
+const STITCH_URL = 'https://stitch.googleapis.com/mcp';
+const PROJECT_ID = '${gcpProject}';
+
+// Cross-platform gcloud path: Windows uses gcloud.cmd from Cloud SDK install
+const GCLOUD = process.platform === 'win32'
+  ? (process.env.LOCALAPPDATA || '') + '/Google/Cloud SDK/google-cloud-sdk/bin/gcloud.cmd'
+  : 'gcloud';
+
+let cachedToken = null;
+let tokenExpiry = 0;
+let pendingRequests = 0;
+let stdinClosed = false;
+let sessionId = null;
+
+function getToken() {
+  if (cachedToken && Date.now() < tokenExpiry) return cachedToken;
+  try {
+    cachedToken = execSync(\`"\${GCLOUD}" auth application-default print-access-token\`, {
+      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000
+    }).trim();
+    tokenExpiry = Date.now() + 50 * 60 * 1000; // 50-minute TTL
+    return cachedToken;
+  } catch {
+    return null;
+  }
+}
+
+function maybeExit() {
+  if (stdinClosed && pendingRequests === 0) process.exit(0);
+}
+
+async function handleMessage(line) {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+
+  // Notifications (no id) don't need responses
+  if (msg.id === undefined && msg.method === 'notifications/initialized') return;
+
+  const token = getToken();
+  if (!token) {
+    if (msg.id !== undefined) {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0', id: msg.id,
+        error: { code: -32000, message: 'Failed to get gcloud auth token. Run: gcloud auth application-default login' }
+      }) + '\\n');
+    }
+    return;
+  }
+
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': \`Bearer \${token}\`,
+    'x-goog-user-project': PROJECT_ID,
+  };
+  if (sessionId) headers['mcp-session-id'] = sessionId;
+
+  pendingRequests++;
+  try {
+    const res = await fetch(STITCH_URL, { method: 'POST', headers, body: JSON.stringify(msg) });
+
+    // Track sticky session
+    const sid = res.headers.get('mcp-session-id');
+    if (sid) sessionId = sid;
+
+    // Retry once on 401 (expired token)
+    if (res.status === 401) {
+      cachedToken = null;
+      tokenExpiry = 0;
+      const retryToken = getToken();
+      if (retryToken) {
+        headers['Authorization'] = \`Bearer \${retryToken}\`;
+        const retryRes = await fetch(STITCH_URL, { method: 'POST', headers, body: JSON.stringify(msg) });
+        const retryText = await retryRes.text();
+        if (retryText.trim()) {
+          process.stdout.write(retryText.endsWith('\\n') ? retryText : retryText + '\\n');
+        }
+        return;
+      }
+    }
+
+    const text = await res.text();
+    if (text.trim()) {
+      process.stdout.write(text.endsWith('\\n') ? text : text + '\\n');
+    }
+  } catch (err) {
+    if (msg.id !== undefined) {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0', id: msg.id,
+        error: { code: -32000, message: \`Stitch API error: \${err.message}\` }
+      }) + '\\n');
+    }
+  } finally {
+    pendingRequests--;
+    maybeExit();
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', handleMessage);
+rl.on('close', () => { stdinClosed = true; maybeExit(); });
+`;
+}
+
+/**
+ * Generate and write the Stitch OAuth proxy script to the target project.
+ * @param {string} targetPath - Project root directory
+ * @param {string} gcpProject - GCP project ID
+ * @returns {{ proxyPath: string }} Path to the generated proxy script
+ */
+export function generateStitchProxy(targetPath, gcpProject) {
+  const claudeDir = join(targetPath, '.claude');
+  if (!existsSync(claudeDir)) {
+    mkdirSync(claudeDir, { recursive: true });
+  }
+
+  const proxyPath = join(claudeDir, 'stitch-proxy.cjs');
+  writeFileSync(proxyPath, getStitchProxyTemplate(gcpProject), 'utf-8');
+
+  return { proxyPath };
+}
+
+/**
+ * Resolve the gcloud CLI binary path.
+ * Checks: system PATH → bundled at ~/.stitch-mcp/ → null.
+ * @param {Function} exec - execSync function (for testing)
+ * @returns {{ gcloudPath: string|null, source: string }}
+ */
+export function findGcloud(exec = execSync) {
+  // Try system PATH first
+  try {
+    exec('gcloud --version', { stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000 });
+    return { gcloudPath: 'gcloud', source: 'system' };
+  } catch { /* not on PATH */ }
+
+  // Windows: try Cloud SDK default install location
+  if (process.platform === 'win32') {
+    const winPath = join(process.env.LOCALAPPDATA || '', 'Google', 'Cloud SDK', 'google-cloud-sdk', 'bin', 'gcloud.cmd');
+    if (existsSync(winPath)) {
+      return { gcloudPath: winPath, source: 'windows-sdk' };
+    }
+  }
+
+  // Try bundled at ~/.stitch-mcp/
+  const bundledDir = join(homedir(), '.stitch-mcp');
+  const bundledBin = process.platform === 'win32'
+    ? join(bundledDir, 'google-cloud-sdk', 'bin', 'gcloud.cmd')
+    : join(bundledDir, 'google-cloud-sdk', 'bin', 'gcloud');
+  if (existsSync(bundledBin)) {
+    return { gcloudPath: bundledBin, source: 'bundled' };
+  }
+
+  return { gcloudPath: null, source: 'not-found' };
+}
+
+/**
+ * Fully automated Stitch MCP setup orchestrator.
+ *
+ * Steps:
+ * 1. Find gcloud CLI
+ * 2. Verify ADC credentials
+ * 3. Detect GCP project
+ * 4. Enable stitch.googleapis.com API
+ * 5. Generate proxy script
+ * 6. Install MCP config in .mcp.json
+ * 7. Health-check the proxy
+ *
+ * @param {string} targetPath - Project root directory
+ * @param {Object} options
+ * @param {string} [options.gcpProject] - GCP project ID (auto-detected if omitted)
+ * @param {Function} [options._exec] - execSync override for testing
+ * @returns {Promise<Object>} Step-by-step results
+ */
+export async function setupStitch(targetPath, options = {}) {
+  const exec = options._exec || execSync;
+  const steps = [];
+
+  // Step 1: Find gcloud
+  const { gcloudPath, source: gcloudSource } = findGcloud(exec);
+  if (!gcloudPath) {
+    steps.push({ step: 'find-gcloud', success: false, error: 'gcloud CLI not found. Install from: https://cloud.google.com/sdk/docs/install' });
+    return { success: false, steps };
+  }
+  steps.push({ step: 'find-gcloud', success: true, gcloudPath, source: gcloudSource });
+
+  const gcloudCmd = gcloudPath.includes(' ') ? `"${gcloudPath}"` : gcloudPath;
+
+  // Step 2: Verify ADC credentials
+  try {
+    exec(`${gcloudCmd} auth application-default print-access-token`, {
+      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 15000
+    });
+    steps.push({ step: 'verify-adc', success: true });
+  } catch {
+    steps.push({ step: 'verify-adc', success: false, error: 'No ADC credentials. Run: gcloud auth application-default login' });
+    return { success: false, steps };
+  }
+
+  // Step 3: Detect GCP project
+  let gcpProject = options.gcpProject;
+  if (!gcpProject) {
+    // Try config.json
+    const configPath = join(targetPath, '.morph', 'config', 'config.json');
+    if (existsSync(configPath)) {
+      try {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        gcpProject = config.gcpProject || config.project?.gcpProject;
+      } catch { /* invalid config */ }
+    }
+  }
+  if (!gcpProject) {
+    // Try gcloud config
+    try {
+      gcpProject = exec(`${gcloudCmd} config get-value project`, {
+        encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000
+      }).trim();
+      if (!gcpProject || gcpProject === '(unset)') gcpProject = null;
+    } catch { /* gcloud config failed */ }
+  }
+  if (!gcpProject) {
+    steps.push({ step: 'detect-project', success: false, error: 'Could not detect GCP project. Pass it explicitly or set via: gcloud config set project <id>' });
+    return { success: false, steps };
+  }
+  steps.push({ step: 'detect-project', success: true, gcpProject });
+
+  // Step 4: Enable Stitch API
+  try {
+    exec(`${gcloudCmd} services enable stitch.googleapis.com --project=${gcpProject}`, {
+      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000
+    });
+    steps.push({ step: 'enable-api', success: true });
+  } catch (err) {
+    steps.push({ step: 'enable-api', success: false, error: `Failed to enable stitch API: ${err.message}` });
+    // Non-fatal — API might already be enabled and user may lack permissions to re-enable
+  }
+
+  // Step 5: Generate proxy
+  const { proxyPath } = generateStitchProxy(targetPath, gcpProject);
+  steps.push({ step: 'generate-proxy', success: true, proxyPath });
+
+  // Step 6: Install MCP config in .mcp.json
+  const mcpResult = await installMcpServers(targetPath, {
+    stitch: { type: 'stdio', command: 'node', args: ['.claude/stitch-proxy.cjs'] }
+  });
+  steps.push({ step: 'install-mcp', success: true, added: mcpResult.added, skipped: mcpResult.skipped });
+
+  // Step 7: Health-check
+  const healthResult = await healthCheckStitchProxy(proxyPath);
+  steps.push({ step: 'health-check', ...healthResult });
+
+  const allCriticalPassed = steps.every(s =>
+    s.success || s.step === 'enable-api' || s.step === 'health-check'
+  );
+
+  return { success: allCriticalPassed, steps, gcpProject };
+}
+
+/**
+ * Health-check the Stitch proxy by sending an MCP initialize handshake.
+ * @param {string} proxyPath - Path to stitch-proxy.cjs
+ * @returns {Promise<Object>} { success, protocolVersion?, error? }
+ */
+export function healthCheckStitchProxy(proxyPath) {
+  return new Promise((resolve) => {
+    const initMsg = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'morph-spec', version: '1.0.0' } }
+    });
+
+    const child = spawn('node', [proxyPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 20000,
+    });
+
+    let output = '';
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+      resolve({ success: false, error: 'Health-check timed out after 20s' });
+    }, 20000);
+
+    child.stdout.on('data', (data) => {
+      output += data.toString();
+      // Check if we got a response
+      const lines = output.split('\n').filter(l => l.trim());
+      for (const line of lines) {
+        try {
+          const resp = JSON.parse(line);
+          if (resp.result?.protocolVersion) {
+            clearTimeout(timer);
+            child.kill();
+            resolve({ success: true, protocolVersion: resp.result.protocolVersion });
+            return;
+          }
+          if (resp.error) {
+            clearTimeout(timer);
+            child.kill();
+            resolve({ success: false, error: resp.error.message || 'MCP error' });
+            return;
+          }
+        } catch { /* not valid JSON yet */ }
+      }
+    });
+
+    child.on('error', (err) => {
+      if (!timedOut) {
+        clearTimeout(timer);
+        resolve({ success: false, error: err.message });
+      }
+    });
+
+    child.on('close', (code) => {
+      if (!timedOut) {
+        clearTimeout(timer);
+        resolve({ success: false, error: output.trim()
+          ? `Proxy exited with code ${code} — unexpected output`
+          : `Proxy exited with code ${code} and no output`
+        });
+      }
+    });
+
+    // Send the initialize message
+    child.stdin.write(initMsg + '\n');
+    child.stdin.end();
+  });
+}
+
+/**
+ * Install a single MCP with provided credentials
+ * @param {string} targetPath - Project root directory
+ * @param {string} name - MCP name
+ * @param {Object} mcpEntry - MCP entry from registry
+ * @param {Object} credentialValues - Map of envVar → value
+ * @returns {Promise<Object>} Result from installMcpServers
+ */
+export async function installMcpWithCredentials(targetPath, name, mcpEntry, credentialValues) {
+  const config = patchConfigForPlatform({ ...mcpEntry.install.config });
+  config.env = { ...config.env, ...credentialValues };
+  return installMcpServers(targetPath, { [name]: config });
+}
+
+/**
+ * Generate setup instructions for a credential-requiring MCP
+ * @param {string} name - MCP name
+ * @param {Object} mcpEntry - MCP entry from registry
+ * @returns {Object} { configSnippet, credentialUrls, cliCommand }
+ */
+export function generateSetupInstructions(name, mcpEntry) {
+  const config = mcpEntry.install.config;
+  const credentials = mcpEntry.install.credentials || [];
+  const setupGuide = mcpEntry.install.setupGuide;
+
+  // Remote HTTP MCPs — show claude mcp add command instead of config snippet
+  if (isRemoteMcp(config)) {
+    const configSnippet = JSON.stringify({ [name]: config }, null, 2);
+    const credentialUrls = credentials.map(c => ({
+      name: c.name,
+      envVar: c.envVar,
+      helpUrl: c.helpUrl
+    }));
+    return {
+      configSnippet,
+      credentialUrls,
+      cliCommand: setupGuide || `claude mcp add --transport http ${name} ${config.url}`,
+      isRemote: true
+    };
+  }
+
+  // Build the config snippet with placeholder values
+  const snippetConfig = { ...config };
+  if (credentials.length > 0) {
+    snippetConfig.env = {};
+    for (const cred of credentials) {
+      snippetConfig.env[cred.envVar] = cred.secret ? 'YOUR_KEY' : 'YOUR_VALUE';
+    }
+  }
+
+  const configSnippet = JSON.stringify({ [name]: snippetConfig }, null, 2);
+
+  const credentialUrls = credentials.map(c => ({
+    name: c.name,
+    envVar: c.envVar,
+    helpUrl: c.helpUrl
+  }));
+
+  return {
+    configSnippet,
+    credentialUrls,
+    cliCommand: `morph-spec mcp setup ${name}`
+  };
+}
+
+/**
+ * Full orchestrator for MCP setup during init or `mcp setup`
+ * @param {string} targetPath - Project root directory
+ * @param {string} stack - Detected project stack
+ * @param {Array} existingMcps - From detectClaudeConfig().mcpServers
+ * @param {Object} options
+ * @param {boolean} options.autoOnly - Only handle auto-installable MCPs
+ * @param {string[]} [options.integrations] - `project.integrations`, matched like the stack
+ * @returns {Object} { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing }
+ */
+export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {}) {
+  const registry = loadMcpRegistry();
+  const relevant = filterByStack(registry, stack, options.integrations ?? []);
+  const installed = getInstalledMcps(existingMcps || [], registry);
+
+  const autoInstallable = {};
+  const alreadyInstalled = {};
+  const needsManualSetup = {};
+  const notRelevant = {};
+  const prerequisitesMissing = {};
+
+  // Categorize all MCPs
+  for (const [name, entry] of Object.entries(registry.mcps)) {
+    if (!entry.install) continue;
+
+    // Check if already installed
+    if (installed[name]) {
+      alreadyInstalled[name] = { entry, source: installed[name].source };
+      continue;
+    }
+
+    // Check if relevant to stack
+    if (!relevant[name]) {
+      notRelevant[name] = entry;
+      continue;
+    }
+
+    // Check prerequisites
+    const prereqResults = checkPrerequisites(entry);
+    const unmetPrereqs = prereqResults.filter(p => !p.met);
+    if (unmetPrereqs.length > 0) {
+      prerequisitesMissing[name] = { entry, unmet: unmetPrereqs };
+      continue;
+    }
+
+    // Categorize by install type
+    if (entry.install.autoInstall) {
+      autoInstallable[name] = entry;
+    } else if (!options.autoOnly) {
+      needsManualSetup[name] = entry;
+    }
+  }
+
+  return {
+    registry,
+    autoInstallable,
+    alreadyInstalled,
+    needsManualSetup,
+    notRelevant,
+    prerequisitesMissing
+  };
+}
+
+/**
+ * Format MCP status table for display
+ * @param {Object} orchestration - Result from orchestrateMcpSetup
+ * @param {Object} justInstalled - Map of names just installed during this run
+ * @returns {Array<Object>} Array of { name, status, detail }
+ */
+export function formatMcpStatusTable(orchestration, justInstalled = {}) {
+  const rows = [];
+
+  const { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing, registry } = orchestration;
+
+  // Installed during this run
+  for (const [name, entry] of Object.entries(justInstalled)) {
+    const mcpEntry = registry.mcps[name];
+    rows.push({
+      name,
+      status: 'installed',
+      detail: mcpEntry ? mcpEntry.usage : ''
+    });
+  }
+
+  // Auto-installable but not yet installed (and not just-installed)
+  for (const [name, entry] of Object.entries(autoInstallable)) {
+    if (justInstalled[name]) continue;
+    rows.push({
+      name,
+      status: 'available',
+      detail: `Run: morph-spec mcp setup --auto`
+    });
+  }
+
+  // Already installed
+  for (const [name, { source }] of Object.entries(alreadyInstalled)) {
+    rows.push({
+      name,
+      status: 'already_configured',
+      detail: `(${source})`
+    });
+  }
+
+  // Needs manual setup
+  for (const [name, entry] of Object.entries(needsManualSetup)) {
+    rows.push({
+      name,
+      status: 'needs_setup',
+      detail: `Run: morph-spec mcp setup ${name}`
+    });
+  }
+
+  // Prerequisites missing
+  for (const [name, { unmet }] of Object.entries(prerequisitesMissing)) {
+    const missing = unmet.map(p => p.name).join(', ');
+    rows.push({
+      name,
+      status: 'prereq_missing',
+      detail: `Missing: ${missing}`
+    });
+  }
+
+  // Not relevant
+  for (const [name] of Object.entries(notRelevant)) {
+    rows.push({
+      name,
+      status: 'not_relevant',
+      detail: 'not relevant to stack'
+    });
+  }
+
+  return rows;
+}