Add tool name filtering to getAgentTools()

Enables filtering tools by name in addition to server-level filtering.
Supports both raw tool names (e.g., 'add') and server-prefixed names
(e.g., 'time__get_current_time').

- Add tools parameter to AgentToolsOptions interface
- Implement filtering logic with validation for prefixed format
- Add TOOL_SEPARATOR constant to eliminate magic strings
- Add comprehensive unit tests (9 test cases)
- Update README with examples and progressive disclosure explanation

Author: peteski22

README.md

@@ -359,8 +359,15 @@ if (await client.isServerHealthy("time")) {
 
 Generate callable functions that work directly with AI agent frameworks. No conversion layers needed.
 
+**Why filter tools?**
+
+AI agents perform better with focused tool sets.
+Tool filtering enables progressive disclosure - operators can expose a subset of server tools via `mcpd` configuration,
+then agents can further narrow down to only the tools needed for their specific task.
+This prevents overwhelming the model's context window and improves response quality.
+
 ```typescript
-// Options: { servers?: string[], format?: 'array' | 'object' | 'map' }
+// Options: { servers?: string[], tools?: string[], format?: 'array' | 'object' | 'map' }
 // Default format is 'array' (for LangChain)
 
 // Use with LangChain JS (array format is default)
@@ -397,6 +404,28 @@ const timeTools = await client.getAgentTools({
   format: "array",
 });
 
+// Filter by tool names (cross-cutting across all servers)
+const mathTools = await client.getAgentTools({
+  tools: ["add", "multiply"],
+});
+
+// Filter by qualified tool names (server-specific)
+const specificTools = await client.getAgentTools({
+  tools: ["time__get_current_time", "math__add"],
+});
+
+// Combine server and tool filtering
+const filteredTools = await client.getAgentTools({
+  servers: ["time", "math"],
+  tools: ["add", "get_current_time"],
+});
+
+// Tool filtering works with different formats
+const toolsObject = await client.getAgentTools({
+  tools: ["add", "multiply"],
+  format: "object",
+});
+
 // Use with Map for efficient lookups
 const toolMap = await client.getAgentTools({ format: "map" });
 const timeTool = toolMap.get("time__get_current_time");

src/client.ts

@@ -50,6 +50,13 @@ import { API_PATHS } from "./apiPaths";
  */
 const SERVER_HEALTH_CACHE_MAXSIZE = 100;
 
+/**
+ * Separator used between server name and tool name in qualified tool names.
+ * Format: `{serverName}{TOOL_SEPARATOR}{toolName}`
+ * Example: "time__get_current_time" where "time" is server and "get_current_time" is tool.
+ */
+const TOOL_SEPARATOR = "__";
+
 /**
  * Client for interacting with MCP (Model Context Protocol) servers through an mcpd daemon.
  *
@@ -789,36 +796,72 @@ export class McpdClient {
   async getAgentTools(options?: {
     format?: "array";
     servers?: string[];
+    tools?: string[];
   }): Promise<AgentFunction[]>;
   async getAgentTools(options: {
     format: "object";
     servers?: string[];
+    tools?: string[];
   }): Promise<Record<string, AgentFunction>>;
   async getAgentTools(options: {
     format: "map";
     servers?: string[];
+    tools?: string[];
   }): Promise<Map<string, AgentFunction>>;
   async getAgentTools(
     options: AgentToolsOptions = {},
   ): Promise<
     AgentFunction[] | Record<string, AgentFunction> | Map<string, AgentFunction>
   > {
-    const { servers, format = "array" } = options;
+    const { servers, tools, format = "array" } = options;
+
+    const allTools = await this.agentTools(servers);
 
-    // Get tools in array format (default internal representation)
-    const tools = await this.agentTools(servers);
+    const filteredTools = tools
+      ? allTools.filter((tool) => this.#matchesToolFilter(tool, tools))
+      : allTools;
 
-    // Return in requested format
     switch (format) {
       case "object":
-        return Object.fromEntries(tools.map((tool) => [tool.name, tool]));
+        return Object.fromEntries(
+          filteredTools.map((tool) => [tool.name, tool]),
+        );
 
       case "map":
-        return new Map(tools.map((tool) => [tool.name, tool]));
+        return new Map(filteredTools.map((tool) => [tool.name, tool]));
 
       case "array":
       default:
-        return tools;
+        return filteredTools;
     }
   }
+
+  /**
+   * Check if a tool matches the tool filter.
+   *
+   * Supports two formats:
+   * - Raw tool name: "get_current_time" (matches tool name only)
+   * - Server-prefixed name: "time__get_current_time" (server + TOOL_SEPARATOR + tool)
+   *
+   * @param tool The tool to check.
+   * @param tools List of tool names/patterns to match against.
+   * @returns True if the tool matches any item in the filter.
+   */
+  #matchesToolFilter(tool: AgentFunction, tools: string[]): boolean {
+    return tools.some((filterItem) => {
+      const separatorIndex = filterItem.indexOf(TOOL_SEPARATOR);
+      if (separatorIndex !== -1) {
+        const leftPart = filterItem.slice(0, separatorIndex).trim();
+        const rightPart = filterItem
+          .slice(separatorIndex + TOOL_SEPARATOR.length)
+          .trim();
+
+        if (leftPart && rightPart && filterItem === tool.name) {
+          return true;
+        }
+      }
+
+      return filterItem === tool._toolName;
+    });
+  }
 }

src/types.ts

@@ -238,6 +238,16 @@ export interface AgentToolsOptions {
    */
   servers?: string[];
 
+  /**
+   * Optional list of tool names to filter by. Supports both:
+   * - Raw tool names: 'get_current_time' (matches tool across all servers)
+   * - Server-prefixed names: 'time__get_current_time' (server + TOOL_SEPARATOR + tool)
+   * If not specified, returns all tools from selected servers.
+   * @example ['add', 'multiply']
+   * @example ['time__get_current_time', 'math__add']
+   */
+  tools?: string[];
+
   /**
    * Output format for the tools.
    * - 'array': Returns array of functions (default, for LangChain)