@librechat/agents 3.0.69 → 3.0.71

package/src/tools/ToolSearch.ts

@@ -465,30 +465,27 @@ function parseSearchResults(stdout: string): t.ToolSearchResponse {
 }
 
 /**
- * Formats search results into a human-readable string.
+ * Formats search results as structured JSON for efficient parsing.
  * @param searchResponse - The parsed search response
- * @returns Formatted string for LLM consumption
+ * @returns JSON string with search results
  */
 function formatSearchResults(searchResponse: t.ToolSearchResponse): string {
   const { tool_references, total_tools_searched, pattern_used } =
     searchResponse;
 
-  if (tool_references.length === 0) {
-    return `No tools matched the pattern "${pattern_used}".\nTotal tools searched: ${total_tools_searched}`;
-  }
-
-  let response = `Found ${tool_references.length} matching tools:\n\n`;
-
-  for (const ref of tool_references) {
-    response += `- ${ref.tool_name} (score: ${ref.match_score.toFixed(2)})\n`;
-    response += `  Matched in: ${ref.matched_field}\n`;
-    response += `  Snippet: ${ref.snippet}\n\n`;
-  }
-
-  response += `Total tools searched: ${total_tools_searched}\n`;
-  response += `Pattern used: ${pattern_used}`;
+  const output = {
+    found: tool_references.length,
+    tools: tool_references.map((ref) => ({
+      name: ref.tool_name,
+      score: Number(ref.match_score.toFixed(2)),
+      matched_in: ref.matched_field,
+      snippet: ref.snippet,
+    })),
+    total_searched: total_tools_searched,
+    query: pattern_used,
+  };
 
-  return response;
+  return JSON.stringify(output, null, 2);
 }
 
 /**
@@ -505,12 +502,61 @@ function getBaseToolName(toolName: string): string {
 }
 
 /**
- * Formats a server listing response when listing all tools from MCP server(s).
- * Provides a cohesive view of all tools grouped by server.
+ * 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.
  * @param tools - Array of tool metadata from the server(s)
  * @param serverNames - The MCP server name(s)
- * @returns Formatted string showing all tools from the server(s)
+ * @returns JSON string showing all tools grouped by server
  */
 function formatServerListing(
   tools: t.ToolMetadata[],
@@ -519,48 +565,46 @@ function formatServerListing(
   const servers = Array.isArray(serverNames) ? serverNames : [serverNames];
 
   if (tools.length === 0) {
-    return `No tools found from MCP server(s): ${servers.join(', ')}.`;
+    return JSON.stringify(
+      {
+        listing_mode: true,
+        servers,
+        total_tools: 0,
+        tools_by_server: {},
+        hint: 'No tools found from the specified MCP server(s).',
+      },
+      null,
+      2
+    );
   }
 
-  const toolsByServer = new Map<string, t.ToolMetadata[]>();
+  const toolsByServer: Record<
+    string,
+    Array<{ name: string; description: string }>
+  > = {};
   for (const tool of tools) {
     const server = extractMcpServerName(tool.name) ?? 'unknown';
-    const existing = toolsByServer.get(server) ?? [];
-    existing.push(tool);
-    toolsByServer.set(server, existing);
-  }
-
-  let response =
-    servers.length === 1
-      ? `## Tools from MCP server: ${servers[0]}\n\n`
-      : `## Tools from MCP servers: ${servers.join(', ')}\n\n`;
-
-  response += `Found ${tools.length} tool(s) (preview only - not yet loaded):\n\n`;
-
-  for (const [server, serverTools] of toolsByServer) {
-    if (servers.length > 1) {
-      response += `### ${server}\n\n`;
-    }
-    for (const tool of serverTools) {
-      const baseName = getBaseToolName(tool.name);
-      response += `- **${baseName}**`;
-      if (tool.description) {
-        const shortDesc =
-          tool.description.length > 80
-            ? tool.description.substring(0, 77) + '...'
-            : tool.description;
-        response += `: ${shortDesc}`;
-      }
-      response += '\n';
-    }
-    if (servers.length > 1) {
-      response += '\n';
+    if (!(server in toolsByServer)) {
+      toolsByServer[server] = [];
     }
+    toolsByServer[server].push({
+      name: getBaseToolName(tool.name),
+      description:
+        tool.description.length > 100
+          ? tool.description.substring(0, 97) + '...'
+          : tool.description,
+    });
   }
 
-  response += `\n_To use a tool, search for it by name (e.g., query: "${getBaseToolName(tools[0]?.name ?? 'tool_name')}") to load it._`;
+  const output = {
+    listing_mode: true,
+    servers,
+    total_tools: tools.length,
+    tools_by_server: toolsByServer,
+    hint: `To use a tool, search for it by name (e.g., query: "${getBaseToolName(tools[0]?.name ?? 'tool_name')}") to load it.`,
+  };
 
-  return response;
+  return JSON.stringify(output, null, 2);
 }
 
 /**
@@ -615,46 +659,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 by name/description. Case-insensitive substring matching.
+${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>(
@@ -885,6 +919,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';
@@ -650,6 +651,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[] = [
       {
@@ -732,34 +817,41 @@ describe('ToolSearch', () => {
       },
     ];
 
-    it('formats server listing with tool names and descriptions', () => {
+    it('returns valid JSON with tool listing', () => {
       const result = formatServerListing(serverTools, 'weather-api');
+      const parsed = JSON.parse(result);
 
-      expect(result).toContain('Tools from MCP server: weather-api');
-      expect(result).toContain('2 tool(s)');
-      expect(result).toContain('get_weather');
-      expect(result).toContain('get_forecast');
-      expect(result).toContain('preview only');
+      expect(parsed.listing_mode).toBe(true);
+      expect(parsed.servers).toEqual(['weather-api']);
+      expect(parsed.total_tools).toBe(2);
+      expect(parsed.tools_by_server['weather-api']).toHaveLength(2);
     });
 
     it('includes hint to search for specific tool to load it', () => {
       const result = formatServerListing(serverTools, 'weather-api');
+      const parsed = JSON.parse(result);
 
-      expect(result).toContain('To use a tool, search for it by name');
+      expect(parsed.hint).toContain('To use a tool, search for it by name');
     });
 
     it('uses base tool name (without MCP suffix) in display', () => {
       const result = formatServerListing(serverTools, 'weather-api');
+      const parsed = JSON.parse(result);
 
-      expect(result).toContain('**get_weather**');
-      expect(result).not.toContain('**get_weather_mcp_weather-api**');
+      const toolNames = parsed.tools_by_server['weather-api'].map(
+        (t: { name: string }) => t.name
+      );
+      expect(toolNames).toContain('get_weather');
+      expect(toolNames).not.toContain('get_weather_mcp_weather-api');
     });
 
     it('handles empty tools array', () => {
       const result = formatServerListing([], 'empty-server');
+      const parsed = JSON.parse(result);
 
-      expect(result).toContain('No tools found');
-      expect(result).toContain('empty-server');
+      expect(parsed.total_tools).toBe(0);
+      expect(parsed.servers).toContain('empty-server');
+      expect(parsed.hint).toContain('No tools found');
     });
 
     it('truncates long descriptions', () => {
@@ -767,17 +859,17 @@ describe('ToolSearch', () => {
         {
           name: 'long_tool_mcp_server',
           description:
-            'This is a very long description that exceeds 80 characters and should be truncated to keep the listing compact and readable.',
+            'This is a very long description that exceeds 100 characters and should be truncated to keep the listing compact and readable for the LLM.',
           parameters: undefined,
         },
       ];
 
       const result = formatServerListing(toolsWithLongDesc, 'server');
+      const parsed = JSON.parse(result);
 
-      expect(result).toContain('...');
-      expect(result.length).toBeLessThan(
-        toolsWithLongDesc[0].description.length + 200
-      );
+      const toolDesc = parsed.tools_by_server['server'][0].description;
+      expect(toolDesc).toContain('...');
+      expect(toolDesc.length).toBeLessThanOrEqual(100);
     });
 
     it('handles multiple servers with grouped output', () => {
@@ -803,21 +895,20 @@ describe('ToolSearch', () => {
         'weather-api',
         'gmail',
       ]);
+      const parsed = JSON.parse(result);
 
-      expect(result).toContain('Tools from MCP servers: weather-api, gmail');
-      expect(result).toContain('3 tool(s)');
-      expect(result).toContain('### weather-api');
-      expect(result).toContain('### gmail');
-      expect(result).toContain('get_weather');
-      expect(result).toContain('send_email');
-      expect(result).toContain('read_inbox');
+      expect(parsed.servers).toEqual(['weather-api', 'gmail']);
+      expect(parsed.total_tools).toBe(3);
+      expect(parsed.tools_by_server['weather-api']).toHaveLength(1);
+      expect(parsed.tools_by_server['gmail']).toHaveLength(2);
     });
 
     it('accepts single server as array', () => {
       const result = formatServerListing(serverTools, ['weather-api']);
+      const parsed = JSON.parse(result);
 
-      expect(result).toContain('Tools from MCP server: weather-api');
-      expect(result).not.toContain('###');
+      expect(parsed.servers).toEqual(['weather-api']);
+      expect(parsed.tools_by_server['weather-api']).toBeDefined();
     });
   });
 });