agent.libx.js 0.93.16 → 0.93.18

package/dist/mcp-C5GuDinb.d.ts

@@ -0,0 +1,101 @@
+import { A as AgentTool } from './tools-GPWp7oXq.js';
+
+/**
+ * MCP bridge — adapt a Model Context Protocol tool list into the agent's AgentTool[],
+ * so any MCP server's tools become first-class agent tools (edge-safe: you supply the
+ * transport via `callTool`; this module has no node/network dependency of its own).
+ *
+ * Pass the server's advertised tools + a `callTool(name, args)` that performs the call
+ * (over stdio/HTTP/whatever you wire up); each becomes an AgentTool the Agent can use.
+ */
+interface McpToolSpec {
+    name: string;
+    description?: string;
+    /** JSON Schema for the tool's arguments (MCP's `inputSchema`). */
+    inputSchema?: object;
+}
+/** Perform an MCP tool call; return its textual result. Throw to surface an error to the model. */
+type McpCall = (name: string, args: any) => Promise<unknown>;
+interface McpImage {
+    mimeType: string;
+    data: string;
+}
+interface McpToolResult {
+    text: string;
+    images?: McpImage[];
+}
+/** Adapt one MCP tool spec into an AgentTool backed by `callTool`. */
+declare function mcpToolToAgentTool(spec: McpToolSpec, callTool: McpCall, prefix?: string): AgentTool;
+/** Adapt a whole MCP tool list into AgentTool[] (names prefixed to avoid collisions).
+ *  Optional `filter` pre-narrows the set at mount time (host allowlist), so a server with
+ *  hundreds of tools needn't mount them all eagerly. */
+declare function mcpToolsToAgentTools(specs: McpToolSpec[], callTool: McpCall, prefix?: string, filter?: (spec: McpToolSpec) => boolean): AgentTool[];
+interface McpToolSearchOptions {
+    /** Prefix stripped from / shown on tool names (cosmetic; mirrors the adapter prefix). Default 'mcp__'. */
+    prefix?: string;
+    /** Max tools returned per `ToolSearch` query. Default 10. */
+    maxResults?: number;
+}
+/**
+ * Deferred-mount mode (ToolSearch-equivalent) for large MCP tool sets. Instead of mounting N
+ * tools into the wire schema (cost + latency + model confusion past a few dozen), mount exactly
+ * TWO bounded tools regardless of N:
+ *   - `ToolSearch({ query })` — ranks the catalog by relevance and returns the top matches with
+ *      their argument schemas, so the model discovers what's available on demand.
+ *   - `McpCall({ name, args })` — invokes any catalog tool by name through the same transport.
+ * Keep `mcpToolsToAgentTools` (eager) as the default for small sets.
+ */
+declare function makeMcpToolSearch(specs: McpToolSpec[], callTool: McpCall, options?: McpToolSearchOptions): AgentTool[];
+/** Minimal shape of a mounted MCP server this module needs — structurally satisfied by
+ *  `MountedMcp` from `mcp.client.ts`, kept local so `mcp.ts` stays node-free/edge-safe. */
+interface MountedMcpLike {
+    name: string;
+    specs: McpToolSpec[];
+    client: {
+        callTool(name: string, args: unknown): Promise<unknown>;
+    };
+}
+/** A flattened catalog entry's origin: which server owns it + the un-prefixed raw tool name. */
+interface McpRoute {
+    server: string;
+    rawName: string;
+}
+/** Flatten servers' specs into one `mcp__<server>__<tool>` namespace + a display→origin map.
+ *  Sanitizing/truncating to provider name rules can MERGE distinct names (`a/b` & `a:b` → `a_b`),
+ *  so dedupe with a numeric suffix — a silent overwrite would orphan a tool. */
+declare function buildMcpCatalog(servers: {
+    name: string;
+    specs: McpToolSpec[];
+}[]): {
+    specs: McpToolSpec[];
+    routes: Map<string, McpRoute>;
+};
+/** Resolve a routed MCP call to its result. Throw to surface an error to the model. */
+type McpRouteResolver = (server: string, rawName: string, args: any) => Promise<unknown>;
+/**
+ * Ergonomic deferred-mount over already-mounted MCP servers: flattens their specs into one
+ * `mcp__<server>__<tool>` namespace and wires a single `ToolSearch`/`McpCall` pair that routes
+ * each call to the owning server's RAW `callTool` (so result normalization happens exactly once —
+ * double-normalizing corrupts image blocks).
+ */
+declare function makeMcpToolSearchFromMounted(mounted: MountedMcpLike[], options?: McpToolSearchOptions): {
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+};
+/**
+ * Lazy variant: same `ToolSearch`/`McpCall` surface, but the server isn't required to be connected.
+ * Each `McpCall` resolves the owning server from the catalog and `resolve(server, rawName, args)`
+ * connects-on-demand — so a turn that calls no MCP tool opens ZERO connections. Edge-safe: the
+ * caller (`mountMcpCatalog` in `mcp.client.ts`) supplies the node-side connect/pool logic.
+ */
+declare function makeLazyMcpToolSearch(servers: {
+    name: string;
+    specs: McpToolSpec[];
+}[], resolve: McpRouteResolver, options?: McpToolSearchOptions): {
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+};
+
+export { type McpCall as M, type McpImage as a, type McpRoute as b, type McpRouteResolver as c, type McpToolResult as d, type McpToolSearchOptions as e, type McpToolSpec as f, type MountedMcpLike as g, buildMcpCatalog as h, makeMcpToolSearch as i, makeMcpToolSearchFromMounted as j, mcpToolToAgentTool as k, mcpToolsToAgentTools as l, makeLazyMcpToolSearch as m };

