@librechat/agents 3.0.66 → 3.0.68

package/dist/types/tools/ToolSearch.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+/** 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
+ */
+declare function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema;
+/**
+ * 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
+ */
+declare function extractMcpServerName(toolName: string): string | undefined;
+/**
+ * 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
+ */
+declare function isFromMcpServer(toolName: string, serverName: string): boolean;
+/**
+ * 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
+ */
+declare function isFromAnyMcpServer(toolName: string, serverNames: string[]): boolean;
+/**
+ * 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)
+ */
+declare function normalizeServerFilter(serverFilter: string | string[] | undefined): string[];
+/**
+ * Escapes special regex characters in a string to use as a literal pattern.
+ * @param pattern - The string to escape
+ * @returns The escaped string safe for use in a RegExp
+ */
+declare function escapeRegexSpecialChars(pattern: string): string;
+/**
+ * Counts the maximum nesting depth of groups in a regex pattern.
+ * @param pattern - The regex pattern to analyze
+ * @returns The maximum nesting depth
+ */
+declare function countNestedGroups(pattern: string): number;
+/**
+ * Detects nested quantifiers that can cause catastrophic backtracking.
+ * Patterns like (a+)+, (a*)*, (a+)*, etc.
+ * @param pattern - The regex pattern to check
+ * @returns True if nested quantifiers are detected
+ */
+declare function hasNestedQuantifiers(pattern: string): boolean;
+/**
+ * Checks if a regex pattern contains potentially dangerous constructs.
+ * @param pattern - The regex pattern to validate
+ * @returns True if the pattern is dangerous
+ */
+declare function isDangerousPattern(pattern: string): boolean;
+/**
+ * Sanitizes a regex pattern for safe execution.
+ * If the pattern is dangerous, it will be escaped to a literal string search.
+ * @param pattern - The regex pattern to sanitize
+ * @returns Object containing the safe pattern and whether it was escaped
+ */
+declare function sanitizeRegex(pattern: string): {
+    safe: string;
+    wasEscaped: boolean;
+};
+/**
+ * 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
+ */
+declare function performLocalSearch(tools: t.ToolMetadata[], query: string, fields: string[], maxResults: number): t.ToolSearchResponse;
+/**
+ * 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
+ */
+declare 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.
+ * 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)
+ */
+declare function formatServerListing(tools: t.ToolMetadata[], serverNames: string | string[]): string;
+/**
+ * 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.
+ *
+ * **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
+ * 2. At runtime via config.configurable.toolRegistry when invoking
+ *
+ * @param params - Configuration parameters for the tool (toolRegistry is optional)
+ * @returns A LangChain DynamicStructuredTool for tool searching
+ *
+ * @example
+ * // Option 1: Code interpreter mode (regex via sandbox)
+ * const tool = createToolSearch({ apiKey, toolRegistry });
+ * await tool.invoke({ query: 'expense.*report' });
+ *
+ * @example
+ * // Option 2: Local mode (safe substring search, no API key needed)
+ * const tool = createToolSearch({ mode: 'local', toolRegistry });
+ * await tool.invoke({ query: 'expense' });
+ */
+declare function createToolSearch(initParams?: t.ToolSearchParams): DynamicStructuredTool<ReturnType<typeof createToolSearchSchema>>;
+export { createToolSearch, performLocalSearch, extractMcpServerName, isFromMcpServer, isFromAnyMcpServer, normalizeServerFilter, getBaseToolName, formatServerListing, sanitizeRegex, escapeRegexSpecialChars, isDangerousPattern, countNestedGroups, hasNestedQuantifiers, };

package/dist/types/types/tools.d.ts

@@ -99,12 +99,18 @@ export type ProgrammaticCache = {
     toolMap: ToolMap;
     toolDefs: LCTool[];
 };
