voyageai-cli 1.30.0 → 1.30.2

package/src/mcp/install.js

@@ -19,11 +19,21 @@ const TARGETS = {
   'claude-code': {
     name: 'Claude Code',
     configPath: () => path.join(os.homedir(), '.claude', 'settings.json'),
-    configKey: 'mcpServers', // same key but different file
+    configKey: 'mcpServers',
   },
   cursor: {
     name: 'Cursor',
     configPath: () => path.join(os.homedir(), '.cursor', 'mcp.json'),
+    // Cursor also supports workspace-level config
+    workspaceConfigPath: () => '.cursor/mcp.json',
+    postInstall: () => {
+      return [
+        'Cursor MCP integration tips:',
+        '  • Restart Cursor to load the vai MCP server',
+        '  • Use @vai in Cursor Chat to invoke vai tools',
+        '  • Run "vai mcp status" to verify installation',
+      ];
+    },
   },
   windsurf: {
     name: 'Windsurf',
@@ -37,6 +47,39 @@ const TARGETS = {
       return path.join(os.homedir(), '.config', 'Code', 'User', 'settings.json');
     },
     configKey: 'mcp.servers',
+    // VS Code needs MCP extension or GitHub Copilot with MCP support
+    postInstall: () => {
+      return [
+        'VS Code MCP integration tips:',
+        '  • Install the vai VS Code extension for native integration',
+        '  • Or use GitHub Copilot Chat with MCP support (requires Copilot subscription)',
+        '  • Or use the vai-vscode extension from the vscode-extension/ folder',
+        '  • Run "vai mcp-server --transport http" for HTTP-based integrations',
+      ];
+    },
+  },
+  'vscode-insiders': {
+    name: 'VS Code Insiders',
+    configPath: () => {
+      if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json');
+      if (process.platform === 'win32') return path.join(process.env.APPDATA || '', 'Code - Insiders', 'User', 'settings.json');
+      return path.join(os.homedir(), '.config', 'Code - Insiders', 'User', 'settings.json');
+    },
+    configKey: 'mcp.servers',
+    postInstall: () => {
+      return [
+        'VS Code Insiders MCP integration tips:',
+        '  • Insiders often has newer MCP features',
+        '  • Install the vai VS Code extension for native integration',
+        '  • Or use GitHub Copilot Chat with MCP support',
+      ];
+    },
+  },
+  'cursor-workspace': {
+    name: 'Cursor (Workspace)',
+    configPath: () => null, // Requires workspace path
+    workspaceConfigPath: () => '.cursor/mcp.json',
+    requiresWorkspace: true,
   },
 };
 
@@ -48,14 +91,57 @@ function buildVaiEntry(opts = {}) {
     command: 'vai',
     args: ['mcp-server'],
   };
+
+  // Transport configuration
   if (opts.transport === 'http') {
     entry.args.push('--transport', 'http');
     if (opts.port) entry.args.push('--port', String(opts.port));
+    if (opts.sse === false) entry.args.push('--no-sse');
   }
+
+  // Environment variables
+  const env = {};
   const apiKey = opts.apiKey || process.env.VOYAGE_API_KEY || '';
