voyageai-cli 1.27.0 → 1.28.0

package/package.json

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

package/src/commands/config.js

@@ -67,6 +67,39 @@ function registerConfig(program) {
       const storedValue = key === 'default-dimensions' ? parseInt(value, 10) : value;
       setConfigValue(internalKey, storedValue);
       console.log(ui.success(`Set ${ui.cyan(key)} = ${SECRET_KEYS.has(internalKey) ? ui.dim(maskSecret(String(storedValue))) : storedValue}`));
+
+      // When setting an API key, auto-configure the matching base URL
+      if (internalKey === 'apiKey') {
+        const { identifyKey, ATLAS_API_BASE, VOYAGE_API_BASE } = require('../lib/api');
+        const keyInfo = identifyKey(storedValue);
+        const currentBase = getConfigValue('baseUrl');
+
+        if (keyInfo.type === 'atlas') {
+          if (currentBase !== ATLAS_API_BASE) {
+            setConfigValue('baseUrl', ATLAS_API_BASE);
+            console.log('');
+            console.log(ui.success(`Auto-configured base URL → ${ui.cyan(ATLAS_API_BASE)}`));
+          }
+          console.log('');
+          console.log(`  🔑 ${ui.bold('MongoDB Atlas key detected')} (al-*)`);
+          console.log(`     Endpoint: ${ui.cyan(ATLAS_API_BASE)}`);
+          console.log(`     Atlas provides Voyage AI models with Atlas-native billing.`);
+          console.log(`     All vai features work identically on both endpoints.`);
+        } else if (keyInfo.type === 'voyage') {
+          if (currentBase !== VOYAGE_API_BASE) {
+            setConfigValue('baseUrl', VOYAGE_API_BASE);
+            console.log('');
+            console.log(ui.success(`Auto-configured base URL → ${ui.cyan(VOYAGE_API_BASE)}`));
+          }
+          console.log('');
+          console.log(`  🔑 ${ui.bold('Voyage AI key detected')} (pa-*)`);
+          console.log(`     Endpoint: ${ui.cyan(VOYAGE_API_BASE)}`);
+        } else {
+          console.log('');
+          console.log(`  ⚠️  Unrecognized key prefix. Expected ${ui.cyan('al-*')} (Atlas) or ${ui.cyan('pa-*')} (Voyage AI).`);
+          console.log(`     Make sure your base URL matches: ${ui.cyan('vai config set base-url <url>')}`);
+        }
+      }
     });
 
   // ── config get [key] ──

package/src/commands/mcp-server.js