package/dist/mcp.client.d.ts

@@ -1,4 +1,4 @@
-import { d as McpToolSpec } from './mcp-wwgXyhbi.js';
+import { e as McpToolSearchOptions, f as McpToolSpec } from './mcp-C5GuDinb.js';
 import { A as AgentTool } from './tools-GPWp7oXq.js';
 import '@livx.cc/wcli/core';
 
@@ -105,6 +105,9 @@ interface MountedMcp {
     name: string;
     client: McpClient;
     tools: AgentTool[];
+    /** Raw tool specs discovered at mount (already fetched internally) — exposed so deferred-mount
+     *  glue (`makeMcpToolSearchFromMounted`) needn't re-call `tools/list`. */
+    specs: McpToolSpec[];
     serverInfo?: {
         name?: string;
         version?: string;
@@ -113,9 +116,84 @@ interface MountedMcp {
 /** Connect one server, discover its tools, and adapt them to prefixed AgentTools (`mcp__<name>__`). */
 declare function mountMcpServer(name: string, cfg: McpServerConfig): Promise<MountedMcp>;
 /**
- * Mount every configured server. A server that fails (bad command, no handshake, timeout) is
- * logged and skipped — one broken server can never block the agent from starting.
+ * Mount every configured server in PARALLEL (one slow/dead server no longer serializes the rest);
+ * each may carry a `mountTimeoutMs` deadline. A server that fails is logged and skipped.
  */
-declare function mountMcpServers(servers?: Record<string, McpServerConfig>): Promise<MountedMcp[]>;
+declare function mountMcpServers(servers?: Record<string, McpServerConfig>, opts?: {
+    mountTimeoutMs?: number;
+}): Promise<MountedMcp[]>;
+/**
+ * One-shot deferred MCP mount: connect every entry (failures dropped, never block startup) and
+ * fold the survivors into a single `ToolSearch`/`McpCall` pair via `makeMcpToolSearchFromMounted`.
+ * The node-only counterpart to that edge-safe helper — returns `mounted` too so callers can close
+ * the clients on shutdown. Eager: it connects all servers up front. For lazy connect + a cached
+ * catalog (zero connections on a turn that uses no MCP tool), use `mountMcpCatalog`.
+ */
+declare function mountMcpDeferred(servers?: Record<string, McpServerConfig>, options?: McpToolSearchOptions & {
+    mountTimeoutMs?: number;
+}): Promise<{
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+    mounted: MountedMcp[];
+}>;
+/** A persistent tool catalog: lets `mountMcpCatalog` build `ToolSearch` WITHOUT connecting when a
+ *  fresh entry exists. The lib defines the interface; the consumer supplies the store (RAM/disk).
+ *  Key = a hash of the server's resolved config (see `mcpConfigKey`). TTL/versioning is the store's. */
+interface McpCatalogStore {
+    get(key: string): McpToolSpec[] | null;
+    set(key: string, specs: McpToolSpec[]): void;
+}
+/** Stable cache key for a server config — command/args/cwd + env NAMES (not secret values), or
+ *  url + header names. Changing any of these invalidates the cached catalog; rotating a secret does not. */
+declare function mcpConfigKey(cfg: McpServerConfig): string;
+/** Default in-memory catalog: process-lifetime, hash-keyed, TTL-expiring (so a server that gains
+ *  tools is picked up after the TTL without a restart). Shared module singleton → cross-turn reuse. */
+declare class MemMcpCatalog implements McpCatalogStore {
+    private ttlMs;
+    private m;
+    constructor(ttlMs?: number);
+    get(key: string): McpToolSpec[] | null;
+    set(key: string, specs: McpToolSpec[]): void;
+}
+/** Opt-in warm pool: keeps stdio MCP clients connected across turns, reaping each after `ttlMs`
+ *  idle. Most stdio MCPs are per-turn by design, so this is off by default; HTTP servers are
+ *  stateless and never pooled. */
+declare class McpPool {
+    private ttlMs;
+    private warm;
+    constructor(ttlMs?: number);
+    get(key: string): McpClient | null;
+    put(key: string, client: McpClient): void;
+    private arm;
+    private evict;
+    closeAll(): Promise<void>;
+}
+interface McpCatalogOptions extends McpToolSearchOptions {
+    /** Where to read/write discovered specs. Default: a shared process-lifetime `MemMcpCatalog`. */
+    catalog?: McpCatalogStore;
+    /** Per-server deadline for the connect+list on a cache MISS. A hung server is skipped, not blocking. */
+    mountTimeoutMs?: number;
+    /** Opt-in: keep stdio clients warm across turns (see `McpPool`). HTTP servers are never pooled. */
+    keepWarm?: boolean;
+    /** Warm-client pool. Default: a shared process-lifetime `McpPool` (only used when `keepWarm`). */
+    pool?: McpPool;
+}
+/**
+ * Lazy + cached MCP mount. Builds the `ToolSearch`/`McpCall` pair from the CACHED catalog when one
+ * exists — connecting NOTHING. On a cache miss it connects once (parallel, deadline-bounded), lists,
+ * caches, then disconnects (or keeps warm if `keepWarm`). A server is connected only when one of its
+ * tools is actually invoked via `McpCall` (memoized per turn; reused from the warm pool if enabled).
+ *
+ * Per-turn cost: a turn using NO MCP tool → 0 connections; a turn using one → exactly one. Latency
+ * scales with tools-used, not servers-configured. Returns `connect`/`close` for explicit control.
+ */
+declare function mountMcpCatalog(servers?: Record<string, McpServerConfig>, opts?: McpCatalogOptions): Promise<{
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+    connect(name: string): Promise<McpClient>;
+    close(): Promise<void>;
+}>;
 
-export { type HttpServerSpec, HttpTransport, McpAuthError, McpClient, type McpServerConfig, type McpTransport, type MountedMcp, type StdioServerSpec, StdioTransport, mountMcpServer, mountMcpServers };
+export { type HttpServerSpec, HttpTransport, McpAuthError, type McpCatalogOptions, type McpCatalogStore, McpClient, McpPool, type McpServerConfig, type McpTransport, MemMcpCatalog, type MountedMcp, type StdioServerSpec, StdioTransport, mcpConfigKey, mountMcpCatalog, mountMcpDeferred, mountMcpServer, mountMcpServers };

package/dist/mcp.client.js

@@ -1,10 +1,76 @@
 // src/mcp.client.ts
 import { spawn } from "child_process";
+import { createHash } from "crypto";
 
 // src/logging.ts
 import { log } from "libx.js/src/modules/log";
 var forComponent = (name) => log.forComponent(name);
 
+// src/relevance.ts
+var STOP = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "into",
+  "your",
+  "you",
+  "are",
+  "was",
+  "will",
+  "use",
+  "using",
+  "run",
+  "add",
+  "fix",
+  "make",
+  "file",
+  "files",
+  "code",
+  "please",
+  "need",
+  "want",
+  "should",
+  "all"
+]);
+function tokenize(s) {
+  const out = /* @__PURE__ */ new Set();
+  for (const w of String(s ?? "").toLowerCase().match(/[a-z0-9]+/g) ?? []) {
+    if (w.length >= 3 && !STOP.has(w)) out.add(w);
+  }
+  return out;
+}
+function idfWeights(corpus) {
+  const N = corpus.length;
+  if (N === 0) return /* @__PURE__ */ new Map();
+  const df = /* @__PURE__ */ new Map();
+  for (const doc of corpus) for (const t of tokenize(doc)) df.set(t, (df.get(t) ?? 0) + 1);
+  const idf = /* @__PURE__ */ new Map();
+  for (const [t, n] of df) idf.set(t, Math.log((N + 1) / (n + 1)) + 1);
+  return idf;
+}
+function relevanceScore(text, queryTokens, idf) {
+  if (queryTokens.size === 0) return 0;
+  const t = tokenize(text);
+  let score = 0;
+  for (const q of queryTokens) if (t.has(q)) score += idf?.get(q) ?? 1;
+  return score;
+}
+function topByRelevance(items, query, text, k, corpus) {
+  if (!Number.isInteger(k) || k < 1) return { kept: items, rest: [] };
+  if (items.length <= k || !query.trim()) return { kept: items, rest: [] };
+  const q = tokenize(query);
+  if (q.size === 0) return { kept: items.slice(0, k), rest: items.slice(k) };
+  const idf = corpus?.length ? idfWeights(corpus) : void 0;
+  const scored = items.map((x, i) => ({ i, s: relevanceScore(text(x), q, idf) }));
+  scored.sort((a, b) => b.s - a.s || a.i - b.i);
+  const keep = new Set(scored.slice(0, k).map((e) => e.i));
+  return { kept: items.filter((_, i) => keep.has(i)), rest: items.filter((_, i) => !keep.has(i)) };
+}
+
 // src/mcp.ts
 function toResult(result) {
   if (result == null) return { text: "" };
@@ -41,6 +107,78 @@ function mcpToolToAgentTool(spec, callTool, prefix = "mcp__") {
 function mcpToolsToAgentTools(specs, callTool, prefix = "mcp__", filter) {
   return (filter ? specs.filter(filter) : specs).map((s) => mcpToolToAgentTool(s, callTool, prefix));
 }
+function describeSpec(s) {
+  const schema = s.inputSchema ? `
+   args: ${JSON.stringify(s.inputSchema)}` : "";
+  return `${s.name} \u2014 ${s.description ?? "(no description)"}${schema}`;
+}
+function makeMcpToolSearch(specs, callTool, options = {}) {
+  const maxResults = options.maxResults ?? 10;
+  const byName = new Map(specs.map((s) => [s.name, s]));
+  const catalogLine = `${specs.length} MCP tool(s) available \u2014 search by keyword, then call by exact name.`;
+  const searchTool = {
+    name: "ToolSearch",
+    description: `Search the available MCP tools by keyword (${catalogLine}). Returns matching tool names + their argument schemas; call one with \`McpCall\`.`,
+    parameters: { type: "object", required: ["query"], properties: { query: { type: "string", description: "keywords to match against tool name + description" } } },
+    async run({ query }) {
+      const q = String(query ?? "").trim();
+      if (!q) return catalogLine;
+      const { kept } = topByRelevance(specs, q, (s) => `${s.name} ${s.description ?? ""}`, maxResults);
+      if (!kept.length) return `(no MCP tool matches "${q}" \u2014 try broader keywords)`;
+      return kept.map(describeSpec).join("\n");
+    }
+  };
+  const callMcpTool = {
+    name: "McpCall",
+    description: "Call an MCP tool discovered via `ToolSearch`, by its exact name. Pass its arguments as `args`.",
+    parameters: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string", description: "exact tool name from ToolSearch" },
+        args: { type: "object", description: "arguments object for the tool (per its schema)" }
+      }
+    },
+    async run({ name, args }) {
+      const n = String(name ?? "");
+      if (!byName.has(n)) return `Error: unknown MCP tool '${n}'. Use ToolSearch to find valid names.`;
+      const r = toResult(await callTool(n, args ?? {}));
+      return r.images?.length ? r : r.text;
+    }
+  };
+  return [searchTool, callMcpTool];
+}
+function buildMcpCatalog(servers) {
+  const specs = [];
+  const routes = /* @__PURE__ */ new Map();
+  for (const m of servers) {
+    for (const s of m.specs) {
+      const base = `mcp__${m.name}__${s.name}`.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128);
+      let display = base;
+      for (let i = 2; routes.has(display); i++) display = `${base.slice(0, 128 - String(i).length - 1)}_${i}`;
+      specs.push({ name: display, description: s.description, inputSchema: s.inputSchema });
+      routes.set(display, { server: m.name, rawName: s.name });
+    }
+  }
+  return { specs, routes };
+}
+function searchOverCatalog(servers, specs, routes, resolve, options) {
+  const tools = specs.length ? makeMcpToolSearch(specs, (name, args) => {
+    const r = routes.get(name);
+    if (!r) throw new Error(`unknown MCP tool '${name}' \u2014 use ToolSearch to find valid names`);
+    return resolve(r.server, r.rawName, args ?? {});
+  }, options) : [];
+  return { tools, serverNames: servers, toolCount: specs.length };
+}
+function makeMcpToolSearchFromMounted(mounted, options) {
+  const { specs, routes } = buildMcpCatalog(mounted);
+  const byName = new Map(mounted.map((m) => [m.name, m]));
+  return searchOverCatalog(mounted.map((m) => m.name), specs, routes, (server, rawName, args) => byName.get(server).client.callTool(rawName, args), options);
+}
+function makeLazyMcpToolSearch(servers, resolve, options) {
+  const { specs, routes } = buildMcpCatalog(servers);
+  return searchOverCatalog(servers.map((s) => s.name), specs, routes, resolve, options);
+}
 
 // src/mcp.client.ts
 var log2 = forComponent("mcp");
