voyageai-cli 1.23.0 → 1.24.0

package/README.md

@@ -81,6 +81,7 @@ MongoDB LeafyGreen design system<br/><br/>
   - [Environment & Auth](#environment--auth)
   - [Shell Completions](#shell-completions)
   - [All Commands](#all-commands)
+- [MCP Server](#mcp-server)
 - [Screenshots](#screenshots)
 - [Requirements](#requirements)
 - [Author](#author)
@@ -534,6 +535,12 @@ Covers all 22 commands, subcommands, flags, model names, and explain topics.
 | `vai eval` | Evaluate retrieval quality (MRR, nDCG, Recall) |
 | `vai eval compare` | Compare configurations side-by-side |
 | `vai benchmark` | 8 subcommands for model comparison |
+| **MCP Server** | |
+| `vai mcp` | Start the MCP server (expose vai tools to AI agents) |
+| `vai mcp install` | Install vai into AI tool configs (Claude, Cursor, etc.) |
+| `vai mcp uninstall` | Remove vai from AI tool configs |
+| `vai mcp status` | Show installation status across all tools |
+| `vai mcp generate-key` | Generate API key for HTTP server auth |
 | **Tools & Learning** | |
 | `vai models` | List models, benchmarks, architecture |
 | `vai explain` | 25 interactive concept explainers |
@@ -547,6 +554,63 @@ Covers all 22 commands, subcommands, flags, model names, and explain topics.
 
 ---
 
+## MCP Server
+
+Expose vai's RAG tools to any MCP-compatible AI agent — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, and more. **11 tools** for embedding, retrieval, reranking, ingestion, and learning — all accessible without writing code.
+
+### One-Command Setup
+
+```bash
+# Install into your AI tool of choice
+vai mcp install claude
+vai mcp install cursor
+vai mcp install all          # all supported tools at once
+
+# Check what's configured
+vai mcp status
+```
+
+The install command **merges** into existing configs — it won't touch your other MCP servers.
+
+### Supported Tools
+
+| Target | AI Tool |
+|--------|---------|
+| `claude` | Claude Desktop |
+| `claude-code` | Claude Code |
+| `cursor` | Cursor |
+| `windsurf` | Windsurf |
+| `vscode` | VS Code |
+
+### What Your Agent Gets
+
+Once installed, your AI agent can use these tools:
+
+| Tool | What It Does |
+|------|-------------|
+| `vai_query` | Full RAG: embed → vector search → rerank |
+| `vai_search` | Raw vector similarity search |
+| `vai_rerank` | Rerank documents against a query |
+| `vai_embed` | Generate embedding vectors |
+| `vai_similarity` | Cosine similarity between texts |
+| `vai_ingest` | Chunk, embed, and store documents |
+| `vai_collections` | List MongoDB collections with vector indexes |
+| `vai_models` | List models with pricing and benchmarks |
+| `vai_topics` | Browse educational topics |
+| `vai_explain` | Get detailed concept explanations |
+| `vai_estimate` | Estimate embedding costs |
+
+### Transport Modes
+
+```bash
+vai mcp                                    # stdio (default, local)
+vai mcp --transport http --port 3100       # HTTP (remote, multi-client)
+```
+
+📖 **Full documentation:** [docs/mcp-server.md](docs/mcp-server.md)
+
+---
+
 ## Screenshots
 
 ### Desktop App — Dark Theme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"

package/src/commands/mcp-server.js

@@ -44,6 +44,80 @@ function registerMcpServer(program) {
       const { generateKey } = require('../mcp/server');
       generateKey();
     });
+
+  // Subcommand: install
+  cmd
+    .command('install [targets...]')
+    .description('Install vai MCP server into AI tool configs (claude, claude-code, cursor, windsurf, vscode, or "all")')
+    .option('--force', 'Overwrite existing vai entry', false)
+    .option('--transport <mode>', 'Transport mode: stdio or http', 'stdio')
+    .option('--port <number>', 'HTTP port (http transport only)', (v) => parseInt(v, 10))
+    .option('--api-key <key>', 'Voyage API key to embed in config')
+    .action((targets, opts) => {
+      const { TARGETS, installTarget } = require('../mcp/install');
+
+      if (!targets.length) {
+        console.log('Usage: vai mcp install <target|all>');
+        console.log(`Available targets: ${Object.keys(TARGETS).join(', ')}, all`);
+        return;
+      }
+
+      const keys = targets.includes('all') ? Object.keys(TARGETS) : targets;
+
+      for (const key of keys) {
+        try {
+          const result = installTarget(key, {
+            force: opts.force,
+            transport: opts.transport,
+            port: opts.port,
+            apiKey: opts.apiKey,
+          });
+          console.log(result.installed ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+        } catch (err) {
+          console.error(`❌ ${key}: ${err.message}`);
+        }
+      }
+    });
+
+  // Subcommand: uninstall
+  cmd
+    .command('uninstall [targets...]')
+    .description('Remove vai MCP server from AI tool configs')
+    .action((targets) => {
+      const { TARGETS, uninstallTarget } = require('../mcp/install');
+
+      if (!targets.length) {
+        console.log('Usage: vai mcp uninstall <target|all>');
+        console.log(`Available targets: ${Object.keys(TARGETS).join(', ')}, all`);
+        return;
+      }
+
+      const keys = targets.includes('all') ? Object.keys(TARGETS) : targets;
+
+      for (const key of keys) {
+        try {
+          const result = uninstallTarget(key);
+          console.log(result.removed ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+        } catch (err) {
+          console.error(`❌ ${key}: ${err.message}`);
+        }
+      }
+    });
+
+  // Subcommand: status
+  cmd
+    .command('status')
+    .description('Show vai MCP installation status across all supported AI tools')
+    .action(() => {
+      const { statusAll } = require('../mcp/install');
+      const results = statusAll();
+
+      console.log('\nvai MCP Server — Installation Status\n');
+      for (const r of results) {
+        console.log(`  ${r.status.padEnd(18)} ${r.name.padEnd(16)} ${r.configPath}`);
+      }
+      console.log('');
+    });
 }
 
 module.exports = { registerMcpServer };

package/src/commands/ping.js

@@ -25,8 +25,8 @@ function registerPing(program) {
       let apiKey;
       try {
         apiKey = requireApiKey();
-      } catch {
-        // requireApiKey calls process.exit, but just in case
+      } catch (err) {
+        console.error(err.message);
         process.exit(1);
       }
 

package/src/lib/api.js

@@ -36,14 +36,12 @@ function requireApiKey() {
   const { getConfigValue } = require('./config');
   const key = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');
   if (!key) {
-    console.error('Error: VOYAGE_API_KEY is not set.');
-    console.error('');
-    console.error('Option 1: export VOYAGE_API_KEY="your-key-here"');
-    console.error('Option 2: vai config set api-key <your-key>');
-    console.error('');
-    console.error('Get one from MongoDB Atlas → AI Models → Create model API key');
-    console.error('       or Voyage AI platform → Dashboard → API Keys');
-    process.exit(1);
+    const msg = 'VOYAGE_API_KEY is not set.\n\n' +
+      'Option 1: export VOYAGE_API_KEY="your-key-here"\n' +
+      'Option 2: vai config set api-key <your-key>\n\n' +
+      'Get one from MongoDB Atlas > AI Models > Create model API key\n' +
+      '       or Voyage AI platform > Dashboard > API Keys';
+    throw new Error(msg);
   }
   return key;
 }

package/src/mcp/install.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Known MCP-compatible tools and their config file locations.
+ */
+const TARGETS = {
+  claude: {
+    name: 'Claude Desktop',
+    configPath: () => {
+      if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+      if (process.platform === 'win32') return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+      return path.join(os.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+    },
+  },
+  'claude-code': {
+    name: 'Claude Code',
+    configPath: () => path.join(os.homedir(), '.claude', 'settings.json'),
+    configKey: 'mcpServers', // same key but different file
+  },
+  cursor: {
+    name: 'Cursor',
+    configPath: () => path.join(os.homedir(), '.cursor', 'mcp.json'),
+  },
+  windsurf: {
+    name: 'Windsurf',
+    configPath: () => path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+  },
+  vscode: {
+    name: 'VS Code',
+    configPath: () => {
+      if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Application Support', 'Code', 'User', 'settings.json');
+      if (process.platform === 'win32') return path.join(process.env.APPDATA || '', 'Code', 'User', 'settings.json');
+      return path.join(os.homedir(), '.config', 'Code', 'User', 'settings.json');
+    },
+    configKey: 'mcp.servers',
+  },
+};
+
+/**
+ * Build the vai MCP server entry.
+ */
+function buildVaiEntry(opts = {}) {
+  const entry = {
+    command: 'vai',
+    args: ['mcp-server'],
+  };
+  if (opts.transport === 'http') {
+    entry.args.push('--transport', 'http');
+    if (opts.port) entry.args.push('--port', String(opts.port));
+  }
+  const apiKey = opts.apiKey || process.env.VOYAGE_API_KEY || '';
+  if (apiKey) {
+    entry.env = { VOYAGE_API_KEY: apiKey };
+  }
+  return entry;
+}
+
+/**
+ * Read a JSON config file, returning {} if it doesn't exist.
+ */
+function readConfig(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Write a JSON config file, creating parent directories as needed.
+ */
+function writeConfig(filePath, config) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Set a nested key like "mcp.servers" on an object.
+ */
+function getNestedKey(obj, keyPath) {
+  const keys = keyPath.split('.');
+  let current = obj;
+  for (const k of keys) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[k];
+  }
+  return current;
+}
+
+function setNestedKey(obj, keyPath, value) {
+  const keys = keyPath.split('.');
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (current[keys[i]] == null || typeof current[keys[i]] !== 'object') {
+      current[keys[i]] = {};
+    }
+    current = current[keys[i]];
+  }
+  current[keys[keys.length - 1]] = value;
+}
+
+/**
+ * Install vai MCP entry into a target tool's config.
+ * Returns { installed: boolean, message: string }
+ */
+function installTarget(targetKey, opts = {}) {
+  const target = TARGETS[targetKey];
+  if (!target) {
+    return { installed: false, message: `Unknown target: ${targetKey}. Available: ${Object.keys(TARGETS).join(', ')}` };
+  }
+
+  const configPath = target.configPath();
+  const mcpKey = target.configKey || 'mcpServers';
+  const config = readConfig(configPath) || {};
+
+  // Get or create the mcpServers object
+  let servers = getNestedKey(config, mcpKey);
+  if (servers == null || typeof servers !== 'object') {
+    servers = {};
+    setNestedKey(config, mcpKey, servers);
+  }
+
+  if (servers.vai && !opts.force) {
+    return { installed: false, message: `${target.name}: vai already configured in ${configPath} — use --force to overwrite` };
+  }
+
+  const existed = !!servers.vai;
+  servers.vai = buildVaiEntry(opts);
+  // Ensure the nested key points to our updated servers
+  setNestedKey(config, mcpKey, servers);
+
+  writeConfig(configPath, config);
+  return { installed: true, message: `${target.name}: ${existed ? 'updated' : 'installed'} vai in ${configPath}` };
+}
+
+/**
+ * Uninstall vai MCP entry from a target tool's config.
+ */
+function uninstallTarget(targetKey) {
+  const target = TARGETS[targetKey];
+  if (!target) {
+    return { removed: false, message: `Unknown target: ${targetKey}` };
+  }
+
+  const configPath = target.configPath();
+  const config = readConfig(configPath);
+  if (!config) {
+    return { removed: false, message: `${target.name}: config not found at ${configPath}` };
+  }
+
+  const mcpKey = target.configKey || 'mcpServers';
+  const servers = getNestedKey(config, mcpKey);
+  if (!servers || !servers.vai) {
+    return { removed: false, message: `${target.name}: vai not configured` };
+  }
+
+  delete servers.vai;
+  setNestedKey(config, mcpKey, servers);
+  writeConfig(configPath, config);
+  return { removed: true, message: `${target.name}: removed vai from ${configPath}` };
+}
+
+/**
+ * Check status of vai MCP across all known tools.
+ */
+function statusAll() {
+  const results = [];
+  for (const [key, target] of Object.entries(TARGETS)) {
+    const configPath = target.configPath();
+    const mcpKey = target.configKey || 'mcpServers';
+    const config = readConfig(configPath);
+
+    let status;
+    if (!config) {
+      status = 'not found';
+    } else {
+      const servers = getNestedKey(config, mcpKey);
+      status = servers && servers.vai ? '✅ installed' : '⬚ not configured';
+    }
+
+    results.push({ target: key, name: target.name, configPath, status });
+  }
+  return results;
+}
+
+module.exports = {
+  TARGETS,
+  installTarget,
+  uninstallTarget,
+  statusAll,
+  buildVaiEntry,
+};