@librechat/agents 3.0.66 → 3.0.68

package/src/tools/{ToolSearchRegex.ts → ToolSearch.ts}

@@ -1,4 +1,4 @@
-// src/tools/ToolSearchRegex.ts
+// src/tools/ToolSearch.ts
 import { z } from 'zod';
 import { config } from 'dotenv';
 import fetch, { RequestInit } from 'node-fetch';
@@ -20,28 +20,111 @@ const MAX_REGEX_COMPLEXITY = 5;
 /** Default search timeout in milliseconds */
 const SEARCH_TIMEOUT = 5000;
 
-const ToolSearchRegexSchema = z.object({
-  query: z
-    .string()
-    .min(1)
-    .max(MAX_PATTERN_LENGTH)
-    .describe(
-      'Regex pattern to search tool names and descriptions. Special regex characters will be sanitized for safety.'
-    ),
-  fields: z
-    .array(z.enum(['name', 'description', 'parameters']))
-    .optional()
-    .default(['name', 'description'])
-    .describe('Which fields to search. Default: name and description'),
-  max_results: z
-    .number()
-    .int()
-    .min(1)
-    .max(50)
-    .optional()
-    .default(10)
-    .describe('Maximum number of matching tools to return'),
-});
+/** Zod schema type for tool search parameters */
+type ToolSearchSchema = z.ZodObject<{
+  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>]>>;
+}>;
+
+/**
+ * Creates the Zod schema with dynamic query description based on mode.
+ * @param mode - The search mode determining query interpretation
+ * @returns Zod schema for tool search parameters
+ */
+function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema {
+  const queryDescription =
+    mode === 'local'
+      ? '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()
+      .max(MAX_PATTERN_LENGTH)
+      .optional()
+      .default('')
+      .describe(queryDescription),
+    fields: z
+      .array(z.enum(['name', 'description', 'parameters']))
+      .optional()
+      .default(['name', 'description'])
+      .describe('Which fields to search. Default: name and description'),
+    max_results: z
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .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.
@@ -170,6 +253,80 @@ function simplifyParametersForSearch(
   return { type: parameters.type };
 }
 
+/**
+ * Performs safe local substring search without regex.
+ * Uses case-insensitive String.includes() for complete safety against ReDoS.
+ * @param tools - Array of tool metadata to search
+ * @param query - The search term (treated as literal substring)
+ * @param fields - Which fields to search
+ * @param maxResults - Maximum results to return
+ * @returns Search response with matching tools
+ */
+function performLocalSearch(
+  tools: t.ToolMetadata[],
+  query: string,
+  fields: string[],
+  maxResults: number
+): t.ToolSearchResponse {
+  const lowerQuery = query.toLowerCase();
+  const results: t.ToolSearchResult[] = [];
+
+  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;
+      }
+    }
+
+    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 (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(' ');
+      }
+    }
+
+    if (bestScore > 0) {
+      results.push({
+        tool_name: tool.name,
+        match_score: bestScore,
+        matched_field: matchedField,
+        snippet,
+      });
+    }
+  }
+
+  results.sort((a, b) => b.match_score - a.match_score);
+  const topResults = results.slice(0, maxResults);
+
+  return {
+    tool_references: topResults,
+    total_tools_searched: tools.length,
+    pattern_used: query,
+  };
+}
+
 /**
  * Generates the JavaScript search script to be executed in the sandbox.
  * Uses plain JavaScript for maximum compatibility with the Code API.
@@ -307,11 +464,87 @@ function formatSearchResults(searchResponse: t.ToolSearchResponse): string {
 }
 
 /**
- * Creates a Tool Search Regex tool for discovering tools from a large registry.
+ * 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.
  *
  * This tool enables AI agents to dynamically discover tools from a large library
  * without loading all tool definitions into the LLM context window. The agent
- * can search for relevant tools on-demand using regex patterns.
+ * can search for relevant tools on-demand.
+ *
+ * **Modes:**
+ * - `code_interpreter` (default): Uses external sandbox for regex search. Safer for complex patterns.
+ * - `local`: Uses safe substring matching locally. No network call, faster, completely safe from ReDoS.
  *
  * The tool registry can be provided either:
  * 1. At initialization time via params.toolRegistry
@@ -321,36 +554,61 @@ function formatSearchResults(searchResponse: t.ToolSearchResponse): string {
  * @returns A LangChain DynamicStructuredTool for tool searching
  *
  * @example
- * // Option 1: Registry at initialization
- * const tool = createToolSearchRegexTool({ apiKey, toolRegistry });
- * await tool.invoke({ query: 'expense' });
+ * // Option 1: Code interpreter mode (regex via sandbox)
+ * const tool = createToolSearch({ apiKey, toolRegistry });
+ * await tool.invoke({ query: 'expense.*report' });
  *
  * @example
- * // Option 2: Registry at runtime
- * const tool = createToolSearchRegexTool({ apiKey });
- * await tool.invoke(
- *   { query: 'expense' },
- *   { configurable: { toolRegistry, onlyDeferred: true } }
- * );
+ * // Option 2: Local mode (safe substring search, no API key needed)
+ * const tool = createToolSearch({ mode: 'local', toolRegistry });
+ * await tool.invoke({ query: 'expense' });
  */
