vesper-wizard 1.0.3 → 2.0.0

package/README.md

@@ -0,0 +1,62 @@
+# vesper-wizard
+
+Zero-friction setup wizard for [Vesper](https://github.com/vesper/mcp-server) — your local MCP-native dataset intelligence layer.
+
+## Install
+
+```bash
+npx vesper-wizard@latest
+```
+
+That's it. The wizard handles everything:
+
+1. Creates `~/.vesper/` directories and local API key
+2. Collects optional credentials (HuggingFace, Kaggle, Nia) — stored locally, never leaves your machine
+3. Installs `@vespermcp/mcp-server` and auto-configures MCP for all detected agents (Claude, Cursor, VS Code, Codex, Gemini CLI)
+4. Verifies the installation
+
+## What you get
+
+After the wizard finishes, your AI assistant can immediately use Vesper tools:
+
+| Tool | Description |
+|------|-------------|
+| `vesper_search` | Search 16,000+ datasets via natural language |
+| `discover_datasets` | Discover from HuggingFace, Kaggle, OpenML, data.world |
+| `download_dataset` | Download any dataset to local storage |
+| `prepare_dataset` | Full pipeline: analyze → clean → split → export |
+| `analyze_quality` | Deep quality analysis with recommendations |
+| `export_dataset` | Export to parquet, csv, feather, jsonl, arrow |
+| `fuse_datasets` | Combine multiple datasets with quality checks |
+
+## Security
+
+- **Local-only**: All credentials stored in `~/.vesper/config.toml`
+- **Keyring-backed**: Uses OS keyring when available, falls back to local TOML
+- **No cloud**: Zero external API calls during setup
+- **No tokens exposed**: Kaggle key input is masked
+
+## Config file
+
+The wizard generates `~/.vesper/config.toml`:
+
+```toml
+api_key = "vesper_sk_local_..."
+hf_token = "hf_..."
+kaggle_username = "your_username"
+kaggle_key = "..."
+```
+
+## Post-setup
+
+Restart your IDE and try in your AI assistant:
+
+```
+vesper_search(query="sentiment analysis")
+prepare_dataset(query="image classification cats dogs")
+analyze_quality(dataset_id="imdb")
+```
+
+## License
+
+MIT

package/package.json

@@ -1,12 +1,30 @@
 {
   "name": "vesper-wizard",
-  "version": "1.0.3",
-  "description": "Interactive setup wizard for Vesper projects",
+  "version": "2.0.0",
+  "description": "Zero-friction setup wizard for Vesper — local MCP server, unified dataset API, and agent auto-config in 60 seconds",
   "bin": {
     "vesper-wizard": "wizard.js"
   },
+  "keywords": [
+    "vesper",
+    "mcp",
+    "wizard",
+    "setup",
+    "datasets",
+    "machine-learning",
+    "huggingface",
+    "kaggle",
+    "openml"
+  ],
   "author": "Vesper Team",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vesper/mcp-server"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
     "inquirer": "^8.2.0"
   }

package/vesper-mcp-config.json

@@ -2,7 +2,5 @@
   "project": "vesper",
   "dataDir": "./datasets",
   "exportFormat": "parquet",
-  "tokens": {
-    "kaggle": "KGAT_1cf06098e5f1d0fbc8f2a2b9efad1632"
-  }
+  "tokens": {}
 }

package/wizard.js

@@ -1,77 +1,377 @@
 #!/usr/bin/env node
 
