@librechat/agents 3.0.70 → 3.0.72

package/src/tools/ToolSearch.ts

@@ -1,5 +1,6 @@
 // src/tools/ToolSearch.ts
 import { z } from 'zod';
+import BM25 from 'okapibm25';
 import { config } from 'dotenv';
 import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
@@ -282,13 +283,101 @@ function simplifyParametersForSearch(
 }
 
 /**
- * Performs safe local substring search without regex.
- * Uses case-insensitive String.includes() for complete safety against ReDoS.
+ * Tokenizes a string into lowercase words for BM25.
+ * @param text - The text to tokenize
+ * @returns Array of lowercase tokens
+ */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length > 0);
+}
+
+/**
+ * Creates a searchable document string from tool metadata.
+ * @param tool - The tool metadata
+ * @param fields - Which fields to include
+ * @returns Combined document string for BM25
+ */
+function createToolDocument(tool: t.ToolMetadata, fields: string[]): string {
+  const parts: string[] = [];
+
+  if (fields.includes('name')) {
+    const baseName = tool.name.replace(/_/g, ' ');
+    parts.push(baseName, baseName);
+  }
+
+  if (fields.includes('description') && tool.description) {
+    parts.push(tool.description);
+  }
+
+  if (fields.includes('parameters') && tool.parameters?.properties) {
+    const paramNames = Object.keys(tool.parameters.properties).join(' ');
+    parts.push(paramNames);
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Determines which field had the best match for a query.
+ * @param tool - The tool to check
+ * @param queryTokens - Tokenized query
+ * @param fields - Fields to check
+ * @returns The matched field and a snippet
+ */
+function findMatchedField(
+  tool: t.ToolMetadata,
+  queryTokens: string[],
+  fields: string[]
+): { field: string; snippet: string } {
+  if (fields.includes('name')) {
+    const nameLower = tool.name.toLowerCase();
+    for (const token of queryTokens) {
+      if (nameLower.includes(token)) {
+        return { field: 'name', snippet: tool.name };
+      }
+    }
+  }
+
+  if (fields.includes('description') && tool.description) {
+    const descLower = tool.description.toLowerCase();
+    for (const token of queryTokens) {
+      if (descLower.includes(token)) {
+        return {
+          field: 'description',
+          snippet: tool.description.substring(0, 100),
+        };
+      }
+    }
+  }
+
+  if (fields.includes('parameters') && tool.parameters?.properties) {
+    const paramNames = Object.keys(tool.parameters.properties);
+    const paramLower = paramNames.join(' ').toLowerCase();
+    for (const token of queryTokens) {
+      if (paramLower.includes(token)) {
+        return { field: 'parameters', snippet: paramNames.join(', ') };
+      }
+    }
+  }
+
+  const fallbackSnippet = tool.description
+    ? tool.description.substring(0, 100)
+    : tool.name;
+  return { field: 'unknown', snippet: fallbackSnippet };
+}
+
+/**
+ * Performs BM25-based search for better relevance ranking.
+ * Uses Okapi BM25 algorithm for term frequency and document length normalization.
  * @param tools - Array of tool metadata to search
- * @param query - The search term (treated as literal substring)
+ * @param query - The search query
  * @param fields - Which fields to search
  * @param maxResults - Maximum results to return
- * @returns Search response with matching tools
+ * @returns Search response with matching tools ranked by BM25 score
  */
 function performLocalSearch(
   tools: t.ToolMetadata[],
@@ -296,50 +385,43 @@ function performLocalSearch(
   fields: string[],
   maxResults: number
 ): t.ToolSearchResponse {
-  const lowerQuery = query.toLowerCase();
-  const results: t.ToolSearchResult[] = [];
+  if (tools.length === 0 || !query.trim()) {
+    return {
+      tool_references: [],
+      total_tools_searched: tools.length,
+      pattern_used: query,
+    };
+  }
 
-  for (const tool of tools) {
-    let bestScore = 0;
-    let matchedField = '';
-    let snippet = '';
-
-    if (fields.includes('name')) {
-      const lowerName = tool.name.toLowerCase();
-      if (lowerName.includes(lowerQuery)) {
-        const isExactMatch = lowerName === lowerQuery;
-        const startsWithQuery = lowerName.startsWith(lowerQuery);
-        bestScore = isExactMatch ? 1.0 : startsWithQuery ? 0.95 : 0.85;
-        matchedField = 'name';
-        snippet = tool.name;
-      }
-    }
+  const documents = tools.map((tool) => createToolDocument(tool, fields));
+  const queryTokens = tokenize(query);
 
-    if (fields.includes('description') && tool.description) {
-      const lowerDesc = tool.description.toLowerCase();
-      if (lowerDesc.includes(lowerQuery) && bestScore === 0) {
-        bestScore = 0.7;
-        matchedField = 'description';
-        snippet = tool.description.substring(0, 100);
-      }
-    }
+  if (queryTokens.length === 0) {
+    return {
+      tool_references: [],
+      total_tools_searched: tools.length,
+      pattern_used: query,
+    };
+  }
 
-    if (fields.includes('parameters') && tool.parameters?.properties) {
-      const paramNames = Object.keys(tool.parameters.properties)
-        .join(' ')
-        .toLowerCase();
-      if (paramNames.includes(lowerQuery) && bestScore === 0) {
-        bestScore = 0.55;
-        matchedField = 'parameters';
-        snippet = Object.keys(tool.parameters.properties).join(' ');
-      }
-    }
+  const scores = BM25(documents, queryTokens, { k1: 1.5, b: 0.75 }) as number[];
+
+  const maxScore = Math.max(...scores.filter((s) => s > 0), 1);
+
+  const results: t.ToolSearchResult[] = [];
+  for (let i = 0; i < tools.length; i++) {
+    if (scores[i] > 0) {
+      const { field, snippet } = findMatchedField(
+        tools[i],
+        queryTokens,
+        fields
+      );
+      const normalizedScore = Math.min(scores[i] / maxScore, 1.0);
 
-    if (bestScore > 0) {
       results.push({
-        tool_name: tool.name,
-        match_score: bestScore,
-        matched_field: matchedField,
+        tool_name: tools[i].name,
+        match_score: normalizedScore,
+        matched_field: field,
         snippet,
       });
     }
@@ -501,6 +583,56 @@ function getBaseToolName(toolName: string): string {
   return toolName.substring(0, delimiterIndex);
 }
 
+/**
+ * Generates a compact listing of deferred tools grouped by server.
+ * Format: "server: tool1, tool2, tool3"
+ * Non-MCP tools are grouped under "other".
+ * @param toolRegistry - The tool registry
+ * @param onlyDeferred - Whether to only include deferred tools
+ * @returns Formatted string with tools grouped by server
+ */
+function getDeferredToolsListing(
+  toolRegistry: t.LCToolRegistry | undefined,
+  onlyDeferred: boolean
+): string {
+  if (!toolRegistry) {
+    return '';
+  }
+
+  const toolsByServer: Record<string, string[]> = {};
+
+  for (const lcTool of toolRegistry.values()) {
+    if (onlyDeferred && lcTool.defer_loading !== true) {
+      continue;
+    }
+
+    const toolName = lcTool.name;
+    const serverName = extractMcpServerName(toolName) ?? 'other';
+    const baseName = getBaseToolName(toolName);
+
+    if (!(serverName in toolsByServer)) {
+      toolsByServer[serverName] = [];
+    }
+    toolsByServer[serverName].push(baseName);
+  }
+
+  const serverNames = Object.keys(toolsByServer).sort((a, b) => {
+    if (a === 'other') return 1;
+    if (b === 'other') return -1;
+    return a.localeCompare(b);
+  });
+
+  if (serverNames.length === 0) {
+    return '';
+  }
+
+  const lines = serverNames.map(
+    (server) => `${server}: ${toolsByServer[server].join(', ')}`
+  );
+
+  return lines.join('\n');
+}
+
 /**
  * Formats a server listing response as structured JSON.
  * NOTE: This is a PREVIEW only - tools are NOT discovered/loaded.
@@ -609,46 +741,36 @@ function createToolSearch(
   const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();
   const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 
-  const availableServers = getAvailableMcpServers(
+  const deferredToolsListing = getDeferredToolsListing(
     initParams.toolRegistry,
     defaultOnlyDeferred
   );
 
-  const serverListText =
-    availableServers.length > 0
-      ? `\n- Available MCP servers: ${availableServers.join(', ')}`
-      : '';
+  const toolsListSection =
+    deferredToolsListing.length > 0
+      ? `
 
-  const mcpInstructions = `
+Deferred tools (search to load):
+${deferredToolsListing}`
+      : '';
 
-MCP Server Tools:
-- Tools from MCP servers follow the naming convention: toolName${Constants.MCP_DELIMITER}serverName
-- Example: "get_weather${Constants.MCP_DELIMITER}weather-api" is the "get_weather" tool from the "weather-api" server
-- Use mcp_server parameter to filter by server (e.g., mcp_server: "weather-api")
-- If mcp_server is provided without a query, lists ALL tools from that server${serverListText}`;
+  const mcpNote =
+    deferredToolsListing.includes(Constants.MCP_DELIMITER) ||
+    deferredToolsListing.split('\n').some((line) => !line.startsWith('other:'))
+      ? `
+- MCP tools use format: toolName${Constants.MCP_DELIMITER}serverName
+- Use mcp_server param to filter by server`
+      : '';
 
   const description =
     mode === 'local'
       ? `
-Searches through available tools to find ones matching your search term.
-
-Usage:
-- Provide a search term to find in tool names and descriptions.
-- Uses case-insensitive substring matching (fast and safe).
-- Use this when you need to discover tools for a specific task.
-- Results include tool names, match quality scores, and snippets showing where the match occurred.
-- Higher scores (0.95+) indicate name matches, medium scores (0.70+) indicate description matches.
-${mcpInstructions}
+Searches deferred tools using BM25 ranking. Multi-word queries supported.
+${mcpNote}${toolsListSection}
 `.trim()
       : `
-Searches through available tools to find ones matching your query pattern.
-
-Usage:
-- Provide a regex pattern to search tool names and descriptions.
-- Use this when you need to discover tools for a specific task.
-- Results include tool names, match quality scores, and snippets showing where the match occurred.
-- Higher scores (0.9+) indicate name matches, medium scores (0.7+) indicate description matches.
-${mcpInstructions}
+Searches deferred tools by regex pattern.
+${mcpNote}${toolsListSection}
 `.trim();
 
   return tool<typeof schema>(
@@ -879,6 +1001,7 @@ export {
   isFromAnyMcpServer,
   normalizeServerFilter,
   getAvailableMcpServers,
+  getDeferredToolsListing,
   getBaseToolName,
   formatServerListing,
   sanitizeRegex,

package/src/tools/__tests__/ToolSearch.test.ts

@@ -16,6 +16,7 @@ import {
   isFromAnyMcpServer,
   normalizeServerFilter,
   getAvailableMcpServers,
+  getDeferredToolsListing,
   getBaseToolName,
   formatServerListing,
 } from '../ToolSearch';
@@ -280,19 +281,21 @@ describe('ToolSearch', () => {
     ];
 
     it('finds tools by exact name match', () => {
-      const result = performLocalSearch(mockTools, 'get_weather', ['name'], 10);
+      // BM25 tokenizes "get weather" from "get_weather"
+      const result = performLocalSearch(mockTools, 'get weather', ['name'], 10);
 
-      expect(result.tool_references.length).toBe(1);
+      expect(result.tool_references.length).toBeGreaterThan(0);
       expect(result.tool_references[0].tool_name).toBe('get_weather');
-      expect(result.tool_references[0].match_score).toBe(1.0);
+      expect(result.tool_references[0].match_score).toBeGreaterThan(0.5);
       expect(result.tool_references[0].matched_field).toBe('name');
     });
 
-    it('finds tools by partial name match (starts with)', () => {
-      const result = performLocalSearch(mockTools, 'get_', ['name'], 10);
+    it('finds tools by partial name match', () => {
+      // BM25 finds tools containing "get" token
+      const result = performLocalSearch(mockTools, 'get', ['name'], 10);
 
       expect(result.tool_references.length).toBe(3);
-      expect(result.tool_references[0].match_score).toBe(0.95);
+      expect(result.tool_references[0].match_score).toBeGreaterThan(0);
       expect(result.tool_references.map((r) => r.tool_name)).toContain(
         'get_weather'
       );
@@ -314,7 +317,7 @@ describe('ToolSearch', () => {
       expect(result.tool_references.map((r) => r.tool_name)).toContain(
         'calculate_expense_totals'
       );
-      expect(result.tool_references[0].match_score).toBe(0.85);
+      expect(result.tool_references[0].match_score).toBeGreaterThan(0);
     });
 
     it('performs case-insensitive search', () => {
@@ -345,16 +348,16 @@ describe('ToolSearch', () => {
       expect(result.tool_references.length).toBe(1);
       expect(result.tool_references[0].tool_name).toBe('send_email');
       expect(result.tool_references[0].matched_field).toBe('description');
-      expect(result.tool_references[0].match_score).toBe(0.7);
+      expect(result.tool_references[0].match_score).toBeGreaterThan(0);
     });
 
     it('searches in parameter names', () => {
       const result = performLocalSearch(mockTools, 'query', ['parameters'], 10);
 
-      expect(result.tool_references.length).toBe(1);
+      expect(result.tool_references.length).toBeGreaterThan(0);
       expect(result.tool_references[0].tool_name).toBe('run_database_query');
       expect(result.tool_references[0].matched_field).toBe('parameters');
-      expect(result.tool_references[0].match_score).toBe(0.55);
+      expect(result.tool_references[0].match_score).toBeGreaterThan(0);
     });
 
     it('prioritizes name matches over description matches', () => {
@@ -423,7 +426,9 @@ describe('ToolSearch', () => {
     it('handles empty query gracefully', () => {
       const result = performLocalSearch(mockTools, '', ['name'], 10);
 
-      expect(result.tool_references.length).toBe(mockTools.length);
+      // BM25 correctly returns no results for empty queries (no terms to match)
+      expect(result.tool_references.length).toBe(0);
+      expect(result.total_tools_searched).toBe(mockTools.length);
     });
 
     it('includes correct metadata in response', () => {
@@ -650,6 +655,90 @@ describe('ToolSearch', () => {
     });
   });
 
+  describe('getDeferredToolsListing', () => {
+    const createRegistry = (): LCToolRegistry => {
+      const registry: LCToolRegistry = new Map();
+      registry.set('get_weather_mcp_weather-api', {
+        name: 'get_weather_mcp_weather-api',
+        description: 'Get weather',
+        defer_loading: true,
+      });
+      registry.set('get_forecast_mcp_weather-api', {
+        name: 'get_forecast_mcp_weather-api',
+        description: 'Get forecast',
+        defer_loading: true,
+      });
+      registry.set('send_email_mcp_gmail', {
+        name: 'send_email_mcp_gmail',
+        description: 'Send email',
+        defer_loading: true,
+      });
+      registry.set('execute_code', {
+        name: 'execute_code',
+        description: 'Execute code',
+        defer_loading: true,
+      });
+      registry.set('read_file', {
+        name: 'read_file',
+        description: 'Read file',
+        defer_loading: false,
+      });
+      return registry;
+    };
+
+    it('groups tools by server with format D', () => {
+      const registry = createRegistry();
+      const listing = getDeferredToolsListing(registry, true);
+
+      expect(listing).toContain('gmail: send_email');
+      expect(listing).toContain('weather-api: get_weather, get_forecast');
+      expect(listing).toContain('other: execute_code');
+    });
+
+    it('sorts servers alphabetically with other last', () => {
+      const registry = createRegistry();
+      const listing = getDeferredToolsListing(registry, true);
+      const lines = listing.split('\n');
+
+      expect(lines[0]).toMatch(/^gmail:/);
+      expect(lines[1]).toMatch(/^weather-api:/);
+      expect(lines[2]).toMatch(/^other:/);
+    });
+
+    it('uses base tool names without MCP suffix', () => {
+      const registry = createRegistry();
+      const listing = getDeferredToolsListing(registry, true);
+
+      expect(listing).toContain('get_weather');
+      expect(listing).not.toContain('get_weather_mcp_weather-api');
+    });
+
+    it('respects onlyDeferred flag', () => {
+      const registry = createRegistry();
+
+      const deferredOnly = getDeferredToolsListing(registry, true);
+      expect(deferredOnly).not.toContain('read_file');
+
+      const allTools = getDeferredToolsListing(registry, false);
+      expect(allTools).toContain('read_file');
+    });
+
+    it('returns empty string for undefined registry', () => {
+      expect(getDeferredToolsListing(undefined, true)).toBe('');
+    });
+
+    it('returns empty string for registry with no matching tools', () => {
+      const registry: LCToolRegistry = new Map();
+      registry.set('read_file', {
+        name: 'read_file',
+        description: 'Read file',
+        defer_loading: false,
+      });
+
+      expect(getDeferredToolsListing(registry, true)).toBe('');
+    });
+  });
+
   describe('performLocalSearch with MCP tools', () => {
     const mcpTools: ToolMetadata[] = [
       {
@@ -708,8 +797,9 @@ describe('ToolSearch', () => {
       );
     });
 
-    it('can search for tools by MCP delimiter', () => {
-      const result = performLocalSearch(mcpTools, '_mcp_', ['name'], 10);
+    it('can search for tools by MCP keyword', () => {
+      // BM25 tokenizes queries, so search for "mcp" to find MCP tools
+      const result = performLocalSearch(mcpTools, 'mcp', ['name'], 10);
 
       expect(result.tool_references.length).toBe(4);
       expect(result.tool_references.map((r) => r.tool_name)).not.toContain(