voyageai-cli 1.26.0 → 1.27.0

package/src/mcp/tools/utility.js

@@ -40,180 +40,198 @@ function suggestTopics(input, topics) {
 }
 
 /**
- * Register utility tools: vai_topics, vai_explain, vai_estimate
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {object} schemas
+ * Handler for vai_topics: list all available educational topics.
+ * @param {object} input - Validated input matching topicsSchema
+ * @returns {Promise<{structuredContent: object, content: Array}>}
  */
-function registerUtilityTools(server, schemas) {
-  // vai_topics — list all available educational topics
-  server.tool(
-    'vai_topics',
-    'List all available educational topics with summaries. Call this FIRST to discover what topics vai can explain — covers embeddings, vector search, RAG, reranking, model selection, multimodal, code generation, and more. Then use vai_explain to dive deep into any topic.',
-    schemas.topicsSchema,
-    async (input) => {
-      const allTopics = listConcepts();
-
-      let topics;
-      if (input.search) {
-        // Filter topics by search term
-        const suggestions = suggestTopics(input.search, allTopics);
-        if (suggestions.length === 0) {
-          return {
-            structuredContent: { search: input.search, results: [], totalTopics: allTopics.length },
-            content: [{ type: 'text', text: `No topics matching "${input.search}". Use vai_topics without a search to see all ${allTopics.length} topics.` }],
-          };
-        }
-        topics = suggestions;
-      } else {
-        // List all topics with summaries
-        topics = allTopics.map(key => {
-          const concept = getConcept(key);
-          return { topic: key, title: concept.title, summary: concept.summary };
-        });
-      }
-
-      // Group by category for better browsing
-      const categories = {
-        'Core Concepts': ['embeddings', 'vector-search', 'rag', 'cosine-similarity', 'input-type', 'two-stage-retrieval'],
-        'Models & Pricing': ['models', 'mixture-of-experts', 'voyage-4-nano', 'shared-embedding-space', 'quantization', 'benchmarking', 'rteb-benchmarks', 'provider-comparison'],
-        'Multimodal': ['multimodal-embeddings', 'cross-modal-search', 'modality-gap', 'multimodal-rag'],
-        'API & Configuration': ['api-keys', 'api-access', 'batch-processing', 'auto-embedding', 'vai-vs-auto-embedding'],
-        'Reranking & Evaluation': ['reranking', 'rerank-eval', 'eval-comparison'],
-        'Code & Chat': ['code-generation', 'scaffolding', 'chat'],
-      };
-
-      const textLines = topics.map(t => `• **${t.topic}** — ${t.summary}`);
-      const searchNote = input.search ? ` matching "${input.search}"` : '';
-
+async function handleVaiTopics(input) {
+  const allTopics = listConcepts();
+
+  let topics;
+  if (input.search) {
+    // Filter topics by search term
+    const suggestions = suggestTopics(input.search, allTopics);
+    if (suggestions.length === 0) {
       return {
-        structuredContent: {
-          search: input.search || null,
-          topics,
-          categories: input.search ? undefined : categories,
-          totalTopics: allTopics.length,
-        },
-        content: [{
-          type: 'text',
-          text: `${topics.length} topic${topics.length === 1 ? '' : 's'}${searchNote} available:\n\n${textLines.join('\n')}\n\nUse vai_explain with any topic name to get the full explanation.`,
-        }],
+        structuredContent: { search: input.search, results: [], totalTopics: allTopics.length },
+        content: [{ type: 'text', text: `No topics matching "${input.search}". Use vai_topics without a search to see all ${allTopics.length} topics.` }],
       };
     }
-  );
-
-  // vai_explain — educational content with fuzzy matching
-  server.tool(
-    'vai_explain',
-    'Get a detailed explanation of a topic. Covers embeddings, vector search, RAG, MoE architecture, shared space, quantization, multimodal, reranking, and more. If the exact topic isn\'t found, suggests similar topics. Use vai_topics first to browse available topics.',
-    schemas.explainSchema,
-    async (input) => {
-      const key = resolveConcept(input.topic);
-      if (!key) {
-        // Try fuzzy matching before giving up
-        const allTopics = listConcepts();
-        const suggestions = suggestTopics(input.topic, allTopics);
-
-        if (suggestions.length > 0) {
-          // Auto-resolve if there's a strong match
-          const bestMatch = suggestions[0];
-          const bestKey = resolveConcept(bestMatch.topic);
-          if (bestKey) {
-            const concept = getConcept(bestKey);
-            return {
-              structuredContent: {
-                topic: bestKey,
-                title: concept.title,
-                summary: concept.summary,
-                content: concept.content,
-                links: concept.links || [],
-                matchedFrom: input.topic,
-                relatedTopics: suggestions.slice(1).map(s => s.topic),
-              },
-              content: [{
-                type: 'text',
-                text: `# ${concept.title}\n\n${concept.summary}\n\n${concept.content}${suggestions.length > 1 ? `\n\n---\nRelated topics: ${suggestions.slice(1).map(s => s.topic).join(', ')}` : ''}`,
-              }],
-            };
-          }
-        }
+    topics = suggestions;
+  } else {
+    // List all topics with summaries
+    topics = allTopics.map(key => {
+      const concept = getConcept(key);
+      return { topic: key, title: concept.title, summary: concept.summary };
+    });
+  }
+
+  // Group by category for better browsing
+  const categories = {
+    'Core Concepts': ['embeddings', 'vector-search', 'rag', 'cosine-similarity', 'input-type', 'two-stage-retrieval'],
+    'Models & Pricing': ['models', 'mixture-of-experts', 'voyage-4-nano', 'shared-embedding-space', 'quantization', 'benchmarking', 'rteb-benchmarks', 'provider-comparison'],
+    'Multimodal': ['multimodal-embeddings', 'cross-modal-search', 'modality-gap', 'multimodal-rag'],
+    'API & Configuration': ['api-keys', 'api-access', 'batch-processing', 'auto-embedding', 'vai-vs-auto-embedding'],
+    'Reranking & Evaluation': ['reranking', 'rerank-eval', 'eval-comparison'],
+    'Code & Chat': ['code-generation', 'scaffolding', 'chat'],
+  };
+
+  const textLines = topics.map(t => `• **${t.topic}** — ${t.summary}`);
+  const searchNote = input.search ? ` matching "${input.search}"` : '';
+
+  return {
+    structuredContent: {
+      search: input.search || null,
+      topics,
+      categories: input.search ? undefined : categories,
+      totalTopics: allTopics.length,
+    },
+    content: [{
+      type: 'text',
+      text: `${topics.length} topic${topics.length === 1 ? '' : 's'}${searchNote} available:\n\n${textLines.join('\n')}\n\nUse vai_explain with any topic name to get the full explanation.`,
+    }],
+  };
+}
 
+/**
+ * Handler for vai_explain: educational content with fuzzy matching.
+ * @param {object} input - Validated input matching explainSchema
+ * @returns {Promise<{structuredContent: object, content: Array}>}
+ */
+async function handleVaiExplain(input) {
+  const key = resolveConcept(input.topic);
+  if (!key) {
+    // Try fuzzy matching before giving up
+    const allTopics = listConcepts();
+    const suggestions = suggestTopics(input.topic, allTopics);
+
+    if (suggestions.length > 0) {
+      // Auto-resolve if there's a strong match
+      const bestMatch = suggestions[0];
+      const bestKey = resolveConcept(bestMatch.topic);
+      if (bestKey) {
+        const concept = getConcept(bestKey);
         return {
-          structuredContent: { error: 'unknown_topic', topic: input.topic, suggestions, available: allTopics },
+          structuredContent: {
+            topic: bestKey,
+            title: concept.title,
+            summary: concept.summary,
+            content: concept.content,
+            links: concept.links || [],
+            matchedFrom: input.topic,
+            relatedTopics: suggestions.slice(1).map(s => s.topic),
+          },
           content: [{
             type: 'text',
-            text: suggestions.length > 0
-              ? `No exact match for "${input.topic}". Did you mean:\n\n${suggestions.map(s => `• **${s.topic}** — ${s.summary}`).join('\n')}\n\nUse vai_topics to see all ${allTopics.length} available topics.`
-              : `Unknown topic: "${input.topic}"\n\nUse vai_topics to browse all ${allTopics.length} available topics.`,
+            text: `# ${concept.title}\n\n${concept.summary}\n\n${concept.content}${suggestions.length > 1 ? `\n\n---\nRelated topics: ${suggestions.slice(1).map(s => s.topic).join(', ')}` : ''}`,
           }],
         };
       }
+    }
 
-      const concept = getConcept(key);
-
-      // Find related topics based on the current topic
-      const allTopics = listConcepts().filter(t => t !== key);
-      const related = suggestTopics(key, allTopics).slice(0, 3);
+    return {
+      structuredContent: { error: 'unknown_topic', topic: input.topic, suggestions, available: allTopics },
+      content: [{
+        type: 'text',
+        text: suggestions.length > 0
+          ? `No exact match for "${input.topic}". Did you mean:\n\n${suggestions.map(s => `• **${s.topic}** — ${s.summary}`).join('\n')}\n\nUse vai_topics to see all ${allTopics.length} available topics.`
+          : `Unknown topic: "${input.topic}"\n\nUse vai_topics to browse all ${allTopics.length} available topics.`,
+      }],
+    };
+  }
+
+  const concept = getConcept(key);
+
+  // Find related topics based on the current topic
+  const allTopics = listConcepts().filter(t => t !== key);
+  const related = suggestTopics(key, allTopics).slice(0, 3);
+
+  return {
+    structuredContent: {
+      topic: key,
+      title: concept.title,
+      summary: concept.summary,
+      content: concept.content,
+      links: concept.links || [],
+      tryIt: concept.tryIt || null,
+      relatedTopics: related.map(r => r.topic),
+    },
+    content: [{
+      type: 'text',
+      text: `# ${concept.title}\n\n${concept.summary}\n\n${concept.content}${concept.links?.length ? `\n\n**Learn more:** ${concept.links.join(', ')}` : ''}${related.length ? `\n\n**Related:** ${related.map(r => r.topic).join(', ')}` : ''}`,
+    }],
+  };
+}
 
+/**
+ * Handler for vai_estimate: cost estimation.
+ * @param {object} input - Validated input matching estimateSchema
+ * @returns {Promise<{structuredContent: object, content: Array}>}
+ */
+async function handleVaiEstimate(input) {
+  const { docs, queries, months } = input;
+  // Average tokens per doc chunk (~250 tokens)
+  const avgTokensPerDoc = 250;
+  const totalEmbedTokens = docs * avgTokensPerDoc;
+
+  const embeddingModels = MODEL_CATALOG
+    .filter(m => m.type === 'embedding' && !m.legacy && !m.unreleased && m.pricePerMToken)
+    .map(m => {
+      const embedCost = (totalEmbedTokens / 1_000_000) * m.pricePerMToken;
+      const queryCostPerMonth = queries > 0 ? (queries * avgTokensPerDoc / 1_000_000) * m.pricePerMToken : 0;
+      const totalCost = embedCost + (queryCostPerMonth * months);
       return {
-        structuredContent: {
-          topic: key,
-          title: concept.title,
-          summary: concept.summary,
-          content: concept.content,
-          links: concept.links || [],
-          tryIt: concept.tryIt || null,
-          relatedTopics: related.map(r => r.topic),
-        },
-        content: [{
-          type: 'text',
-          text: `# ${concept.title}\n\n${concept.summary}\n\n${concept.content}${concept.links?.length ? `\n\n**Learn more:** ${concept.links.join(', ')}` : ''}${related.length ? `\n\n**Related:** ${related.map(r => r.topic).join(', ')}` : ''}`,
-        }],
+        model: m.name,
+        pricePerMToken: m.pricePerMToken,
+        embeddingCost: Math.round(embedCost * 100) / 100,
+        monthlyCost: Math.round(queryCostPerMonth * 100) / 100,
+        totalCost: Math.round(totalCost * 100) / 100,
       };
-    }
+    })
+    .sort((a, b) => a.totalCost - b.totalCost);
+
+  const structured = {
+    input: { docs, queries, months },
+    estimates: embeddingModels,
+    recommendation: embeddingModels[0]?.model || getDefaultModel(),
+  };
+
+  const lines = embeddingModels.map(e =>
+    `• ${e.model}: embed $${e.embeddingCost} + $${e.monthlyCost}/mo queries = $${e.totalCost} total (${months}mo)`
+  );
+
+  return {
+    structuredContent: structured,
+    content: [{ type: 'text', text: `Cost estimate for ${docs.toLocaleString()} docs, ${queries.toLocaleString()} queries/mo over ${months} months:\n\n${lines.join('\n')}\n\nRecommended: ${structured.recommendation}` }],
+  };
+}
+
+/**
+ * Register utility tools: vai_topics, vai_explain, vai_estimate
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {object} schemas
+ */
+function registerUtilityTools(server, schemas) {
+  server.tool(
+    'vai_topics',
+    'List all available educational topics with summaries. Call this FIRST to discover what topics vai can explain — covers embeddings, vector search, RAG, reranking, model selection, multimodal, code generation, and more. Then use vai_explain to dive deep into any topic.',
+    schemas.topicsSchema,
+    handleVaiTopics
+  );
+
+  server.tool(
+    'vai_explain',
+    'Get a detailed explanation of a topic. Covers embeddings, vector search, RAG, MoE architecture, shared space, quantization, multimodal, reranking, and more. If the exact topic isn\'t found, suggests similar topics. Use vai_topics first to browse available topics.',
+    schemas.explainSchema,
+    handleVaiExplain
   );
 
-  // vai_estimate — cost estimation
   server.tool(
     'vai_estimate',
     'Estimate costs for Voyage AI embedding and query operations at various scales. Use when planning ingestion, budgeting, or comparing model costs.',
     schemas.estimateSchema,
-    async (input) => {
-      const { docs, queries, months } = input;
-      // Average tokens per doc chunk (~250 tokens)
-      const avgTokensPerDoc = 250;
-      const totalEmbedTokens = docs * avgTokensPerDoc;
-
-      const embeddingModels = MODEL_CATALOG
-        .filter(m => m.type === 'embedding' && !m.legacy && !m.unreleased && m.pricePerMToken)
-        .map(m => {
-          const embedCost = (totalEmbedTokens / 1_000_000) * m.pricePerMToken;
-          const queryCostPerMonth = queries > 0 ? (queries * avgTokensPerDoc / 1_000_000) * m.pricePerMToken : 0;
-          const totalCost = embedCost + (queryCostPerMonth * months);
-          return {
-            model: m.name,
-            pricePerMToken: m.pricePerMToken,
-            embeddingCost: Math.round(embedCost * 100) / 100,
-            monthlyCost: Math.round(queryCostPerMonth * 100) / 100,
-            totalCost: Math.round(totalCost * 100) / 100,
-          };
-        })
-        .sort((a, b) => a.totalCost - b.totalCost);
-
-      const structured = {
-        input: { docs, queries, months },
-        estimates: embeddingModels,
-        recommendation: embeddingModels[0]?.model || getDefaultModel(),
-      };
-
-      const lines = embeddingModels.map(e =>
-        `• ${e.model}: embed $${e.embeddingCost} + $${e.monthlyCost}/mo queries = $${e.totalCost} total (${months}mo)`
-      );
-
-      return {
-        structuredContent: structured,
-        content: [{ type: 'text', text: `Cost estimate for ${docs.toLocaleString()} docs, ${queries.toLocaleString()} queries/mo over ${months} months:\n\n${lines.join('\n')}\n\nRecommended: ${structured.recommendation}` }],
-      };
-    }
+    handleVaiEstimate
   );
 }
 
-module.exports = { registerUtilityTools };
+module.exports = { registerUtilityTools, handleVaiTopics, handleVaiExplain, handleVaiEstimate };