voyageai-cli 1.23.1 → 1.26.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.1",
+  "version": "1.26.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"

package/src/cli.js

@@ -37,6 +37,7 @@ const { register: registerQuickstart } = require('./commands/quickstart');
 const { registerBug } = require('./commands/bug');
 const { registerChat } = require('./commands/chat');
 const { registerMcpServer } = require('./commands/mcp-server');
+const { registerWorkflow } = require('./commands/workflow');
 const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
 
 const version = getVersion();
@@ -78,6 +79,7 @@ registerQuickstart(program);
 registerBug(program);
 registerChat(program);
 registerMcpServer(program);
+registerWorkflow(program);
 
 // Append disclaimer to all help output
 program.addHelpText('after', `

package/src/commands/about.js

@@ -20,7 +20,7 @@ function registerAbout(program) {
             name: 'Michael Lynn',
             role: 'Principal Staff Developer Advocate, MongoDB',
             github: 'https://github.com/mrlynn',
-            vai_website: 'https://vai.mlynn.org',
+            vai_website: 'https://vaicli.com',
             website: 'https://mlynn.org',
           },
           links: {

package/src/commands/bug.js

@@ -15,7 +15,7 @@ function getVersion() {
 }
 
 const GITHUB_ISSUES_URL = 'https://github.com/mrlynn/voyageai-cli/issues/new';
-const BUG_API_URL = 'https://vai.mlynn.org/api/bugs';
+const BUG_API_URL = 'https://vaicli.com/api/bugs';
 
 /**
  * Generate a GitHub issue URL with pre-filled template

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/playground.js

@@ -85,6 +85,23 @@ function createPlaygroundServer() {
         return;
       }
 
+      // Serve watermark image
+      if (req.method === 'GET' && req.url === '/icons/watermark.png') {
+        const wmPath = path.join(__dirname, '..', 'playground', 'icons', 'watermark.png');
+        if (fs.existsSync(wmPath)) {
+          const data = fs.readFileSync(wmPath);
+          res.writeHead(200, {
+            'Content-Type': 'image/png',
+            'Cache-Control': 'public, max-age=86400',
+          });
+          res.end(data);
+        } else {
+          res.writeHead(404);
+          res.end('Watermark not found');
+        }
+        return;
+      }
+
       // Serve icon assets: /icons/{dark|light}/{size}.png
       const iconMatch = req.url.match(/^\/icons\/(dark|light)\/(\d+)\.png$/);
       if (req.method === 'GET' && iconMatch) {
@@ -193,6 +210,20 @@ function createPlaygroundServer() {
               }
             }
             
+            // Add binary files
+            if (structure.binaryFiles) {
+              for (const file of structure.binaryFiles) {
+                const srcPath = path.join(__dirname, '..', 'lib', 'templates', target, file.source);
+                if (fs.existsSync(srcPath)) {
+                  files.push({
+                    name: `${projectName}/${file.output}`,
+                    content: fs.readFileSync(srcPath),
+                    binary: true,
+                  });
+                }
+              }
+            }
+
             // Create ZIP
             const zipBuffer = createZip(files);
             

package/src/commands/scaffold.js

@@ -129,6 +129,23 @@ function registerScaffold(program) {
             });
           }
         }
+
+        // Add binary files (copied as-is from templates dir)
+        if (structure.binaryFiles) {
+          for (const file of structure.binaryFiles) {
+            const srcPath = path.join(__dirname, '..', 'lib', 'templates', target, file.source);
+            const destPath = path.join(projectDir, file.output);
+            const binarySize = fs.existsSync(srcPath) ? fs.statSync(srcPath).size : 0;
+            manifest.push({
+              path: file.output,
+              fullPath: destPath,
+              source: `${target}/${file.source}`,
+              size: binarySize,
+              binary: true,
+              binarySrc: srcPath,
+            });
+          }
+        }
         
         // JSON output mode
         if (opts.json) {
@@ -171,7 +188,12 @@ function registerScaffold(program) {
         
         // Write all files
         for (const file of manifest) {
-          writeFile(file.fullPath, file.content);
+          if (file.binary) {
+            ensureDir(path.dirname(file.fullPath));
+            fs.copyFileSync(file.binarySrc, file.fullPath);
+          } else {
+            writeFile(file.fullPath, file.content);
+          }
           if (!opts.quiet) {
             console.log(`  ${ui.cyan('✓')} ${file.path}`);
           }

package/src/commands/workflow.js

@@ -0,0 +1,336 @@
+'use strict';
+
+const pc = require('picocolors');
+const ui = require('../lib/ui');
+
+/**
+ * Parse repeatable --input key=value options into an object.
+ * Used as Commander's option reducer.
+ *
+ * @param {string} pair - "key=value" string
+ * @param {object} prev - Accumulated object
+ * @returns {object}
+ */
+function collectInputs(pair, prev) {
+  const eq = pair.indexOf('=');
+  if (eq === -1) {
+    throw new Error(`Invalid input format: "${pair}". Expected key=value`);
+  }
+  const key = pair.slice(0, eq).trim();
+  const value = pair.slice(eq + 1).trim();
+  prev[key] = value;
+  return prev;
+}
+
+/**
+ * Register the workflow command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerWorkflow(program) {
+  const wfCmd = program
+    .command('workflow')
+    .alias('wf')
+    .description('Run, validate, and manage composable RAG workflows');
+
+  // ── workflow run <file> ──
+  wfCmd
+    .command('run <file>')
+    .description('Execute a workflow file or built-in template')
+    .option('--input <key=value>', 'Set a workflow input (repeatable)', collectInputs, {})
+    .option('--db <name>', 'Override default database')
+    .option('--collection <name>', 'Override default collection')
+    .option('--json', 'Output results as JSON', false)
+    .option('--quiet', 'Suppress progress output', false)
+    .option('--dry-run', 'Show execution plan without running', false)
+    .option('--verbose', 'Show step details', false)
+    .action(async (file, opts) => {
+      const { loadWorkflow, executeWorkflow, buildExecutionPlan, validateWorkflow } = require('../lib/workflow');
+
+      let definition;
+      try {
+        definition = loadWorkflow(file);
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+
+      // Validation
+      const errors = validateWorkflow(definition);
+      if (errors.length > 0) {
+        console.error(ui.error('Workflow validation failed:'));
+        for (const e of errors) console.error(`  ${pc.red('-')} ${e}`);
+        process.exit(1);
+      }
+
+      const workflowName = definition.name || file;
+
+      if (opts.dryRun) {
+        // Dry run: show plan
+        const layers = buildExecutionPlan(definition.steps);
+        const stepMap = new Map(definition.steps.map(s => [s.id, s]));
+
+        if (opts.json) {
+          console.log(JSON.stringify({ name: workflowName, layers, steps: definition.steps, inputs: opts.input }, null, 2));
+          return;
+        }
+
+        console.log();
+        console.log(`${pc.bold('vai workflow:')} ${workflowName} ${pc.dim('(dry run)')}`);
+        console.log(pc.dim('═'.repeat(50)));
+        console.log();
+
+        // Show inputs
+        const inputKeys = Object.keys(opts.input);
+        if (inputKeys.length > 0) {
+          console.log(pc.bold('Inputs:'));
+          for (const [k, v] of Object.entries(opts.input)) {
+            console.log(`  ${pc.cyan(k)}: ${JSON.stringify(v)}`);
+          }
+          console.log();
+        }
+
+        // Show execution plan
+        console.log(pc.bold('Execution plan:'));
+        let stepNum = 1;
+        for (let i = 0; i < layers.length; i++) {
+          const layer = layers[i];
+          for (const stepId of layer) {
+            const step = stepMap.get(stepId);
+            const toolDesc = `${step.tool}(${summarizeInputs(step.inputs)})`;
+            console.log(`  ${pc.dim(`${stepNum}.`)} ${pc.cyan(stepId)} ${pc.dim('->')} ${toolDesc}`);
+            stepNum++;
+          }
+          if (layer.length > 1) {
+            console.log(`     ${pc.dim(`(${layer.join(' and ')} run in parallel)`)}`);
+          }
+        }
+        console.log();
+        return;
+      }
+
+      // Execute workflow
+      try {
+        const result = await executeWorkflow(definition, {
+          inputs: opts.input,
+          db: opts.db,
+          collection: opts.collection,
+          dryRun: false,
+          verbose: opts.verbose,
+          json: opts.json,
+          onStepStart: !opts.quiet ? (stepId, step) => {
+            process.stderr.write(`  ${pc.dim('...')} ${step.name || stepId}\r`);
+          } : undefined,
+          onStepComplete: !opts.quiet ? (stepId, output, durationMs) => {
+            const stepDef = definition.steps.find(s => s.id === stepId);
+            const summary = summarizeOutput(stepDef?.tool, output);
+            console.error(`  ${pc.green('✔')} ${stepDef?.name || stepId}  ${pc.dim(summary)}  ${pc.dim(`[${durationMs}ms]`)}`);
+          } : undefined,
+          onStepSkip: !opts.quiet ? (stepId, reason) => {
+            const stepDef = definition.steps.find(s => s.id === stepId);
+            console.error(`  ${pc.yellow('⊘')} ${stepDef?.name || stepId}  ${pc.dim(`skipped: ${reason}`)}`);
+          } : undefined,
+          onStepError: !opts.quiet ? (stepId, err) => {
+            const stepDef = definition.steps.find(s => s.id === stepId);
+            console.error(`  ${pc.red('✗')} ${stepDef?.name || stepId}  ${pc.red(err.message)}`);
+          } : undefined,
+        });
+
+        if (!opts.quiet) {
+          console.error();
+          console.error(`${pc.bold('vai workflow:')} ${workflowName}`);
+          console.error(pc.dim('═'.repeat(50)));
+          // Step summaries already printed via callbacks
+          console.error();
+          console.error(`${pc.dim('Complete.')} ${result.steps.length} steps, ${result.totalTimeMs}ms total.`);
+          console.error();
+        }
+
+        // Output
+        if (opts.json) {
+          console.log(JSON.stringify(result.output, null, 2));
+        } else if (result.output) {
+          // Pretty-print top results if they exist
+          const output = result.output;
+          if (output.results && Array.isArray(output.results)) {
+            const top = output.results.slice(0, 5);
+            console.log(pc.bold('Top results:'));
+            for (let i = 0; i < top.length; i++) {
+              const r = top[i];
+              const source = r.source || r.text?.slice(0, 50) || `result ${i + 1}`;
+              const score = r.score != null ? ` (${r.score.toFixed(2)})` : '';
+              console.log(`  ${pc.dim(`[${i + 1}]`)} ${source}${pc.dim(score)}`);
+            }
+          } else if (output.summary) {
+            console.log(output.summary);
+          } else if (output.comparison) {
+            console.log(pc.bold('Cost comparison:'));
+            for (const item of output.comparison) {
+              if (item && item.model) {
+                console.log(`  ${pc.cyan(item.model)}: $${item.totalCost} total (embed: $${item.embeddingCost}, queries: $${item.monthlyQueryCost}/mo)`);
+              }
+            }
+          } else {
+            console.log(JSON.stringify(output, null, 2));
+          }
+        }
+      } catch (err) {
+        console.error(ui.error(err.message));
+        if (opts.verbose) {
+          console.error(pc.dim(err.stack));
+        }
+        process.exit(1);
+      }
+    });
+
+  // ── workflow validate <file> ──
+  wfCmd
+    .command('validate <file>')
+    .description('Validate a workflow file without executing')
+    .action((file) => {
+      const { loadWorkflow, validateWorkflow, buildExecutionPlan } = require('../lib/workflow');
+
+      let definition;
+      try {
+        definition = loadWorkflow(file);
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+
+      const errors = validateWorkflow(definition);
+      if (errors.length > 0) {
+        console.error(ui.error(`Workflow has ${errors.length} error(s):`));
+        for (const e of errors) console.error(`  ${pc.red('-')} ${e}`);
+        process.exit(1);
+      }
+
+      const layers = buildExecutionPlan(definition.steps);
+      console.log(ui.success(`${definition.name} is valid`));
+      console.log(`  ${pc.dim('Steps:')} ${definition.steps.length}`);
+      console.log(`  ${pc.dim('Layers:')} ${layers.length} (${layers.map(l => l.length).join(' + ')} steps)`);
+
+      if (definition.inputs) {
+        const required = Object.entries(definition.inputs).filter(([, s]) => s.required).map(([k]) => k);
+        if (required.length > 0) {
+          console.log(`  ${pc.dim('Required inputs:')} ${required.join(', ')}`);
+        }
+      }
+    });
+
+  // ── workflow list ──
+  wfCmd
+    .command('list')
+    .description('List built-in workflow templates')
+    .action(() => {
+      const { listBuiltinWorkflows } = require('../lib/workflow');
+
+      const workflows = listBuiltinWorkflows();
+      if (workflows.length === 0) {
+        console.log(pc.dim('No built-in workflows found.'));
+        return;
+      }
+
+      console.log();
+      console.log(pc.bold('Built-in workflow templates:'));
+      console.log();
+      for (const wf of workflows) {
+        console.log(`  ${pc.cyan(wf.name.padEnd(28))} ${wf.description}`);
+      }
+      console.log();
+      console.log(pc.dim('Run with: vai workflow run <name> --input key=value'));
+      console.log();
+    });
+
+  // ── workflow init ──
+  wfCmd
+    .command('init')
+    .description('Scaffold a new workflow file')
+    .option('--name <name>', 'Workflow name')
+    .option('--output <file>', 'Output file path')
+    .action((opts) => {
+      const fs = require('fs');
+      const name = opts.name || 'my-workflow';
+      const filename = opts.output || `./${name}.vai-workflow.json`;
+
+      const scaffold = {
+        $schema: 'https://vai.dev/schemas/workflow-v1.json',
+        name: name.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+        description: 'TODO: describe what this workflow does',
+        version: '1.0.0',
+        inputs: {
+          query: {
+            type: 'string',
+            description: 'The search query',
+            required: true,
+          },
+        },
+        defaults: {},
+        steps: [
+          {
+            id: 'search',
+            name: 'Search knowledge base',
+            tool: 'query',
+            inputs: {
+              query: '{{ inputs.query }}',
+              limit: 10,
+            },
+          },
+        ],
+        output: {
+          results: '{{ search.output.results }}',
+          query: '{{ inputs.query }}',
+        },
+      };
+
+      fs.writeFileSync(filename, JSON.stringify(scaffold, null, 2) + '\n');
+      console.log(ui.success(`Created ${filename}`));
+      console.log(`  ${pc.dim('Run with:')} vai workflow run ${filename} --input query="your question"`);
+      console.log(`  ${pc.dim('Validate:')} vai workflow validate ${filename}`);
+    });
+}
+
+/**
+ * Summarize step inputs for dry-run display.
+ */
+function summarizeInputs(inputs) {
+  if (!inputs) return '';
+  const parts = [];
+  for (const [k, v] of Object.entries(inputs)) {
+    if (typeof v === 'string' && v.includes('{{')) {
+      parts.push(`${k}=<ref>`);
+    } else if (typeof v === 'string') {
+      parts.push(`${k}=${v.length > 20 ? v.slice(0, 20) + '...' : v}`);
+    } else if (typeof v === 'number' || typeof v === 'boolean') {
+      parts.push(`${k}=${v}`);
+    }
+  }
+  return parts.join(', ');
+}
+
+/**
+ * Summarize step output for display.
+ */
+function summarizeOutput(tool, output) {
+  if (!output) return '';
+  if (output.results && output.resultCount != null) {
+    return `${output.resultCount} results`;
+  }
+  if (output.insertedCount != null) {
+    return `${output.insertedCount} docs inserted`;
+  }
+  if (output.similarity != null) {
+    return `similarity: ${output.similarity.toFixed(4)}`;
+  }
+  if (output.text) {
+    return `${output.text.length} chars`;
+  }
+  if (output.embedding) {
+    return `${output.dimensions}d embedding`;
+  }
+  if (output.totalCost != null) {
+    return `$${output.totalCost}`;
+  }
+  return '';
+}
+
+module.exports = { registerWorkflow, collectInputs };