@librechat/agents 3.0.67 → 3.0.68

package/src/tools/ToolSearch.ts

@@ -22,11 +22,12 @@ const SEARCH_TIMEOUT = 5000;
 
 /** Zod schema type for tool search parameters */
 type ToolSearchSchema = z.ZodObject<{
-  query: z.ZodString;
+  query: z.ZodDefault<z.ZodOptional<z.ZodString>>;
   fields: z.ZodDefault<
     z.ZodOptional<z.ZodArray<z.ZodEnum<['name', 'description', 'parameters']>>>
   >;
   max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  mcp_server: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>>;
 }>;
 
 /**
@@ -37,11 +38,16 @@ type ToolSearchSchema = z.ZodObject<{
 function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {
   const queryDescription =
     mode === 'local'
-      ? 'Search term to find in tool names and descriptions. Case-insensitive substring matching.'
-      : 'Regex pattern to search tool names and descriptions. Special regex characters will be sanitized for safety.';
+      ? 'Search term to find in tool names and descriptions. Case-insensitive substring matching. Optional if mcp_server is provided.'
+      : 'Regex pattern to search tool names and descriptions. Optional if mcp_server is provided.';
 
   return z.object({
-    query: z.string().min(1).max(MAX_PATTERN_LENGTH).describe(queryDescription),
+    query: z
+      .string()
+      .max(MAX_PATTERN_LENGTH)
+      .optional()
+      .default('')
+      .describe(queryDescription),
     fields: z
       .array(z.enum(['name', 'description', 'parameters']))
       .optional()
@@ -55,9 +61,71 @@ function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {
       .optional()
       .default(10)
       .describe('Maximum number of matching tools to return'),
+    mcp_server: z
+      .union([z.string(), z.array(z.string())])
+      .optional()
+      .describe(
+        'Filter to tools from specific MCP server(s). Can be a single server name or array of names. If provided without a query, lists all tools from those servers.'
+      ),
   });
 }
 
+/**
+ * Extracts the MCP server name from a tool name.
+ * MCP tools follow the pattern: toolName_mcp_serverName
+ * @param toolName - The full tool name
+ * @returns The server name if it's an MCP tool, undefined otherwise
+ */
+function extractMcpServerName(toolName: string): string | undefined {
+  const delimiterIndex = toolName.indexOf(Constants.MCP_DELIMITER);
+  if (delimiterIndex === -1) {
+    return undefined;
+  }
+  return toolName.substring(delimiterIndex + Constants.MCP_DELIMITER.length);
+}
+
+/**
+ * Checks if a tool belongs to a specific MCP server.
+ * @param toolName - The full tool name
+ * @param serverName - The server name to match
+ * @returns True if the tool belongs to the specified server
+ */
+function isFromMcpServer(toolName: string, serverName: string): boolean {
+  const toolServer = extractMcpServerName(toolName);
+  return toolServer === serverName;
+}
+
+/**
+ * Checks if a tool belongs to any of the specified MCP servers.
+ * @param toolName - The full tool name
+ * @param serverNames - Array of server names to match
+ * @returns True if the tool belongs to any of the specified servers
+ */
+function isFromAnyMcpServer(toolName: string, serverNames: string[]): boolean {
+  const toolServer = extractMcpServerName(toolName);
+  if (toolServer === undefined) {
+    return false;
+  }
+  return serverNames.includes(toolServer);
+}
+
+/**
+ * Normalizes server filter input to always be an array.
+ * @param serverFilter - String, array of strings, or undefined
+ * @returns Array of server names (empty if none specified)
+ */
+function normalizeServerFilter(
+  serverFilter: string | string[] | undefined
+): string[] {
+  if (serverFilter === undefined) {
+    return [];
+  }
+  if (typeof serverFilter === 'string') {
+    return serverFilter === '' ? [] : [serverFilter];
+  }
+  return serverFilter.filter((s) => s !== '');
+}
+
 /**
  * Escapes special regex characters in a string to use as a literal pattern.
  * @param pattern - The string to escape
@@ -395,6 +463,78 @@ function formatSearchResults(searchResponse: t.ToolSearchResponse): string {
   return response;
 }
 
+/**
+ * Extracts the base tool name (without MCP server suffix) from a full tool name.
+ * @param toolName - The full tool name
+ * @returns The base tool name without server suffix
+ */
+function getBaseToolName(toolName: string): string {
+  const delimiterIndex = toolName.indexOf(Constants.MCP_DELIMITER);
+  if (delimiterIndex === -1) {
+    return toolName;
+  }
+  return toolName.substring(0, delimiterIndex);
+}
+
+/**
+ * Formats a server listing response when listing all tools from MCP server(s).
+ * Provides a cohesive view of all tools grouped by server.
+ * 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)
+ */
+function formatServerListing(
+  tools: t.ToolMetadata[],
+  serverNames: string | string[]
+): string {
+  const servers = Array.isArray(serverNames) ? serverNames : [serverNames];
+
+  if (tools.length === 0) {
+    return `No tools found from MCP server(s): ${servers.join(', ')}.`;
+  }
+
+  const toolsByServer = new Map<string, t.ToolMetadata[]>();
+  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';
+    }
+  }
+
+  response += `\n_To use a tool, search for it by name (e.g., query: "${getBaseToolName(tools[0]?.name ?? 'tool_name')}") to load it._`;
+
+  return response;
+}
+
 /**
  * Creates a Tool Search tool for discovering tools from a large registry.
  *
@@ -447,6 +587,14 @@ function createToolSearch(
   const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();
   const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 
+  const mcpInstructions = `
+
+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`;
+
   const description =
     mode === 'local'
       ? `
@@ -458,6 +606,7 @@ Usage:
 - 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}
 `.trim()
       : `
 Searches through available tools to find ones matching your query pattern.
@@ -467,6 +616,7 @@ Usage:
 - 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}
 `.trim();
 
   return tool<typeof schema>(
@@ -475,11 +625,13 @@ Usage:
         query,
         fields = ['name', 'description'],
         max_results = 10,
+        mcp_server,
       } = params;
 
       const {
         toolRegistry: paramToolRegistry,
         onlyDeferred: paramOnlyDeferred,
+        mcpServer: paramMcpServer,
       } = config.toolCall ?? {};
 
       const toolRegistry = paramToolRegistry ?? initParams.toolRegistry;
@@ -487,6 +639,10 @@ Usage:
         paramOnlyDeferred !== undefined
           ? paramOnlyDeferred
           : defaultOnlyDeferred;
+      const rawServerFilter =
+        mcp_server ?? paramMcpServer ?? initParams.mcpServer;
+      const serverFilters = normalizeServerFilter(rawServerFilter);
+      const hasServerFilter = serverFilters.length > 0;
 
       if (toolRegistry == null) {
         return [
@@ -504,9 +660,18 @@ Usage:
 
       const toolsArray: t.LCTool[] = Array.from(toolRegistry.values());
       const deferredTools: t.ToolMetadata[] = toolsArray
-        .filter((lcTool) =>
-          onlyDeferred === true ? lcTool.defer_loading === true : true
-        )
+        .filter((lcTool) => {
+          if (onlyDeferred === true && lcTool.defer_loading !== true) {
+            return false;
+          }
+          if (
+            hasServerFilter &&
+            !isFromAnyMcpServer(lcTool.name, serverFilters)
+          ) {
+            return false;
+          }
+          return true;
+        })
         .map((lcTool) => ({
           name: lcTool.name,
           description: lcTool.description ?? '',
@@ -514,11 +679,39 @@ Usage:
         }));
 
       if (deferredTools.length === 0) {
+        const serverMsg = hasServerFilter
+          ? ` from MCP server(s): ${serverFilters.join(', ')}`
+          : '';
         return [
-          'No tools available to search. The tool registry is empty or no deferred tools are registered.',
+          `No tools available to search${serverMsg}. The tool registry is empty or no matching deferred tools are registered.`,
           {
             tool_references: [],
-            metadata: { total_searched: 0, pattern: query },
+            metadata: {
+              total_searched: 0,
+              pattern: query,
+              mcp_server: serverFilters,
+            },
+          },
+        ];
+      }
+
+      const isServerListing = hasServerFilter && query === '';
+
+      if (isServerListing) {
+        const formattedOutput = formatServerListing(
+          deferredTools,
+          serverFilters
+        );
+
+        return [
+          formattedOutput,
+          {
+            tool_references: [],
+            metadata: {
+              total_available: deferredTools.length,
+              mcp_server: serverFilters,
+              listing_mode: true,
+            },
           },
         ];
       }
@@ -539,6 +732,7 @@ Usage:
             metadata: {
               total_searched: searchResponse.total_tools_searched,
               pattern: searchResponse.pattern_used,
+              mcp_server: serverFilters.length > 0 ? serverFilters : undefined,
             },
           },
         ];
@@ -648,6 +842,12 @@ Usage:
 export {
   createToolSearch,
   performLocalSearch,
+  extractMcpServerName,
+  isFromMcpServer,
+  isFromAnyMcpServer,
+  normalizeServerFilter,
+  getBaseToolName,
+  formatServerListing,
   sanitizeRegex,
   escapeRegexSpecialChars,
   isDangerousPattern,

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

@@ -1,6 +1,6 @@
 // src/tools/__tests__/ToolSearch.test.ts
 /**
- * Unit tests for Tool Search Regex.
+ * Unit tests for Tool Search.
  * Tests helper functions and sanitization logic without hitting the API.
  */
 import { describe, it, expect } from '@jest/globals';
