@alfe.ai/mcp-bundler 0.0.1

package/dist/index.cjs

@@ -0,0 +1,460 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/tool-naming.ts
+/**
+* Tool name sanitization and collision handling.
+*
+* OpenClaw constraint: tool names must match `[A-Za-z0-9_-]` and be ≤64 chars.
+* Pattern mirrored from `openclaw/src/agents/pi-bundle-mcp-names.ts`.
+*
+* Strategy: prefix every tool with its server name (`{server}__{tool}`),
+* sanitize disallowed chars to `_`, truncate, then suffix-disambiguate
+* (`-2`, `-3`, ...) on collision.
+*/
+const DISALLOWED = /[^A-Za-z0-9_-]/g;
+const MAX_LEN = 64;
+const SEPARATOR = "__";
+function sanitizeNameSegment(value) {
+	return value.replace(DISALLOWED, "_");
+}
+function buildNamespacedToolName(server, tool) {
+	const base = `${sanitizeNameSegment(server)}${SEPARATOR}${sanitizeNameSegment(tool)}`;
+	if (base.length <= MAX_LEN) return base;
+	const reservedForServer = sanitizeNameSegment(server).length + 2;
+	const toolBudget = Math.max(1, MAX_LEN - reservedForServer);
+	return `${sanitizeNameSegment(server)}${SEPARATOR}${sanitizeNameSegment(tool).slice(0, toolBudget)}`;
+}
+/**
+* Disambiguate a candidate name against an existing set by appending `-2`, `-3`, etc.
+* Mutates nothing; returns the chosen name. Caller is responsible for inserting it
+* into the set.
+*/
+function disambiguateAgainst(candidate, taken) {
+	if (!taken.has(candidate)) return candidate;
+	for (let i = 2; i < 1e3; i += 1) {
+		const suffix = `-${i.toString()}`;
+		const room = MAX_LEN - suffix.length;
+		const next = `${candidate.length > room ? candidate.slice(0, room) : candidate}${suffix}`;
+		if (!taken.has(next)) return next;
+	}
+	return `${candidate.slice(0, MAX_LEN - 6)}-x${(taken.size % 1e3).toString().padStart(3, "0")}`;
+}
+//#endregion
+//#region src/connection.ts
+/** Env keys OpenClaw rejects from stdio MCP env blocks. Filter them out before spawning. */
+const STDIO_ENV_DENYLIST = new Set([
+	"NODE_OPTIONS",
+	"PYTHONSTARTUP",
+	"PYTHONPATH",
+	"PERL5OPT",
+	"RUBYOPT",
+	"SHELLOPTS",
+	"PS4"
+]);
+function sanitizeStdioEnv(env) {
+	if (!env) return {};
+	const safe = {};
+	for (const [k, v] of Object.entries(env)) {
+		if (STDIO_ENV_DENYLIST.has(k)) continue;
+		safe[k] = v;
+	}
+	return safe;
+}
+/**
+* One Connection per MCP server. Owns lifecycle (lazy-spawn, close, refresh-lock).
+* Refresh-lock pattern adapted from AIWerk `index.ts:219-250` — prevents
+* reconnect + `notifications/tools/list_changed` race.
+*/
+var Connection = class {
+	name;
+	config;
+	deps;
+	logger;
+	client;
+	tools = [];
+	connectInFlight;
+	refreshInFlight = false;
+	refreshQueued = false;
+	lastUsedAt = Date.now();
+	constructor(params) {
+		this.name = params.name;
+		this.config = params.config;
+		this.deps = params.deps;
+		this.logger = params.logger;
+	}
+	/** Returns the most recent known tool list. May be empty if the server hasn't connected yet. */
+	snapshotTools() {
+		return this.tools;
+	}
+	/** Whether an MCP child process / remote connection has been established. */
+	isConnected() {
+		return this.client !== void 0;
+	}
+	/** Idle timestamp for reaping. */
+	idleSinceMs() {
+		return Date.now() - this.lastUsedAt;
+	}
+	/**
+	* Lazy connect + tool discovery. Safe to call concurrently; in-flight
+	* connects coalesce.
+	*/
+	async ensureConnected() {
+		if (this.client) return;
+		if (this.connectInFlight) return this.connectInFlight;
+		this.connectInFlight = this.connectAndDiscover().finally(() => {
+			this.connectInFlight = void 0;
+		});
+		return this.connectInFlight;
+	}
+	async connectAndDiscover() {
+		const safeConfig = "command" in this.config ? {
+			...this.config,
+			env: sanitizeStdioEnv(this.config.env)
+		} : this.config;
+		this.logger?.debug(`[mcp-bundler] connecting server "${this.name}"`);
+		const client = await this.deps.connect(safeConfig);
+		try {
+			const advertised = await client.listTools();
+			this.client = client;
+			this.tools = advertised.map((t) => ({
+				prefixed: buildNamespacedToolName(this.name, t.name),
+				server: this.name,
+				original: t.name,
+				label: (t.description ?? t.name).slice(0, 80),
+				description: t.description ?? "",
+				parameters: t.inputSchema
+			}));
+			this.lastUsedAt = Date.now();
+			this.logger?.info(`[mcp-bundler] server "${this.name}" connected, ${this.tools.length.toString()} tool(s)`);
+		} catch (err) {
+			await client.close().catch(() => void 0);
+			throw err;
+		}
+	}
+	/**
+	* Re-discover tools. Used on reconnect or `tools/list_changed` notification.
+	* Refresh-lock collapses concurrent refreshes; if one is in flight, the next
+	* is queued (max 1 queued, since N>1 queued provides no extra freshness).
+	*/
+	async refresh() {
+		if (!this.client) return this.ensureConnected();
+		if (this.refreshInFlight) {
+			this.refreshQueued = true;
+			return;
+		}
+		this.refreshInFlight = true;
+		try {
+			this.tools = (await this.client.listTools()).map((t) => ({
+				prefixed: buildNamespacedToolName(this.name, t.name),
+				server: this.name,
+				original: t.name,
+				label: (t.description ?? t.name).slice(0, 80),
+				description: t.description ?? "",
+				parameters: t.inputSchema
+			}));
+			this.logger?.debug(`[mcp-bundler] server "${this.name}" refreshed, ${this.tools.length.toString()} tool(s)`);
+		} finally {
+			this.refreshInFlight = false;
+			if (this.refreshQueued) {
+				this.refreshQueued = false;
+				this.refresh().catch((err) => {
+					this.logger?.warn(`[mcp-bundler] queued refresh for "${this.name}" failed`, { err: err instanceof Error ? err.message : String(err) });
+				});
+			}
+		}
+	}
+	async callTool(originalName, args, signal) {
+		await this.ensureConnected();
+		if (!this.client) throw new Error(`server "${this.name}" failed to connect`);
+		this.lastUsedAt = Date.now();
+		return this.client.callTool(originalName, args, signal ? { signal } : void 0);
+	}
+	/**
+	* Close the underlying transport. Idempotent. If a connect is in flight
+	* (warmup racing with reconcile-removal), wait for it to settle and then
+	* close the client it produced — otherwise the child process is orphaned.
+	*/
+	async close() {
+		if (this.connectInFlight) await this.connectInFlight.catch(() => void 0);
+		const c = this.client;
+		this.client = void 0;
+		this.tools = [];
+		if (c) await c.close().catch((err) => {
+			this.logger?.warn(`[mcp-bundler] close error for "${this.name}"`, { err: err instanceof Error ? err.message : String(err) });
+		});
+	}
+	/**
+	* Stable hash of the config for diff detection in `reconcile`.
+	* Two configs with the same hash are equivalent (no restart needed).
+	*/
+	configFingerprint() {
+		return JSON.stringify(this.config);
+	}
+};
+/**
+* Build the production `connect` factory using the official MCP SDK.
+* Kept in a separate function so tests can substitute a mock without
+* pulling the SDK into the test bundle.
+*/
+async function defaultConnect(server) {
+	const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+	const client = new Client({
+		name: "alfe-mcp-bundler",
+		version: "0.0.0"
+	}, {});
+	if ("command" in server) {
+		const stdio = server;
+		const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+		const transport = new StdioClientTransport({
+			command: stdio.command,
+			args: stdio.args ?? [],
+			env: { ...sanitizeStdioEnv(stdio.env) },
+			cwd: stdio.cwd
+		});
+		await client.connect(transport);
+	} else {
+		const remote = server;
+		if (remote.transport === "streamable-http") {
+			const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+			const transport = new StreamableHTTPClientTransport(new URL(remote.url), { requestInit: { headers: remote.headers ?? {} } });
+			await client.connect(transport);
+		} else {
+			const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
+			const transport = new SSEClientTransport(new URL(remote.url), { requestInit: { headers: remote.headers ?? {} } });
+			await client.connect(transport);
+		}
+	}
+	return {
+		async listTools() {
+			return (await client.listTools()).tools.map((t) => ({
+				name: t.name,
+				description: t.description,
+				inputSchema: t.inputSchema
+			}));
+		},
+		async callTool(name, args, opts) {
+			return await client.callTool({
+				name,
+				arguments: args
+			}, void 0, opts);
+		},
+		async close() {
+			await client.close();
+		}
+	};
+}
+//#endregion
+//#region src/bundler.ts
+const DEFAULT_IDLE_TTL_MS = 600 * 1e3;
+const DEFAULT_IDLE_SWEEP_INTERVAL_MS = 60 * 1e3;
+/**
+* Provider-agnostic MCP server bundler. Holds N MCP server connections,
+* exposes a unified namespaced tool catalog, and routes calls to the right
+* server.
+*
+* Designed to be embedded in any host (OpenClaw plugin, AI proxy, Lambda).
+* Public surface is intentionally synchronous where the host needs sync
+* (snapshot, listTools), async only where I/O is unavoidable.
+*/
+var McpBundler = class {
+	logger;
+	connections = /* @__PURE__ */ new Map();
+	idleTtlMs;
+	idleSweepIntervalMs;
+	idleSweepTimer;
+	deps;
+	disposed = false;
+	reconcileLatch = Promise.resolve();
+	constructor(opts = {}, deps) {
+		this.logger = opts.logger;
+		this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+		this.idleSweepIntervalMs = opts.idleSweepIntervalMs ?? DEFAULT_IDLE_SWEEP_INTERVAL_MS;
+		this.deps = deps ?? { connect: defaultConnect };
+		if (this.idleTtlMs > 0) this.startIdleSweep();
+	}
+	/**
+	* Diff `desired` against current connections, spawn newcomers, dispose
+	* removals, hot-restart on config change. Pull-based — call whenever the
+	* host's config snapshot may have changed. Cheap if no diff.
+	*
+	* Lazy: newly-added servers are NOT eagerly connected; they connect on the
+	* first `callTool()` (or first `listTools()` after `forceDiscover()`).
+	* This avoids paying spawn cost for servers the agent never uses.
+	*/
+	async reconcile(desired) {
+		if (this.disposed) throw new Error("McpBundler: disposed");
+		const slot = this.reconcileLatch.then(async () => this.doReconcile(desired));
+		this.reconcileLatch = slot.catch(() => void 0);
+		return slot;
+	}
+	async doReconcile(desired) {
+		if (this.disposed) throw new Error("McpBundler: disposed");
+		const desiredNames = new Set(Object.keys(desired));
+		const currentNames = new Set(this.connections.keys());
+		const added = [];
+		const removed = [];
+		const changed = [];
+		const unchanged = [];
+		for (const name of currentNames) if (!desiredNames.has(name)) {
+			const conn = this.connections.get(name);
+			this.connections.delete(name);
+			if (conn) await conn.close();
+			removed.push(name);
+		}
+		for (const [name, config] of Object.entries(desired)) {
+			const existing = this.connections.get(name);
+			if (!existing) {
+				this.connections.set(name, new Connection({
+					name,
+					config,
+					deps: this.deps,
+					logger: this.logger
+				}));
+				added.push(name);
+				continue;
+			}
+			const nextFingerprint = JSON.stringify(config);
+			if (existing.configFingerprint() !== nextFingerprint) {
+				await existing.close();
+				this.connections.set(name, new Connection({
+					name,
+					config,
+					deps: this.deps,
+					logger: this.logger
+				}));
+				changed.push(name);
+			} else unchanged.push(name);
+		}
+		if (added.length || removed.length || changed.length) this.logger?.info("[mcp-bundler] reconciled", {
+			added: added.length,
+			removed: removed.length,
+			changed: changed.length,
+			unchanged: unchanged.length
+		});
+		return {
+			added,
+			removed,
+			changed,
+			unchanged
+		};
+	}
+	/**
+	* Synchronous snapshot of all currently-known tools across connected servers.
+	* Servers that have not connected yet contribute nothing. Intended for use
+	* inside OpenClaw's plugin tool factory which must be sync.
+	*
+	* Tool names are namespaced and disambiguated (suffix `-2`, `-3` on collision)
+	* so cross-server name clashes never produce duplicate registrations.
+	*/
+	listTools() {
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		for (const conn of this.connections.values()) for (const tool of conn.snapshotTools()) {
+			const finalName = disambiguateAgainst(tool.prefixed, seen);
+			seen.add(finalName);
+			out.push(finalName === tool.prefixed ? tool : {
+				...tool,
+				prefixed: finalName
+			});
+		}
+		return out;
+	}
+	/**
+	* Eagerly connect to every configured server and discover tools. Used by
+	* hosts that want a hot list rather than the lazy default. Errors are
+	* swallowed per-server (logged), so one bad server doesn't fail the batch.
+	*/
+	async warmup() {
+		if (this.disposed) return;
+		await Promise.allSettled(Array.from(this.connections.values()).map(async (conn) => {
+			try {
+				await conn.ensureConnected();
+			} catch (err) {
+				this.logger?.warn(`[mcp-bundler] warmup failed for "${conn.name}"`, { err: err instanceof Error ? err.message : String(err) });
+			}
+		}));
+	}
+	/**
+	* Invoke a tool by its namespaced name. Routes to the originating server.
+	* Errors are returned as `{ isError: true, content: [...] }` so a failing
+	* tool doesn't crash the host.
+	*/
+	async callTool(prefixed, args, signal) {
+		if (this.disposed) return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: "mcp-bundler disposed"
+			}]
+		};
+		const route = this.routeToolName(prefixed);
+		if (!route) return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: `unknown tool: ${prefixed}`
+			}]
+		};
+		try {
+			return await route.connection.callTool(route.original, args, signal);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			this.logger?.error(`[mcp-bundler] tool call failed for "${prefixed}"`, { err: msg });
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `tool ${prefixed} failed: ${msg}`
+				}]
+			};
+		}
+	}
+	/**
+	* Resolve a namespaced tool name back to its server connection and original
+	* tool name. Returns undefined if the tool is not currently advertised.
+	*/
+	routeToolName(prefixed) {
+		for (const conn of this.connections.values()) for (const tool of conn.snapshotTools()) if (tool.prefixed === prefixed) return {
+			connection: conn,
+			original: tool.original
+		};
+	}
+	/**
+	* Tear down all connections and stop background tasks. Idempotent.
+	* Call from `registerRuntimeLifecycle({ cleanup })` in the host plugin.
+	*/
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.idleSweepTimer) {
+			clearInterval(this.idleSweepTimer);
+			this.idleSweepTimer = void 0;
+		}
+		await Promise.allSettled(Array.from(this.connections.values()).map((c) => c.close()));
+		this.connections.clear();
+	}
+	startIdleSweep() {
+		this.idleSweepTimer = setInterval(() => {
+			this.sweepIdle().catch((err) => {
+				this.logger?.warn("[mcp-bundler] idle sweep error", { err: err instanceof Error ? err.message : String(err) });
+			});
+		}, this.idleSweepIntervalMs);
+		if (typeof this.idleSweepTimer === "object" && "unref" in this.idleSweepTimer) this.idleSweepTimer.unref();
+	}
+	async sweepIdle() {
+		if (this.idleTtlMs <= 0) return;
+		const targets = [];
+		for (const conn of this.connections.values()) if (conn.isConnected() && conn.idleSinceMs() > this.idleTtlMs) targets.push(conn);
+		if (targets.length === 0) return;
+		this.logger?.debug(`[mcp-bundler] reaping ${targets.length.toString()} idle server(s)`);
+		await Promise.allSettled(targets.map((c) => c.close()));
+	}
+};
+//#endregion
+exports.Connection = Connection;
+exports.McpBundler = McpBundler;
+exports.STDIO_ENV_DENYLIST = STDIO_ENV_DENYLIST;
+exports.buildNamespacedToolName = buildNamespacedToolName;
+exports.defaultConnect = defaultConnect;
+exports.disambiguateAgainst = disambiguateAgainst;
+exports.sanitizeNameSegment = sanitizeNameSegment;
+exports.sanitizeStdioEnv = sanitizeStdioEnv;