-/** Parameters for creating a Tool Search Regex tool */
-export type ToolSearchRegexParams = {
+/** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
+export type ToolSearchMode = 'code_interpreter' | 'local';
+/** Parameters for creating a Tool Search tool */
+export type ToolSearchParams = {
     apiKey?: string;
     toolRegistry?: LCToolRegistry;
     onlyDeferred?: boolean;
     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;
 };
 /** Simplified tool metadata for search purposes */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.66",
+  "version": "3.0.68",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -57,7 +57,7 @@
     "memory": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/memory.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "tool": "node --trace-warnings -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'openrouter' --name 'Jo' --location 'New York, NY'",
     "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
-    "tool_search_regex": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search_regex.ts",
+    "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
     "programmatic_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec.ts",
     "code_exec_ptc": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "programmatic_exec_agent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec_agent.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",

package/src/common/enum.ts

@@ -159,11 +159,13 @@ export enum Callback {
 export enum Constants {
   OFFICIAL_CODE_BASEURL = 'https://api.librechat.ai/v1',
   EXECUTE_CODE = 'execute_code',
-  TOOL_SEARCH_REGEX = 'tool_search_regex',
+  TOOL_SEARCH = 'tool_search',
   PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
   WEB_SEARCH = 'web_search',
   CONTENT_AND_ARTIFACT = 'content_and_artifact',
   LC_TRANSFER_TO_ = 'lc_transfer_to_',
+  /** Delimiter for MCP tools: toolName_mcp_serverName */
+  MCP_DELIMITER = '_mcp_',
 }
 
 export enum TitleMethod {

package/src/index.ts

@@ -12,7 +12,7 @@ export * from './graphs';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/ProgrammaticToolCalling';
-export * from './tools/ToolSearchRegex';
+export * from './tools/ToolSearch';
 export * from './tools/handlers';
 export * from './tools/search';
 

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

@@ -41,7 +41,7 @@ describe('Tool Discovery Functions', () => {
     return new ToolMessage({
       content: `Found ${discoveredTools.length} tools`,
       tool_call_id: toolCallId,
-      name: Constants.TOOL_SEARCH_REGEX,
+      name: Constants.TOOL_SEARCH,
       artifact: {
         tool_references: discoveredTools.map((name) => ({
           tool_name: name,
@@ -79,7 +79,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'database' },
           },
         ]),
@@ -97,12 +97,12 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'database' },
           },
           {
             id: 'call_2',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'file' },
           },
         ]),
@@ -137,7 +137,7 @@ describe('Tool Discovery Functions', () => {
         new ToolMessage({
           content: 'Some result',
           tool_call_id: 'orphan_call',
-          name: Constants.TOOL_SEARCH_REGEX,
+          name: Constants.TOOL_SEARCH,
         }),
       ];
 
@@ -153,7 +153,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'old_call',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'old' },
           },
         ]),
@@ -163,7 +163,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching again...', [
           {
             id: 'new_call',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'new' },
           },
         ]),
@@ -182,7 +182,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Working...', [
           {
             id: 'search_call',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'test' },
           },
           { id: 'other_call', name: 'get_weather', args: { city: 'NYC' } },
@@ -202,14 +202,14 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'xyz' },
           },
         ]),
         new ToolMessage({
           content: 'No tools found',
           tool_call_id: 'call_1',
-          name: Constants.TOOL_SEARCH_REGEX,
+          name: Constants.TOOL_SEARCH,
           artifact: {
             tool_references: [],
             metadata: { total_searched: 10, pattern: 'xyz' },
@@ -228,14 +228,14 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'test' },
           },
         ]),
         new ToolMessage({
           content: 'Error occurred',
           tool_call_id: 'call_1',
-          name: Constants.TOOL_SEARCH_REGEX,
+          name: Constants.TOOL_SEARCH,
           // No artifact
         }),
       ];
@@ -251,7 +251,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'test' },
           },
         ]),
@@ -271,7 +271,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('First search', [
           {
             id: 'first_call',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'first' },
           },
         ]),
@@ -280,7 +280,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Second search', [
           {
             id: 'second_call',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'second' },
           },
         ]),
@@ -301,7 +301,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'test' },
           },
         ]),
@@ -335,7 +335,7 @@ describe('Tool Discovery Functions', () => {
         new ToolMessage({
           content: 'Result',
           tool_call_id: 'orphan',
-          name: Constants.TOOL_SEARCH_REGEX,
+          name: Constants.TOOL_SEARCH,
         }),
       ];
 
@@ -364,7 +364,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Working...', [
           {
             id: 'search_call',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'test' },
           },
           { id: 'weather_call', name: 'get_weather', args: { city: 'NYC' } },
@@ -384,7 +384,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'old_call',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'old' },
           },
         ]),
@@ -410,7 +410,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'test' },
           },
         ]),