-  if (apiKey) {
-    entry.env = { VOYAGE_API_KEY: apiKey };
+  const mongoUri = opts.mongodbUri || process.env.MONGODB_URI || '';
+
+  if (apiKey) env.VOYAGE_API_KEY = apiKey;
+  if (mongoUri) env.MONGODB_URI = mongoUri;
+  if (opts.db) env.VAI_DEFAULT_DB = opts.db;
+  if (opts.collection) env.VAI_DEFAULT_COLLECTION = opts.collection;
+  if (opts.verbose) env.VAI_MCP_VERBOSE = '1';
+
+  if (Object.keys(env).length > 0) {
+    entry.env = env;
   }
+
+  return entry;
+}
+
+/**
+ * Build an extended vai MCP entry with tool descriptions for Cursor/VS Code.
+ * This helps the AI understand what tools are available.
+ */
+function buildVaiEntryWithMetadata(opts = {}) {
+  const entry = buildVaiEntry(opts);
+
+  // Add metadata for better AI tool discovery
+  entry.metadata = {
+    name: 'vai',
+    description: 'Voyage AI semantic search and RAG tools for MongoDB Atlas Vector Search',
+    tools: [
+      { name: 'vai_query', description: 'Full RAG query with reranking' },
+      { name: 'vai_search', description: 'Raw vector similarity search' },
+      { name: 'vai_rerank', description: 'Rerank documents by relevance' },
+      { name: 'vai_embed', description: 'Generate embeddings for text' },
+      { name: 'vai_similarity', description: 'Compare text similarity' },
+      { name: 'vai_ingest', description: 'Chunk and store documents' },
+      { name: 'vai_collections', description: 'List MongoDB collections' },
+      { name: 'vai_models', description: 'List available Voyage AI models' },
+      { name: 'vai_explain', description: 'Explain embedding concepts' },
+      { name: 'vai_estimate', description: 'Estimate embedding costs' },
+    ],
+  };
+
   return entry;
 }
 
