@mcp-z/client 1.0.0

package/dist/cjs/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 {};