package/dist/index.d.cts

@@ -0,0 +1,241 @@
+//#region src/types.d.ts
+/**
+ * Shape of a single MCP server entry — matches OpenClaw `mcp.servers.{name}`.
+ * Either a stdio child process spec or a remote URL spec.
+ */
+type McpServerConfig = StdioServerConfig | RemoteServerConfig;
+interface StdioServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+}
+interface RemoteServerConfig {
+  url: string;
+  transport?: 'sse' | 'streamable-http';
+  headers?: Record<string, string>;
+  connectionTimeoutMs?: number;
+}
+type McpTransportKind = 'stdio' | 'sse' | 'streamable-http';
+/**
+ * One tool surfaced from one MCP server, after namespacing.
+ */
+interface McpToolDescriptor {
+  /** Namespaced name as the LLM sees it: `{serverName}__{originalName}`, sanitized + max 64 chars. */
+  prefixed: string;
+  /** Server name (key in `mcp.servers.*`). */
+  server: string;
+  /** Original tool name as advertised by the MCP server. */
+  original: string;
+  /** Human label for the tool (truncated description, suitable for UI). */
+  label: string;
+  /** Full description from the MCP server. */
+  description: string;
+  /** JSON Schema (object) for tool parameters. */
+  parameters: Record<string, unknown>;
+}
+interface ReconcileDiff {
+  added: string[];
+  removed: string[];
+  changed: string[];
+  unchanged: string[];
+}
+interface Logger {
+  debug: (msg: string, meta?: Record<string, unknown>) => void;
+  info: (msg: string, meta?: Record<string, unknown>) => void;
+  warn: (msg: string, meta?: Record<string, unknown>) => void;
+  error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+interface McpToolCallResult {
+  content: Record<string, unknown>[];
+  isError?: boolean;
+}
+interface BundlerOptions {
+  logger?: Logger;
+  /** Idle TTL for spawned children (ms). 0 disables. Default: 600_000 (10 min). */
+  idleTtlMs?: number;
+  /** Sweep interval for idle reaping (ms). Default: 60_000 (1 min). */
+  idleSweepIntervalMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/connection.d.ts
+/** Env keys OpenClaw rejects from stdio MCP env blocks. Filter them out before spawning. */
+declare const STDIO_ENV_DENYLIST: Set<string>;
+declare function sanitizeStdioEnv(env: Record<string, string> | undefined): Record<string, string>;
+interface ConnectionDeps {
+  /**
+   * Factory for an MCP Client connected to the given config. Injected so tests
+   * can mock without spawning real processes. In production this wraps
+   * `@modelcontextprotocol/sdk/client`.
+   */
+  connect: (server: McpServerConfig) => Promise<McpClientHandle>;
+}
+/**
+ * Minimal interface our connection layer needs from an MCP client. Mirrors
+ * the @modelcontextprotocol/sdk Client surface but kept narrow so we can
+ * mock cleanly in tests.
+ */
+interface McpClientHandle {
+  listTools(): Promise<{
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+  }[]>;
+  callTool(name: string, args: unknown, opts?: {
+    signal?: AbortSignal;
+  }): Promise<McpToolCallResult>;
+  close(): Promise<void>;
+}
+/**
+ * One Connection per MCP server. Owns lifecycle (lazy-spawn, close, refresh-lock).
+ * Refresh-lock pattern adapted from AIWerk `index.ts:219-250` — prevents
+ * reconnect + `notifications/tools/list_changed` race.
+ */
+declare class Connection {
+  readonly name: string;
+  readonly config: McpServerConfig;
+  private readonly deps;
+  private readonly logger;
+  private client;
+  private tools;
+  private connectInFlight;
+  private refreshInFlight;
+  private refreshQueued;
+  private lastUsedAt;
+  constructor(params: {
+    name: string;
+    config: McpServerConfig;
+    deps: ConnectionDeps;
+    logger?: Logger;
+  });
+  /** Returns the most recent known tool list. May be empty if the server hasn't connected yet. */
+  snapshotTools(): McpToolDescriptor[];
+  /** Whether an MCP child process / remote connection has been established. */
+  isConnected(): boolean;
+  /** Idle timestamp for reaping. */
+  idleSinceMs(): number;
+  /**
+   * Lazy connect + tool discovery. Safe to call concurrently; in-flight
+   * connects coalesce.
+   */
+  ensureConnected(): Promise<void>;
+  private connectAndDiscover;
+  /**
+   * Re-discover tools. Used on reconnect or `tools/list_changed` notification.
+   * Refresh-lock collapses concurrent refreshes; if one is in flight, the next
+   * is queued (max 1 queued, since N>1 queued provides no extra freshness).
+   */
+  refresh(): Promise<void>;
+  callTool(originalName: string, args: unknown, signal?: AbortSignal): Promise<McpToolCallResult>;
+  /**
+   * Close the underlying transport. Idempotent. If a connect is in flight
+   * (warmup racing with reconcile-removal), wait for it to settle and then
+   * close the client it produced — otherwise the child process is orphaned.
+   */
+  close(): Promise<void>;
+  /**
+   * Stable hash of the config for diff detection in `reconcile`.
+   * Two configs with the same hash are equivalent (no restart needed).
+   */
+  configFingerprint(): string;
+}
+/**
+ * Build the production `connect` factory using the official MCP SDK.
+ * Kept in a separate function so tests can substitute a mock without
+ * pulling the SDK into the test bundle.
+ */
+declare function defaultConnect(server: McpServerConfig): Promise<McpClientHandle>;
+//# sourceMappingURL=connection.d.ts.map
+//#endregion
+//#region src/bundler.d.ts
+/**
+ * Provider-agnostic MCP server bundler. Holds N MCP server connections,
+ * exposes a unified namespaced tool catalog, and routes calls to the right
+ * server.
+ *
+ * Designed to be embedded in any host (OpenClaw plugin, AI proxy, Lambda).
+ * Public surface is intentionally synchronous where the host needs sync
+ * (snapshot, listTools), async only where I/O is unavoidable.
+ */
+declare class McpBundler {
+  private readonly logger;
+  private readonly connections;
+  private readonly idleTtlMs;
+  private readonly idleSweepIntervalMs;
+  private idleSweepTimer;
+  private readonly deps;
+  private disposed;
+  private reconcileLatch;
+  constructor(opts?: BundlerOptions, deps?: ConnectionDeps);
+  /**
+   * Diff `desired` against current connections, spawn newcomers, dispose
+   * removals, hot-restart on config change. Pull-based — call whenever the
+   * host's config snapshot may have changed. Cheap if no diff.
+   *
+   * Lazy: newly-added servers are NOT eagerly connected; they connect on the
+   * first `callTool()` (or first `listTools()` after `forceDiscover()`).
+   * This avoids paying spawn cost for servers the agent never uses.
+   */
+  reconcile(desired: Record<string, McpServerConfig>): Promise<ReconcileDiff>;
+  private doReconcile;
+  /**
+   * Synchronous snapshot of all currently-known tools across connected servers.
+   * Servers that have not connected yet contribute nothing. Intended for use
+   * inside OpenClaw's plugin tool factory which must be sync.
+   *
+   * Tool names are namespaced and disambiguated (suffix `-2`, `-3` on collision)
+   * so cross-server name clashes never produce duplicate registrations.
+   */
+  listTools(): McpToolDescriptor[];
+  /**
+   * Eagerly connect to every configured server and discover tools. Used by
+   * hosts that want a hot list rather than the lazy default. Errors are
+   * swallowed per-server (logged), so one bad server doesn't fail the batch.
+   */
+  warmup(): Promise<void>;
+  /**
+   * Invoke a tool by its namespaced name. Routes to the originating server.
+   * Errors are returned as `{ isError: true, content: [...] }` so a failing
+   * tool doesn't crash the host.
+   */
+  callTool(prefixed: string, args: unknown, signal?: AbortSignal): Promise<McpToolCallResult>;
+  /**
+   * Resolve a namespaced tool name back to its server connection and original
+   * tool name. Returns undefined if the tool is not currently advertised.
+   */
+  private routeToolName;
+  /**
+   * Tear down all connections and stop background tasks. Idempotent.
+   * Call from `registerRuntimeLifecycle({ cleanup })` in the host plugin.
+   */
+  dispose(): Promise<void>;
+  private startIdleSweep;
+  private sweepIdle;
+}
+//# sourceMappingURL=bundler.d.ts.map
+//#endregion
+//#region src/tool-naming.d.ts
+/**
+ * Tool name sanitization and collision handling.
+ *
+ * OpenClaw constraint: tool names must match `[A-Za-z0-9_-]` and be ≤64 chars.
+ * Pattern mirrored from `openclaw/src/agents/pi-bundle-mcp-names.ts`.
+ *
+ * Strategy: prefix every tool with its server name (`{server}__{tool}`),
+ * sanitize disallowed chars to `_`, truncate, then suffix-disambiguate
+ * (`-2`, `-3`, ...) on collision.
+ */
+declare function sanitizeNameSegment(value: string): string;
+declare function buildNamespacedToolName(server: string, tool: string): string;
+/**
+ * Disambiguate a candidate name against an existing set by appending `-2`, `-3`, etc.
+ * Mutates nothing; returns the chosen name. Caller is responsible for inserting it
+ * into the set.
+ */
+declare function disambiguateAgainst(candidate: string, taken: ReadonlySet<string>): string;
+//# sourceMappingURL=tool-naming.d.ts.map
+
+//#endregion
+export { type BundlerOptions, Connection, type ConnectionDeps, type Logger, McpBundler, type McpClientHandle, type McpServerConfig, type McpToolCallResult, type McpToolDescriptor, type McpTransportKind, type ReconcileDiff, type RemoteServerConfig, STDIO_ENV_DENYLIST, type StdioServerConfig, buildNamespacedToolName, defaultConnect, disambiguateAgainst, sanitizeNameSegment, sanitizeStdioEnv };
+//# sourceMappingURL=index.d.cts.map