voyageai-cli 1.26.1 → 1.28.0

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 };