-function createToolSearchRegexTool(
-  initParams: t.ToolSearchRegexParams = {}
-): DynamicStructuredTool<typeof ToolSearchRegexSchema> {
-  const apiKey: string =
-    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??
-    initParams.apiKey ??
-    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
-    '';
+function createToolSearch(
+  initParams: t.ToolSearchParams = {}
+): DynamicStructuredTool<ReturnType<typeof createToolSearchSchema>> {
+  const mode: t.ToolSearchMode = initParams.mode ?? 'code_interpreter';
+  const defaultOnlyDeferred = initParams.onlyDeferred ?? true;
+  const schema = createToolSearchSchema(mode);
 
-  if (!apiKey) {
-    throw new Error('No API key provided for tool search regex tool.');
+  const apiKey: string =
+    mode === 'code_interpreter'
+      ? ((initParams[EnvVar.CODE_API_KEY] as string | undefined) ??
+        initParams.apiKey ??
+        getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
+        '')
+      : '';
+
+  if (mode === 'code_interpreter' && !apiKey) {
+    throw new Error(
+      'No API key provided for tool search in code_interpreter mode. Use mode: "local" to search without an API key.'
+    );
   }
 
   const baseEndpoint = initParams.baseUrl ?? getCodeBaseURL();
   const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
-  const defaultOnlyDeferred = initParams.onlyDeferred ?? true;
 
-  const description = `
+  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'
+      ? `
+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}
+`.trim()
+      : `
 Searches through available tools to find ones matching your query pattern.
 
 Usage:
@@ -358,45 +616,42 @@ 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 ToolSearchRegexSchema>(
+  return tool<typeof schema>(
     async (params, config) => {
       const {
         query,
         fields = ['name', 'description'],
         max_results = 10,
+        mcp_server,
       } = params;
 
-      // Extra params injected by ToolNode (follows web_search pattern)
       const {
         toolRegistry: paramToolRegistry,
         onlyDeferred: paramOnlyDeferred,
+        mcpServer: paramMcpServer,
       } = config.toolCall ?? {};
 
-      const { safe: sanitizedPattern, wasEscaped } = sanitizeRegex(query);
-
-      let warningMessage = '';
-      if (wasEscaped) {
-        warningMessage =
-          'Note: The provided pattern was converted to a literal search for safety.\n\n';
-      }
-
-      // Priority: ToolNode injection (via config.toolCall) > initialization params
       const toolRegistry = paramToolRegistry ?? initParams.toolRegistry;
       const onlyDeferred =
         paramOnlyDeferred !== undefined
           ? paramOnlyDeferred
           : defaultOnlyDeferred;
+      const rawServerFilter =
+        mcp_server ?? paramMcpServer ?? initParams.mcpServer;
+      const serverFilters = normalizeServerFilter(rawServerFilter);
+      const hasServerFilter = serverFilters.length > 0;
 
       if (toolRegistry == null) {
         return [
-          `${warningMessage}Error: No tool registry provided. Configure toolRegistry at agent level or initialization.`,
+          'Error: No tool registry provided. Configure toolRegistry at agent level or initialization.',
           {
             tool_references: [],
             metadata: {
               total_searched: 0,
-              pattern: sanitizedPattern,
+              pattern: query,
               error: 'No tool registry provided',
             },
           },
@@ -404,11 +659,16 @@ Usage:
       }
 
       const toolsArray: t.LCTool[] = Array.from(toolRegistry.values());
-
       const deferredTools: t.ToolMetadata[] = toolsArray
         .filter((lcTool) => {
-          if (onlyDeferred === true) {
-            return lcTool.defer_loading === true;
+          if (onlyDeferred === true && lcTool.defer_loading !== true) {
+            return false;
+          }
+          if (
+            hasServerFilter &&
+            !isFromAnyMcpServer(lcTool.name, serverFilters)
+          ) {
+            return false;
           }
           return true;
         })
@@ -419,18 +679,72 @@ Usage:
         }));
 
       if (deferredTools.length === 0) {
+        const serverMsg = hasServerFilter
+          ? ` from MCP server(s): ${serverFilters.join(', ')}`
+          : '';
         return [
-          `${warningMessage}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: sanitizedPattern,
+              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,
+            },
+          },
+        ];
+      }
+
+      if (mode === 'local') {
+        const searchResponse = performLocalSearch(
+          deferredTools,
+          query,
+          fields,
+          max_results
+        );
+        const formattedOutput = formatSearchResults(searchResponse);
+
+        return [
+          formattedOutput,
+          {
+            tool_references: searchResponse.tool_references,
+            metadata: {
+              total_searched: searchResponse.total_tools_searched,
+              pattern: searchResponse.pattern_used,
+              mcp_server: serverFilters.length > 0 ? serverFilters : undefined,
+            },
+          },
+        ];
+      }
+
+      const { safe: sanitizedPattern, wasEscaped } = sanitizeRegex(query);
+      let warningMessage = '';
+      if (wasEscaped) {
+        warningMessage =
+          'Note: The provided pattern was converted to a literal search for safety.\n\n';
+      }
+
       const searchScript = generateSearchScript(
         deferredTools,
         fields,
@@ -468,7 +782,7 @@ Usage:
 
         if (result.stderr && result.stderr.trim()) {
           // eslint-disable-next-line no-console
-          console.warn('[ToolSearchRegex] stderr:', result.stderr);
+          console.warn('[ToolSearch] stderr:', result.stderr);
         }
 
         if (!result.stdout || !result.stdout.trim()) {
@@ -499,7 +813,7 @@ Usage:
         ];
       } catch (error) {
         // eslint-disable-next-line no-console
-        console.error('[ToolSearchRegex] Error:', error);
+        console.error('[ToolSearch] Error:', error);
 
         const errorMessage =
           error instanceof Error ? error.message : String(error);
@@ -517,16 +831,23 @@ Usage:
       }
     },
     {
-      name: Constants.TOOL_SEARCH_REGEX,
+      name: Constants.TOOL_SEARCH,
       description,
-      schema: ToolSearchRegexSchema,
+      schema,
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );
 }
 
 export {
-  createToolSearchRegexTool,
+  createToolSearch,
+  performLocalSearch,
+  extractMcpServerName,
+  isFromMcpServer,
+  isFromAnyMcpServer,
+  normalizeServerFilter,
+  getBaseToolName,
+  formatServerListing,
   sanitizeRegex,
   escapeRegexSpecialChars,
   isDangerousPattern,

package/src/tools/__tests__/{ToolSearchRegex.integration.test.ts → ToolSearch.integration.test.ts}

@@ -1,19 +1,19 @@
-// src/tools/__tests__/ToolSearchRegex.integration.test.ts
+// src/tools/__tests__/ToolSearch.integration.test.ts
 /**
  * Integration tests for Tool Search Regex.
  * These tests hit the LIVE Code API and verify end-to-end search functionality.
  *
- * Run with: npm test -- ToolSearchRegex.integration.test.ts
+ * Run with: npm test -- ToolSearch.integration.test.ts
  */
 import { config as dotenvConfig } from 'dotenv';
 dotenvConfig();
 
 import { describe, it, expect, beforeAll } from '@jest/globals';
-import { createToolSearchRegexTool } from '../ToolSearchRegex';
+import { createToolSearch } from '../ToolSearch';
 import { createToolSearchToolRegistry } from '@/test/mockTools';
 
-describe('ToolSearchRegex - Live API Integration', () => {
-  let searchTool: ReturnType<typeof createToolSearchRegexTool>;
+describe('ToolSearch - Live API Integration', () => {
+  let searchTool: ReturnType<typeof createToolSearch>;
   const toolRegistry = createToolSearchToolRegistry();
 
   beforeAll(() => {
@@ -24,7 +24,7 @@ describe('ToolSearchRegex - Live API Integration', () => {
       );
     }
 
-    searchTool = createToolSearchRegexTool({ apiKey, toolRegistry });
+    searchTool = createToolSearch({ apiKey, toolRegistry });
   });
 
   it('searches for expense-related tools', async () => {