@mcp-z/client 1.0.0

package/dist/cjs/spawn/spawn-server.js

@@ -0,0 +1,410 @@
+/**
+ * Low-level single server spawning utilities.
+ * Provides core process spawning with path resolution, environment management, and lifecycle control.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "spawnProcess", {
+    enumerable: true,
+    get: function() {
+        return spawnProcess;
+    }
+});
+var _child_process = require("child_process");
+var _process = /*#__PURE__*/ _interop_require_wildcard(require("process"));
+var _loggerts = require("../utils/logger.js");
+var _pathutilsts = require("../utils/path-utils.js");
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+function _iterable_to_array_limit(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function _sliced_to_array(arr, i) {
+    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Normalize environment variables by merging with process.env and filtering undefined values.
+ */ function normalizeEnv(env) {
+    var merged = _object_spread({}, _process.env, env || {});
+    var result = {};
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = Object.entries(merged)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array(_step.value, 2), key = _step_value[0], value = _step_value[1];
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return result;
+}
+function spawnProcess(opts) {
+    var _opts_cwd, _opts_stdio, _opts_shell;
+    var name = opts.name;
+    var command = opts.command;
+    var cwd = (_opts_cwd = opts.cwd) !== null && _opts_cwd !== void 0 ? _opts_cwd : _process.cwd();
+    var stdio = (_opts_stdio = opts.stdio) !== null && _opts_stdio !== void 0 ? _opts_stdio : 'inherit';
+    var shell = (_opts_shell = opts.shell) !== null && _opts_shell !== void 0 ? _opts_shell : _process.platform === 'win32';
+    // Resolve paths in args relative to the working directory
+    var args = opts.args ? (0, _pathutilsts.resolveArgsPaths)(opts.args, cwd) : [];
+    // Merge environment variables
+    var env = normalizeEnv(opts.env);
+    // Create resolved config for return value
+    var resolvedConfig = {
+        name: name,
+        command: command,
+        args: args,
+        cwd: cwd,
+        env: env,
+        stdio: stdio,
+        shell: shell
+    };
+    // Log spawn operation
+    _loggerts.logger.info("[".concat(name, "] → ").concat(command, " ").concat(args.join(' ')));
+    // Spawn the process
+    var spawnOpts = {
+        cwd: cwd,
+        env: env,
+        stdio: stdio,
+        shell: shell
+    };
+    var child = (0, _child_process.spawn)(command, args, spawnOpts);
+    // Attach lifecycle logging
+    child.on('exit', function(code, sig) {
+        return _loggerts.logger.info("[".concat(name, "] exited (code=").concat(code, ", signal=").concat(sig || 'none', ")"));
+    });
+    child.on('error', function(err) {
+        return _loggerts.logger.info("[".concat(name, "] process error: ").concat(err.message));
+    });
+    // Create stop function with graceful shutdown
+    var stop = function() {
+        var signal = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : 'SIGINT', _$opts = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+        return _async_to_generator(function() {
+            var _opts_timeoutMs, timeoutMs, closePromise;
+            return _ts_generator(this, function(_state) {
+                // If already exited, return immediately
+                if (child.exitCode !== null || child.signalCode !== null) {
+                    return [
+                        2,
+                        {
+                            timedOut: false,
+                            killed: false
+                        }
+                    ];
+                }
+                timeoutMs = (_opts_timeoutMs = _$opts.timeoutMs) !== null && _opts_timeoutMs !== void 0 ? _opts_timeoutMs : 500;
+                // Wait for 'close' event (process exit + stdio streams closed)
+                // This is better than 'exit' because it ensures stdio is fully cleaned up
+                closePromise = new Promise(function(resolve) {
+                    var isResolved = false;
+                    var wasKilled = false;
+                    var resolveOnce = function(timedOut) {
+                        if (isResolved) return;
+                        isResolved = true;
+                        clearTimeout(timeout);
+                        resolve({
+                            timedOut: timedOut,
+                            killed: wasKilled
+                        });
+                    };
+                    // Set timeout for forceful kill
+                    var timeout = setTimeout(function() {
+                        try {
+                            // Check again before SIGKILL
+                            if (child.exitCode === null && !child.killed) {
+                                child.kill('SIGKILL');
+                                wasKilled = true;
+                            }
+                        } catch (_) {}
+                        // Even if kill fails, resolve
+                        resolveOnce(true);
+                    }, timeoutMs);
+                    // Listen for 'close' event (not 'exit') to wait for stdio close
+                    child.once('close', function() {
+                        resolveOnce(false);
+                    });
+                    // Also listen for 'error' event in case spawn failed
+                    // This prevents promise from hanging forever if process never started
+                    child.once('error', function() {
+                        resolveOnce(false);
+                    });
+                    // Send graceful shutdown signal
+                    try {
+                        // Check one more time before killing
+                        if (child.exitCode !== null) {
+                            resolveOnce(false);
+                            return;
+                        }
+                        var killed = child.kill(signal);
+                        // If kill returned false, process already exited
+                        if (!killed) {
+                            resolveOnce(false);
+                        }
+                    } catch (_err) {
+                        // If kill throws, process is gone or unreachable
+                        resolveOnce(false);
+                    }
+                });
+                return [
+                    2,
+                    closePromise
+                ];
+            });
+        })();
+    };
+    return {
+        config: resolvedConfig,
+        process: child,
+        close: stop
+    };
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/spawn/spawn-server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/spawn/spawn-server.ts"],"sourcesContent":["/**\n * Low-level single server spawning utilities.\n * Provides core process spawning with path resolution, environment management, and lifecycle control.\n */\n\nimport { type ChildProcess, type SpawnOptions, type StdioOptions, spawn } from 'child_process';\nimport * as process from 'process';\nimport { logger } from '../utils/logger.ts';\nimport { resolveArgsPaths } from '../utils/path-utils.ts';\n\n/**\n * Options for spawning a single server process.\n * @internal\n */\nexport interface SpawnProcessOptions {\n  /** Server name for logging */\n  name: string;\n  /** Command to execute (e.g., 'node', 'npx') */\n  command: string;\n  /** Command arguments (paths will be resolved relative to cwd) */\n  args?: string[];\n  /** Working directory (must be absolute path) */\n  cwd?: string;\n  /** Additional environment variables (merged with process.env) */\n  env?: Record<string, string>;\n  /** Standard I/O configuration */\n  stdio?: StdioOptions;\n  /** Use shell for command execution (default: false, true on Windows) */\n  shell?: boolean;\n}\n\n/**\n * Handle to a spawned server process.\n * Provides access to the process, resolved config, and lifecycle control.\n * @hidden\n */\nexport interface ServerProcess {\n  /**\n   * The resolved server configuration that was actually used.\n   * Useful for debugging and understanding what was spawned.\n   */\n  config: {\n    name: string;\n    command: string;\n    args: string[];\n    cwd: string;\n    env: Record<string, string>;\n    stdio: StdioOptions;\n    shell: boolean;\n  };\n\n  /**\n   * The spawned child process.\n   */\n  process: ChildProcess;\n\n  /**\n   * Close the server gracefully.\n   * Sends the specified signal (default: SIGINT), then SIGKILL after timeout.\n   *\n   * @param signal - Signal to send (default: SIGINT)\n   * @param opts - Options including timeout\n   * @returns Promise resolving to whether the process timed out and was force-killed\n   */\n  close: (signal?: NodeJS.Signals, opts?: { timeoutMs?: number }) => Promise<{ timedOut: boolean; killed: boolean }>;\n}\n\n/**\n * Normalize environment variables by merging with process.env and filtering undefined values.\n */\nfunction normalizeEnv(env?: Record<string, string>): Record<string, string> {\n  const merged = { ...process.env, ...(env || {}) };\n  const result: Record<string, string> = {};\n  for (const [key, value] of Object.entries(merged)) {\n    if (value !== undefined) {\n      result[key] = value;\n    }\n  }\n  return result;\n}\n\n/**\n * Spawn a single server process with path resolution and environment management.\n *\n * @internal\n * @param opts - Server spawn options\n * @returns ServerProcess handle with resolved config, process, and stop function\n *\n * @example\n * const handle = spawnProcess({\n *   name: 'echo',\n *   command: 'node',\n *   args: ['./bin/server.js', '--port', '3000'],\n *   cwd: '/home/user/project/test/lib/servers/echo',\n *   env: { LOG_LEVEL: 'error' }\n * });\n *\n * // Later...\n * await handle.close();\n */\nexport function spawnProcess(opts: SpawnProcessOptions): ServerProcess {\n  const name = opts.name;\n  const command = opts.command;\n  const cwd = opts.cwd ?? process.cwd();\n  const stdio = opts.stdio ?? 'inherit';\n  const shell = opts.shell ?? process.platform === 'win32';\n\n  // Resolve paths in args relative to the working directory\n  const args = opts.args ? resolveArgsPaths(opts.args, cwd) : [];\n\n  // Merge environment variables\n  const env = normalizeEnv(opts.env);\n\n  // Create resolved config for return value\n  const resolvedConfig = {\n    name,\n    command,\n    args,\n    cwd,\n    env,\n    stdio,\n    shell,\n  };\n\n  // Log spawn operation\n  logger.info(`[${name}] → ${command} ${args.join(' ')}`);\n\n  // Spawn the process\n  const spawnOpts: SpawnOptions = { cwd, env, stdio, shell };\n  const child = spawn(command, args, spawnOpts);\n\n  // Attach lifecycle logging\n  child.on('exit', (code, sig) => logger.info(`[${name}] exited (code=${code}, signal=${sig || 'none'})`));\n  child.on('error', (err) => logger.info(`[${name}] process error: ${err.message}`));\n\n  // Create stop function with graceful shutdown\n  const stop = async (signal: NodeJS.Signals = 'SIGINT', opts: { timeoutMs?: number } = {}): Promise<{ timedOut: boolean; killed: boolean }> => {\n    // If already exited, return immediately\n    if (child.exitCode !== null || child.signalCode !== null) {\n      return { timedOut: false, killed: false };\n    }\n\n    const timeoutMs = opts.timeoutMs ?? 500;\n\n    // Wait for 'close' event (process exit + stdio streams closed)\n    // This is better than 'exit' because it ensures stdio is fully cleaned up\n    const closePromise = new Promise<{ timedOut: boolean; killed: boolean }>((resolve) => {\n      let isResolved = false;\n      let wasKilled = false;\n\n      const resolveOnce = (timedOut: boolean) => {\n        if (isResolved) return;\n        isResolved = true;\n        clearTimeout(timeout);\n        resolve({ timedOut, killed: wasKilled });\n      };\n\n      // Set timeout for forceful kill\n      const timeout = setTimeout(() => {\n        try {\n          // Check again before SIGKILL\n          if (child.exitCode === null && !child.killed) {\n            child.kill('SIGKILL');\n            wasKilled = true;\n          }\n        } catch (_) {}\n        // Even if kill fails, resolve\n        resolveOnce(true);\n      }, timeoutMs);\n\n      // Listen for 'close' event (not 'exit') to wait for stdio close\n      child.once('close', () => {\n        resolveOnce(false);\n      });\n\n      // Also listen for 'error' event in case spawn failed\n      // This prevents promise from hanging forever if process never started\n      child.once('error', () => {\n        resolveOnce(false);\n      });\n\n      // Send graceful shutdown signal\n      try {\n        // Check one more time before killing\n        if (child.exitCode !== null) {\n          resolveOnce(false);\n          return;\n        }\n\n        const killed = child.kill(signal);\n        // If kill returned false, process already exited\n        if (!killed) {\n          resolveOnce(false);\n        }\n      } catch (_err) {\n        // If kill throws, process is gone or unreachable\n        resolveOnce(false);\n      }\n    });\n\n    return closePromise;\n  };\n\n  return {\n    config: resolvedConfig,\n    process: child,\n    close: stop,\n  };\n}\n"],"names":["spawnProcess","normalizeEnv","env","merged","process","result","Object","entries","key","value","undefined","opts","name","command","cwd","stdio","shell","platform","args","resolveArgsPaths","resolvedConfig","logger","info","join","spawnOpts","child","spawn","on","code","sig","err","message","stop","signal","timeoutMs","closePromise","exitCode","signalCode","timedOut","killed","Promise","resolve","isResolved","wasKilled","resolveOnce","clearTimeout","timeout","setTimeout","kill","_","once","_err","config","close"],"mappings":"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"}

package/dist/cjs/spawn/spawn-servers.d.cts

@@ -0,0 +1,151 @@
+/**
+ * High-level multi-server registry management.
+ * Starts multiple servers from a servers configuration object.
+ * Supports stdio, http, and ws transports.
+ * Implements Claude Code-compatible configuration with start extension support.
+ */
+import { type ManagedClient } from '../client-helpers.js';
+import { connectMcpClient } from '../connection/connect-client.js';
+import { type SearchOptions, type SearchResponse } from '../search/index.js';
+import type { McpServerEntry } from '../types.js';
+import { type ServerProcess } from './spawn-server.js';
+/**
+ * Servers configuration type - a map of server names to their configurations.
+ */
+export type ServersConfig = Record<string, McpServerEntry>;
+/**
+ * Dialect for server spawning.
+ *
+ * - 'servers': Spawn stdio servers (Claude Code compatible)
+ * - 'start': Spawn HTTP servers with start blocks
+ */
+export type Dialect = 'servers' | 'start';
+/**
+ * Options for creating a server registry.
+ */
+export interface CreateServerRegistryOptions {
+    /** Working directory for spawned processes (default: process.cwd()) */
+    cwd?: string;
+    /**
+     * Base environment for all servers.
+     * If provided, process.env is NOT included (caller has full control).
+     * If omitted, process.env is used as the base (default behavior).
+     */
+    env?: Record<string, string>;
+    /**
+     * Dialects controlling which servers to spawn.
+     * - ['servers']: Spawn stdio servers only (default, Claude Code compatible)
+     * - ['start']: Only spawn servers with start blocks (HTTP servers)
+     * - ['servers', 'start']: Spawn both stdio servers and start blocks
+     * @default ['servers']
+     */
+    dialects?: Dialect[];
+}
+/**
+ * Result of closing the registry.
+ */
+export interface CloseResult {
+    /** Whether any process timed out during shutdown */
+    timedOut: boolean;
+    /** Number of processes that were force-killed */
+    killedCount: number;
+}
+/**
+ * A registry of spawned MCP servers with connection management.
+ * Provides access to individual server handles, connection management, and collection-wide close.
+ */
+type RegistryConnectOptions = Parameters<typeof connectMcpClient>[2];
+export interface ServerRegistry {
+    /**
+     * The resolved servers configuration that was used.
+     * Useful for debugging and understanding what was started.
+     */
+    config: ServersConfig;
+    /**
+     * Map of server name to server process handle.
+     * @hidden
+     */
+    servers: Map<string, ServerProcess>;
+    /**
+     * Set of connected clients tracked by this registry.
+     * Automatically populated when using registry.connect().
+     */
+    clients: Set<ManagedClient>;
+    /**
+     * Connect to a server by name.
+     * The connected client is automatically tracked for close.
+     *
+     * @param name - Server name from configuration
+     * @returns Connected MCP SDK Client
+     */
+    connect: (name: string, options?: RegistryConnectOptions) => Promise<ManagedClient>;
+    /**
+     * Close all clients and servers gracefully.
+     * First closes all tracked clients, then sends the specified signal to all server processes.
+     *
+     * @param signal - Signal to send to processes (default: SIGINT)
+     * @param opts - Options including timeout
+     * @returns Promise resolving to whether any process timed out and how many were force-killed
+     */
+    close: (signal?: NodeJS.Signals, opts?: {
+        timeoutMs?: number;
+    }) => Promise<CloseResult>;
+    /**
+     * Search indexed capabilities across all currently connected clients.
+     * Requires at least one connected client; respects SearchOptions filters.
+     */
+    searchCapabilities: (query: string, options?: SearchOptions) => Promise<SearchResponse>;
+    /**
+     * Support for `await using` pattern (automatic close).
+     */
+    [Symbol.asyncDispose]: () => Promise<void>;
+}
+/**
+ * Create a registry of MCP servers from configuration.
+ *
+ * **Fast start**: Returns immediately after processes are created.
+ * Use `registry.connect()` for lazy MCP connection.
+ *
+ * @param serversConfig - Map of server names to their configurations
+ * @param options - Options for registry creation
+ * @param options.cwd - Working directory for spawned processes (default: process.cwd())
+ * @param options.env - Base environment for all servers. If provided, process.env is NOT included.
+ *                      If omitted, process.env is used as the base (default behavior).
+ * @param options.dialects - Dialects controlling which servers to spawn (default: ['servers'])
+ *   - ['servers']: Spawn stdio servers only (Claude Code compatible)
+ *   - ['start']: Only spawn servers with start blocks (HTTP servers)
+ *   - ['servers', 'start']: Spawn both stdio servers and start blocks
+ * @returns ServerRegistry instance with config, server map, connect method, and close function
+ *
+ * @example
+ * // Fast server start (does NOT wait for readiness)
+ * const registry = createServerRegistry({
+ *   'echo': { command: 'node', args: ['server.ts'] },
+ * });
+ *
+ * // Connect when needed (waits for MCP handshake)
+ * const client = await registry.connect('echo');
+ *
+ * // Cleanup (closes all clients AND processes)
+ * await registry.close();
+ *
+ * @example
+ * // Start HTTP servers with start blocks
+ * const registry = createServerRegistry(
+ *   {
+ *     'http-server': {
+ *       url: 'http://localhost:8080/mcp',
+ *       start: { command: 'node', args: ['http.ts', '--port', '8080'] }
+ *     },
+ *   },
+ *   { dialects: ['start'] }
+ * );
+ *
+ * @example
+ * // Using await using for automatic close
+ * await using registry = createServerRegistry(config);
+ * const client = await registry.connect('server');
+ * // Auto-disposed when scope exits
+ */
+export declare function createServerRegistry(serversConfig: ServersConfig, options?: CreateServerRegistryOptions): ServerRegistry;
+export {};