@mcp-ts/sdk 1.3.10 → 1.5.0

package/dist/shared/index.js

@@ -212,6 +212,870 @@ function findToolByName(connections, toolName) {
   return void 0;
 }
 
+// src/shared/tool-index.ts
+var CALIBRATION_DIVISOR = 3.6;
+function classifyChar(ch) {
+  const code = ch.charCodeAt(0);
+  if (code <= 32 || ch === "{" || ch === "}" || ch === "[" || ch === "]" || ch === ":" || ch === ",") return 1;
+  if (code >= 33 && code <= 47) return 1.5;
+  if (code >= 48 && code <= 57) return 2;
+  if (code >= 65 && code <= 90) return 3.5;
+  if (code >= 97 && code <= 122) return 4;
+  return 2.5;
+}
+var ToolIndex = class _ToolIndex {
+  constructor(options = {}) {
+    /** All indexed tools keyed by name (supports duplicates). */
+    __publicField(this, "tools", /* @__PURE__ */ new Map());
+    /** Precomputed lightweight summaries keyed by document. */
+    __publicField(this, "toolSummaries", /* @__PURE__ */ new Map());
+    /** Pre-computed search text for keyword matching (lowercase), keyed by document. */
+    __publicField(this, "searchTexts", /* @__PURE__ */ new Map());
+    /** Pre-computed IDF values per token (computed once on build). */
+    __publicField(this, "idf", /* @__PURE__ */ new Map());
+    /** Per-tool TF vectors (Map<token, tf>). */
+    __publicField(this, "tfVectors", /* @__PURE__ */ new Map());
+    /** Optional: pre-computed embedding vectors per tool. */
+    __publicField(this, "embeddings", /* @__PURE__ */ new Map());
+    /** BM25: document lengths in tokens for each tool. */
+    __publicField(this, "docLengths", /* @__PURE__ */ new Map());
+    /** BM25: average document length across the entire index. */
+    __publicField(this, "avgDocLength", 0);
+    /** Cached total estimated token cost across all indexed tools. */
+    __publicField(this, "totalTokenCost", 0);
+    __publicField(this, "options");
+    this.options = {
+      embedFn: options.embedFn ?? void 0,
+      keywordWeight: options.keywordWeight ?? 0.4
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Indexing
+  // -----------------------------------------------------------------------
+  /**
+   * Build (or rebuild) the index from the given tool set.
+   * Call this after connecting / reconnecting to MCP servers.
+   */
+  async buildIndex(tools) {
+    this.tools.clear();
+    this.toolSummaries.clear();
+    this.searchTexts.clear();
+    this.idf.clear();
+    this.tfVectors.clear();
+    this.embeddings.clear();
+    this.docLengths.clear();
+    this.avgDocLength = 0;
+    this.totalTokenCost = 0;
+    const allTokenSets = /* @__PURE__ */ new Map();
+    let totalLength = 0;
+    for (const tool of tools) {
+      const docKey = this.getDocumentKey(tool);
+      if (!this.tools.has(tool.name)) {
+        this.tools.set(tool.name, []);
+      }
+      this.tools.get(tool.name).push(tool);
+      const estimatedTokens = _ToolIndex.estimateTokens(tool);
+      this.toolSummaries.set(docKey, {
+        name: tool.name,
+        description: tool.description ?? "",
+        serverName: tool.serverName,
+        sessionId: tool.sessionId,
+        estimatedTokens
+      });
+      this.totalTokenCost += estimatedTokens;
+      const text = this.buildSearchableText(tool).toLowerCase();
+      this.searchTexts.set(docKey, text);
+      const tokens = this.tokenize(text);
+      const tf = /* @__PURE__ */ new Map();
+      const uniqueTokens = /* @__PURE__ */ new Set();
+      for (const tok of tokens) {
+        tf.set(tok, (tf.get(tok) ?? 0) + 1);
+        uniqueTokens.add(tok);
+      }
+      const maxTf = Math.max(...tf.values(), 1);
+      for (const [k, v] of tf) {
+        tf.set(k, v / maxTf);
+      }
+      this.tfVectors.set(docKey, tf);
+      allTokenSets.set(docKey, uniqueTokens);
+      const length = tokens.length;
+      this.docLengths.set(docKey, length);
+      totalLength += length;
+    }
+    this.avgDocLength = totalLength / (tools.length || 1);
+    const totalDocs = tools.length || 1;
+    const dfCounts = /* @__PURE__ */ new Map();
+    for (const tokenSet of allTokenSets.values()) {
+      for (const tok of tokenSet) {
+        dfCounts.set(tok, (dfCounts.get(tok) ?? 0) + 1);
+      }
+    }
+    for (const [tok, df] of dfCounts) {
+      this.idf.set(tok, Math.log(totalDocs / df) + 1);
+    }
+    if (this.options.embedFn) {
+      const names = [...this.searchTexts.keys()];
+      const texts = names.map((n) => this.searchTexts.get(n));
+      try {
+        const vectors = await this.options.embedFn(texts);
+        for (let i = 0; i < names.length; i++) {
+          if (vectors[i]) {
+            this.embeddings.set(names[i], vectors[i]);
+          }
+        }
+      } catch (err) {
+        console.warn("[ToolIndex] Embedding generation failed, falling back to keyword-only search:", err);
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Search
+  // -----------------------------------------------------------------------
+  /**
+   * Search the index and return the top-K most relevant tools.
+   *
+   * When an `embedFn` is configured the final score is a weighted blend of
+   * keyword TF-IDF similarity and embedding cosine-similarity:
+   *
+   *   `score = keywordWeight × keyword_score + (1 - keywordWeight) × cosine_score`
+   */
+  async search(query, topK = 5) {
+    if (this.tools.size === 0) return [];
+    const queryLower = query.toLowerCase();
+    const queryTokens = this.tokenize(queryLower);
+    const keywordScores = /* @__PURE__ */ new Map();
+    const k1 = 1.2;
+    const b = 0.75;
+    for (const [docKey, docTf] of this.tfVectors) {
+      let score = 0;
+      const docLen = this.docLengths.get(docKey) ?? 0;
+      for (const tok of queryTokens) {
+        const tfVal = docTf.get(tok) ?? 0;
+        if (tfVal === 0) continue;
+        const idf = this.idf.get(tok) ?? 0;
+        const numerator = tfVal * (k1 + 1);
+        const denominator = tfVal + k1 * (1 - b + b * (docLen / this.avgDocLength));
+        score += idf * (numerator / denominator);
+      }
+      keywordScores.set(docKey, score);
+    }
+    let embeddingScores = null;
+    if (this.options.embedFn && this.embeddings.size > 0) {
+      try {
+        const [queryEmbedding] = await this.options.embedFn([queryLower]);
+        if (queryEmbedding) {
+          embeddingScores = /* @__PURE__ */ new Map();
+          for (const [docKey, vec] of this.embeddings) {
+            embeddingScores.set(docKey, this.cosineSimilarity(queryEmbedding, vec));
+          }
+        }
+      } catch {
+      }
+    }
+    const kw = this.options.keywordWeight;
+    const finalScores = [];
+    for (const docKey of this.toolSummaries.keys()) {
+      const kwScore = keywordScores.get(docKey) ?? 0;
+      const embScore = embeddingScores?.get(docKey) ?? 0;
+      const score = embeddingScores ? kw * kwScore + (1 - kw) * embScore : kwScore;
+      if (score > 0) {
+        finalScores.push({ docKey, score });
+      }
+    }
+    finalScores.sort((a, b2) => b2.score - a.score);
+    return finalScores.slice(0, topK).map(({ docKey }) => {
+      return this.toolSummaries.get(docKey);
+    });
+  }
+  /**
+   * Search tools using a regex pattern.
+   * Matches against name, description, and parameter metadata.
+   */
+  searchRegex(pattern, topK = 5) {
+    if (this.tools.size === 0) return [];
+    try {
+      let flags = "";
+      let cleanPattern = pattern;
+      if (pattern.includes("(?i)")) {
+        flags = "i";
+        cleanPattern = pattern.replace(/\(\?i\)/g, "");
+      }
+      const regex = new RegExp(cleanPattern, flags || void 0);
+      const matches = [];
+      for (const [docKey, text] of this.searchTexts) {
+        const tool = this.toolSummaries.get(docKey);
+        if (!tool) continue;
+        if (regex.test(text) || regex.test(tool.name)) {
+          let score = 1;
+          if (tool.name === cleanPattern) score = 10;
+          else if (tool.name.startsWith(cleanPattern)) score = 5;
+          else if (tool.name.toLowerCase().includes(cleanPattern.toLowerCase())) score = 2;
+          matches.push({ docKey, score });
+        }
+      }
+      matches.sort((a, b) => b.score - a.score);
+      return matches.slice(0, topK).map(({ docKey }) => {
+        return this.toolSummaries.get(docKey);
+      });
+    } catch (err) {
+      console.warn("[ToolIndex] Regex search failed:", err);
+      return [];
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Accessors
+  // -----------------------------------------------------------------------
+  /**
+   * Get tool definition(s) by name.
+   * If namespace is provided, it tries to match sessionId or serverName.
+   */
+  getTool(name, namespace) {
+    const list = this.tools.get(name) ?? [];
+    if (!namespace) return list;
+    return list.filter((t) => t.sessionId === namespace || t.serverName === namespace);
+  }
+  /** All indexed tool names. */
+  getToolNames() {
+    return [...this.tools.keys()];
+  }
+  /** Number of indexed tools (including duplicates). */
+  get size() {
+    let count = 0;
+    for (const list of this.tools.values()) {
+      count += list.length;
+    }
+    return count;
+  }
+  /** Total estimated token cost of all indexed tool schemas. */
+  getTotalTokenCost() {
+    return this.totalTokenCost;
+  }
+  // -----------------------------------------------------------------------
+  // Static Helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Estimate token count of a tool's full schema (name + description + inputSchema).
+   *
+   * Uses character-class weighted counting calibrated against cl100k_base.
+   * Accuracy is typically within ±10% for JSON Schema payloads.
+   */
+  static estimateTokens(tool) {
+    const parts = [tool.name];
+    if (tool.description) parts.push(tool.description);
+    if (tool.inputSchema) parts.push(JSON.stringify(tool.inputSchema));
+    const text = parts.join(" ");
+    let weightedLen = 0;
+    for (let i = 0; i < text.length; i++) {
+      weightedLen += 1 / classifyChar(text[i]);
+    }
+    return Math.ceil(weightedLen / (1 / CALIBRATION_DIVISOR));
+  }
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+  /** Build a single searchable string from tool metadata. */
+  buildSearchableText(tool) {
+    const parts = [tool.name];
+    if (tool.description) parts.push(tool.description);
+    if (tool.inputSchema && typeof tool.inputSchema === "object") {
+      const schema = tool.inputSchema;
+      const props = schema.properties;
+      if (props) {
+        for (const [key, val] of Object.entries(props)) {
+          parts.push(key);
+          if (val && typeof val === "object" && val.description) {
+            parts.push(val.description);
+          }
+        }
+      }
+    }
+    return parts.join(" ");
+  }
+  getDocumentKey(tool) {
+    return `${tool.sessionId}::${tool.serverName}::${tool.name}`;
+  }
+  /** Simple whitespace + camelCase + snake_case tokenizer. */
+  tokenize(text) {
+    return text.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]/g, " ").replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((t) => t.length > 1);
+  }
+  /** Cosine similarity between two vectors. */
+  cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < len; i++) {
+      dot += a[i] * b[i];
+      magA += a[i] * a[i];
+      magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom > 0 ? dot / denom : 0;
+  }
+};
+
+// src/shared/schema-compressor.ts
+var SchemaCompressor = class _SchemaCompressor {
+  /**
+   * Convert a full MCP Tool definition to a compact summary.
+   *
+   * The compact form omits `inputSchema` entirely and optionally generates
+   * a short `parameterHint` from the schema's top-level properties.
+   */
+  static toCompact(tool) {
+    const compact = {
+      name: tool.name,
+      description: tool.description
+    };
+    if (tool.inputSchema && typeof tool.inputSchema === "object") {
+      const schema = tool.inputSchema;
+      if (schema.properties) {
+        const required = new Set(schema.required ?? []);
+        const parts = [];
+        for (const [key, val] of Object.entries(schema.properties)) {
+          const type = val?.type ?? "any";
+          const enumSuffix = val?.enum && Array.isArray(val.enum) ? `: ${val.enum.map((e) => `'${e}'`).join(" | ")}` : `: ${type}`;
+          parts.push(required.has(key) ? `${key}${enumSuffix}` : `${key}?${enumSuffix}`);
+        }
+        if (parts.length > 0) {
+          compact.parameterHint = `(${parts.join(", ")})`;
+        }
+      }
+    }
+    return compact;
+  }
+  /**
+   * Convert an array of tools to compact form, optionally limiting the count.
+   */
+  static compactAll(tools, options) {
+    const limited = options?.maxTools ? tools.slice(0, options.maxTools) : tools;
+    return limited.map((t) => _SchemaCompressor.toCompact(t));
+  }
+  /**
+   * Estimate token savings from using compact vs full tool schemas.
+   */
+  static estimateSavings(tools) {
+    let fullTokens = 0;
+    let compactTokens = 0;
+    for (const tool of tools) {
+      fullTokens += ToolIndex.estimateTokens(tool);
+      const compact = _SchemaCompressor.toCompact(tool);
+      const text = [compact.name, compact.description ?? "", compact.parameterHint ?? ""].join(" ");
+      compactTokens += Math.ceil(text.length / 4);
+    }
+    const saved = fullTokens - compactTokens;
+    const pct = fullTokens > 0 ? (saved / fullTokens * 100).toFixed(1) : "0.0";
+    return {
+      fullTokens,
+      compactTokens,
+      savedTokens: saved,
+      savingsPercent: `${pct}%`
+    };
+  }
+};
+
+// src/shared/meta-tools.ts
+function createSearchToolDefinition() {
+  return {
+    name: "mcp_search_tool_bm25",
+    description: 'Search the catalog of available tools using BM25 natural language ranking. Returns tool names, descriptions, and server info. Use this FIRST to find relevant tools before calling them. Example queries: "database query", "send email", "github pull request".',
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Natural language description of the capability you need."
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of results to return (default: 5, max: 20)."
+        }
+      },
+      required: ["query"]
+    }
+  };
+}
+function createRegexSearchToolDefinition() {
+  return {
+    name: "mcp_search_tool_regex",
+    description: 'Search the catalog of available tools using a Python-style regex pattern. Matches against tool names, descriptions, and parameter descriptions. Example patterns: "^github_", "weather", "(?i)slack".',
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: 'Regex pattern to search for (e.g., "^get_.*_data", "database").'
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of results to return (default: 5, max: 20)."
+        }
+      },
+      required: ["query"]
+    }
+  };
+}
+function createGetSchemaToolDefinition() {
+  return {
+    name: "mcp_get_tool_schema",
+    description: "Get the full input schema (parameters) for a specific tool. Call this after mcp_search_tool_bm25 to get the parameter details needed to call a tool correctly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        toolName: {
+          type: "string",
+          description: "The exact tool name returned by mcp_search_tool_bm25."
+        },
+        serverName: {
+          type: "string",
+          description: "Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name."
+        }
+      },
+      required: ["toolName"]
+    }
+  };
+}
+function createExecuteToolDefinition() {
+  return {
+    name: "mcp_execute_tool",
+    description: "Execute a tool that was discovered via mcp_search_tool_bm25. You MUST call mcp_get_tool_schema first to know the correct parameters. Pass the exact tool name and its arguments.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        toolName: {
+          type: "string",
+          description: "The exact tool name from mcp_search_tool_bm25 results."
+        },
+        serverName: {
+          type: "string",
+          description: "Optional: The server name provided in mcp_search_tool_bm25. Required if multiple tools have the same name."
+        },
+        args: {
+          type: "object",
+          description: "Arguments matching the tool's inputSchema. Omit or pass {} if the tool takes no parameters.",
+          additionalProperties: true
+        }
+      },
+      required: ["toolName"]
+    }
+  };
+}
+async function executeMetaTool(toolName, args, router, callToolFn) {
+  const resolveToolSchema = (name, namespace) => {
+    try {
+      return { tool: router.getToolSchema(name, namespace) };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        error: {
+          content: [{ type: "text", text: errorMessage }],
+          isError: true
+        }
+      };
+    }
+  };
+  switch (toolName) {
+    case "mcp_search_tool_bm25": {
+      const query = String(args.query ?? "");
+      const limit = Math.min(Number(args.limit) || 5, 20);
+      const results = await router.searchTools(query, limit);
+      const text = results.length === 0 ? "No tools found matching your query. Try different keywords." : results.map(
+        (t, i) => `${i + 1}. **${t.name}** (server: ${t.serverName})
+   ${t.description}
+   Estimated tokens: ${t.estimatedTokens}`
+      ).join("\n");
+      return {
+        content: [{ type: "text", text }],
+        isError: false
+      };
+    }
+    case "mcp_search_tool_regex": {
+      const pattern = String(args.query ?? "");
+      const limit = Math.min(Number(args.limit) || 5, 20);
+      const results = await router.searchToolsRegex(pattern, limit);
+      const text = results.length === 0 ? "No tools matched your regex pattern. Try a broader pattern." : results.map(
+        (t, i) => `${i + 1}. **${t.name}** (server: ${t.serverName})
+   ${t.description}
+   Estimated tokens: ${t.estimatedTokens}`
+      ).join("\n");
+      return {
+        content: [{ type: "text", text }],
+        isError: false
+      };
+    }
+    case "mcp_get_tool_schema": {
+      const name = String(args.toolName ?? "");
+      const namespace = String(args.serverName ?? "") || void 0;
+      const { tool, error } = resolveToolSchema(name, namespace);
+      if (error) {
+        return error;
+      }
+      if (!tool) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Tool "${name}" not found. Use mcp_search_tool_bm25 to find available tools first.`
+            }
+          ],
+          isError: true
+        };
+      }
+      const schema = {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(schema, null, 2) }],
+        isError: false
+      };
+    }
+    case "mcp_execute_tool": {
+      const targetToolName = String(args.toolName ?? "");
+      const namespace = String(args.serverName ?? "") || void 0;
+      const toolArgs = args.args ?? {};
+      if (!targetToolName) {
+        return {
+          content: [{ type: "text", text: 'Missing required parameter "toolName". Specify which tool to execute.' }],
+          isError: true
+        };
+      }
+      const { tool, error } = resolveToolSchema(targetToolName, namespace);
+      if (error) {
+        return error;
+      }
+      if (!tool) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Tool "${targetToolName}" not found. Use mcp_search_tool_bm25 to discover available tools first.`
+            }
+          ],
+          isError: true
+        };
+      }
+      if (!callToolFn) {
+        return {
+          content: [{ type: "text", text: "Tool execution is not available. No callToolFn was configured." }],
+          isError: true
+        };
+      }
+      try {
+        const result = await callToolFn(targetToolName, toolArgs, namespace);
+        if (result && typeof result === "object" && "content" in result) {
+          return result;
+        }
+        const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        return {
+          content: [{ type: "text", text }],
+          isError: false
+        };
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Tool execution failed: ${errorMessage}` }],
+          isError: true
+        };
+      }
+    }
+    default:
+      return null;
+  }
+}
+function isMetaTool(toolName) {
+  return toolName === "mcp_search_tool_bm25" || toolName === "mcp_search_tool_regex" || toolName === "mcp_get_tool_schema" || toolName === "mcp_execute_tool";
+}
+function resolveMetaToolProxy(toolName, args) {
+  if (toolName === "mcp_execute_tool") {
+    const innerName = args?.toolName;
+    const innerArgs = args?.args;
+    return {
+      toolName: typeof innerName === "string" && innerName ? innerName : toolName,
+      args: innerArgs && typeof innerArgs === "object" && !Array.isArray(innerArgs) ? innerArgs : {}
+    };
+  }
+  const match = toolName.match(/(?:tool_[^_]+_)?(.+)$/);
+  const resolvedName = match?.[1] ?? toolName;
+  return { toolName: resolvedName, args: args ?? {} };
+}
+
+// src/shared/tool-router.ts
+var ToolRouter = class {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.options = options;
+    __publicField(this, "index");
+    __publicField(this, "allTools", []);
+    __publicField(this, "groupsMap", /* @__PURE__ */ new Map());
+    __publicField(this, "strategy");
+    __publicField(this, "maxTools");
+    __publicField(this, "compactSchemas");
+    __publicField(this, "activeGroups");
+    __publicField(this, "customGroups");
+    __publicField(this, "initialized", false);
+    this.strategy = options.strategy ?? "all";
+    this.maxTools = options.maxTools ?? 40;
+    this.compactSchemas = options.compactSchemas ?? false;
+    this.activeGroups = new Set(options.activeGroups ?? []);
+    this.customGroups = options.groups;
+    this.index = new ToolIndex({
+      embedFn: options.embedFn,
+      keywordWeight: options.keywordWeight
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Core Public API
+  // -----------------------------------------------------------------------
+  /**
+   * Get tools filtered by the current strategy.
+   * This is the main method adapters should call.
+   *
+   * - `all`    → returns all tools (unchanged behavior)
+   * - `search` → returns only meta-tools (mcp_search_tool_bm25, mcp_get_tool_schema, mcp_execute_tool)
+   * - `groups` → returns tools from active groups only
+   */
+  async getFilteredTools() {
+    await this.ensureInitialized();
+    switch (this.strategy) {
+      case "search":
+        return this.getMetaToolDefinitions();
+      case "groups":
+        return this.getGroupFilteredTools();
+      case "all":
+      default:
+        if (this.compactSchemas) {
+          return this.allTools.map((t) => {
+            const compact = SchemaCompressor.toCompact(t);
+            return {
+              name: compact.name,
+              description: (compact.description ?? "") + (compact.parameterHint ? ` Parameters: ${compact.parameterHint}` : ""),
+              inputSchema: { type: "object", properties: {} }
+            };
+          });
+        }
+        return [...this.allTools];
+    }
+  }
+  /**
+   * Search tools by natural-language query.
+   * Works regardless of strategy.
+   */
+  async searchTools(query, topK) {
+    await this.ensureInitialized();
+    return this.index.search(query, topK ?? this.maxTools);
+  }
+  /**
+   * Search tools by regex pattern.
+   * Matches against name, description, and parameter metadata.
+   */
+  async searchToolsRegex(pattern, topK) {
+    await this.ensureInitialized();
+    return this.index.searchRegex(pattern, topK ?? this.maxTools);
+  }
+  /**
+   * Get the full tool definition by name.
+   * If tool name is ambiguous, use namespace to specify the server.
+   */
+  getToolSchema(toolName, namespace) {
+    const matches = this.index.getTool(toolName, namespace);
+    if (matches.length === 0) return void 0;
+    if (matches.length > 1) {
+      const servers = matches.map((m) => m.serverName).join(", ");
+      throw new Error(
+        `Tool "${toolName}" is provided by multiple servers: [${servers}]. Please specify the desired "serverName" as a namespace.`
+      );
+    }
+    return matches[0];
+  }
+  /**
+   * Get compact (schema-less) summaries for all tools.
+   */
+  getCompactTools() {
+    return SchemaCompressor.compactAll(this.allTools);
+  }
+  // -----------------------------------------------------------------------
+  // Group Management
+  // -----------------------------------------------------------------------
+  /** Get all available groups with their tool lists and active status. */
+  getGroups() {
+    return new Map(this.groupsMap);
+  }
+  /** Activate specific groups. Pass empty array to activate all. */
+  setActiveGroups(groups) {
+    this.activeGroups = new Set(groups);
+    for (const [name, info] of this.groupsMap) {
+      info.active = this.activeGroups.size === 0 || this.activeGroups.has(name);
+    }
+  }
+  /** Get the names of currently active groups. */
+  getActiveGroups() {
+    return [...this.activeGroups];
+  }
+  // -----------------------------------------------------------------------
+  // Stats & Introspection
+  // -----------------------------------------------------------------------
+  /** Total token cost of all tools if loaded without filtering. */
+  getTotalTokenCost() {
+    return this.index.getTotalTokenCost();
+  }
+  /** Estimate token cost of the currently filtered tool set. */
+  async getFilteredTokenCost() {
+    const tools = await this.getFilteredTools();
+    let total = 0;
+    for (const tool of tools) {
+      total += ToolIndex.estimateTokens(tool);
+    }
+    return total;
+  }
+  /** Get compression stats showing savings from current strategy. */
+  getCompressionStats() {
+    return SchemaCompressor.estimateSavings(this.allTools);
+  }
+  /** Number of total indexed tools. */
+  get totalToolCount() {
+    return this.allTools.length;
+  }
+  /** Change strategy at runtime. */
+  setStrategy(strategy) {
+    this.strategy = strategy;
+  }
+  /**
+   * Force a re-index of tools from all connected clients.
+   * Call this after adding/removing MCP server connections.
+   */
+  async refresh() {
+    this.initialized = false;
+    await this.ensureInitialized();
+  }
+  /**
+   * Execute a tool by routing to the correct MCP client.
+   * Used by the `mcp_execute_tool` meta-tool to proxy tool calls.
+   */
+  async callTool(toolName, args, namespace) {
+    await this.ensureInitialized();
+    const indexedTool = this.getToolSchema(toolName, namespace);
+    if (!indexedTool) {
+      throw new Error(
+        `Tool "${toolName}" not found${namespace ? ` on server "${namespace}"` : ""}. Use mcp_search_tool_bm25 or mcp_search_tool_regex to discover available tools.`
+      );
+    }
+    const clients = this.getClients();
+    const targetClient = clients.find(
+      (c) => typeof c.getSessionId === "function" && c.getSessionId() === indexedTool.sessionId
+    ) ?? clients.find((c) => c.isConnected());
+    if (!targetClient) {
+      throw new Error(`No connected client found for tool "${toolName}"`);
+    }
+    return await targetClient.callTool(toolName, args);
+  }
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+  /** Lazy initialization — fetches tools from all connected clients. */
+  async ensureInitialized() {
+    if (this.initialized) return;
+    this.allTools = await this.fetchAllTools();
+    await this.index.buildIndex(this.allTools);
+    this.buildGroups();
+    this.initialized = true;
+  }
+  /** Fetch tools from all connected MCP clients. */
+  async fetchAllTools() {
+    const clients = this.getClients();
+    const result = [];
+    for (const client of clients) {
+      if (!client.isConnected()) continue;
+      try {
+        const { tools } = await client.listTools();
+        const serverId = typeof client.getServerId === "function" ? client.getServerId() ?? "unknown" : "unknown";
+        const serverName = (typeof client.getServerName === "function" ? client.getServerName() : void 0) ?? serverId;
+        const sessionId = typeof client.getSessionId === "function" ? client.getSessionId() ?? "unknown" : "unknown";
+        for (const tool of tools) {
+          result.push({
+            ...tool,
+            serverName,
+            sessionId
+          });
+        }
+      } catch (err) {
+        console.warn("[ToolRouter] Failed to fetch tools from client:", err);
+      }
+    }
+    return result;
+  }
+  /** Resolve the client input to a flat array of ToolClient instances. */
+  getClients() {
+    if (Array.isArray(this.client)) {
+      return this.client;
+    }
+    if (typeof this.client.getClients === "function") {
+      return this.client.getClients();
+    }
+    return [this.client];
+  }
+  /** Build group map from custom config or auto-detect from server names. */
+  buildGroups() {
+    this.groupsMap.clear();
+    if (this.customGroups) {
+      for (const [name, tools] of Object.entries(this.customGroups)) {
+        this.groupsMap.set(name, {
+          tools,
+          active: this.activeGroups.size === 0 || this.activeGroups.has(name)
+        });
+      }
+    } else {
+      const serverTools = /* @__PURE__ */ new Map();
+      for (const tool of this.allTools) {
+        const group = tool.serverName;
+        if (!serverTools.has(group)) {
+          serverTools.set(group, []);
+        }
+        serverTools.get(group).push(tool.name);
+      }
+      for (const [serverName, tools] of serverTools) {
+        this.groupsMap.set(serverName, {
+          tools,
+          active: this.activeGroups.size === 0 || this.activeGroups.has(serverName)
+        });
+      }
+    }
+  }
+  /** Return only tools belonging to currently active groups. */
+  getGroupFilteredTools() {
+    const activeToolNames = /* @__PURE__ */ new Set();
+    for (const [, info] of this.groupsMap) {
+      if (info.active) {
+        for (const name of info.tools) {
+          activeToolNames.add(name);
+        }
+      }
+    }
+    const filtered = this.allTools.filter((t) => activeToolNames.has(t.name));
+    if (this.compactSchemas) {
+      return filtered.slice(0, this.maxTools).map((t) => {
+        const compact = SchemaCompressor.toCompact(t);
+        return {
+          name: compact.name,
+          description: (compact.description ?? "") + (compact.parameterHint ? ` Parameters: ${compact.parameterHint}` : ""),
+          inputSchema: { type: "object", properties: {} }
+        };
+      });
+    }
+    return filtered.slice(0, this.maxTools);
+  }
+  /** The 4 meta-tool definitions exposed in `search` strategy. */
+  getMetaToolDefinitions() {
+    return [
+      createSearchToolDefinition(),
+      createRegexSearchToolDefinition(),
+      createGetSchemaToolDefinition(),
+      createExecuteToolDefinition()
+    ];
+  }
+};
+
 exports.AuthenticationError = AuthenticationError;
 exports.ConfigurationError = ConfigurationError;
 exports.ConnectionError = ConnectionError;
@@ -233,11 +1097,19 @@ exports.SESSION_TTL_SECONDS = SESSION_TTL_SECONDS;
 exports.SOFTWARE_ID = SOFTWARE_ID;
 exports.SOFTWARE_VERSION = SOFTWARE_VERSION;
 exports.STATE_EXPIRATION_MS = STATE_EXPIRATION_MS;
+exports.SchemaCompressor = SchemaCompressor;
 exports.SessionNotFoundError = SessionNotFoundError;
 exports.SessionValidationError = SessionValidationError;
 exports.TOKEN_EXPIRY_BUFFER_MS = TOKEN_EXPIRY_BUFFER_MS;
 exports.ToolExecutionError = ToolExecutionError;
+exports.ToolIndex = ToolIndex;
+exports.ToolRouter = ToolRouter;
 exports.UnauthorizedError = UnauthorizedError;
+exports.createExecuteToolDefinition = createExecuteToolDefinition;
+exports.createGetSchemaToolDefinition = createGetSchemaToolDefinition;
+exports.createRegexSearchToolDefinition = createRegexSearchToolDefinition;
+exports.createSearchToolDefinition = createSearchToolDefinition;
+exports.executeMetaTool = executeMetaTool;
 exports.findToolByName = findToolByName;
 exports.getToolUiResourceUri = getToolUiResourceUri;
 exports.isCallToolSuccess = isCallToolSuccess;
@@ -245,6 +1117,8 @@ exports.isConnectAuthRequired = isConnectAuthRequired;
 exports.isConnectError = isConnectError;
 exports.isConnectSuccess = isConnectSuccess;
 exports.isListToolsSuccess = isListToolsSuccess;
+exports.isMetaTool = isMetaTool;
+exports.resolveMetaToolProxy = resolveMetaToolProxy;
 exports.sanitizeServerLabel = sanitizeServerLabel;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map