@mcp-z/client 1.0.0

package/dist/esm/spawn/spawn-servers.js

@@ -0,0 +1,406 @@
+/**
+ * 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 * as fs from 'fs';
+import * as process from 'process';
+import { decorateClient } from '../client-helpers.js';
+import { validateServers } from '../config/validate-config.js';
+import { connectMcpClient } from '../connection/connect-client.js';
+import { buildCapabilityIndex, searchCapabilities as executeCapabilitySearch } from '../search/index.js';
+import { logger } from '../utils/logger.js';
+import { spawnProcess } from './spawn-server.js';
+/**
+ * Infer transport type: explicit type > URL protocol > default 'stdio'
+ */ function inferTransportType(config) {
+    if (config.type) {
+        return config.type;
+    }
+    if (config.url) {
+        const url = new URL(config.url);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            return 'http';
+        }
+    }
+    return 'stdio';
+}
+/**
+ * Helper to filter undefined values from environment
+ */ function filterEnv(env) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(env)){
+        if (value !== undefined) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+/**
+ * Determine spawn behavior based on dialects and config structure.
+ *
+ * Dialects:
+ * - ['servers'] (default): Claude Code compatible - ignores start blocks, stdio only
+ * - ['start']: Only spawn servers with start blocks (HTTP server testing)
+ * - ['servers', 'start']: Spawn both start blocks and stdio servers (full MCP-Z extension support)
+ *
+ * Environment merging (when baseEnv provided):
+ * - HTTP servers (start block): { ...baseEnv, ...entry.start.env }
+ * - Stdio servers: { ...baseEnv, ...entry.env }
+ *
+ * When baseEnv is not provided, process.env is used as the base.
+ */ function getSpawnConfig(entry, dialects, baseEnv) {
+    const transportType = inferTransportType(entry);
+    const hasServers = dialects.includes('servers');
+    const hasStart = dialects.includes('start');
+    // If only 'servers' dialect: Claude Code compatible (ignore start blocks, stdio only)
+    if (hasServers && !hasStart) {
+        if (transportType === 'stdio' && entry.command) {
+            return {
+                shouldSpawn: true,
+                command: entry.command,
+                args: entry.args || [],
+                env: filterEnv({
+                    ...baseEnv,
+                    ...entry.env
+                })
+            };
+        }
+        return {
+            shouldSpawn: false
+        };
+    }
+    // If only 'start' dialect: Only spawn servers with start blocks
+    if (hasStart && !hasServers) {
+        if (entry.start) {
+            return {
+                shouldSpawn: true,
+                command: entry.start.command,
+                args: entry.start.args || [],
+                env: filterEnv({
+                    ...baseEnv,
+                    ...entry.start.env
+                })
+            };
+        }
+        return {
+            shouldSpawn: false
+        };
+    }
+    // Both dialects: Spawn both start blocks and stdio servers
+    // Priority: start blocks first, then stdio
+    if (entry.start) {
+        return {
+            shouldSpawn: true,
+            command: entry.start.command,
+            args: entry.start.args || [],
+            env: filterEnv({
+                ...baseEnv,
+                ...entry.start.env
+            })
+        };
+    }
+    if (transportType === 'stdio' && entry.command) {
+        return {
+            shouldSpawn: true,
+            command: entry.command,
+            args: entry.args || [],
+            env: filterEnv({
+                ...baseEnv,
+                ...entry.env
+            })
+        };
+    }
+    return {
+        shouldSpawn: false
+    };
+}
+/**
+ * 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 function createServerRegistry(serversConfig, options) {
+    var _ref, _ref1, _ref2;
+    const cwd = (_ref = options === null || options === void 0 ? void 0 : options.cwd) !== null && _ref !== void 0 ? _ref : process.cwd();
+    const dialects = (_ref1 = options === null || options === void 0 ? void 0 : options.dialects) !== null && _ref1 !== void 0 ? _ref1 : [
+        'servers'
+    ];
+    // Determine base environment:
+    // - If options.env provided, use it (process.env NOT included)
+    // - If options.env omitted, use process.env as base
+    const baseEnv = (_ref2 = options === null || options === void 0 ? void 0 : options.env) !== null && _ref2 !== void 0 ? _ref2 : process.env;
+    // Validate working directory exists (fail fast for configuration errors)
+    if (!fs.existsSync(cwd)) {
+        throw new Error(`Cannot start servers: working directory '${cwd}' does not exist`);
+    }
+    // Validate configuration (fail fast with clear errors)
+    const validation = validateServers(serversConfig);
+    if (!validation.valid) {
+        var _ref3;
+        var _validation_errors;
+        throw new Error(`Invalid servers configuration:\n${(_ref3 = (_validation_errors = validation.errors) === null || _validation_errors === void 0 ? void 0 : _validation_errors.join('\n')) !== null && _ref3 !== void 0 ? _ref3 : 'Unknown validation error'}`);
+    }
+    // Log validation warnings (non-blocking)
+    if (validation.warnings && validation.warnings.length > 0) {
+        for (const warning of validation.warnings){
+            logger.warn(warning);
+        }
+    }
+    const servers = new Map();
+    const clients = new Set();
+    const sharedStdioClients = new Map();
+    // Start each server in the configuration
+    for (const [name, entry] of Object.entries(serversConfig)){
+        // Infer transport type from config
+        const transportType = inferTransportType(entry);
+        // Determine spawn behavior based on dialects
+        const spawnConfig = getSpawnConfig(entry, dialects, baseEnv);
+        // Check if we should spawn this server
+        if (!spawnConfig.shouldSpawn) {
+            // External server - just log, no spawn needed
+            if (entry.url) {
+                logger.info(`[${name}] external ${transportType} server (url: ${entry.url})`);
+            } else {
+                logger.warn(`[${name}] skipping: no spawn configuration (missing start or command) and no url for external server`);
+            }
+            continue;
+        }
+        try {
+            // Validate spawn config
+            if (!spawnConfig.command) {
+                throw new Error(`Server "${name}" missing command field`);
+            }
+            // All servers use the same working directory (cwd from options)
+            const resolvedCwd = cwd;
+            // Start the server
+            logger.info(`[${name}] starting ${transportType} server (${spawnConfig.command} ${(spawnConfig.args || []).join(' ')})`);
+            // stdio servers need 'pipe' for MCP communication over stdin/stdout
+            // network servers use 'inherit' so we see their logs
+            const stdio = transportType === 'stdio' ? 'pipe' : 'inherit';
+            const handle = spawnProcess({
+                name,
+                command: spawnConfig.command,
+                ...spawnConfig.args !== undefined && {
+                    args: spawnConfig.args
+                },
+                cwd: resolvedCwd,
+                ...spawnConfig.env && Object.keys(spawnConfig.env).length > 0 && {
+                    env: spawnConfig.env
+                },
+                stdio
+            });
+            // Add server to registry (starting is fast, readiness is lazy)
+            servers.set(name, handle);
+            logger.info(`[${name}] started successfully`);
+        } catch (e) {
+            logger.info(`[${name}] start ERROR: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // Create connect function that tracks clients
+    const connect = async (name, options)=>{
+        const serverEntry = serversConfig[name];
+        if (!serverEntry) {
+            const available = Object.keys(serversConfig).join(', ');
+            throw new Error(`Server '${name}' not found in config. Available servers: ${available || 'none'}`);
+        }
+        const transportType = inferTransportType(serverEntry);
+        if (transportType === 'stdio') {
+            // Stdio is a single logical connection; reuse one client and lease references.
+            let entry = sharedStdioClients.get(name);
+            if (!entry) {
+                entry = {
+                    refs: 0
+                };
+                sharedStdioClients.set(name, entry);
+            }
+            if (!entry.client) {
+                if (!entry.connecting) {
+                    entry.connecting = (async ()=>{
+                        // Pass minimal RegistryLike object to connectMcpClient
+                        const registryLike = {
+                            config: serversConfig,
+                            servers
+                        };
+                        const rawClient = await connectMcpClient(registryLike, name, options);
+                        const decorated = decorateClient(rawClient, {
+                            serverName: name
+                        });
+                        entry.client = decorated;
+                        entry.connecting = undefined;
+                        return decorated;
+                    })().catch((error)=>{
+                        sharedStdioClients.delete(name);
+                        throw error;
+                    });
+                }
+                await entry.connecting;
+            }
+            if (!entry.client) {
+                throw new Error(`Failed to connect to stdio server '${name}'`);
+            }
+            entry.refs += 1;
+            let released = false;
+            let lease;
+            lease = new Proxy(entry.client, {
+                get (target, prop) {
+                    if (prop === 'close') {
+                        return async ()=>{
+                            if (released) return;
+                            released = true;
+                            clients.delete(lease);
+                            entry.refs = Math.max(0, entry.refs - 1);
+                            if (entry.refs === 0) {
+                                sharedStdioClients.delete(name);
+                                await target.close();
+                            }
+                        };
+                    }
+                    const value = Reflect.get(target, prop, target);
+                    if (typeof value === 'function') {
+                        return value.bind(target);
+                    }
+                    return value;
+                }
+            });
+            clients.add(lease);
+            return lease;
+        }
+        // Pass minimal RegistryLike object to connectMcpClient
+        const registryLike = {
+            config: serversConfig,
+            servers
+        };
+        const rawClient = await connectMcpClient(registryLike, name, options);
+        const decorated = decorateClient(rawClient, {
+            serverName: name
+        });
+        clients.add(decorated);
+        return decorated;
+    };
+    // Create close function that stops all clients and servers
+    const close = async (signal = 'SIGINT', opts = {})=>{
+        logger.info(`[registry] closing (${signal})`);
+        // First, close all tracked clients
+        const clientClosePromises = Array.from(clients).map(async (client)=>{
+            try {
+                await client.close();
+            } catch  {
+            // Ignore errors during client close
+            }
+        });
+        await Promise.all(clientClosePromises);
+        clients.clear();
+        // Then close all server processes
+        if (servers.size === 0) {
+            return {
+                timedOut: false,
+                killedCount: 0
+            };
+        }
+        // Close all servers in parallel
+        const closeResults = await Promise.all(Array.from(servers.values()).map((server)=>server.close(signal, opts)));
+        // Check if any timed out and count how many were force-killed
+        const timedOut = closeResults.some((result)=>result.timedOut);
+        const killedCount = closeResults.filter((result)=>result.killed).length;
+        return {
+            timedOut,
+            killedCount
+        };
+    };
+    const searchFromRegistry = async (query, options = {})=>{
+        var _options_servers;
+        const requestedServers = (_options_servers = options.servers) !== null && _options_servers !== void 0 ? _options_servers : Object.keys(serversConfig);
+        if (requestedServers.length === 0) {
+            throw new Error('Cannot search capabilities: registry has no configured servers');
+        }
+        const unknownServers = requestedServers.filter((name)=>!(name in serversConfig));
+        if (unknownServers.length > 0) {
+            throw new Error(`Cannot search capabilities: unknown server(s) [${unknownServers.join(', ')}]`);
+        }
+        const capabilityClients = new Map();
+        const failures = [];
+        const ensureClient = async (serverName)=>{
+            for (const client of clients){
+                if (client.serverName === serverName) {
+                    return client;
+                }
+            }
+            return connect(serverName);
+        };
+        await Promise.all(requestedServers.map(async (serverName)=>{
+            try {
+                const managed = await ensureClient(serverName);
+                capabilityClients.set(serverName, managed.nativeClient);
+            } catch (error) {
+                failures.push({
+                    server: serverName,
+                    reason: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }));
+        if (capabilityClients.size === 0) {
+            const failureDetails = failures.length > 0 ? ` Connection failures: ${failures.map((f)=>`${f.server} (${f.reason})`).join('; ')}` : '';
+            throw new Error(`Cannot search capabilities: unable to connect to any requested servers.${failureDetails}`);
+        }
+        if (failures.length > 0) {
+            throw new Error(`Cannot search capabilities: failed to connect to server(s) [${failures.map((f)=>f.server).join(', ')}]. Reasons: ${failures.map((f)=>`${f.server}: ${f.reason}`).join('; ')}`);
+        }
+        const index = await buildCapabilityIndex(capabilityClients);
+        return executeCapabilitySearch(index, query, options);
+    };
+    // Async dispose for `await using` pattern
+    const asyncDispose = async ()=>{
+        await close();
+    };
+    return {
+        config: serversConfig,
+        servers,
+        clients,
+        connect,
+        close,
+        searchCapabilities: searchFromRegistry,
+        [Symbol.asyncDispose]: asyncDispose
+    };
+}

package/dist/esm/spawn/spawn-servers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/spawn/spawn-servers.ts"],"sourcesContent":["/**\n * High-level multi-server registry management.\n * Starts multiple servers from a servers configuration object.\n * Supports stdio, http, and ws transports.\n * Implements Claude Code-compatible configuration with start extension support.\n */\n\nimport * as fs from 'fs';\nimport * as process from 'process';\nimport { decorateClient, type ManagedClient } from '../client-helpers.ts';\nimport { validateServers } from '../config/validate-config.ts';\nimport { connectMcpClient } from '../connection/connect-client.ts';\nimport { buildCapabilityIndex, type CapabilityClient, searchCapabilities as executeCapabilitySearch, type SearchOptions, type SearchResponse } from '../search/index.ts';\nimport type { McpServerEntry, TransportType } from '../types.ts';\nimport { logger } from '../utils/logger.ts';\nimport { type ServerProcess, spawnProcess } from './spawn-server.ts';\n\n/**\n * Servers configuration type - a map of server names to their configurations.\n */\nexport type ServersConfig = Record<string, McpServerEntry>;\n\n/**\n * Dialect for server spawning.\n *\n * - 'servers': Spawn stdio servers (Claude Code compatible)\n * - 'start': Spawn HTTP servers with start blocks\n */\nexport type Dialect = 'servers' | 'start';\n\n/**\n * Options for creating a server registry.\n */\nexport interface CreateServerRegistryOptions {\n  /** Working directory for spawned processes (default: process.cwd()) */\n  cwd?: string;\n\n  /**\n   * Base environment for all servers.\n   * If provided, process.env is NOT included (caller has full control).\n   * If omitted, process.env is used as the base (default behavior).\n   */\n  env?: Record<string, string>;\n\n  /**\n   * Dialects controlling which servers to spawn.\n   * - ['servers']: Spawn stdio servers only (default, Claude Code compatible)\n   * - ['start']: Only spawn servers with start blocks (HTTP servers)\n   * - ['servers', 'start']: Spawn both stdio servers and start blocks\n   * @default ['servers']\n   */\n  dialects?: Dialect[];\n}\n\n/**\n * Result of closing the registry.\n */\nexport interface CloseResult {\n  /** Whether any process timed out during shutdown */\n  timedOut: boolean;\n  /** Number of processes that were force-killed */\n  killedCount: number;\n}\n\n/**\n * Infer transport type: explicit type > URL protocol > default 'stdio'\n */\nfunction inferTransportType(config: { type?: TransportType; url?: string }): TransportType {\n  if (config.type) {\n    return config.type;\n  }\n\n  if (config.url) {\n    const url = new URL(config.url);\n    if (url.protocol === 'http:' || url.protocol === 'https:') {\n      return 'http';\n    }\n  }\n\n  return 'stdio';\n}\n\n/**\n * Spawn configuration result (internal)\n */\ninterface SpawnConfig {\n  shouldSpawn: boolean;\n  command?: string;\n  args?: string[];\n  env?: Record<string, string>;\n}\n\n/**\n * Helper to filter undefined values from environment\n */\nfunction filterEnv(env: Record<string, string | undefined>): Record<string, string> {\n  const filtered: Record<string, string> = {};\n  for (const [key, value] of Object.entries(env)) {\n    if (value !== undefined) {\n      filtered[key] = value;\n    }\n  }\n  return filtered;\n}\n\n/**\n * Determine spawn behavior based on dialects and config structure.\n *\n * Dialects:\n * - ['servers'] (default): Claude Code compatible - ignores start blocks, stdio only\n * - ['start']: Only spawn servers with start blocks (HTTP server testing)\n * - ['servers', 'start']: Spawn both start blocks and stdio servers (full MCP-Z extension support)\n *\n * Environment merging (when baseEnv provided):\n * - HTTP servers (start block): { ...baseEnv, ...entry.start.env }\n * - Stdio servers: { ...baseEnv, ...entry.env }\n *\n * When baseEnv is not provided, process.env is used as the base.\n */\nfunction getSpawnConfig(entry: McpServerEntry, dialects: Dialect[], baseEnv: Record<string, string | undefined>): SpawnConfig {\n  const transportType = inferTransportType(entry);\n  const hasServers = dialects.includes('servers');\n  const hasStart = dialects.includes('start');\n\n  // If only 'servers' dialect: Claude Code compatible (ignore start blocks, stdio only)\n  if (hasServers && !hasStart) {\n    if (transportType === 'stdio' && entry.command) {\n      return {\n        shouldSpawn: true,\n        command: entry.command,\n        args: entry.args || [],\n        env: filterEnv({ ...baseEnv, ...entry.env }),\n      };\n    }\n    return { shouldSpawn: false };\n  }\n\n  // If only 'start' dialect: Only spawn servers with start blocks\n  if (hasStart && !hasServers) {\n    if (entry.start) {\n      return {\n        shouldSpawn: true,\n        command: entry.start.command,\n        args: entry.start.args || [],\n        env: filterEnv({ ...baseEnv, ...entry.start.env }),\n      };\n    }\n    return { shouldSpawn: false };\n  }\n\n  // Both dialects: Spawn both start blocks and stdio servers\n  // Priority: start blocks first, then stdio\n  if (entry.start) {\n    return {\n      shouldSpawn: true,\n      command: entry.start.command,\n      args: entry.start.args || [],\n      env: filterEnv({ ...baseEnv, ...entry.start.env }),\n    };\n  }\n\n  if (transportType === 'stdio' && entry.command) {\n    return {\n      shouldSpawn: true,\n      command: entry.command,\n      args: entry.args || [],\n      env: filterEnv({ ...baseEnv, ...entry.env }),\n    };\n  }\n\n  return { shouldSpawn: false };\n}\n\n/**\n * A registry of spawned MCP servers with connection management.\n * Provides access to individual server handles, connection management, and collection-wide close.\n */\ntype RegistryConnectOptions = Parameters<typeof connectMcpClient>[2];\n\nexport interface ServerRegistry {\n  /**\n   * The resolved servers configuration that was used.\n   * Useful for debugging and understanding what was started.\n   */\n  config: ServersConfig;\n\n  /**\n   * Map of server name to server process handle.\n   * @hidden\n   */\n  servers: Map<string, ServerProcess>;\n\n  /**\n   * Set of connected clients tracked by this registry.\n   * Automatically populated when using registry.connect().\n   */\n  clients: Set<ManagedClient>;\n\n  /**\n   * Connect to a server by name.\n   * The connected client is automatically tracked for close.\n   *\n   * @param name - Server name from configuration\n   * @returns Connected MCP SDK Client\n   */\n  connect: (name: string, options?: RegistryConnectOptions) => Promise<ManagedClient>;\n\n  /**\n   * Close all clients and servers gracefully.\n   * First closes all tracked clients, then sends the specified signal to all server processes.\n   *\n   * @param signal - Signal to send to processes (default: SIGINT)\n   * @param opts - Options including timeout\n   * @returns Promise resolving to whether any process timed out and how many were force-killed\n   */\n  close: (signal?: NodeJS.Signals, opts?: { timeoutMs?: number }) => Promise<CloseResult>;\n\n  /**\n   * Search indexed capabilities across all currently connected clients.\n   * Requires at least one connected client; respects SearchOptions filters.\n   */\n  searchCapabilities: (query: string, options?: SearchOptions) => Promise<SearchResponse>;\n\n  /**\n   * Support for `await using` pattern (automatic close).\n   */\n  [Symbol.asyncDispose]: () => Promise<void>;\n}\n\n/**\n * Create a registry of MCP servers from configuration.\n *\n * **Fast start**: Returns immediately after processes are created.\n * Use `registry.connect()` for lazy MCP connection.\n *\n * @param serversConfig - Map of server names to their configurations\n * @param options - Options for registry creation\n * @param options.cwd - Working directory for spawned processes (default: process.cwd())\n * @param options.env - Base environment for all servers. If provided, process.env is NOT included.\n *                      If omitted, process.env is used as the base (default behavior).\n * @param options.dialects - Dialects controlling which servers to spawn (default: ['servers'])\n *   - ['servers']: Spawn stdio servers only (Claude Code compatible)\n *   - ['start']: Only spawn servers with start blocks (HTTP servers)\n *   - ['servers', 'start']: Spawn both stdio servers and start blocks\n * @returns ServerRegistry instance with config, server map, connect method, and close function\n *\n * @example\n * // Fast server start (does NOT wait for readiness)\n * const registry = createServerRegistry({\n *   'echo': { command: 'node', args: ['server.ts'] },\n * });\n *\n * // Connect when needed (waits for MCP handshake)\n * const client = await registry.connect('echo');\n *\n * // Cleanup (closes all clients AND processes)\n * await registry.close();\n *\n * @example\n * // Start HTTP servers with start blocks\n * const registry = createServerRegistry(\n *   {\n *     'http-server': {\n *       url: 'http://localhost:8080/mcp',\n *       start: { command: 'node', args: ['http.ts', '--port', '8080'] }\n *     },\n *   },\n *   { dialects: ['start'] }\n * );\n *\n * @example\n * // Using await using for automatic close\n * await using registry = createServerRegistry(config);\n * const client = await registry.connect('server');\n * // Auto-disposed when scope exits\n */\nexport function createServerRegistry(serversConfig: ServersConfig, options?: CreateServerRegistryOptions): ServerRegistry {\n  const cwd = options?.cwd ?? process.cwd();\n  const dialects = options?.dialects ?? ['servers'];\n\n  // Determine base environment:\n  // - If options.env provided, use it (process.env NOT included)\n  // - If options.env omitted, use process.env as base\n  const baseEnv: Record<string, string | undefined> = options?.env ?? process.env;\n\n  // Validate working directory exists (fail fast for configuration errors)\n  if (!fs.existsSync(cwd)) {\n    throw new Error(`Cannot start servers: working directory '${cwd}' does not exist`);\n  }\n\n  // Validate configuration (fail fast with clear errors)\n  const validation = validateServers(serversConfig);\n  if (!validation.valid) {\n    throw new Error(`Invalid servers configuration:\\n${validation.errors?.join('\\n') ?? 'Unknown validation error'}`);\n  }\n\n  // Log validation warnings (non-blocking)\n  if (validation.warnings && validation.warnings.length > 0) {\n    for (const warning of validation.warnings) {\n      logger.warn(warning);\n    }\n  }\n\n  const servers = new Map<string, ServerProcess>();\n  const clients = new Set<ManagedClient>();\n  const sharedStdioClients = new Map<string, { client?: ManagedClient; connecting?: Promise<ManagedClient>; refs: number }>();\n\n  // Start each server in the configuration\n  for (const [name, entry] of Object.entries(serversConfig)) {\n    // Infer transport type from config\n    const transportType = inferTransportType(entry);\n\n    // Determine spawn behavior based on dialects\n    const spawnConfig = getSpawnConfig(entry, dialects, baseEnv);\n\n    // Check if we should spawn this server\n    if (!spawnConfig.shouldSpawn) {\n      // External server - just log, no spawn needed\n      if (entry.url) {\n        logger.info(`[${name}] external ${transportType} server (url: ${entry.url})`);\n      } else {\n        logger.warn(`[${name}] skipping: no spawn configuration (missing start or command) and no url for external server`);\n      }\n      continue;\n    }\n\n    try {\n      // Validate spawn config\n      if (!spawnConfig.command) {\n        throw new Error(`Server \"${name}\" missing command field`);\n      }\n\n      // All servers use the same working directory (cwd from options)\n      const resolvedCwd = cwd;\n\n      // Start the server\n      logger.info(`[${name}] starting ${transportType} server (${spawnConfig.command} ${(spawnConfig.args || []).join(' ')})`);\n\n      // stdio servers need 'pipe' for MCP communication over stdin/stdout\n      // network servers use 'inherit' so we see their logs\n      const stdio = transportType === 'stdio' ? 'pipe' : 'inherit';\n\n      const handle = spawnProcess({\n        name,\n        command: spawnConfig.command,\n        ...(spawnConfig.args !== undefined && { args: spawnConfig.args }),\n        cwd: resolvedCwd,\n        ...(spawnConfig.env && Object.keys(spawnConfig.env).length > 0 && { env: spawnConfig.env }),\n        stdio,\n      });\n\n      // Add server to registry (starting is fast, readiness is lazy)\n      servers.set(name, handle);\n      logger.info(`[${name}] started successfully`);\n    } catch (e) {\n      logger.info(`[${name}] start ERROR: ${e instanceof Error ? e.message : String(e)}`);\n    }\n  }\n\n  // Create connect function that tracks clients\n  const connect = async (name: string, options?: RegistryConnectOptions): Promise<ManagedClient> => {\n    const serverEntry = serversConfig[name];\n    if (!serverEntry) {\n      const available = Object.keys(serversConfig).join(', ');\n      throw new Error(`Server '${name}' not found in config. Available servers: ${available || 'none'}`);\n    }\n\n    const transportType = inferTransportType(serverEntry);\n\n    if (transportType === 'stdio') {\n      // Stdio is a single logical connection; reuse one client and lease references.\n      let entry = sharedStdioClients.get(name);\n      if (!entry) {\n        entry = { refs: 0 };\n        sharedStdioClients.set(name, entry);\n      }\n\n      if (!entry.client) {\n        if (!entry.connecting) {\n          entry.connecting = (async () => {\n            // Pass minimal RegistryLike object to connectMcpClient\n            const registryLike = { config: serversConfig, servers };\n            const rawClient = await connectMcpClient(registryLike, name, options);\n            const decorated = decorateClient(rawClient, { serverName: name });\n            entry.client = decorated;\n            entry.connecting = undefined;\n            return decorated;\n          })().catch((error) => {\n            sharedStdioClients.delete(name);\n            throw error;\n          });\n        }\n\n        await entry.connecting;\n      }\n\n      if (!entry.client) {\n        throw new Error(`Failed to connect to stdio server '${name}'`);\n      }\n\n      entry.refs += 1;\n      let released = false;\n      let lease: ManagedClient;\n\n      lease = new Proxy(entry.client, {\n        get(target, prop) {\n          if (prop === 'close') {\n            return async () => {\n              if (released) return;\n              released = true;\n              clients.delete(lease);\n              entry.refs = Math.max(0, entry.refs - 1);\n              if (entry.refs === 0) {\n                sharedStdioClients.delete(name);\n                await target.close();\n              }\n            };\n          }\n\n          const value = Reflect.get(target, prop, target) as unknown;\n          if (typeof value === 'function') {\n            return (value as (...args: unknown[]) => unknown).bind(target);\n          }\n          return value;\n        },\n      }) as ManagedClient;\n\n      clients.add(lease);\n      return lease;\n    }\n\n    // Pass minimal RegistryLike object to connectMcpClient\n    const registryLike = { config: serversConfig, servers };\n    const rawClient = await connectMcpClient(registryLike, name, options);\n    const decorated = decorateClient(rawClient, { serverName: name });\n    clients.add(decorated);\n    return decorated;\n  };\n\n  // Create close function that stops all clients and servers\n  const close = async (signal: NodeJS.Signals = 'SIGINT', opts: { timeoutMs?: number } = {}): Promise<CloseResult> => {\n    logger.info(`[registry] closing (${signal})`);\n\n    // First, close all tracked clients\n    const clientClosePromises = Array.from(clients).map(async (client) => {\n      try {\n        await client.close();\n      } catch {\n        // Ignore errors during client close\n      }\n    });\n    await Promise.all(clientClosePromises);\n    clients.clear();\n\n    // Then close all server processes\n    if (servers.size === 0) {\n      return { timedOut: false, killedCount: 0 };\n    }\n\n    // Close all servers in parallel\n    const closeResults = await Promise.all(Array.from(servers.values()).map((server) => server.close(signal, opts)));\n\n    // Check if any timed out and count how many were force-killed\n    const timedOut = closeResults.some((result) => result.timedOut);\n    const killedCount = closeResults.filter((result) => result.killed).length;\n\n    return { timedOut, killedCount };\n  };\n\n  const searchFromRegistry = async (query: string, options: SearchOptions = {}): Promise<SearchResponse> => {\n    const requestedServers = options.servers ?? Object.keys(serversConfig);\n    if (requestedServers.length === 0) {\n      throw new Error('Cannot search capabilities: registry has no configured servers');\n    }\n\n    const unknownServers = requestedServers.filter((name) => !(name in serversConfig));\n    if (unknownServers.length > 0) {\n      throw new Error(`Cannot search capabilities: unknown server(s) [${unknownServers.join(', ')}]`);\n    }\n\n    const capabilityClients = new Map<string, CapabilityClient>();\n    const failures: Array<{ server: string; reason: string }> = [];\n\n    const ensureClient = async (serverName: string): Promise<ManagedClient> => {\n      for (const client of clients) {\n        if (client.serverName === serverName) {\n          return client;\n        }\n      }\n      return connect(serverName);\n    };\n\n    await Promise.all(\n      requestedServers.map(async (serverName) => {\n        try {\n          const managed = await ensureClient(serverName);\n          capabilityClients.set(serverName, managed.nativeClient);\n        } catch (error) {\n          failures.push({\n            server: serverName,\n            reason: error instanceof Error ? error.message : String(error),\n          });\n        }\n      })\n    );\n\n    if (capabilityClients.size === 0) {\n      const failureDetails = failures.length > 0 ? ` Connection failures: ${failures.map((f) => `${f.server} (${f.reason})`).join('; ')}` : '';\n      throw new Error(`Cannot search capabilities: unable to connect to any requested servers.${failureDetails}`);\n    }\n\n    if (failures.length > 0) {\n      throw new Error(`Cannot search capabilities: failed to connect to server(s) [${failures.map((f) => f.server).join(', ')}]. Reasons: ${failures.map((f) => `${f.server}: ${f.reason}`).join('; ')}`);\n    }\n\n    const index = await buildCapabilityIndex(capabilityClients);\n    return executeCapabilitySearch(index, query, options);\n  };\n\n  // Async dispose for `await using` pattern\n  const asyncDispose = async (): Promise<void> => {\n    await close();\n  };\n\n  return {\n    config: serversConfig,\n    servers,\n    clients,\n    connect,\n    close,\n    searchCapabilities: searchFromRegistry,\n    [Symbol.asyncDispose]: asyncDispose,\n  };\n}\n"],"names":["fs","process","decorateClient","validateServers","connectMcpClient","buildCapabilityIndex","searchCapabilities","executeCapabilitySearch","logger","spawnProcess","inferTransportType","config","type","url","URL","protocol","filterEnv","env","filtered","key","value","Object","entries","undefined","getSpawnConfig","entry","dialects","baseEnv","transportType","hasServers","includes","hasStart","command","shouldSpawn","args","start","createServerRegistry","serversConfig","options","cwd","existsSync","Error","validation","valid","errors","join","warnings","length","warning","warn","servers","Map","clients","Set","sharedStdioClients","name","spawnConfig","info","resolvedCwd","stdio","handle","keys","set","e","message","String","connect","serverEntry","available","get","refs","client","connecting","registryLike","rawClient","decorated","serverName","catch","error","delete","released","lease","Proxy","target","prop","Math","max","close","Reflect","bind","add","signal","opts","clientClosePromises","Array","from","map","Promise","all","clear","size","timedOut","killedCount","closeResults","values","server","some","result","filter","killed","searchFromRegistry","query","requestedServers","unknownServers","capabilityClients","failures","ensureClient","managed","nativeClient","push","reason","failureDetails","f","index","asyncDispose","Symbol"],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Configuration Types
+ *
+ * Auto-generated from schemas/servers.schema.json
+ */
+export type { MCPServers, McpServerEntry, StartConfig } from '../schemas/servers.d.js';
+/**
+ * Transport type for server configuration
+ * Standard MCP transport types matching Claude Code's schemas
+ */
+export type TransportType = 'stdio' | 'http' | 'sse-ide' | 'ws-ide' | 'sdk';

package/dist/esm/types.js

@@ -0,0 +1,9 @@
+/**
+ * MCP Configuration Types
+ *
+ * Auto-generated from schemas/servers.schema.json
+ */ // Re-export all generated types
+/**
+ * Transport type for server configuration
+ * Standard MCP transport types matching Claude Code's schemas
+ */ export { };

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/types.ts"],"sourcesContent":["/**\n * MCP Configuration Types\n *\n * Auto-generated from schemas/servers.schema.json\n */\n\n// Re-export all generated types\nexport type { MCPServers, McpServerEntry, StartConfig } from '../schemas/servers.d.ts';\n\n/**\n * Transport type for server configuration\n * Standard MCP transport types matching Claude Code's schemas\n */\nexport type TransportType = 'stdio' | 'http' | 'sse-ide' | 'ws-ide' | 'sdk';\n"],"names":[],"mappings":"AAAA;;;;CAIC,GAED,gCAAgC;AAGhC;;;CAGC,GACD,WAA4E"}

package/dist/esm/utils/logger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sanitized logger with log level filtering
+ * Provides credential redaction and verbosity control for all log output
+ */
+/**
+ * Log level for filtering output
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Logger interface - subset of Console
+ */
+export type Logger = Pick<Console, 'info' | 'error' | 'warn' | 'debug'>;
+/**
+ * Set the global log level
+ * Users can call this to control library verbosity
+ *
+ * @param level - Log level: 'debug' (all), 'info', 'warn', 'error', 'silent' (none)
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Get current log level
+ */
+export declare function getLogLevel(): LogLevel;
+export declare const logger: Logger;

package/dist/esm/utils/logger.js

@@ -0,0 +1,59 @@
+/**
+ * Sanitized logger with log level filtering
+ * Provides credential redaction and verbosity control for all log output
+ */ import { sanitizeForLogging } from './sanitizer.js';
+// Log level hierarchy (higher number = more important)
+const levels = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4
+};
+// Default to 'warn' - quiet library, only show warnings and errors
+let currentLevel = process.env.LOG_LEVEL || 'warn';
+/**
+ * Check if a log should be output based on current level
+ */ function shouldLog(level) {
+    return levels[level] >= levels[currentLevel];
+}
+/**
+ * Set the global log level
+ * Users can call this to control library verbosity
+ *
+ * @param level - Log level: 'debug' (all), 'info', 'warn', 'error', 'silent' (none)
+ */ export function setLogLevel(level) {
+    currentLevel = level;
+}
+/**
+ * Get current log level
+ */ export function getLogLevel() {
+    return currentLevel;
+}
+/**
+ * Create a sanitized logger with log level filtering
+ */ function createSanitizedLogger() {
+    const createLogMethod = (consoleMethod)=>{
+        return (message, ...args)=>{
+            // Check if this log level should be output
+            if (!shouldLog(consoleMethod)) {
+                return;
+            }
+            const metadata = args.length > 0 && typeof args[0] === 'object' ? args[0] : {};
+            const { message: clean, meta: cleanMeta } = sanitizeForLogging(message, metadata);
+            if (Object.keys(cleanMeta).length > 0) {
+                console[consoleMethod](clean, cleanMeta);
+            } else {
+                console[consoleMethod](clean);
+            }
+        };
+    };
+    return {
+        info: createLogMethod('info'),
+        warn: createLogMethod('warn'),
+        error: createLogMethod('error'),
+        debug: createLogMethod('debug')
+    };
+}
+// Singleton instance - shared across all operations
+export const logger = createSanitizedLogger();

package/dist/esm/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/utils/logger.ts"],"sourcesContent":["/**\n * Sanitized logger with log level filtering\n * Provides credential redaction and verbosity control for all log output\n */\n\nimport type { SpawnMetadata } from '../connection/types.ts';\nimport { sanitizeForLogging } from './sanitizer.ts';\n\n/**\n * Log level for filtering output\n */\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';\n\n/**\n * Logger interface - subset of Console\n */\nexport type Logger = Pick<Console, 'info' | 'error' | 'warn' | 'debug'>;\n\n// Log level hierarchy (higher number = more important)\nconst levels: Record<LogLevel, number> = {\n  debug: 0,\n  info: 1,\n  warn: 2,\n  error: 3,\n  silent: 4,\n};\n\n// Default to 'warn' - quiet library, only show warnings and errors\nlet currentLevel: LogLevel = (process.env.LOG_LEVEL as LogLevel) || 'warn';\n\n/**\n * Check if a log should be output based on current level\n */\nfunction shouldLog(level: keyof Omit<typeof levels, 'silent'>): boolean {\n  return levels[level] >= levels[currentLevel];\n}\n\n/**\n * Set the global log level\n * Users can call this to control library verbosity\n *\n * @param level - Log level: 'debug' (all), 'info', 'warn', 'error', 'silent' (none)\n */\nexport function setLogLevel(level: LogLevel): void {\n  currentLevel = level;\n}\n\n/**\n * Get current log level\n */\nexport function getLogLevel(): LogLevel {\n  return currentLevel;\n}\n\n/**\n * Create a sanitized logger with log level filtering\n */\nfunction createSanitizedLogger(): Logger {\n  const createLogMethod = (consoleMethod: 'info' | 'warn' | 'error' | 'debug') => {\n    return (message: string, ...args: unknown[]) => {\n      // Check if this log level should be output\n      if (!shouldLog(consoleMethod)) {\n        return;\n      }\n\n      const metadata = args.length > 0 && typeof args[0] === 'object' ? (args[0] as SpawnMetadata) : {};\n      const { message: clean, meta: cleanMeta } = sanitizeForLogging(message, metadata);\n      if (Object.keys(cleanMeta).length > 0) {\n        console[consoleMethod](clean, cleanMeta);\n      } else {\n        console[consoleMethod](clean);\n      }\n    };\n  };\n\n  return {\n    info: createLogMethod('info'),\n    warn: createLogMethod('warn'),\n    error: createLogMethod('error'),\n    debug: createLogMethod('debug'),\n  };\n}\n\n// Singleton instance - shared across all operations\nexport const logger = createSanitizedLogger();\n"],"names":["sanitizeForLogging","levels","debug","info","warn","error","silent","currentLevel","process","env","LOG_LEVEL","shouldLog","level","setLogLevel","getLogLevel","createSanitizedLogger","createLogMethod","consoleMethod","message","args","metadata","length","clean","meta","cleanMeta","Object","keys","console","logger"],"mappings":"AAAA;;;CAGC,GAGD,SAASA,kBAAkB,QAAQ,iBAAiB;AAYpD,uDAAuD;AACvD,MAAMC,SAAmC;IACvCC,OAAO;IACPC,MAAM;IACNC,MAAM;IACNC,OAAO;IACPC,QAAQ;AACV;AAEA,mEAAmE;AACnE,IAAIC,eAAyB,AAACC,QAAQC,GAAG,CAACC,SAAS,IAAiB;AAEpE;;CAEC,GACD,SAASC,UAAUC,KAA0C;IAC3D,OAAOX,MAAM,CAACW,MAAM,IAAIX,MAAM,CAACM,aAAa;AAC9C;AAEA;;;;;CAKC,GACD,OAAO,SAASM,YAAYD,KAAe;IACzCL,eAAeK;AACjB;AAEA;;CAEC,GACD,OAAO,SAASE;IACd,OAAOP;AACT;AAEA;;CAEC,GACD,SAASQ;IACP,MAAMC,kBAAkB,CAACC;QACvB,OAAO,CAACC,SAAiB,GAAGC;YAC1B,2CAA2C;YAC3C,IAAI,CAACR,UAAUM,gBAAgB;gBAC7B;YACF;YAEA,MAAMG,WAAWD,KAAKE,MAAM,GAAG,KAAK,OAAOF,IAAI,CAAC,EAAE,KAAK,WAAYA,IAAI,CAAC,EAAE,GAAqB,CAAC;YAChG,MAAM,EAAED,SAASI,KAAK,EAAEC,MAAMC,SAAS,EAAE,GAAGxB,mBAAmBkB,SAASE;YACxE,IAAIK,OAAOC,IAAI,CAACF,WAAWH,MAAM,GAAG,GAAG;gBACrCM,OAAO,CAACV,cAAc,CAACK,OAAOE;YAChC,OAAO;gBACLG,OAAO,CAACV,cAAc,CAACK;YACzB;QACF;IACF;IAEA,OAAO;QACLnB,MAAMa,gBAAgB;QACtBZ,MAAMY,gBAAgB;QACtBX,OAAOW,gBAAgB;QACvBd,OAAOc,gBAAgB;IACzB;AACF;AAEA,oDAAoD;AACpD,OAAO,MAAMY,SAASb,wBAAwB"}

package/dist/esm/utils/path-utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Path resolution utilities for cluster spawning.
+ * Handles ~, relative paths, absolute paths, and special cases (URLs, npm packages, flags).
+ */
+/**
+ * Resolve a file path relative to a working directory.
+ *
+ * Handles three cases:
+ * - `~` or `~/path` - Expands to home directory
+ * - Absolute paths - Returns as-is
+ * - Relative paths - Resolves relative to cwd
+ *
+ * @param filePath - The path to resolve
+ * @param cwd - The working directory for resolving relative paths
+ * @returns The resolved absolute path
+ *
+ * @example
+ * resolvePath('~/config.json', '/unused')  // → '/home/user/config.json'
+ * resolvePath('/absolute/path', '/unused') // → '/absolute/path'
+ * resolvePath('./relative', '/base')       // → '/base/relative'
+ */
+export declare function resolvePath(filePath: string, cwd: string): string;
+/**
+ * Resolve paths in command arguments array.
+ *
+ * Intelligently handles different argument types:
+ * - Flags with paths: `--env-file=./path` → `--env-file=/absolute/path`
+ * - Flags without paths: `--port=3000` → unchanged
+ * - Command flags: `--verbose` → unchanged
+ * - URLs: `http://example.com` → unchanged
+ * - npm packages: `@scope/package` or `package-name` → unchanged
+ * - Regular paths: `./script.js` → `/absolute/script.js`
+ *
+ * @param args - Array of command arguments
+ * @param cwd - Working directory for resolving relative paths
+ * @returns Array with paths resolved
+ *
+ * @example
+ * resolveArgsPaths(['./bin/server.js', '--env-file=./config.env', '--port=3000'], '/home/user')
+ * // → ['/home/user/bin/server.js', '--env-file=/home/user/config.env', '--port=3000']
+ *
+ * resolveArgsPaths(['@scope/package', 'https://example.com'], '/unused')
+ * // → ['@scope/package', 'https://example.com'] (unchanged)
+ */
+export declare function resolveArgsPaths(args: string[], cwd: string): string[];