@@ -14,6 +14,7 @@ function registerMcpServer(program) {
     .option('--host <address>', 'Bind address (http transport only)', '127.0.0.1')
     .option('--db <name>', 'Default MongoDB database for tools')
     .option('--collection <name>', 'Default collection for tools')
+    .option('--no-sse', 'Disable SSE transport (SSE is enabled by default for HTTP)')
     .option('--verbose', 'Enable debug logging to stderr')
     .action(async (opts) => {
       if (opts.verbose) {
@@ -27,7 +28,9 @@ function registerMcpServer(program) {
       const { runStdioServer, runHttpServer } = require('../mcp/server');
 
       if (opts.transport === 'http') {
-        await runHttpServer({ port: opts.port, host: opts.host });
+        // SSE is enabled by default for HTTP transport (required for n8n, etc.)
+        // Use --no-sse to disable if needed
+        await runHttpServer({ port: opts.port, host: opts.host, sse: opts.sse !== false });
       } else if (opts.transport === 'stdio') {
         await runStdioServer();
       } else {

package/src/commands/playground.js

@@ -14,13 +14,16 @@ function registerPlayground(program) {
     .command('playground')
     .description('Launch interactive web playground for Voyage AI')
     .option('-p, --port <port>', 'Port to serve on', '3333')
+    .option('--host <address>', 'Bind address', '127.0.0.1')
     .option('--no-open', 'Skip auto-opening browser')
     .action(async (opts) => {
       const port = parseInt(opts.port, 10) || 3333;
+      const host = opts.host || '127.0.0.1';
       const server = createPlaygroundServer();
 
-      server.listen(port, () => {
-        const url = `http://localhost:${port}`;
+      server.listen(port, host, () => {
+        const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+        const url = `http://${displayHost}:${port}`;
         console.log(`🧭 Playground running at ${url} — Press Ctrl+C to stop`);
 
         if (opts.open !== false) {
@@ -366,6 +369,20 @@ function createPlaygroundServer() {
         return;
       }
 
+      // API: List example workflows (must be before the :name route)
+      if (req.method === 'GET' && req.url === '/api/workflows/examples') {
+        try {
+          const { listExampleWorkflows } = require('../lib/workflow');
+          const examples = listExampleWorkflows();
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ examples }));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+        return;
+      }
+
       // API: Get a specific workflow by name
       if (req.method === 'GET' && req.url?.startsWith('/api/workflows/')) {
         const name = decodeURIComponent(req.url.replace('/api/workflows/', ''));

package/src/commands/workflow.js

@@ -22,6 +22,45 @@ function collectInputs(pair, prev) {
   return prev;
 }
 
+/**
+ * Interactively prompt the user for missing workflow inputs using @clack/prompts.
+ * Only prompts for inputs not already provided via --input flags.
+ *
+ * @param {object} definition - Workflow definition
+ * @param {object} existingInputs - Inputs already provided via --input
+ * @returns {Promise<object>} Merged inputs (existing + prompted)
+ */
+async function promptForInputs(definition, existingInputs) {
+  const { buildInputSteps } = require('../lib/workflow');
+  const { createCLIRenderer } = require('../lib/wizard-cli');
+  const { runWizard } = require('../lib/wizard');
+
+  const allSteps = buildInputSteps(definition);
+  // Only prompt for inputs not already provided
+  const steps = allSteps.filter(s => !(s.id in existingInputs));
+  if (steps.length === 0) return existingInputs;
+
+  const renderer = createCLIRenderer({
+    title: `${definition.name || 'Workflow'} inputs`,
+    doneMessage: 'Inputs ready.',
+    showBackHint: true,
+  });
+
+  const { answers, cancelled } = await runWizard({
+    steps,
+    config: {},
+    renderer,
+    initial: {},
+  });
+
+  if (cancelled) {
+    console.log(pc.dim('Cancelled.'));
+    process.exit(0);
+  }
+
+  return { ...existingInputs, ...answers };
+}
+
 /**
  * Register the workflow command on a Commander program.
  * @param {import('commander').Command} program
@@ -43,6 +82,7 @@ function registerWorkflow(program) {
     .option('--quiet', 'Suppress progress output', false)
     .option('--dry-run', 'Show execution plan without running', false)
     .option('--verbose', 'Show step details', false)
+    .option('--no-interactive', 'Disable interactive input prompting')
     .action(async (file, opts) => {
       const { loadWorkflow, executeWorkflow, buildExecutionPlan, validateWorkflow } = require('../lib/workflow');
 
@@ -64,6 +104,11 @@ function registerWorkflow(program) {
 
       const workflowName = definition.name || file;
 
+      // Interactive prompting for missing inputs
+      if (opts.interactive !== false && process.stdin.isTTY) {
+        opts.input = await promptForInputs(definition, opts.input);
+      }
+
       if (opts.dryRun) {
         // Dry run: show plan
         const layers = buildExecutionPlan(definition.steps);

package/src/lib/api.js

@@ -4,10 +4,24 @@ const ATLAS_API_BASE = 'https://ai.mongodb.com/v1';
 const VOYAGE_API_BASE = 'https://api.voyageai.com/v1';
 const MAX_RETRIES = 3;
 
+/**
+ * Identify the key type from its prefix.
+ * @param {string} key
+ * @returns {{ type: 'atlas'|'voyage'|'unknown', label: string, expectedBase: string }}
+ */
+function identifyKey(key) {
+  if (key.startsWith('al-')) {
+    return { type: 'atlas', label: 'MongoDB Atlas', expectedBase: ATLAS_API_BASE };
+  }
+  if (key.startsWith('pa-')) {
+    return { type: 'voyage', label: 'Voyage AI (direct)', expectedBase: VOYAGE_API_BASE };
+  }
+  return { type: 'unknown', label: 'Unknown provider', expectedBase: ATLAS_API_BASE };
+}
+
 /**
  * Resolve the API base URL.
  * Priority: VOYAGE_API_BASE env → config baseUrl → auto-detect from key prefix.
- * Keys starting with 'pa-' that work on Voyage platform use VOYAGE_API_BASE.
  * @returns {string}
  */
 function getApiBase() {
@@ -20,6 +34,10 @@ function getApiBase() {
   const configBase = getConfigValue('baseUrl');
   if (configBase) return configBase.replace(/\/+$/, '');
 
+  // Auto-detect from key prefix
+  const key = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');
+  if (key) return identifyKey(key).expectedBase;
+
   // Default to Atlas endpoint
   return ATLAS_API_BASE;
 }
@@ -29,7 +47,7 @@ const API_BASE = ATLAS_API_BASE;
 
 /**
  * Get the Voyage API key or exit with a helpful error.
- * Checks: env var → config file.
+ * Validates that the key prefix matches the configured base URL and warns on mismatch.
  * @returns {string}
  */
 function requireApiKey() {
@@ -43,6 +61,25 @@ function requireApiKey() {
       '       or Voyage AI platform > Dashboard > API Keys';
     throw new Error(msg);
   }
+
+  // Validate key/endpoint match and warn on mismatch
+  const base = getApiBase();
+  const keyInfo = identifyKey(key);
+
+  if (keyInfo.type !== 'unknown' && keyInfo.expectedBase !== base) {
+    const mismatch =
+      `\n⚠️  API key/endpoint mismatch detected!\n` +
+      `   Key type:   ${keyInfo.label} (${key.slice(0, 5)}...)\n` +
+      `   Endpoint:   ${base}\n` +
+      `   Expected:   ${keyInfo.expectedBase}\n\n` +
+      `   This will likely cause a 401 or 403 error.\n\n` +
+      `   Fix: Update your base URL to match your key:\n` +
+      `     vai config set base-url ${keyInfo.expectedBase}\n\n` +
+      `   Or switch to a ${base.includes('ai.mongodb.com') ? 'MongoDB Atlas' : 'Voyage AI'} key:\n` +
+      `     vai config set api-key <your-${base.includes('ai.mongodb.com') ? 'atlas' : 'voyage'}-key>\n`;
+    process.stderr.write(mismatch);
+  }
+
   return key;
 }
 
@@ -162,6 +199,7 @@ module.exports = {
   API_BASE,
   ATLAS_API_BASE,
   VOYAGE_API_BASE,
+  identifyKey,
   getApiBase,
   requireApiKey,
   apiRequest,

package/src/lib/workflow.js

@@ -92,10 +92,12 @@ function validateWorkflow(definition) {
     }
 
     // Check template references point to known step IDs or reserved prefixes
+    // "item" and "index" are injected by forEach at runtime
+    const forEachVars = step.forEach ? new Set(['item', 'index']) : new Set();
     if (step.inputs) {
       const deps = extractDependencies(step.inputs);
       for (const dep of deps) {
-        if (!stepIds.has(dep) && !definition.steps.some(s => s.id === dep)) {
+        if (!forEachVars.has(dep) && !stepIds.has(dep) && !definition.steps.some(s => s.id === dep)) {
           errors.push(`${stepPrefix}: references unknown step "${dep}"`);
         }
       }
@@ -1162,6 +1164,36 @@ function coerceInput(value, type) {
   return value;
 }
 
+// ════════════════════════════════════════════════════════════════════
+// Input Schema Helpers
+// ════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert a workflow's `inputs` object into wizard-engine-compatible step definitions.
+ * Used by both CLI (via @clack/prompts) and playground (via input modal) to
+ * prompt users for missing inputs before execution.
+ *
+ * @param {object} definition - Workflow definition with an `inputs` property
+ * @returns {import('./wizard').Step[]}
+ */
+function buildInputSteps(definition) {
+  if (!definition.inputs) return [];
+  return Object.entries(definition.inputs).map(([key, spec]) => ({
+    id: key,
+    label: spec.description || key,
+    type: 'text',
+    required: !!spec.required,
+    placeholder: spec.type === 'number' ? 'number' : (spec.type || 'string'),
+    defaultValue: spec.default !== undefined ? String(spec.default) : undefined,
+    validate: (val) => {
+      if (spec.type === 'number' && val && isNaN(Number(val))) {
+        return 'Must be a number';
+      }
+      return true;
+    },
+  }));
+}
+
 // ════════════════════════════════════════════════════════════════════
 // Built-in Templates
 // ════════════════════════════════════════════════════════════════════
@@ -1196,8 +1228,60 @@ function listBuiltinWorkflows() {
   });
 }
 
+// ════════════════════════════════════════════════════════════════════
+// Example Workflows
+// ════════════════════════════════════════════════════════════════════
+
+const EXAMPLE_CATEGORIES = {
+  'search-filter-transform': 'Retrieval',
+  'conditional-fallback-search': 'Retrieval',
+  'multi-query-fusion': 'Retrieval',
+  'rag-with-guardrails': 'RAG',
+  'question-answer-with-citations': 'RAG',
+  'topic-deep-dive': 'RAG',
+  'dedup-and-ingest': 'Ingestion',
+  'content-quality-gate': 'Ingestion',
+  'embedding-model-comparison': 'Analysis',
+  'batch-similarity-check': 'Analysis',
+  'collection-inventory': 'Analysis',
+};
+
+/**
+ * Get the path to the example workflows directory.
+ */
+function getExamplesDir() {
+  return path.join(__dirname, '..', '..', 'examples', 'workflows');
+}
+
 /**
- * Load a workflow definition from a file path or built-in template name.
+ * List example workflow files with category metadata.
+ * @returns {Array<{ name: string, description: string, file: string, category: string, isExample: boolean }>}
+ */
+function listExampleWorkflows() {
+  const dir = getExamplesDir();
+  if (!fs.existsSync(dir)) return [];
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  return files.map(f => {
+    try {
+      const def = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      const stem = f.replace('.json', '');
+      return {
+        name: stem,
+        description: def.description || def.name || f,
+        file: f,
+        category: EXAMPLE_CATEGORIES[stem] || 'Other',
+        isExample: true,
+      };
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+}
+
+/**
+ * Load a workflow definition from a file path, built-in template name,
+ * or example workflow name.
  *
  * @param {string} nameOrPath - File path or template name (e.g., "multi-collection-search")
  * @returns {object} Parsed workflow definition
@@ -1216,6 +1300,13 @@ function loadWorkflow(nameOrPath) {
     return JSON.parse(content);
   }
 
+  // Try as an example workflow name
+  const examplePath = path.join(getExamplesDir(), `${nameOrPath}.json`);
+  if (fs.existsSync(examplePath)) {
+    const content = fs.readFileSync(examplePath, 'utf8');
+    return JSON.parse(content);
+  }
+
   // Try with .json extension appended
   const withJson = nameOrPath.endsWith('.json') ? nameOrPath : `${nameOrPath}.json`;
   if (fs.existsSync(withJson)) {
@@ -1249,8 +1340,13 @@ module.exports = {
 
   // Templates
   listBuiltinWorkflows,
+  listExampleWorkflows,
   loadWorkflow,
   getWorkflowsDir,
+  getExamplesDir,
+
+  // Input helpers
+  buildInputSteps,
 
   // Constants
   VAI_TOOLS,

package/src/mcp/server.js

@@ -51,7 +51,7 @@ async function runStdioServer() {
  * @param {number} options.port
  * @param {string} options.host
  */
-async function runHttpServer({ port = 3100, host = '127.0.0.1' } = {}) {
+async function runHttpServer({ port = 3100, host = '127.0.0.1', sse = false } = {}) {
   const express = require('express');
   const { StreamableHTTPServerTransport } = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
   const { getConfigValue } = require('../lib/config');
@@ -131,8 +131,21 @@ async function runHttpServer({ port = 3100, host = '127.0.0.1' } = {}) {
     res.status(405).json({ error: 'Method not allowed. Stateless server — no sessions to delete.' });
   });
 
+  // SSE transport (opt-in via --sse flag)
+  if (sse) {
+    const { setupSSE, getSessionCount } = require('./sse-transport');
+    setupSSE(app, authenticateRequest);
+
+    // Add SSE session count endpoint
+    app.get('/health/sse', (_req, res) => {
+      res.json({ sseSessions: getSessionCount() });
+    });
+  }
+
   app.listen(port, host, () => {
-    const msg = `vai MCP server v${VERSION} running on http://${host}:${port}/mcp`;
+    const transports = ['Streamable HTTP (POST /mcp)'];
+    if (sse) transports.push('SSE (GET /sse)');
+    const msg = `vai MCP server v${VERSION} running on http://${host}:${port}\n  Transports: ${transports.join(', ')}`;
     if (process.env.VAI_MCP_VERBOSE) {
       process.stderr.write(msg + '\n');
       process.stderr.write(`Authentication: ${requireAuth ? 'enabled' : 'disabled (no keys configured)'}\n`);

package/src/mcp/sse-transport.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const { SSEServerTransport } = require('@modelcontextprotocol/sdk/server/sse.js');
+const { createServer } = require('./server');
+
+/** @type {Map<string, { server: any, transport: SSEServerTransport, createdAt: number, lastActivity: number }>} */
+const sessions = new Map();
+
+const MAX_SESSIONS = 50;
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Prune idle or expired SSE sessions.
+ */
+function pruneSessions() {
+  const now = Date.now();
+  for (const [id, entry] of sessions) {
+    if (now - entry.lastActivity > IDLE_TIMEOUT_MS) {
+      if (process.env.VAI_MCP_VERBOSE) {
+        process.stderr.write(`SSE session ${id} idle-pruned after ${Math.floor((now - entry.lastActivity) / 1000)}s\n`);
+      }
+      try { entry.transport.close(); } catch { /* ignore */ }
+      sessions.delete(id);
+    }
+  }
+}
+
+// Run pruning every 5 minutes
+let _pruneInterval = null;
+
+/**
+ * Register SSE transport routes on an Express app.
+ *
+ * GET  /sse      — Client opens an SSE stream (returns event stream + session ID)
+ * POST /messages — Client sends JSON-RPC messages to a session
+ *
+ * @param {import('express').Express} app
+ * @param {Function} authenticateRequest — Express middleware for bearer auth
+ */
+function setupSSE(app, authenticateRequest) {
+  // Start the pruning interval
+  if (!_pruneInterval) {
+    _pruneInterval = setInterval(pruneSessions, 5 * 60 * 1000);
+    _pruneInterval.unref(); // Don't keep process alive just for pruning
+  }
+
+  // SSE connection endpoint — client GETs this to open a stream
+  app.get('/sse', authenticateRequest, async (req, res) => {
+    // Enforce max concurrent sessions
+    pruneSessions();
+    if (sessions.size >= MAX_SESSIONS) {
+      return res.status(503).json({
+        error: `Too many active SSE sessions (max ${MAX_SESSIONS}). Try again later.`,
+      });
+    }
+
+    const server = createServer();
+    const transport = new SSEServerTransport('/messages', res);
+    const sessionId = transport.sessionId;
+
+    sessions.set(sessionId, {
+      server,
+      transport,
+      createdAt: Date.now(),
+      lastActivity: Date.now(),
+    });
+
+    if (process.env.VAI_MCP_VERBOSE) {
+      process.stderr.write(`SSE session ${sessionId} connected (active: ${sessions.size})\n`);
+    }
+
+    // Clean up on disconnect
+    res.on('close', () => {
+      sessions.delete(sessionId);
+      try { transport.close(); } catch { /* ignore */ }
+      if (process.env.VAI_MCP_VERBOSE) {
+        process.stderr.write(`SSE session ${sessionId} disconnected (active: ${sessions.size})\n`);
+      }
+    });
+
+    await server.connect(transport);
+  });
+
+  // SSE message endpoint — client POSTs JSON-RPC messages here
+  app.post('/messages', authenticateRequest, async (req, res) => {
+    const sessionId = req.query.sessionId;
+    if (!sessionId) {
+      return res.status(400).json({ error: 'Missing sessionId query parameter' });
+    }
+
+    const entry = sessions.get(sessionId);
+    if (!entry) {
+      return res.status(404).json({
+        error: 'Session not found. It may have expired or been disconnected.',
+      });
+    }
+
+    // Update last activity for idle tracking
+    entry.lastActivity = Date.now();
+
+    await entry.transport.handlePostMessage(req, res, req.body);
+  });
+}
+
+/**
+ * Get current SSE session count (for health endpoint).
+ */
+function getSessionCount() {
+  return sessions.size;
+}
+
+module.exports = { setupSSE, getSessionCount };