@vespermcp/mcp-server 1.2.21 → 1.2.24

package/scripts/wizard.cjs

@@ -0,0 +1,652 @@
+#!/usr/bin/env node
+
+// ─────────────────────────────────────────────────────────────
+//  vesper-wizard  —  Zero-friction local setup for Vesper MCP
+//  Run:  npx vesper-wizard@latest
+// ─────────────────────────────────────────────────────────────
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { execSync, spawnSync } = require('child_process');
+const http = require('http');
+const https = require('https');
+const readline = require('readline');
+
+// ── Paths ────────────────────────────────────────────────────
+const HOME = os.homedir();
+const VESPER_DIR = path.join(HOME, '.vesper');
+const CONFIG_TOML = path.join(VESPER_DIR, 'config.toml');
+const CONFIG_JSON = path.join(VESPER_DIR, 'config.json');
+const DATA_DIR = path.join(VESPER_DIR, 'data');
+const IS_WIN = process.platform === 'win32';
+const APPDATA = process.env.APPDATA || path.join(HOME, 'AppData', 'Roaming');
+
+// ── Helpers ──────────────────────────────────────────────────
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function generateLocalKey() {
+  const random = crypto.randomBytes(24).toString('hex');
+  return `vesper_sk_local_${random}`;
+}
+
+function readToml(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const content = fs.readFileSync(filePath, 'utf8');
+  const obj = {};
+  for (const line of content.split('\n')) {
+    const m = line.match(/^\s*(\w+)\s*=\s*"(.*)"\s*$/);
+    if (m) obj[m[1]] = m[2];
+  }
+  return obj;
+}
+
+function writeToml(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  const lines = Object.entries(data).map(([k, v]) => `${k} = "${v}"`);
+  fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf8');
+}
+
+function readWizardState() {
+  if (!fs.existsSync(CONFIG_JSON)) return {};
+  try {
+    const content = fs.readFileSync(CONFIG_JSON, 'utf8').trim();
+    return content ? JSON.parse(content) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeWizardState(state) {
+  ensureDir(path.dirname(CONFIG_JSON));
+  fs.writeFileSync(CONFIG_JSON, JSON.stringify(state, null, 2), 'utf8');
+}
+
+function hasCompletedOnboarding() {
+  const state = readWizardState();
+  return state.onboardingCompleted === true;
+}
+
+function markOnboardingCompleted() {
+  const state = readWizardState();
+  state.onboardingCompleted = true;
+  writeWizardState(state);
+}
+
+function dim(text) { return `\x1b[2m${text}\x1b[0m`; }
+function bold(text) { return `\x1b[1m${text}\x1b[0m`; }
+function green(text) { return `\x1b[32m${text}\x1b[0m`; }
+function cyan(text) { return `\x1b[36m${text}\x1b[0m`; }
+function yellow(text) { return `\x1b[33m${text}\x1b[0m`; }
+function red(text) { return `\x1b[31m${text}\x1b[0m`; }
+function magenta(text) { return `\x1b[35m${text}\x1b[0m`; }
+
+// ── Vesper API URL resolution ────────────────────────────────
+const VESPER_API_URL = process.env.VESPER_API_URL || '';
+const DEFAULT_VESPER_API_CANDIDATES = [
+  'https://getvesper.dev',
+  'http://localhost:3000',
+  'http://127.0.0.1:3000',
+];
+
+// ── Device Auth Helpers ──────────────────────────────────────
+function httpJson(method, url, body) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const opts = {
+      method,
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      headers: { 'Content-Type': 'application/json' },
+    };
+    const req = lib.request(opts, (res) => {
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        try { resolve({ status: res.statusCode, body: JSON.parse(data) }); }
+        catch { resolve({ status: res.statusCode, body: data }); }
+      });
+    });
+    req.on('error', reject);
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+async function probeDeviceAuth(baseUrl) {
+  try {
+    const res = await httpJson('POST', `${baseUrl}/api/auth/device/start`);
+    if (res.status === 201 && !!res.body && !!res.body.code) {
+      return { baseUrl, status: 'ready', response: res.body };
+    }
+
+    if (res.status === 503 && res.body && res.body.requiresSetup) {
+      return {
+        baseUrl,
+        status: 'setup-required',
+        response: res.body,
+        message: res.body.error || 'Auth storage is not initialized.',
+      };
+    }
+
+    return {
+      baseUrl,
+      status: 'unreachable',
+      response: res.body,
+      message: typeof res.body === 'string' ? res.body : JSON.stringify(res.body),
+    };
+  } catch (error) {
+    return {
+      baseUrl,
+      status: 'unreachable',
+      message: error && error.message ? error.message : 'Request failed',
+    };
+  }
+}
+
+async function resolveVesperApiBaseUrl() {
+  const candidates = VESPER_API_URL
+    ? [VESPER_API_URL]
+    : DEFAULT_VESPER_API_CANDIDATES;
+
+  let setupRequiredProbe = null;
+
+  for (const candidate of candidates) {
+    const probe = await probeDeviceAuth(candidate);
+    if (probe.status === 'ready') {
+      return probe;
+    }
+
+    if (!setupRequiredProbe && probe.status === 'setup-required') {
+      setupRequiredProbe = probe;
+    }
+  }
+
+  return setupRequiredProbe;
+}
+
+function openBrowser(url) {
+  try {
+    if (process.platform === 'win32') {
+      spawnSync('cmd', ['/c', 'start', '', url], { stdio: 'ignore' });
+    } else if (process.platform === 'darwin') {
+      spawnSync('open', [url], { stdio: 'ignore' });
+    } else {
+      spawnSync('xdg-open', [url], { stdio: 'ignore' });
+    }
+  } catch { /* browser open is best-effort */ }
+}
+
+function isInteractiveTerminal() {
+  return Boolean(process.stdin && process.stdin.isTTY && process.stdout && process.stdout.isTTY);
+}
+
+function askYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`  ${question} ${dim('[Y/n]')} `, (answer) => {
+      rl.close();
+      resolve(!answer || answer.toLowerCase().startsWith('y'));
+    });
+  });
+}
+
+function askInput(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`  ${question} `, (answer) => {
+      rl.close();
+      resolve(String(answer || '').trim());
+    });
+  });
+}
+
+async function askChoice(question, choices, defaultValue) {
+  console.log(`  ${question}`);
+  choices.forEach((choice, index) => {
+    console.log(`    ${dim(String(index + 1) + ')')} ${choice.label}`);
+  });
+
+  const prompt = defaultValue ? `${dim('[default: ' + defaultValue + ']')}` : '';
+  const answer = await askInput(`${prompt} ${cyan('→')} Choose an option:`);
+  if (!answer && defaultValue) {
+    return defaultValue;
+  }
+
+  const numeric = Number(answer);
+  if (Number.isFinite(numeric) && numeric >= 1 && numeric <= choices.length) {
+    return choices[numeric - 1].value;
+  }
+
+  const matched = choices.find((choice) => choice.value === answer);
+  return matched ? matched.value : defaultValue;
+}
+
+function isCloudApiKey(value) {
+  return !!value && value.startsWith('vesper_sk_') && !value.startsWith('vesper_sk_local_');
+}
+
+async function promptForManualApiKey() {
+  console.log(`\n  ${cyan('■')} ${bold('Manual API Key')}`);
+  console.log(`  ${dim('Paste a Vesper cloud API key. It will be stored locally in config.toml.\n')}`);
+
+  while (true) {
+    const value = await askInput(`${cyan('→')} Vesper API key:`);
+    if (isCloudApiKey(value)) {
+      return value;
+    }
+    console.log(`  ${yellow('!')} ${yellow('Expected a Vesper key starting with vesper_sk_')}`);
+  }
+}
+
+async function chooseAuthMode(existingKey, existingAuthMode) {
+  const hasExistingKey = !!existingKey;
+  if (hasExistingKey) {
+    console.log(`      ${dim('Current key:')} ${dim(existingKey.slice(0, 24) + '...')}`);
+    console.log(`      ${dim('Current mode:')} ${dim(existingAuthMode || (isCloudApiKey(existingKey) ? 'cloud' : 'local_unified'))}`);
+  }
+
+  const choices = [];
+  choices.push({ value: 'browser', label: 'Sign in through the browser' });
+  choices.push({ value: 'manual', label: 'Provide Vesper API key manually' });
+
+  return await askChoice(`${cyan('→')} How do you want to authenticate Vesper?`, choices, 'browser');
+}
+
+async function deviceAuthFlow() {
+  console.log(`\n  ${cyan('■')} ${bold('Device Authentication')}`);
+  console.log(`  ${dim('Link your CLI to a Vesper account for cloud features\n')}`);
+
+  const resolvedApiBaseUrl = await resolveVesperApiBaseUrl();
+  if (!resolvedApiBaseUrl) {
+    console.log(`  ${red('✗')} ${red('Could not reach any Vesper auth endpoint.')}`);
+    console.log(`      ${dim('Tried:')} ${dim((VESPER_API_URL ? [VESPER_API_URL] : DEFAULT_VESPER_API_CANDIDATES).join(', '))}`);
+    console.log(`      ${dim('If your landing app is running locally, start it on http://localhost:3000 or set VESPER_API_URL.')}`);
+    console.log(`      ${dim('Falling back to manual key entry.\n')}`);
+    return null;
+  }
+
+  if (resolvedApiBaseUrl.status === 'setup-required') {
+    console.log(`  ${yellow('!')} ${yellow('Reached Vesper auth endpoint, but local auth storage is not initialized.')}`);
+    console.log(`      ${dim('Endpoint:')} ${dim(resolvedApiBaseUrl.baseUrl)}`);
+    console.log(`      ${dim('Reason:')} ${dim(resolvedApiBaseUrl.message || 'Apply Supabase migrations first.')}`);
+    console.log(`      ${dim('Run the SQL in supabase/migrations/001_device_auth.sql and 002_rate_limits.sql, then retry.')}`);
+    console.log(`      ${dim('Falling back to manual key entry.\n')}`);
+    return null;
+  }
+
+  console.log(`  ${dim('Auth endpoint:')} ${dim(resolvedApiBaseUrl.baseUrl)}\n`);
+
+  // Step 1: Call /api/auth/device/start
+  process.stdout.write(`  ${dim('Requesting device code...')}`);
+  let startRes;
+  try {
+    startRes = await httpJson('POST', `${resolvedApiBaseUrl.baseUrl}/api/auth/device/start`);
+  } catch (err) {
+    console.log(` ${red('✗')}`);
+    console.log(`      ${red('Could not reach Vesper API at')} ${dim(resolvedApiBaseUrl.baseUrl)}`);
+    console.log(`      ${dim('Falling back to manual key entry.\n')}`);
+    return null;
+  }
+
+  if (startRes.status !== 201 || !startRes.body.code) {
+    console.log(` ${red('✗')}`);
+    console.log(`      ${red('Unexpected response:')} ${dim(JSON.stringify(startRes.body))}`);
+    return null;
+  }
+
+  const { code, loginUrl } = startRes.body;
+  console.log(` ${green('✓')}\n`);
+
+  // Step 2: Display code and open browser
+  console.log(`  ┌───────────────────────────────────────────────┐`);
+  console.log(`  │                                               │`);
+  console.log(`  │   ${bold('Your device code:')}  ${cyan(bold(code))}              │`);
+  console.log(`  │                                               │`);
+  console.log(`  │   ${dim('Open this URL to sign in:')}                   │`);
+  console.log(`  │   ${cyan(loginUrl.padEnd(41))}│`);
+  console.log(`  │                                               │`);
+  console.log(`  └───────────────────────────────────────────────┘\n`);
+
+  const shouldAutoOpenBrowser = process.env.VESPER_WIZARD_AUTO_OPEN !== '0';
+  if (shouldAutoOpenBrowser) {
+    openBrowser(loginUrl);
+    if (!hasCompletedOnboarding()) {
+      markOnboardingCompleted();
+    }
+    console.log(`  ${dim('Browser opened automatically for device auth.')}`);
+  } else {
+    console.log(`  ${dim('Browser auto-open disabled via VESPER_WIZARD_AUTO_OPEN=0. Open the URL manually to continue.')}`);
+  }
+  console.log(`  ${dim('Waiting for you to sign in...')}\n`);
+
+  // Step 3: Poll until confirmed or expired
+  const POLL_INTERVAL = 3000; // 3 seconds
+  const MAX_POLLS = 200;      // 10 min max (200 × 3s)
+  let polls = 0;
+  const spinner = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+  while (polls < MAX_POLLS) {
+    polls++;
+    const frame = spinner[polls % spinner.length];
+    process.stdout.write(`\r  ${cyan(frame)} Polling... (${polls})`);
+
+    try {
+      const pollRes = await httpJson('GET', `${resolvedApiBaseUrl.baseUrl}/api/auth/device/poll?code=${code}`);
+
+      if (pollRes.body.status === 'confirmed' && pollRes.body.apiKey) {
+        process.stdout.write(`\r  ${green('✓')} Device authenticated!            \n`);
+        console.log(`      ${dim('Email:')} ${pollRes.body.email || 'linked'}`);
+        return pollRes.body.apiKey;
+      }
+
+      if (pollRes.body.status === 'expired') {
+        process.stdout.write(`\r  ${red('✗')} Device code expired.             \n`);
+        console.log(`      ${dim('Run the wizard again to get a new code.')}`);
+        return null;
+      }
+    } catch {
+      // Network hiccup — keep polling
+    }
+
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+  }
+
+  process.stdout.write(`\r  ${red('✗')} Timed out waiting for authentication.\n`);
+  return null;
+}
+
+function printBanner() {
+  console.log(`
+${dim('─────────────────────────────────────────────────')}
+
+  ${bold('██    ██ ███████ ███████ ██████  ███████ ██████')}
+  ${bold('██    ██ ██      ██      ██   ██ ██      ██   ██')}
+  ${bold('██    ██ █████   ███████ ██████  █████   ██████')}
+  ${bold(' ██  ██  ██           ██ ██      ██      ██   ██')}
+  ${bold('  ████   ███████ ███████ ██      ███████ ██   ██')}
+
+  ${cyan('dataset intelligence layer')}
+  ${dim('local-first • zero-config • agent-native')}
+
+${dim('─────────────────────────────────────────────────')}
+`);
+}
+
+// ── MCP Auto-Config ──────────────────────────────────────────
+function getAllAgentConfigs() {
+  const isMac = process.platform === 'darwin';
+  return [
+    {
+      name: 'Claude Code',
+      path: path.join(HOME, '.claude.json'),
+      format: 'mcpServers',
+    },
+    {
+      name: 'Claude Desktop',
+      path: IS_WIN
+        ? path.join(APPDATA, 'Claude', 'claude_desktop_config.json')
+        : isMac
+          ? path.join(HOME, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+          : path.join(HOME, '.config', 'claude', 'claude_desktop_config.json'),
+      format: 'mcpServers',
+    },
+    {
+      name: 'Cursor',
+      path: path.join(HOME, '.cursor', 'mcp.json'),
+      format: 'mcpServers',
+    },
+    {
+      name: 'VS Code',
+      path: IS_WIN
+        ? path.join(APPDATA, 'Code', 'User', 'mcp.json')
+        : isMac
+          ? path.join(HOME, 'Library', 'Application Support', 'Code', 'User', 'mcp.json')
+          : path.join(HOME, '.config', 'Code', 'User', 'mcp.json'),
+      format: 'servers',
+    },
+    {
+      name: 'Codex',
+      path: path.join(HOME, '.codex', 'config.toml'),
+      format: 'toml',
+    },
+    {
+      name: 'Gemini CLI',
+      path: path.join(HOME, '.gemini', 'settings.json'),
+      format: 'mcpServers',
+    },
+  ];
+}
+
+function installMcpToAgent(agent) {
+  const npxCmd = IS_WIN ? 'npx.cmd' : 'npx';
+  const serverEntry = { command: npxCmd, args: ['-y', '-p', '@vespermcp/mcp-server@latest', 'vespermcp'] };
+
+  try {
+    if (agent.format === 'toml') {
+      let content = fs.existsSync(agent.path) ? fs.readFileSync(agent.path, 'utf8') : '';
+      if (content.includes('[mcp_servers.vesper]')) return true;
+      ensureDir(path.dirname(agent.path));
+      content += `\n[mcp_servers.vesper]\ncommand = "${serverEntry.command}"\nargs = [${serverEntry.args.map(a => `"${a}"`).join(', ')}]\n`;
+      fs.writeFileSync(agent.path, content, 'utf8');
+      return true;
+    }
+
+    let config = {};
+    if (fs.existsSync(agent.path)) {
+      try { config = JSON.parse(fs.readFileSync(agent.path, 'utf8').trim() || '{}'); } catch { config = {}; }
+    } else {
+      ensureDir(path.dirname(agent.path));
+    }
+
+    const key = agent.format === 'servers' ? 'servers' : 'mcpServers';
+    if (!config[key]) config[key] = {};
+
+    const entry = agent.format === 'servers'
+      ? { type: 'stdio', ...serverEntry }
+      : serverEntry;
+
+    config[key].vesper = entry;
+    fs.writeFileSync(agent.path, JSON.stringify(config, null, 2), 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Server Health Check ──────────────────────────────────────
+async function checkServerHealth() {
+  try {
+    // Quick stdio check — spawn server and see if it responds
+    const result = spawnSync(IS_WIN ? 'npx.cmd' : 'npx', ['-y', '@vespermcp/mcp-server@latest', '--version'], {
+      timeout: 10000,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result.status === 0 || (result.stderr && result.stderr.includes('Vesper'));
+  } catch {
+    return false;
+  }
+}
+
+// ── Main Wizard ──────────────────────────────────────────────
+async function main() {
+  if (!isInteractiveTerminal()) {
+    console.error(red('vesper-wizard is interactive and cannot run in MCP stdio mode.'));
+    console.error(dim('Use this command for MCP server runtime instead:'));
+    console.error(cyan('npx -y -p @vespermcp/mcp-server@latest vespermcp'));
+    process.exit(2);
+  }
+
+  printBanner();
+
+  console.log(`  ${green('→')} Setting up Vesper on ${bold(os.hostname())}\n`);
+
+  // ─── Step 1: Create directories ────────────────────────────
+  process.stdout.write(`  ${dim('[')}${cyan('1/6')}${dim(']')} Creating local directories...`);
+  ensureDir(VESPER_DIR);
+  ensureDir(DATA_DIR);
+  ensureDir(path.join(DATA_DIR, 'raw'));
+  ensureDir(path.join(DATA_DIR, 'processed'));
+  ensureDir(path.join(VESPER_DIR, 'datasets'));
+  console.log(` ${green('✓')}`);
+
+  // ─── Step 2: Authenticate (device flow or local key) ──────
+  console.log(`\n  ${dim('[')}${cyan('2/6')}${dim(']')} Authentication`);
+
+  const existing = readToml(CONFIG_TOML);
+  let localKey = existing.api_key || '';
+  let authMode = existing.auth_mode || '';
+
+  const authChoice = await chooseAuthMode(localKey, authMode);
+
+  if (authChoice === 'manual') {
+    localKey = await promptForManualApiKey();
+    authMode = 'cloud';
+    console.log(`      ${green('✓')} Cloud API key saved from manual input`);
+  } else if (authChoice === 'browser') {
+    const cloudKey = await deviceAuthFlow();
+    if (cloudKey) {
+      localKey = cloudKey;
+      authMode = 'cloud';
+    } else {
+      console.log(`\n      ${yellow('!')} Browser sign-in did not complete. Falling back to manual key entry.`);
+      localKey = await promptForManualApiKey();
+      authMode = 'cloud';
+    }
+  }
+
+  const configData = { ...existing, api_key: localKey, auth_mode: authMode };
+  writeToml(CONFIG_TOML, configData);
+  console.log(`      ${dim('Key:')} ${dim(localKey.slice(0, 24) + '...')}  ${dim('→')} ${dim(CONFIG_TOML)}`);
+
+  // ─── Step 3: Local vault initialization ────────────────────
+  process.stdout.write(`\n  ${dim('[')}${cyan('3/6')}${dim(']')} Initializing local credentials vault...`);
+  const vaultData = readToml(CONFIG_TOML);
+  if (!vaultData.auth_mode) vaultData.auth_mode = 'local_unified';
+  writeToml(CONFIG_TOML, vaultData);
+  console.log(` ${green('✓')}`);
+  console.log(`      ${dim('Mode:')} ${dim(vaultData.auth_mode === 'cloud' ? 'cloud (linked to Vesper account)' : 'single local Vesper key (no external keys required)')}`);
+
+  // ─── Step 4: Verify @vespermcp/mcp-server command ───────────
+  console.log(`\n  ${dim('[')}${cyan('4/6')}${dim(']')} Verifying Vesper MCP server command...`);
+  try {
+    const npmCmd = IS_WIN ? 'npx.cmd' : 'npx';
+    const verify = spawnSync(npmCmd, ['-y', '-p', '@vespermcp/mcp-server@latest', 'vespermcp', '--version'], {
+      stdio: 'pipe',
+      timeout: 30000,
+      encoding: 'utf8',
+    });
+    if (verify.status === 0) {
+      console.log(`      ${green('✓')} @vespermcp/mcp-server command is available`);
+    } else {
+      console.log(`      ${yellow('⚠')} Could not verify vespermcp binary. MCP clients will still install it on first run.`);
+    }
+  } catch {
+    console.log(`      ${yellow('⚠')} Could not verify vespermcp binary. MCP clients will still install it on first run.`);
+  }
+
+  // ─── Step 5: Auto-configure all detected IDEs ──────────────
+  process.stdout.write(`\n  ${dim('[')}${cyan('5/6')}${dim(']')} Configuring coding agents...`);
+  const agents = getAllAgentConfigs();
+  const configuredAgents = [];
+  const skippedAgents = [];
+
+  for (const agent of agents) {
+    const dirExists = fs.existsSync(path.dirname(agent.path));
+    const fileExists = fs.existsSync(agent.path);
+    if (fileExists || dirExists) {
+      const ok = installMcpToAgent(agent);
+      if (ok) configuredAgents.push(agent.name);
+      else skippedAgents.push(agent.name);
+    }
+  }
+  console.log(` ${green('✓')}`);
+
+  if (configuredAgents.length > 0) {
+    console.log(`\n  ┌───────────────────────────────────────────────┐`);
+    console.log(`  │  ${bold('MCP Auto-Configured')}                           │`);
+    console.log(`  ├───────────────────────────────────────────────┤`);
+    for (const name of configuredAgents) {
+      console.log(`  │  ${green('✓')} ${name.padEnd(42)}│`);
+    }
+    console.log(`  └───────────────────────────────────────────────┘`);
+  }
+
+  // ─── Step 6: Verify ────────────────────────────────────────
+  console.log(`\n  ${dim('[')}${cyan('6/6')}${dim(']')} Verifying installation...`);
+
+  const dbExists = fs.existsSync(path.join(DATA_DIR, 'metadata.db'));
+  const vecExists = fs.existsSync(path.join(DATA_DIR, 'vectors.json')) || fs.existsSync(path.join(DATA_DIR, 'vectors.bin'));
+  const keyStored = fs.existsSync(CONFIG_TOML);
+
+  console.log(`      ${keyStored ? green('✓') : red('✗')} Local API key         ${dim(CONFIG_TOML)}`);
+  console.log(`      ${dbExists ? green('✓') : yellow('⚠')} Dataset index         ${dim(dbExists ? 'ready' : 'will build on first search')}`);
+  console.log(`      ${vecExists ? green('✓') : yellow('⚠')} Vector store          ${dim(vecExists ? 'ready' : 'will build on first search')}`);
+  console.log(`      ${configuredAgents.length > 0 ? green('✓') : yellow('⚠')} MCP agents            ${dim(configuredAgents.length + ' configured')}`);
+
+  // ─── Final Summary ─────────────────────────────────────────
+  const finalConfig = readToml(CONFIG_TOML);
+  const isCloud = finalConfig.auth_mode === 'cloud';
+  console.log(`
+${dim('═════════════════════════════════════════════════')}
+
+  ${green(bold('✓ Vesper is ready!'))}
+
+  ${bold(isCloud ? 'Your cloud API key:' : 'Your local API key:')}
+  ${cyan(finalConfig.api_key || localKey)}
+
+  ${bold('Auth mode:')}
+  ${dim(isCloud ? '☁  Cloud (linked to Vesper account)' : '🔑 Local-only (key never leaves your machine)')}
+
+  ${bold('Config file:')}
+  ${dim(CONFIG_TOML)}
+
+  ${bold('What just happened:')}
+  ${dim('1.')} ${isCloud ? 'Linked to your Vesper cloud account' : 'Generated a local API key (never leaves your machine)'}
+  ${dim('2.')} Initialized local credentials vault
+  ${dim('3.')} Auto-configured MCP for ${configuredAgents.length > 0 ? configuredAgents.join(', ') : 'detected agents'}
+  ${dim('4.')} Vesper server ready on stdio transport
+
+${dim('─────────────────────────────────────────────────')}
+
+  ${bold('Quick start — try in your AI assistant:')}
+
+  ${cyan('Search datasets')}
+  ${dim('>')} vesper_search(query="sentiment analysis")
+
+  ${cyan('Download & prepare')}
+  ${dim('>')} prepare_dataset(query="image classification cats dogs")
+
+  ${cyan('Quality analysis')}
+  ${dim('>')} analyze_quality(dataset_id="imdb")
+
+  ${cyan('Export to your project')}
+  ${dim('>')} export_dataset(dataset_id="imdb", format="parquet")
+
+${dim('─────────────────────────────────────────────────')}
+
+  ${bold('Unified API — one interface, every source:')}
+  HuggingFace · Kaggle · OpenML · data.world
+
+  ${dim('Agents call localhost Vesper APIs with one local key.')}
+  ${dim('Vesper adapters handle provider routing internally.')}
+
+${dim('─────────────────────────────────────────────────')}
+
+  ${yellow('→')} Restart your IDE to activate MCP
+  ${dim('Docs:')} https://github.com/vesper/mcp-server
+
+${dim('═════════════════════════════════════════════════')}
+`);
+}
+
+main().catch((err) => {
+  console.error(`\n${red('Error:')} ${err.message || err}`);
+  process.exit(1);
+});