@mcp-z/client 1.0.0

package/dist/esm/search/types.js

@@ -0,0 +1,8 @@
+/**
+ * Search types for MCP capability discovery
+ *
+ * Enables agents to discover tools, prompts, and resources without
+ * loading full schemas into context.
+ */ /**
+ * Index containing all capabilities from connected servers
+ */ export { };

package/dist/esm/search/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/search/types.ts"],"sourcesContent":["/**\n * Search types for MCP capability discovery\n *\n * Enables agents to discover tools, prompts, and resources without\n * loading full schemas into context.\n */\n\nimport type { PromptArgument } from '../connection/types.ts';\n\n/**\n * Types of MCP capabilities that can be searched\n */\nexport type CapabilityType = 'tool' | 'prompt' | 'resource';\n\n/**\n * Fields that can be searched within capabilities\n */\nexport type SearchField = 'name' | 'description' | 'schema' | 'server';\n\n/**\n * Options for configuring search behavior\n */\nexport interface SearchOptions {\n  /**\n   * Filter to specific capability types\n   * @default ['tool', 'prompt', 'resource']\n   */\n  types?: CapabilityType[];\n\n  /**\n   * Filter to specific servers by name\n   * @default all servers in config\n   */\n  servers?: string[];\n\n  /**\n   * Which fields to search within\n   * @default ['name', 'description', 'schema']\n   */\n  searchFields?: SearchField[];\n\n  /**\n   * Maximum number of results to return\n   * @default 20\n   */\n  limit?: number;\n\n  /**\n   * Minimum relevance score (0-1) for results\n   * @default 0\n   */\n  threshold?: number;\n}\n\n/**\n * A single search result representing a matched capability\n */\nexport interface SearchResult {\n  /** The type of capability */\n  type: CapabilityType;\n\n  /** The server that provides this capability */\n  server: string;\n\n  /** The name of the capability */\n  name: string;\n\n  /** Human-readable description (may be truncated) */\n  description: string | undefined;\n\n  /** Which fields matched the search query */\n  matchedOn: string[];\n\n  /** Relevance score from 0 (low) to 1 (high) */\n  score: number;\n}\n\n/**\n * Complete search response\n */\nexport interface SearchResponse {\n  /** The original search query */\n  query: string;\n\n  /** Matching results, sorted by relevance */\n  results: SearchResult[];\n\n  /** Total number of matches before limit was applied */\n  total: number;\n}\n\n/**\n * Internal representation of a tool for indexing\n */\nexport interface IndexedTool {\n  type: 'tool';\n  server: string;\n  name: string;\n  description: string | undefined;\n  /** Flattened searchable text from inputSchema property descriptions */\n  schemaText: string;\n}\n\n/**\n * Internal representation of a prompt for indexing\n */\nexport interface IndexedPrompt {\n  type: 'prompt';\n  server: string;\n  name: string;\n  description: string | undefined;\n  /** Flattened searchable text from arguments */\n  argumentsText: string;\n  arguments: PromptArgument[] | undefined;\n}\n\n/**\n * Internal representation of a resource for indexing\n */\nexport interface IndexedResource {\n  type: 'resource';\n  server: string;\n  name: string;\n  description: string | undefined;\n  uri: string;\n  mimeType: string | undefined;\n}\n\n/**\n * Union of all indexed capability types\n */\nexport type IndexedCapability = IndexedTool | IndexedPrompt | IndexedResource;\n\n/**\n * Index containing all capabilities from connected servers\n */\nexport interface CapabilityIndex {\n  /** All indexed capabilities */\n  capabilities: IndexedCapability[];\n\n  /** Servers that were indexed */\n  servers: string[];\n\n  /** When the index was created */\n  indexedAt: Date;\n}\n"],"names":[],"mappings":"AAAA;;;;;CAKC,GAgID;;CAEC,GACD,WASC"}

package/dist/esm/spawn/spawn-server.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Low-level single server spawning utilities.
+ * Provides core process spawning with path resolution, environment management, and lifecycle control.
+ */
+import { type ChildProcess, type StdioOptions } from 'child_process';
+/**
+ * Options for spawning a single server process.
+ * @internal
+ */
+export interface SpawnProcessOptions {
+    /** Server name for logging */
+    name: string;
+    /** Command to execute (e.g., 'node', 'npx') */
+    command: string;
+    /** Command arguments (paths will be resolved relative to cwd) */
+    args?: string[];
+    /** Working directory (must be absolute path) */
+    cwd?: string;
+    /** Additional environment variables (merged with process.env) */
+    env?: Record<string, string>;
+    /** Standard I/O configuration */
+    stdio?: StdioOptions;
+    /** Use shell for command execution (default: false, true on Windows) */
+    shell?: boolean;
+}
+/**
+ * Handle to a spawned server process.
+ * Provides access to the process, resolved config, and lifecycle control.
+ * @hidden
+ */
+export interface ServerProcess {
+    /**
+     * The resolved server configuration that was actually used.
+     * Useful for debugging and understanding what was spawned.
+     */
+    config: {
+        name: string;
+        command: string;
+        args: string[];
+        cwd: string;
+        env: Record<string, string>;
+        stdio: StdioOptions;
+        shell: boolean;
+    };
+    /**
+     * The spawned child process.
+     */
+    process: ChildProcess;
+    /**
+     * Close the server gracefully.
+     * Sends the specified signal (default: SIGINT), then SIGKILL after timeout.
+     *
+     * @param signal - Signal to send (default: SIGINT)
+     * @param opts - Options including timeout
+     * @returns Promise resolving to whether the process timed out and was force-killed
+     */
+    close: (signal?: NodeJS.Signals, opts?: {
+        timeoutMs?: number;
+    }) => Promise<{
+        timedOut: boolean;
+        killed: boolean;
+    }>;
+}
+/**
+ * Spawn a single server process with path resolution and environment management.
+ *
+ * @internal
+ * @param opts - Server spawn options
+ * @returns ServerProcess handle with resolved config, process, and stop function
+ *
+ * @example
+ * const handle = spawnProcess({
+ *   name: 'echo',
+ *   command: 'node',
+ *   args: ['./bin/server.js', '--port', '3000'],
+ *   cwd: '/home/user/project/test/lib/servers/echo',
+ *   env: { LOG_LEVEL: 'error' }
+ * });
+ *
+ * // Later...
+ * await handle.close();
+ */
+export declare function spawnProcess(opts: SpawnProcessOptions): ServerProcess;

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