@@ -235,38 +373,211 @@ var McpClient = class {
     await this.transport.close();
   }
 };
-async function mountMcpServer(name, cfg) {
-  const transport = cfg.url ? new HttpTransport({ url: cfg.url, headers: cfg.headers, bearerToken: cfg.bearerToken, timeoutMs: cfg.timeoutMs }) : new StdioTransport({ command: cfg.command, args: cfg.args, env: cfg.env, cwd: cfg.cwd, timeoutMs: cfg.timeoutMs });
-  const client = new McpClient(transport);
-  const init = await client.connect();
-  const specs = await client.listTools();
-  const tools = mcpToolsToAgentTools(specs, (tool, a) => client.callTool(tool, a), `mcp__${name}__`);
-  return { name, client, tools, serverInfo: init?.serverInfo };
+function buildTransport(cfg) {
+  return cfg.url ? new HttpTransport({ url: cfg.url, headers: cfg.headers, bearerToken: cfg.bearerToken, timeoutMs: cfg.timeoutMs }) : new StdioTransport({ command: cfg.command, args: cfg.args, env: cfg.env, cwd: cfg.cwd, timeoutMs: cfg.timeoutMs });
 }
-async function mountMcpServers(servers = {}) {
-  const out = [];
-  for (const [name, cfg] of Object.entries(servers)) {
-    if (!cfg || cfg.disabled) continue;
+function withTimeout(p, ms, label) {
+  if (!ms || ms <= 0) return p;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`MCP "${label}" mount exceeded ${ms}ms`)), ms);
+    timer.unref?.();
+    p.then((v) => {
+      clearTimeout(timer);
+      resolve(v);
+    }, (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+  });
+}
+async function mountWithDeadline(name, cfg, mountTimeoutMs) {
+  const client = new McpClient(buildTransport(cfg));
+  try {
+    return await withTimeout((async () => {
+      const init = await client.connect();
+      const specs = await client.listTools();
+      const tools = mcpToolsToAgentTools(specs, (tool, a) => client.callTool(tool, a), `mcp__${name}__`);
+      return { name, client, tools, specs, serverInfo: init?.serverInfo };
+    })(), mountTimeoutMs, name);
+  } catch (e) {
+    await client.close().catch((err) => log2.debug(`close after failed mount of "${name}": ${err}`));
+    throw e;
+  }
+}
+function mountMcpServer(name, cfg) {
+  return mountWithDeadline(name, cfg);
+}
+function validEntries(servers) {
+  return Object.entries(servers).filter(([name, cfg]) => {
+    if (!cfg || cfg.disabled) return false;
     if (!cfg.command && !cfg.url) {
       log2.warn(`MCP server "${name}" needs a command (stdio) or url (http) \u2014 skipping`);
-      continue;
+      return false;
     }
+    return true;
+  });
+}
+function logMountFailure(name, e) {
+  if (e instanceof McpAuthError) log2.warn(`MCP "${name}" needs-auth: HTTP ${e.status} \u2014 set bearerToken or headers in its config; skipping`);
+  else log2.error(`MCP server "${name}" failed to mount: ${e?.message ?? e}`);
+}
+async function mountMcpServers(servers = {}, opts = {}) {
+  const entries = validEntries(servers);
+  const settled = await Promise.allSettled(entries.map(([name, cfg]) => mountWithDeadline(name, cfg, opts.mountTimeoutMs)));
+  const out = [];
+  settled.forEach((r, i) => {
+    const name = entries[i][0];
+    if (r.status === "fulfilled") {
+      out.push(r.value);
+      log2.info(`MCP "${name}" mounted \u2014 ${r.value.tools.length} tool(s)${r.value.serverInfo?.name ? ` from ${r.value.serverInfo.name}` : ""}`);
+    } else logMountFailure(name, r.reason);
+  });
+  return out;
+}
+async function mountMcpDeferred(servers = {}, options) {
+  const mounted = await mountMcpServers(servers, { mountTimeoutMs: options?.mountTimeoutMs });
+  return { ...makeMcpToolSearchFromMounted(mounted, options), mounted };
+}
+function mcpConfigKey(cfg) {
+  const parts = cfg.url ? ["http", cfg.url, ...Object.keys(cfg.headers ?? {}).sort()] : ["stdio", cfg.command ?? "", ...cfg.args ?? [], cfg.cwd ?? "", ...Object.keys(cfg.env ?? {}).sort()];
+  return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 16);
+}
+var MemMcpCatalog = class {
+  constructor(ttlMs = 5 * 6e4) {
+    this.ttlMs = ttlMs;
+  }
+  ttlMs;
+  m = /* @__PURE__ */ new Map();
+  get(key) {
+    const e = this.m.get(key);
+    if (!e) return null;
+    if (Date.now() > e.exp) {
+      this.m.delete(key);
+      return null;
+    }
+    return e.specs;
+  }
+  set(key, specs) {
+    this.m.set(key, { specs, exp: Date.now() + this.ttlMs });
+  }
+};
+var McpPool = class {
+  constructor(ttlMs = 5 * 6e4) {
+    this.ttlMs = ttlMs;
+  }
+  ttlMs;
+  warm = /* @__PURE__ */ new Map();
+  get(key) {
+    const e = this.warm.get(key);
+    if (!e) return null;
+    this.arm(key, e);
+    return e.client;
+  }
+  put(key, client) {
+    const prev = this.warm.get(key);
+    if (prev) {
+      clearTimeout(prev.timer);
+      if (prev.client !== client) void prev.client.close().catch((err) => log2.debug(`warm-pool replace close failed: ${err}`));
+    }
+    const e = { client, timer: void 0 };
+    this.warm.set(key, e);
+    this.arm(key, e);
+  }
+  arm(key, e) {
+    clearTimeout(e.timer);
+    e.timer = setTimeout(() => {
+      void this.evict(key);
+    }, this.ttlMs);
+    e.timer.unref?.();
+  }
+  async evict(key) {
+    const e = this.warm.get(key);
+    if (!e) return;
+    this.warm.delete(key);
+    await e.client.close().catch((err) => log2.debug(`warm-pool evict close failed: ${err}`));
+  }
+  async closeAll() {
+    for (const e of this.warm.values()) {
+      clearTimeout(e.timer);
+      await e.client.close().catch(() => {
+      });
+    }
+    this.warm.clear();
+  }
+};
+var defaultCatalog = new MemMcpCatalog();
+var defaultPool = new McpPool();
+async function mountMcpCatalog(servers = {}, opts = {}) {
+  const catalog = opts.catalog ?? defaultCatalog;
+  const pool = opts.pool ?? defaultPool;
+  const discovered = (await Promise.all(validEntries(servers).map(async ([name, cfg]) => {
+    const key = mcpConfigKey(cfg);
+    const cached = catalog.get(key);
+    if (cached) return { name, cfg, key, specs: cached };
+    const client = new McpClient(buildTransport(cfg));
     try {
-      const m = await mountMcpServer(name, cfg);
-      out.push(m);
-      log2.info(`MCP "${name}" mounted \u2014 ${m.tools.length} tool(s)${m.serverInfo?.name ? ` from ${m.serverInfo.name}` : ""}`);
+      const specs = await withTimeout((async () => {
+        await client.connect();
+        return client.listTools();
+      })(), opts.mountTimeoutMs, name);
+      catalog.set(key, specs);
+      if (opts.keepWarm && !cfg.url) pool.put(key, client);
+      else await client.close().catch(() => {
+      });
+      return { name, cfg, key, specs };
     } catch (e) {
-      if (e instanceof McpAuthError) log2.warn(`MCP "${name}" needs-auth: HTTP ${e.status} \u2014 set bearerToken or headers in its config; skipping`);
-      else log2.error(`MCP server "${name}" failed to mount: ${e?.message ?? e}`);
+      await client.close().catch(() => {
+      });
+      logMountFailure(name, e);
+      return null;
     }
-  }
-  return out;
+  }))).filter(Boolean);
+  const byName = new Map(discovered.map((d) => [d.name, d]));
+  const inflight = /* @__PURE__ */ new Map();
+  const live = [];
+  const connect = (name) => {
+    let p = inflight.get(name);
+    if (p) return p;
+    p = (async () => {
+      const d = byName.get(name);
+      if (!d) throw new Error(`MCP server '${name}' is not in the catalog`);
+      const warmable = opts.keepWarm && !d.cfg.url;
+      if (warmable) {
+        const w = pool.get(d.key);
+        if (w) return w;
+      }
+      const client = new McpClient(buildTransport(d.cfg));
+      await client.connect();
+      if (warmable) pool.put(d.key, client);
+      else live.push(client);
+      return client;
+    })();
+    inflight.set(name, p);
+    return p;
+  };
+  const search = makeLazyMcpToolSearch(
+    discovered.map((d) => ({ name: d.name, specs: d.specs })),
+    async (server, rawName, args) => (await connect(server)).callTool(rawName, args),
+    opts
+  );
+  const close = async () => {
+    for (const c of live) await c.close().catch(() => {
+    });
+    live.length = 0;
+    inflight.clear();
+  };
+  return { ...search, connect, close };
 }
 export {
   HttpTransport,
   McpAuthError,
   McpClient,
+  McpPool,
+  MemMcpCatalog,
   StdioTransport,
+  mcpConfigKey,
+  mountMcpCatalog,
+  mountMcpDeferred,
   mountMcpServer,
   mountMcpServers
 };