@@ -110,7 +196,7 @@ function setNestedKey(obj, keyPath, value) {
 
 /**
  * Install vai MCP entry into a target tool's config.
- * Returns { installed: boolean, message: string }
+ * Returns { installed: boolean, message: string, tips?: string[] }
  */
 function installTarget(targetKey, opts = {}) {
   const target = TARGETS[targetKey];
@@ -118,7 +204,19 @@ function installTarget(targetKey, opts = {}) {
     return { installed: false, message: `Unknown target: ${targetKey}. Available: ${Object.keys(TARGETS).join(', ')}` };
   }
 
+  // Handle workspace-level installs
+  if (target.requiresWorkspace) {
+    if (!opts.workspacePath) {
+      return { installed: false, message: `${target.name}: requires --workspace-path option` };
+    }
+    return installWorkspaceConfig(target, opts);
+  }
+
   const configPath = target.configPath();
+  if (!configPath) {
+    return { installed: false, message: `${target.name}: config path not available` };
+  }
+
   const mcpKey = target.configKey || 'mcpServers';
   const config = readConfig(configPath) || {};
 
@@ -134,12 +232,63 @@ function installTarget(targetKey, opts = {}) {
   }
 
   const existed = !!servers.vai;
-  servers.vai = buildVaiEntry(opts);
+
+  // Use extended entry with metadata for Cursor/VS Code
+  if (targetKey === 'cursor' || targetKey.startsWith('vscode')) {
+    servers.vai = buildVaiEntryWithMetadata(opts);
+  } else {
+    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}` };
+
+  const result = {
+    installed: true,
+    message: `${target.name}: ${existed ? 'updated' : 'installed'} vai in ${configPath}`,
+  };
+
+  // Add post-install tips if available
+  if (target.postInstall) {
+    result.tips = target.postInstall();
+  }
+
+  return result;
+}
+
+/**
+ * Install vai MCP config at workspace level.
+ */
+function installWorkspaceConfig(target, opts) {
+  const workspacePath = opts.workspacePath;
+  const relativeConfigPath = target.workspaceConfigPath();
+  const configPath = path.join(workspacePath, relativeConfigPath);
+
+  const config = readConfig(configPath) || {};
+  const mcpKey = target.configKey || 'mcpServers';
+
+  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 = buildVaiEntryWithMetadata(opts);
+  setNestedKey(config, mcpKey, servers);
+
+  writeConfig(configPath, config);
+  return {
+    installed: true,
+    message: `${target.name}: ${existed ? 'updated' : 'installed'} vai in ${configPath}`,
+    tips: ['Workspace-level config will be used when opening this folder in Cursor'],
+  };
 }
 
 /**
@@ -175,7 +324,17 @@ function uninstallTarget(targetKey) {
 function statusAll() {
   const results = [];
   for (const [key, target] of Object.entries(TARGETS)) {
-    const configPath = target.configPath();
+    // Skip workspace-only targets in global status
+    if (target.requiresWorkspace) {
+      continue;
+    }
+
+    const configPath = target.configPath?.();
+    if (!configPath) {
+      results.push({ target: key, name: target.name, configPath: 'N/A', status: 'workspace-only' });
+      continue;
+    }
+
     const mcpKey = target.configKey || 'mcpServers';
     const config = readConfig(configPath);
 
@@ -192,10 +351,124 @@ function statusAll() {
   return results;
 }
 
+/**
+ * Get detailed information about a target for help/docs.
+ */
+function getTargetInfo(targetKey) {
+  const target = TARGETS[targetKey];
+  if (!target) return null;
+
+  return {
+    key: targetKey,
+    name: target.name,
+    configPath: target.configPath?.() || null,
+    workspaceConfigPath: target.workspaceConfigPath?.() || null,
+    requiresWorkspace: target.requiresWorkspace || false,
+    tips: target.postInstall?.() || [],
+  };
+}
+
+/**
+ * Generate a sample .cursor/mcp.json or .vscode/settings.json for documentation.
+ */
+function generateSampleConfig(targetKey, opts = {}) {
+  const target = TARGETS[targetKey];
+  if (!target) return null;
+
+  const mcpKey = target.configKey || 'mcpServers';
+  const entry = buildVaiEntryWithMetadata(opts);
+
+  const config = {};
+  setNestedKey(config, mcpKey, { vai: entry });
+
+  return JSON.stringify(config, null, 2);
+}
+
+/**
+ * Verify that vai is accessible in PATH.
+ */
+function verifyVaiInstallation() {
+  const { execSync } = require('child_process');
+  try {
+    const version = execSync('vai --version', { encoding: 'utf8', timeout: 5000 }).trim();
+    return { installed: true, version };
+  } catch {
+    return { installed: false, version: null };
+  }
+}
+
+/**
+ * Diagnose MCP installation issues.
+ */
+function diagnose(targetKey) {
+  const results = [];
+
+  // Check vai installation
+  const vaiStatus = verifyVaiInstallation();
+  if (!vaiStatus.installed) {
+    results.push({ level: 'error', message: 'vai CLI not found in PATH. Run: npm install -g voyageai-cli' });
+  } else {
+    results.push({ level: 'ok', message: `vai ${vaiStatus.version} installed` });
+  }
+
+  // Check target config
+  const target = TARGETS[targetKey];
+  if (!target) {
+    results.push({ level: 'error', message: `Unknown target: ${targetKey}` });
+    return results;
+  }
+
+  const configPath = target.configPath?.();
+  if (!configPath) {
+    results.push({ level: 'warning', message: `${target.name}: No global config path (may require workspace config)` });
+  } else if (!fs.existsSync(configPath)) {
+    results.push({ level: 'warning', message: `${target.name}: Config file not found at ${configPath}` });
+  } else {
+    const config = readConfig(configPath);
+    const mcpKey = target.configKey || 'mcpServers';
+    const servers = getNestedKey(config, mcpKey);
+
+    if (servers?.vai) {
+      results.push({ level: 'ok', message: `${target.name}: vai configured in ${configPath}` });
+
+      // Validate the entry
+      const entry = servers.vai;
+      if (entry.command !== 'vai') {
+        results.push({ level: 'warning', message: `${target.name}: command should be "vai", found "${entry.command}"` });
+      }
+      if (!entry.args?.includes('mcp-server')) {
+        results.push({ level: 'warning', message: `${target.name}: args should include "mcp-server"` });
+      }
+    } else {
+      results.push({ level: 'warning', message: `${target.name}: vai not configured. Run: vai mcp install ${targetKey}` });
+    }
+  }
+
+  // Check environment variables
+  if (process.env.VOYAGE_API_KEY) {
+    results.push({ level: 'ok', message: 'VOYAGE_API_KEY environment variable set' });
+  } else {
+    results.push({ level: 'warning', message: 'VOYAGE_API_KEY not set (required for embeddings)' });
+  }
+
+  if (process.env.MONGODB_URI) {
+    results.push({ level: 'ok', message: 'MONGODB_URI environment variable set' });
+  } else {
+    results.push({ level: 'warning', message: 'MONGODB_URI not set (required for vector search)' });
+  }
+
+  return results;
+}
+
 module.exports = {
   TARGETS,
   installTarget,
   uninstallTarget,
   statusAll,
   buildVaiEntry,
+  buildVaiEntryWithMetadata,
+  getTargetInfo,
+  generateSampleConfig,
+  verifyVaiInstallation,
+  diagnose,
 };

package/src/mcp/schemas/index.js

@@ -87,6 +87,166 @@ const ingestSchema = {
   model: z.string().default('voyage-4-large').describe('Voyage AI embedding model'),
 };
 
+/** vai_index_workspace input schema */
+const indexWorkspaceSchema = {
+  path: z.string().optional().describe('Workspace directory path. Defaults to current working directory.'),
+  db: z.string().optional().describe('MongoDB database name'),
+  collection: z.string().optional().describe('Collection to store indexed documents'),
+  contentType: z.enum(['code', 'docs', 'config', 'all']).default('code')
+    .describe('Type of content to index: code (source files), docs (markdown/text), config (json/yaml), or all'),
+  model: z.string().default('voyage-4-large').describe('Voyage AI embedding model'),
+  maxFiles: z.number().int().min(1).max(10000).default(1000).describe('Maximum number of files to index'),
+  maxFileSize: z.number().int().min(1000).max(1000000).default(100000).describe('Maximum file size in bytes'),
+  chunkSize: z.number().int().min(100).max(4000).default(512).describe('Target chunk size in characters'),
+  chunkOverlap: z.number().int().min(0).max(500).default(50).describe('Overlap between chunks in characters'),
+  batchSize: z.number().int().min(1).max(50).default(10).describe('Number of files to process per batch'),
+};
+
+/** vai_search_code input schema */
+const searchCodeSchema = {
+  query: z.string().min(1).max(5000).describe('Semantic search query for code'),
+  db: z.string().optional().describe('MongoDB database name'),
+  collection: z.string().optional().describe('Collection with indexed code'),
+  limit: z.number().int().min(1).max(50).default(10).describe('Maximum number of results'),
+  language: z.string().optional().describe('Filter by programming language (e.g., "js", "py", "go")'),
+  category: z.enum(['code', 'docs', 'config']).optional().describe('Filter by content category'),
+  model: z.string().optional().describe('Voyage AI embedding model'),
+  filter: z.record(z.string(), z.unknown()).optional().describe('Additional MongoDB filter'),
+};
+
+/** vai_explain_code input schema */
+const explainCodeSchema = {
+  code: z.string().min(1).max(10000).describe('Code snippet to explain'),
+  language: z.string().optional().describe('Programming language of the code'),
+  db: z.string().optional().describe('MongoDB database name'),
+  collection: z.string().optional().describe('Collection with indexed documentation'),
+  contextLimit: z.number().int().min(1).max(20).default(5).describe('Number of context documents to retrieve'),
+  model: z.string().optional().describe('Voyage AI embedding model'),
+};
+
+/** vai_code_index input schema */
+const codeIndexSchema = {
+  source: z.string().min(1).describe(
+    'Local directory path or GitHub repo URL (e.g., "/path/to/project" or "https://github.com/org/repo")'
+  ),
+  db: z.string().optional().describe('MongoDB database name. Default: "vai_code_search"'),
+  collection: z.string().optional().describe(
+    'Collection name. Auto-derived from project name if omitted.'
+  ),
+  model: z.string().optional().describe(
+    'Embedding model. Default: auto-detected (voyage-code-3 for code, voyage-4-large for docs)'
+  ),
+  branch: z.string().default('main').describe('Git branch for remote repos'),
+  maxFiles: z.number().int().min(1).max(10000).default(5000)
+    .describe('Maximum files to index'),
+  maxFileSize: z.number().int().min(1000).max(1000000).default(100000)
+    .describe('Maximum file size in bytes'),
+  chunkSize: z.number().int().min(100).max(4000).default(512)
+    .describe('Target chunk size in characters'),
+  chunkOverlap: z.number().int().min(0).max(500).default(50)
+    .describe('Overlap between chunks in characters'),
+  batchSize: z.number().int().min(1).max(50).default(20)
+    .describe('Files per embedding batch'),
+  refresh: z.boolean().default(false)
+    .describe('Incremental refresh: only re-index changed files'),
+  contentType: z.enum(['code', 'docs', 'config', 'all']).default('code')
+    .describe('Type of content to index'),
+};
+
+/** vai_code_search input schema */
+const codeSearchSchema = {
+  query: z.string().min(1).max(5000).describe(
+    'Natural language search query (e.g., "where do we handle auth timeouts")'
+  ),
+  db: z.string().optional().describe('MongoDB database name'),
+  collection: z.string().optional().describe('Collection with indexed code'),
+  limit: z.number().int().min(1).max(50).default(10)
+    .describe('Maximum number of results'),
+  language: z.string().optional()
+    .describe('Filter by programming language (e.g., "js", "py", "go")'),
+  category: z.enum(['code', 'docs', 'config']).optional()
+    .describe('Filter by content category'),
+  rerank: z.boolean().default(true)
+    .describe('Rerank results with Voyage AI reranker for better relevance'),
+  rerankModel: z.enum(['rerank-2.5', 'rerank-2.5-lite']).default('rerank-2.5')
+    .describe('Reranking model'),
+  model: z.string().optional()
+    .describe('Embedding model for query. Default: voyage-code-3'),
+  filter: z.record(z.string(), z.unknown()).optional()
+    .describe('Additional MongoDB filter on metadata fields'),
+};
+
+/** vai_code_query input schema */
+const codeQuerySchema = {
+  query: z.string().min(1).max(5000).describe(
+    'Question about the codebase (e.g., "how does the auth middleware work")'
+  ),
+  db: z.string().optional().describe('MongoDB database name'),
+  collection: z.string().optional().describe('Collection with indexed code'),
+  limit: z.number().int().min(1).max(20).default(5)
+    .describe('Maximum results (fewer, higher quality)'),
+  language: z.string().optional()
+    .describe('Filter by programming language'),
+  model: z.string().optional()
+    .describe('Embedding model. Default: voyage-code-3'),
+  filter: z.record(z.string(), z.unknown()).optional()
+    .describe('Additional MongoDB filter'),
+};
+
+/** vai_code_find_similar input schema */
+const codeFindSimilarSchema = {
+  code: z.string().min(1).max(10000).describe(
+    'Code snippet to find similar implementations for'
+  ),
+  db: z.string().optional().describe('MongoDB database name'),
+  collection: z.string().optional().describe('Collection with indexed code'),
+  limit: z.number().int().min(1).max(50).default(10)
+    .describe('Maximum results'),
+  language: z.string().optional()
+    .describe('Filter by programming language'),
+  model: z.string().optional()
+    .describe('Embedding model. Default: voyage-code-3'),
+  threshold: z.number().min(0).max(1).default(0.5)
+    .describe('Minimum similarity score (0-1)'),
+  filter: z.record(z.string(), z.unknown()).optional()
+    .describe('Additional MongoDB filter'),
+};
+
+/** vai_code_status input schema */
+const codeStatusSchema = {
+  db: z.string().optional().describe('MongoDB database name'),
+  collection: z.string().optional().describe('Collection to check'),
+};
+
+/** vai_generate_workflow input schema */
+const generateWorkflowSchema = {
+  description: z.string().min(1).max(500).describe('Natural language description of the workflow to generate'),
+  category: z.enum(['retrieval', 'analysis', 'ingestion', 'domain-specific', 'utility', 'integration']).optional()
+    .describe('Workflow category'),
+  tools: z.array(z.string()).optional()
+    .describe('Explicit list of tools to include (e.g., ["query", "rerank", "generate"]). If omitted, tools are inferred from the description.'),
+};
+
+/** vai_validate_workflow input schema */
+const validateWorkflowSchema = {
+  workflow: z.object({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    inputs: z.record(z.string(), z.unknown()).optional(),
+    defaults: z.record(z.string(), z.unknown()).optional(),
+    steps: z.array(z.object({
+      id: z.string(),
+      tool: z.string(),
+      name: z.string().optional(),
+      inputs: z.record(z.string(), z.unknown()).optional(),
+      condition: z.string().optional(),
+      forEach: z.string().optional(),
+    })),
+    output: z.record(z.string(), z.unknown()).optional(),
+  }).describe('The workflow JSON definition to validate'),
+};
+
 module.exports = {
   querySchema,
   searchSchema,
@@ -99,4 +259,14 @@ module.exports = {
   explainSchema,
   estimateSchema,
   ingestSchema,
+  indexWorkspaceSchema,
+  searchCodeSchema,
+  explainCodeSchema,
+  codeIndexSchema,
+  codeSearchSchema,
+  codeQuerySchema,
+  codeFindSimilarSchema,
+  codeStatusSchema,
+  generateWorkflowSchema,
+  validateWorkflowSchema,
 };

package/src/mcp/server.js

@@ -8,6 +8,9 @@ const { registerEmbeddingTools } = require('./tools/embedding');
 const { registerManagementTools } = require('./tools/management');
 const { registerUtilityTools } = require('./tools/utility');
 const { registerIngestTool } = require('./tools/ingest');
+const { registerWorkspaceTools } = require('./tools/workspace');
+const { registerCodeSearchTools } = require('./tools/code-search');
+const { registerAuthoringTools } = require('./tools/authoring');
 
 const VERSION = require('../../package.json').version;
 
@@ -27,6 +30,9 @@ function createServer() {
   registerManagementTools(server, schemas);
   registerUtilityTools(server, schemas);
   registerIngestTool(server, schemas);
+  registerWorkspaceTools(server, schemas);
+  registerCodeSearchTools(server, schemas);
+  registerAuthoringTools(server, schemas);
 
   return server;
 }
@@ -66,7 +72,7 @@ async function runHttpServer({ port = 3100, host = '127.0.0.1', sse = false } =
   const allKeys = envKey ? [...serverKeys, envKey] : serverKeys;
   const requireAuth = allKeys.length > 0;
 
-  /** Bearer token authentication middleware */
+  /** Bearer token authentication middleware (timing-safe comparison) */
   function authenticateRequest(req, res, next) {
     if (!requireAuth) return next();
     const authHeader = req.headers.authorization;
@@ -74,7 +80,13 @@ async function runHttpServer({ port = 3100, host = '127.0.0.1', sse = false } =
       return res.status(401).json({ error: 'Missing or invalid Authorization header' });
     }
     const token = authHeader.slice(7);
-    if (!allKeys.includes(token)) {
+    const tokenBuf = Buffer.from(token);
+    const match = allKeys.some(key => {
+      const keyBuf = Buffer.from(key);
+      if (keyBuf.length !== tokenBuf.length) return false;
+      return crypto.timingSafeEqual(keyBuf, tokenBuf);
+    });
+    if (!match) {
       return res.status(401).json({ error: 'Invalid API key' });
     }
     next();
@@ -93,7 +105,6 @@ async function runHttpServer({ port = 3100, host = '127.0.0.1', sse = false } =
 
     // Check Voyage AI connectivity
     try {
-      const { getConfigValue } = require('../lib/config');
       const hasKey = !!(process.env.VOYAGE_API_KEY || getConfigValue('apiKey'));
       health.voyageAi = hasKey ? 'configured' : 'not configured';
     } catch {
@@ -102,7 +113,6 @@ async function runHttpServer({ port = 3100, host = '127.0.0.1', sse = false } =
 
     // Check MongoDB connectivity
     try {
-      const { getConfigValue } = require('../lib/config');
       const hasUri = !!(process.env.MONGODB_URI || getConfigValue('mongodbUri'));
       health.mongodb = hasUri ? 'configured' : 'not configured';
     } catch {
@@ -173,3 +183,8 @@ function generateKey() {
 }
 
 module.exports = { createServer, runStdioServer, runHttpServer, generateKey };
+
+// Allow direct execution: `node src/mcp/server.js`
+if (require.main === module) {
+  runStdioServer();
+}