@@ -0,0 +1,145 @@
+/**
+ * Low-level single server spawning utilities.
+ * Provides core process spawning with path resolution, environment management, and lifecycle control.
+ */ import { spawn } from 'child_process';
+import * as process from 'process';
+import { logger } from '../utils/logger.js';
+import { resolveArgsPaths } from '../utils/path-utils.js';
+/**
+ * Normalize environment variables by merging with process.env and filtering undefined values.
+ */ function normalizeEnv(env) {
+    const merged = {
+        ...process.env,
+        ...env || {}
+    };
+    const result = {};
+    for (const [key, value] of Object.entries(merged)){
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Spawn a single server process with path resolution and environment management.
+ *
+ * @internal
+ * @param opts - Server spawn options
+ * @returns ServerProcess handle with resolved config, process, and stop function
+ *
+ * @example
+ * const handle = spawnProcess({
+ *   name: 'echo',
+ *   command: 'node',
+ *   args: ['./bin/server.js', '--port', '3000'],
+ *   cwd: '/home/user/project/test/lib/servers/echo',
+ *   env: { LOG_LEVEL: 'error' }
+ * });
+ *
+ * // Later...
+ * await handle.close();
+ */ export function spawnProcess(opts) {
+    var _opts_cwd, _opts_stdio, _opts_shell;
+    const name = opts.name;
+    const command = opts.command;
+    const cwd = (_opts_cwd = opts.cwd) !== null && _opts_cwd !== void 0 ? _opts_cwd : process.cwd();
+    const stdio = (_opts_stdio = opts.stdio) !== null && _opts_stdio !== void 0 ? _opts_stdio : 'inherit';
+    const shell = (_opts_shell = opts.shell) !== null && _opts_shell !== void 0 ? _opts_shell : process.platform === 'win32';
+    // Resolve paths in args relative to the working directory
+    const args = opts.args ? resolveArgsPaths(opts.args, cwd) : [];
+    // Merge environment variables
+    const env = normalizeEnv(opts.env);
+    // Create resolved config for return value
+    const resolvedConfig = {
+        name,
+        command,
+        args,
+        cwd,
+        env,
+        stdio,
+        shell
+    };
+    // Log spawn operation
+    logger.info(`[${name}] → ${command} ${args.join(' ')}`);
+    // Spawn the process
+    const spawnOpts = {
+        cwd,
+        env,
+        stdio,
+        shell
+    };
+    const child = spawn(command, args, spawnOpts);
+    // Attach lifecycle logging
+    child.on('exit', (code, sig)=>logger.info(`[${name}] exited (code=${code}, signal=${sig || 'none'})`));
+    child.on('error', (err)=>logger.info(`[${name}] process error: ${err.message}`));
+    // Create stop function with graceful shutdown
+    const stop = async (signal = 'SIGINT', opts = {})=>{
+        var _opts_timeoutMs;
+        // If already exited, return immediately
+        if (child.exitCode !== null || child.signalCode !== null) {
+            return {
+                timedOut: false,
+                killed: false
+            };
+        }
+        const 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
+        const closePromise = new Promise((resolve)=>{
+            let isResolved = false;
+            let wasKilled = false;
+            const resolveOnce = (timedOut)=>{
+                if (isResolved) return;
+                isResolved = true;
+                clearTimeout(timeout);
+                resolve({
+                    timedOut,
+                    killed: wasKilled
+                });
+            };
+            // Set timeout for forceful kill
+            const timeout = setTimeout(()=>{
+                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', ()=>{
+                resolveOnce(false);
+            });
+            // Also listen for 'error' event in case spawn failed
+            // This prevents promise from hanging forever if process never started
+            child.once('error', ()=>{
+                resolveOnce(false);
+            });
+            // Send graceful shutdown signal
+            try {
+                // Check one more time before killing
+                if (child.exitCode !== null) {
+                    resolveOnce(false);
+                    return;
+                }
+                const 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 closePromise;
+    };
+    return {
+        config: resolvedConfig,
+        process: child,
+        close: stop
+    };
+}

package/dist/esm/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":["spawn","process","logger","resolveArgsPaths","normalizeEnv","env","merged","result","key","value","Object","entries","undefined","spawnProcess","opts","name","command","cwd","stdio","shell","platform","args","resolvedConfig","info","join","spawnOpts","child","on","code","sig","err","message","stop","signal","exitCode","signalCode","timedOut","killed","timeoutMs","closePromise","Promise","resolve","isResolved","wasKilled","resolveOnce","clearTimeout","timeout","setTimeout","kill","_","once","_err","config","close"],"mappings":"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"}

package/dist/esm/spawn/spawn-servers.d.ts

@@ -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 {};