@@ -446,7 +446,7 @@ describe('Tool Discovery Functions', () => {
         createAIMessage('Searching...', [
           {
             id: 'call_1',
-            name: Constants.TOOL_SEARCH_REGEX,
+            name: Constants.TOOL_SEARCH,
             args: { pattern: 'test' },
           },
         ]),

package/src/messages/tools.ts

@@ -43,7 +43,7 @@ export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
   for (let i = latestAIParentIndex + 1; i < messages.length; i++) {
     const msg = messages[i];
     if (!(msg instanceof ToolMessage)) continue;
-    if (msg.name !== Constants.TOOL_SEARCH_REGEX) continue;
+    if (msg.name !== Constants.TOOL_SEARCH) continue;
     if (!toolCallIds.has(msg.tool_call_id)) continue;
 
     // This is a tool search result from the current turn
@@ -88,7 +88,7 @@ export function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean {
     const msg = messages[i];
     if (
       msg instanceof ToolMessage &&
-      msg.name === Constants.TOOL_SEARCH_REGEX &&
+      msg.name === Constants.TOOL_SEARCH &&
       toolCallIds.has(msg.tool_call_id)
     ) {
       return true;

package/src/scripts/programmatic_exec_agent.ts

@@ -23,7 +23,7 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
 import { createCodeExecutionTool } from '@/tools/CodeExecutor';
 import { createProgrammaticToolCallingTool } from '@/tools/ProgrammaticToolCalling';
-import { createToolSearchRegexTool } from '@/tools/ToolSearchRegex';
+import { createToolSearch } from '@/tools/ToolSearch';
 import { getLLMConfig } from '@/utils/llmConfig';
 import { getArgs } from '@/scripts/args';
 import { Run } from '@/run';
@@ -40,7 +40,7 @@ import {
 
 /**
  * Tool registry only needs business logic tools that require filtering.
- * Special tools (execute_code, run_tools_with_code, tool_search_regex)
+ * Special tools (execute_code, run_tools_with_code, tool_search)
  * are always bound directly to the LLM and don't need registry entries.
  */
 function createAgentToolRegistry(): t.LCToolRegistry {
@@ -73,7 +73,7 @@ async function main(): Promise<void> {
   // Create special tools (PTC, code execution, tool search)
   const codeExecTool = createCodeExecutionTool();
   const ptcTool = createProgrammaticToolCallingTool();
-  const toolSearchTool = createToolSearchRegexTool();
+  const toolSearchTool = createToolSearch();
 
   // Build complete tool list and map
   const allTools = [...mockTools, codeExecTool, ptcTool, toolSearchTool];
@@ -199,7 +199,7 @@ Use the run_tools_with_code tool to do this efficiently - don't call each tool s
   console.log('='.repeat(70));
   console.log('\nKey observations:');
   console.log(
-    '1. LLM only sees tools with allowed_callers including "direct" (get_weather, execute_code, run_tools_with_code, tool_search_regex)'
+    '1. LLM only sees tools with allowed_callers including "direct" (get_weather, execute_code, run_tools_with_code, tool_search)'
   );
   console.log(
     '2. When PTC is invoked, ToolNode automatically injects programmatic tools (get_team_members, get_expenses, get_weather)'

package/src/scripts/{tool_search_regex.ts → tool_search.ts}

@@ -1,7 +1,7 @@
-// src/scripts/tool_search_regex.ts
+// src/scripts/tool_search.ts
 /**
  * Test script for the Tool Search Regex tool.
- * Run with: npm run tool_search_regex
+ * Run with: npm run tool_search
  *
  * Demonstrates runtime registry injection - the tool registry is passed
  * at invocation time, not at initialization time.
@@ -9,7 +9,7 @@
 import { config } from 'dotenv';
 config();
 
-import { createToolSearchRegexTool } from '@/tools/ToolSearchRegex';
+import { createToolSearch } from '@/tools/ToolSearch';
 import type { LCToolRegistry } from '@/types';
 import { createToolSearchToolRegistry } from '@/test/mockTools';
 
@@ -22,7 +22,7 @@ interface RunTestOptions {
 }
 
 async function runTest(
-  searchTool: ReturnType<typeof createToolSearchRegexTool>,
+  searchTool: ReturnType<typeof createToolSearch>,
   testName: string,
   query: string,
   options: RunTestOptions
@@ -82,7 +82,7 @@ async function main(): Promise<void> {
   );
 
   console.log('\nCreating Tool Search Regex tool WITH registry for testing...');
-  const searchTool = createToolSearchRegexTool({ apiKey, toolRegistry });
+  const searchTool = createToolSearch({ apiKey, toolRegistry });
   console.log('Tool created successfully!');
   console.log(
     'Note: In production, ToolNode injects toolRegistry via params when invoked through the graph.\n'

package/src/tools/ToolNode.ts

@@ -132,7 +132,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           toolMap,
           toolDefs,
         };
-      } else if (call.name === Constants.TOOL_SEARCH_REGEX) {
+      } else if (call.name === Constants.TOOL_SEARCH) {
         invokeParams = {
           ...invokeParams,
           toolRegistry: this.toolRegistry,