-// Vesper Wizard CLI: Interactive setup for fast configuration
+// ─────────────────────────────────────────────────────────────
+//  vesper-wizard  —  Zero-friction local setup for Vesper MCP
+//  Run:  npx vesper-wizard@latest
+// ─────────────────────────────────────────────────────────────
+
 const inquirer = require('inquirer');
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { execSync, spawnSync } = require('child_process');
+
+// ── Paths ────────────────────────────────────────────────────
+const HOME = os.homedir();
+const VESPER_DIR = path.join(HOME, '.vesper');
+const CONFIG_TOML = path.join(VESPER_DIR, 'config.toml');
+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 upsertEnvValue(filePath, key, value) {
+  const line = `${key}=${value}`;
+  let content = '';
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf8');
+    const regex = new RegExp(`^${key}=.*$`, 'm');
+    if (regex.test(content)) {
+      content = content.replace(regex, line);
+    } else {
+      content = content.replace(/\n?$/, `\n${line}\n`);
+    }
+  } else {
+    ensureDir(path.dirname(filePath));
+    content = `${line}\n`;
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+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`; }
+
+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', '@vespermcp/mcp-server@latest'] };
+
+  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() {
-  console.log('\nWelcome to the Vesper Wizard!\n');
+  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: Generate local API key ────────────────────────
+  process.stdout.write(`  ${dim('[')}${cyan('2/6')}${dim(']')} Generating local API key...`);
+  const existing = readToml(CONFIG_TOML);
+  const localKey = existing.api_key || generateLocalKey();
+  const configData = { ...existing, api_key: localKey };
+  writeToml(CONFIG_TOML, configData);
+  console.log(` ${green('✓')}`);
+  console.log(`      ${dim('Key:')} ${dim(localKey.slice(0, 20) + '...')}  ${dim('→')} ${dim(CONFIG_TOML)}`);
+
+  // ─── Step 3: Credential collection ─────────────────────────
+  console.log(`\n  ${dim('[')}${cyan('3/6')}${dim(']')} ${bold('Credentials')} ${dim('(all optional — press Enter to skip)')}\n`);
 
-  // Step 1: Project basics
-  const { projectName } = await inquirer.prompt([
+  const { hfToken, kaggleUsername, kaggleKey, niaApiKey } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'projectName',
-      message: 'Project name:',
-      default: path.basename(process.cwd()),
+      name: 'hfToken',
+      message: `  ${dim('HuggingFace token')}`,
+      prefix: '   ',
     },
-  ]);
-
-  // Step 2: Data directory
-  const { dataDir } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'dataDir',
-      message: 'Path to your data directory:',
-      default: './datasets',
+      name: 'kaggleUsername',
+      message: `  ${dim('Kaggle username')}`,
+      prefix: '   ',
     },
-  ]);
-
-  // Step 3: Default export format
-  const { exportFormat } = await inquirer.prompt([
     {
-      type: 'list',
-      name: 'exportFormat',
-      message: 'Default export format:',
-      choices: ['parquet', 'csv', 'feather'],
-      default: 'parquet',
+      type: 'password',
+      name: 'kaggleKey',
+      message: `  ${dim('Kaggle API key')}`,
+      mask: '*',
+      prefix: '   ',
     },
-  ]);
-
-  // Step 4: Add tokens/credentials
-  const { addTokens } = await inquirer.prompt([
     {
-      type: 'confirm',
-      name: 'addTokens',
-      message: 'Would you like to add API tokens or credentials now?',
-      default: true,
+      type: 'input',
+      name: 'niaApiKey',
+      message: `  ${dim('Nia API key (NIA_API_KEY)')}`,
+      prefix: '   ',
     },
   ]);
-  let tokens = {};
-  if (addTokens) {
-    const { kaggleToken } = await inquirer.prompt([
-      {
-        type: 'input',
-        name: 'kaggleToken',
-        message: 'Kaggle API token (leave blank to skip):',
-      },
-    ]);
-    if (kaggleToken) tokens.kaggle = kaggleToken;
-    // Add more tokens as needed
+
+  // Save credentials to config.toml (local keyring)
+  const saved = [];
+  if (hfToken) { configData.hf_token = hfToken; saved.push('HuggingFace'); }
+  if (kaggleUsername) { configData.kaggle_username = kaggleUsername; saved.push('Kaggle user'); }
+  if (kaggleKey) { configData.kaggle_key = kaggleKey; saved.push('Kaggle key'); }
+  if (niaApiKey) {
+    configData.nia_api_key = niaApiKey;
+    saved.push('Nia');
+
+    // Also write to .env.local for Next.js apps
+    const rootEnv = path.join(process.cwd(), '.env.local');
+    upsertEnvValue(rootEnv, 'NIA_API_KEY', niaApiKey);
+    const landingDir = path.join(process.cwd(), 'landing');
+    if (fs.existsSync(landingDir) && fs.statSync(landingDir).isDirectory()) {
+      upsertEnvValue(path.join(landingDir, '.env.local'), 'NIA_API_KEY', niaApiKey);
+    }
+  }
+
+  writeToml(CONFIG_TOML, configData);
+  if (saved.length > 0) {
+    console.log(`\n      ${green('✓')} Stored locally: ${saved.join(', ')}`);
+    console.log(`      ${dim('Location:')} ${CONFIG_TOML}`);
+    console.log(`      ${dim('Security: local keyring — never leaves this machine')}`);
+  } else {
+    console.log(`\n      ${dim('No credentials added (core tools work without them)')}`);
+  }
+
+  // ─── Step 4: Install @vespermcp/mcp-server ─────────────────
+  console.log(`\n  ${dim('[')}${cyan('4/6')}${dim(']')} Installing Vesper MCP server...`);
+  try {
+    const npmCmd = IS_WIN ? 'npx.cmd' : 'npx';
+    spawnSync(npmCmd, ['-y', '@vespermcp/mcp-server@latest', '--setup', '--silent'], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+    console.log(`      ${green('✓')} @vespermcp/mcp-server installed`);
+  } catch {
+    console.log(`      ${yellow('⚠')} Could not auto-install — run manually: npx @vespermcp/mcp-server --setup`);
+  }
+
+  // ─── 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 ─────────────────────────────────────────
+  console.log(`
+${dim('═════════════════════════════════════════════════')}
+
+  ${green(bold('✓ Vesper is ready!'))}
+
+  ${bold('Your local API key:')}
+  ${cyan(localKey)}
+
+  ${bold('Config file:')}
+  ${dim(CONFIG_TOML)}
+
+  ${bold('What just happened:')}
+  ${dim('1.')} Generated a local API key (never leaves your machine)
+  ${dim('2.')} Stored credentials in local keyring
+  ${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('All routing is automatic. Agents call ONE set of')}
+  ${dim('tools and Vesper handles source resolution.')}
+
+${dim('─────────────────────────────────────────────────')}
+
+  ${yellow('→')} Restart your IDE to activate MCP
+  ${dim('Docs:')} https://github.com/vesper/mcp-server
 
-  // Step 5: Write config file
-  const config = {
-    project: projectName,
-    dataDir,
-    exportFormat,
-    tokens,
-  };
-  const configPath = path.join(process.cwd(), 'vesper-mcp-config.json');
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-  console.log(`\nConfiguration saved to ${configPath}`);
-  console.log('\nVesper is ready to use!\n');
+${dim('═════════════════════════════════════════════════')}
+`);
 }
 
-main();
+main().catch((err) => {
+  console.error(`\n${red('Error:')} ${err.message || err}`);
+  process.exit(1);
+});