@@ -11,6 +11,12 @@ import {
   countNestedGroups,
   hasNestedQuantifiers,
   performLocalSearch,
+  extractMcpServerName,
+  isFromMcpServer,
+  isFromAnyMcpServer,
+  normalizeServerFilter,
+  getBaseToolName,
+  formatServerListing,
 } from '../ToolSearch';
 import type { ToolMetadata } from '@/types';
 
@@ -438,4 +444,291 @@ describe('ToolSearch', () => {
       expect(result.tool_references[0].snippet.length).toBeGreaterThan(0);
     });
   });
+
+  describe('extractMcpServerName', () => {
+    it('extracts server name from MCP tool name', () => {
+      expect(extractMcpServerName('get_weather_mcp_weather-server')).toBe(
+        'weather-server'
+      );
+      expect(extractMcpServerName('send_email_mcp_gmail')).toBe('gmail');
+      expect(extractMcpServerName('query_database_mcp_postgres-mcp')).toBe(
+        'postgres-mcp'
+      );
+    });
+
+    it('returns undefined for non-MCP tools', () => {
+      expect(extractMcpServerName('get_weather')).toBeUndefined();
+      expect(extractMcpServerName('send_email')).toBeUndefined();
+      expect(extractMcpServerName('regular_tool_name')).toBeUndefined();
+    });
+
+    it('handles edge cases', () => {
+      expect(extractMcpServerName('_mcp_server')).toBe('server');
+      expect(extractMcpServerName('tool_mcp_')).toBe('');
+    });
+  });
+
+  describe('getBaseToolName', () => {
+    it('extracts base name from MCP tool name', () => {
+      expect(getBaseToolName('get_weather_mcp_weather-server')).toBe(
+        'get_weather'
+      );
+      expect(getBaseToolName('send_email_mcp_gmail')).toBe('send_email');
+    });
+
+    it('returns full name for non-MCP tools', () => {
+      expect(getBaseToolName('get_weather')).toBe('get_weather');
+      expect(getBaseToolName('regular_tool')).toBe('regular_tool');
+    });
+  });
+
+  describe('isFromMcpServer', () => {
+    it('returns true for matching MCP server', () => {
+      expect(
+        isFromMcpServer('get_weather_mcp_weather-server', 'weather-server')
+      ).toBe(true);
+      expect(isFromMcpServer('send_email_mcp_gmail', 'gmail')).toBe(true);
+    });
+
+    it('returns false for non-matching MCP server', () => {
+      expect(
+        isFromMcpServer('get_weather_mcp_weather-server', 'other-server')
+      ).toBe(false);
+      expect(isFromMcpServer('send_email_mcp_gmail', 'outlook')).toBe(false);
+    });
+
+    it('returns false for non-MCP tools', () => {
+      expect(isFromMcpServer('get_weather', 'weather-server')).toBe(false);
+      expect(isFromMcpServer('regular_tool', 'any-server')).toBe(false);
+    });
+  });
+
+  describe('isFromAnyMcpServer', () => {
+    it('returns true if tool is from any of the specified servers', () => {
+      expect(
+        isFromAnyMcpServer('get_weather_mcp_weather-api', [
+          'weather-api',
+          'gmail',
+        ])
+      ).toBe(true);
+      expect(
+        isFromAnyMcpServer('send_email_mcp_gmail', ['weather-api', 'gmail'])
+      ).toBe(true);
+    });
+
+    it('returns false if tool is not from any specified server', () => {
+      expect(
+        isFromAnyMcpServer('get_weather_mcp_weather-api', ['gmail', 'slack'])
+      ).toBe(false);
+    });
+
+    it('returns false for non-MCP tools', () => {
+      expect(isFromAnyMcpServer('regular_tool', ['weather-api', 'gmail'])).toBe(
+        false
+      );
+    });
+
+    it('returns false for empty server list', () => {
+      expect(isFromAnyMcpServer('get_weather_mcp_weather-api', [])).toBe(false);
+    });
+  });
+
+  describe('normalizeServerFilter', () => {
+    it('converts string to single-element array', () => {
+      expect(normalizeServerFilter('gmail')).toEqual(['gmail']);
+    });
+
+    it('passes through arrays unchanged', () => {
+      expect(normalizeServerFilter(['gmail', 'slack'])).toEqual([
+        'gmail',
+        'slack',
+      ]);
+    });
+
+    it('returns empty array for undefined', () => {
+      expect(normalizeServerFilter(undefined)).toEqual([]);
+    });
+
+    it('returns empty array for empty string', () => {
+      expect(normalizeServerFilter('')).toEqual([]);
+    });
+
+    it('filters out empty strings from arrays', () => {
+      expect(normalizeServerFilter(['gmail', '', 'slack'])).toEqual([
+        'gmail',
+        'slack',
+      ]);
+    });
+  });
+
+  describe('performLocalSearch with MCP tools', () => {
+    const mcpTools: ToolMetadata[] = [
+      {
+        name: 'get_weather_mcp_weather-server',
+        description: 'Get weather from MCP server',
+        parameters: undefined,
+      },
+      {
+        name: 'get_forecast_mcp_weather-server',
+        description: 'Get forecast from MCP server',
+        parameters: undefined,
+      },
+      {
+        name: 'send_email_mcp_gmail',
+        description: 'Send email via Gmail MCP',
+        parameters: undefined,
+      },
+      {
+        name: 'read_inbox_mcp_gmail',
+        description: 'Read inbox via Gmail MCP',
+        parameters: undefined,
+      },
+      {
+        name: 'get_weather',
+        description: 'Regular weather tool (not MCP)',
+        parameters: undefined,
+      },
+    ];
+
+    it('searches across all tools including MCP tools', () => {
+      const result = performLocalSearch(
+        mcpTools,
+        'weather',
+        ['name', 'description'],
+        10
+      );
+
+      expect(result.tool_references.length).toBe(3);
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_weather_mcp_weather-server'
+      );
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'get_weather'
+      );
+    });
+
+    it('finds MCP tools by searching the full name including server suffix', () => {
+      const result = performLocalSearch(mcpTools, 'gmail', ['name'], 10);
+
+      expect(result.tool_references.length).toBe(2);
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'send_email_mcp_gmail'
+      );
+      expect(result.tool_references.map((r) => r.tool_name)).toContain(
+        'read_inbox_mcp_gmail'
+      );
+    });
+
+    it('can search for tools by MCP delimiter', () => {
+      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(
+        'get_weather'
+      );
+    });
+  });
+
+  describe('formatServerListing', () => {
+    const serverTools: ToolMetadata[] = [
+      {
+        name: 'get_weather_mcp_weather-api',
+        description: 'Get current weather conditions for a location',
+        parameters: undefined,
+      },
+      {
+        name: 'get_forecast_mcp_weather-api',
+        description: 'Get weather forecast for the next 7 days',
+        parameters: undefined,
+      },
+    ];
+
+    it('formats server listing with tool names and descriptions', () => {
+      const result = formatServerListing(serverTools, 'weather-api');
+
+      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');
+    });
+
+    it('includes hint to search for specific tool to load it', () => {
+      const result = formatServerListing(serverTools, 'weather-api');
+
+      expect(result).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');
+
+      expect(result).toContain('**get_weather**');
+      expect(result).not.toContain('**get_weather_mcp_weather-api**');
+    });
+
+    it('handles empty tools array', () => {
+      const result = formatServerListing([], 'empty-server');
+
+      expect(result).toContain('No tools found');
+      expect(result).toContain('empty-server');
+    });
+
+    it('truncates long descriptions', () => {
+      const toolsWithLongDesc: ToolMetadata[] = [
+        {
+          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.',
+          parameters: undefined,
+        },
+      ];
+
+      const result = formatServerListing(toolsWithLongDesc, 'server');
+
+      expect(result).toContain('...');
+      expect(result.length).toBeLessThan(
+        toolsWithLongDesc[0].description.length + 200
+      );
+    });
+
+    it('handles multiple servers with grouped output', () => {
+      const multiServerTools: ToolMetadata[] = [
+        {
+          name: 'get_weather_mcp_weather-api',
+          description: 'Get weather',
+          parameters: undefined,
+        },
+        {
+          name: 'send_email_mcp_gmail',
+          description: 'Send email',
+          parameters: undefined,
+        },
+        {
+          name: 'read_inbox_mcp_gmail',
+          description: 'Read inbox',
+          parameters: undefined,
+        },
+      ];
+
+      const result = formatServerListing(multiServerTools, [
+        'weather-api',
+        'gmail',
+      ]);
+
+      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');
+    });
+
+    it('accepts single server as array', () => {
+      const result = formatServerListing(serverTools, ['weather-api']);
+
+      expect(result).toContain('Tools from MCP server: weather-api');
+      expect(result).not.toContain('###');
+    });
+  });
 });

package/src/types/tools.ts

@@ -131,7 +131,7 @@ export type ProgrammaticCache = { toolMap: ToolMap; toolDefs: LCTool[] };
 /** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
 export type ToolSearchMode = 'code_interpreter' | 'local';
 
-/** Parameters for creating a Tool Search Regex tool */
+/** Parameters for creating a Tool Search tool */
 export type ToolSearchParams = {
   apiKey?: string;
   toolRegistry?: LCToolRegistry;
@@ -139,6 +139,8 @@ export type ToolSearchParams = {
   baseUrl?: string;
   /** Search mode: 'code_interpreter' (default) uses sandbox for regex, 'local' uses safe substring matching */
   mode?: ToolSearchMode;
+  /** Filter tools to only those from specific MCP server(s). Can be a single name or array of names. */
+  mcpServer?: string | string[];
   [key: string]: unknown;
 };