@mcp-z/client 1.0.0

package/dist/cjs/connection/connect-client.js

@@ -0,0 +1,536 @@
+/**
+ * connect-mcp-client.ts
+ *
+ * Helper to connect MCP SDK clients to servers with intelligent transport inference.
+ * Automatically detects transport type from URL protocol or type field.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "connectMcpClient", {
+    enumerable: true,
+    get: function() {
+        return connectMcpClient;
+    }
+});
+require("../monkey-patches.js");
+var _index = require("@modelcontextprotocol/sdk/client/index.js");
+var _sse = require("@modelcontextprotocol/sdk/client/sse.js");
+var _stdio = require("@modelcontextprotocol/sdk/client/stdio.js");
+var _streamableHttp = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+var _getport = /*#__PURE__*/ _interop_require_default(require("get-port"));
+var _indexts = require("../auth/index.js");
+var _indexts1 = require("../dcr/index.js");
+var _loggerts = require("../utils/logger.js");
+var _existingprocesstransportts = require("./existing-process-transport.js");
+var _waitforhttpreadyts = require("./wait-for-http-ready.js");
+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 _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+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 _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
+        };
+    }
+}
+/**
+ * Wrap promise with timeout - throws if promise takes too long
+ * Clears timeout when promise completes to prevent hanging event loop
+ * @param promise - Promise to wrap
+ * @param ms - Timeout in milliseconds
+ * @param operation - Description of operation for error message
+ * @returns Promise result or timeout error
+ */ function withTimeout(promise, ms, operation) {
+    return _async_to_generator(function() {
+        var timeoutId;
+        return _ts_generator(this, function(_state) {
+            return [
+                2,
+                Promise.race([
+                    promise.finally(function() {
+                        return clearTimeout(timeoutId);
+                    }),
+                    new Promise(function(_, reject) {
+                        timeoutId = setTimeout(function() {
+                            return reject(new Error("Timeout after ".concat(ms, "ms: ").concat(operation)));
+                        }, ms);
+                    })
+                ])
+            ];
+        });
+    })();
+}
+/**
+ * Extract base URL from MCP server URL
+ * @param mcpUrl - Full MCP endpoint URL (e.g., https://example.com/mcp)
+ * @returns Base URL (e.g., https://example.com)
+ */ function extractBaseUrl(mcpUrl) {
+    var url = new URL(mcpUrl);
+    return "".concat(url.protocol, "//").concat(url.host);
+}
+/**
+ * Infer transport type from server configuration with validation.
+ *
+ * Priority:
+ * 1. Explicit type field (if present)
+ * 2. URL protocol (if URL present): http://, https://
+ * 3. Default to 'stdio' (if neither present)
+ *
+ * @param config - Server configuration
+ * @returns Transport type
+ * @throws Error if configuration is invalid or has conflicts
+ */ function inferTransportType(config) {
+    // Priority 1: Explicit type field
+    if (config.type) {
+        // Validate consistency with URL if both present
+        if (config.url) {
+            var url = new URL(config.url);
+            var protocol = url.protocol;
+            if ((protocol === 'http:' || protocol === 'https:') && config.type !== 'http' && config.type !== 'sse-ide') {
+                throw new Error("Conflicting transport: URL protocol '".concat(protocol, "' requires type 'http', but got '").concat(config.type, "'"));
+            }
+        }
+        // Return normalized type
+        if (config.type === 'http' || config.type === 'sse-ide') return 'http';
+        if (config.type === 'stdio') return 'stdio';
+        throw new Error("Unsupported transport type: ".concat(config.type));
+    }
+    // Priority 2: Infer from URL protocol
+    if (config.url) {
+        var url1 = new URL(config.url);
+        var protocol1 = url1.protocol;
+        if (protocol1 === 'http:' || protocol1 === 'https:') {
+            return 'http';
+        }
+        throw new Error("Unsupported URL protocol: ".concat(protocol1));
+    }
+    // Priority 3: Default to stdio
+    return 'stdio';
+}
+function connectMcpClient(registryOrConfig, serverName, options) {
+    return _async_to_generator(function() {
+        var _ref, isRegistry, serversConfig, registry, logger, serverConfig, available, transportType, client, serverHandle, transport, transport1, isSpawnedHttp, url, baseUrl, capabilities, authToken, port, redirectUri, authenticator, tokens, staticHeaders, dcrHeaders, mergedHeaders, transportOptions, transport2, error, errorMessage, cause, isConnectionRefused, shouldFallback, sseClient, staticHeaders1, dcrHeaders1, mergedHeaders1, sseTransportOptions, sseTransport, sseError;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    // Detect whether we have a RegistryLike instance or just config
+                    isRegistry = 'servers' in registryOrConfig && _instanceof(registryOrConfig.servers, Map);
+                    serversConfig = isRegistry ? registryOrConfig.config : registryOrConfig;
+                    registry = isRegistry ? registryOrConfig : undefined;
+                    logger = (_ref = options === null || options === void 0 ? void 0 : options.logger) !== null && _ref !== void 0 ? _ref : _loggerts.logger;
+                    serverConfig = serversConfig[serverName];
+                    if (!serverConfig) {
+                        available = Object.keys(serversConfig).join(', ');
+                        throw new Error("Server '".concat(serverName, "' not found in config. Available servers: ").concat(available || 'none'));
+                    }
+                    // Infer transport type with validation
+                    transportType = inferTransportType(serverConfig);
+                    // Create MCP client
+                    client = new _index.Client({
+                        name: 'mcp-cli-client',
+                        version: '1.0.0'
+                    }, {
+                        capabilities: {}
+                    });
+                    if (!(transportType === 'stdio')) return [
+                        3,
+                        5
+                    ];
+                    // Check if we have a spawned process in the registry
+                    serverHandle = registry === null || registry === void 0 ? void 0 : registry.servers.get(serverName);
+                    if (!serverHandle) return [
+                        3,
+                        2
+                    ];
+                    // Reuse the already-spawned process
+                    transport = new _existingprocesstransportts.ExistingProcessTransport(serverHandle.process);
+                    return [
+                        4,
+                        client.connect(transport)
+                    ];
+                case 1:
+                    _state.sent();
+                    return [
+                        3,
+                        4
+                    ];
+                case 2:
+                    // No registry or server not in registry - spawn new process directly
+                    // This is the standard fallback when process management is not used
+                    if (!serverConfig.command) {
+                        throw new Error("Server '".concat(serverName, "' has stdio transport but missing 'command' field"));
+                    }
+                    transport1 = new _stdio.StdioClientTransport({
+                        command: serverConfig.command,
+                        args: serverConfig.args || [],
+                        env: serverConfig.env || {}
+                    });
+                    // client.connect() performs initialize handshake - when it resolves, server is ready
+                    return [
+                        4,
+                        client.connect(transport1)
+                    ];
+                case 3:
+                    _state.sent();
+                    _state.label = 4;
+                case 4:
+                    return [
+                        3,
+                        22
+                    ];
+                case 5:
+                    if (!(transportType === 'http')) return [
+                        3,
+                        22
+                    ];
+                    if (!('url' in serverConfig) || !serverConfig.url) {
+                        throw new Error("Server '".concat(serverName, "' has http transport but missing 'url' field"));
+                    }
+                    // Check if this is a freshly spawned HTTP server (from registry)
+                    // that might not be ready yet - transport readiness check needed
+                    isSpawnedHttp = registry === null || registry === void 0 ? void 0 : registry.servers.has(serverName);
+                    if (!isSpawnedHttp) return [
+                        3,
+                        7
+                    ];
+                    logger.debug("[connectMcpClient] waiting for HTTP server '".concat(serverName, "' at ").concat(serverConfig.url));
+                    return [
+                        4,
+                        (0, _waitforhttpreadyts.waitForHttpReady)(serverConfig.url)
+                    ];
+                case 6:
+                    _state.sent();
+                    logger.debug("[connectMcpClient] HTTP server '".concat(serverName, "' ready"));
+                    _state.label = 7;
+                case 7:
+                    url = new URL(serverConfig.url);
+                    // Check for DCR support and handle authentication automatically
+                    baseUrl = extractBaseUrl(serverConfig.url);
+                    return [
+                        4,
+                        withTimeout((0, _indexts.probeAuthCapabilities)(baseUrl), 5000, 'DCR capability discovery')
+                    ];
+                case 8:
+                    capabilities = _state.sent();
+                    if (!capabilities.supportsDcr) return [
+                        3,
+                        11
+                    ];
+                    logger.debug("\uD83D\uDD10 Server '".concat(serverName, "' supports DCR authentication"));
+                    return [
+                        4,
+                        (0, _getport.default)()
+                    ];
+                case 9:
+                    port = _state.sent();
+                    redirectUri = "http://localhost:".concat(port, "/callback");
+                    // Handle authentication using DcrAuthenticator with fully resolved redirectUri
+                    authenticator = new _indexts1.DcrAuthenticator(_object_spread({
+                        headless: false,
+                        redirectUri: redirectUri,
+                        logger: logger
+                    }, options === null || options === void 0 ? void 0 : options.dcrAuthenticator));
+                    return [
+                        4,
+                        authenticator.ensureAuthenticated(baseUrl, capabilities)
+                    ];
+                case 10:
+                    tokens = _state.sent();
+                    authToken = tokens.accessToken;
+                    logger.debug("✅ Authentication complete for '".concat(serverName, "'"));
+                    return [
+                        3,
+                        12
+                    ];
+                case 11:
+                    logger.debug("ℹ️  Server '".concat(serverName, "' does not support DCR - connecting without authentication"));
+                    _state.label = 12;
+                case 12:
+                    _state.trys.push([
+                        12,
+                        14,
+                        ,
+                        22
+                    ]);
+                    // Try modern Streamable HTTP first (protocol version 2025-03-26)
+                    // Merge static headers from config with DCR auth headers (DCR Authorization takes precedence)
+                    staticHeaders = serverConfig.headers || {};
+                    dcrHeaders = authToken ? {
+                        Authorization: "Bearer ".concat(authToken)
+                    } : {};
+                    mergedHeaders = _object_spread({}, staticHeaders, dcrHeaders);
+                    transportOptions = Object.keys(mergedHeaders).length > 0 ? {
+                        requestInit: {
+                            headers: mergedHeaders
+                        }
+                    } : undefined;
+                    transport2 = new _streamableHttp.StreamableHTTPClientTransport(url, transportOptions);
+                    // Type assertion: SDK transport has sessionId: string | undefined but Transport expects string
+                    // This is safe at runtime - the undefined is valid per MCP spec
+                    return [
+                        4,
+                        withTimeout(client.connect(transport2), 30000, 'StreamableHTTP connection')
+                    ];
+                case 13:
+                    _state.sent();
+                    return [
+                        3,
+                        22
+                    ];
+                case 14:
+                    error = _state.sent();
+                    // Fall back to SSE transport (MCP protocol version 2024-11-05)
+                    // SSE is a standard MCP transport used by many servers (e.g., FastMCP ecosystem)
+                    errorMessage = _instanceof(error, Error) ? error.message : String(error);
+                    // Fast-fail: Don't try SSE if connection was refused (server not running)
+                    // Check error.cause.code for ECONNREFUSED (fetch errors wrap the actual error in cause)
+                    cause = _instanceof(error, Error) ? error.cause : undefined;
+                    isConnectionRefused = (cause === null || cause === void 0 ? void 0 : cause.code) === 'ECONNREFUSED' || errorMessage.includes('Connection refused');
+                    if (!isConnectionRefused) return [
+                        3,
+                        16
+                    ];
+                    // Clean up client resources before throwing
+                    return [
+                        4,
+                        client.close().catch(function() {})
+                    ];
+                case 15:
+                    _state.sent();
+                    throw new Error("Server not running at ".concat(url));
+                case 16:
+                    // Check for known errors that indicate SSE fallback is needed
+                    shouldFallback = errorMessage.includes('Missing session ID') || // FastMCP specific
+                    errorMessage.includes('404') || // Server doesn't have streamable HTTP endpoint
+                    errorMessage.includes('405'); // Method not allowed
+                    if (shouldFallback) {
+                        logger.warn("Streamable HTTP failed (".concat(errorMessage, "), falling back to SSE transport"));
+                    } else {
+                        logger.warn('Streamable HTTP connection failed, trying SSE transport as fallback');
+                    }
+                    // Create new client for SSE transport (required per SDK pattern)
+                    sseClient = new _index.Client({
+                        name: 'mcp-cli-client',
+                        version: '1.0.0'
+                    }, {
+                        capabilities: {}
+                    });
+                    // SSE transport with merged headers (static + DCR auth)
+                    // Reuse the same header merging logic as Streamable HTTP
+                    staticHeaders1 = serverConfig.headers || {};
+                    dcrHeaders1 = authToken ? {
+                        Authorization: "Bearer ".concat(authToken)
+                    } : {};
+                    mergedHeaders1 = _object_spread({}, staticHeaders1, dcrHeaders1);
+                    sseTransportOptions = Object.keys(mergedHeaders1).length > 0 ? {
+                        requestInit: {
+                            headers: mergedHeaders1
+                        }
+                    } : undefined;
+                    sseTransport = new _sse.SSEClientTransport(url, sseTransportOptions);
+                    _state.label = 17;
+                case 17:
+                    _state.trys.push([
+                        17,
+                        19,
+                        ,
+                        21
+                    ]);
+                    return [
+                        4,
+                        withTimeout(sseClient.connect(sseTransport), 30000, 'SSE connection')
+                    ];
+                case 18:
+                    _state.sent();
+                    // Return SSE client instead of original
+                    return [
+                        2,
+                        sseClient
+                    ];
+                case 19:
+                    sseError = _state.sent();
+                    // SSE connection failed - clean up both clients before throwing
+                    return [
+                        4,
+                        Promise.all([
+                            client.close().catch(function() {}),
+                            sseClient.close().catch(function() {})
+                        ])
+                    ];
+                case 20:
+                    _state.sent();
+                    throw sseError;
+                case 21:
+                    return [
+                        3,
+                        22
+                    ];
+                case 22:
+                    return [
+                        2,
+                        client
+                    ]; // Guaranteed ready when returned
+            }
+        });
+    })();
+}
+/* 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/connection/connect-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/connection/connect-client.ts"],"sourcesContent":["/**\n * connect-mcp-client.ts\n *\n * Helper to connect MCP SDK clients to servers with intelligent transport inference.\n * Automatically detects transport type from URL protocol or type field.\n */\n\nimport '../monkey-patches.ts';\n\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';\nimport type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';\nimport getPort from 'get-port';\nimport { probeAuthCapabilities } from '../auth/index.ts';\nimport { DcrAuthenticator, type DcrAuthenticatorOptions } from '../dcr/index.ts';\nimport type { ServerProcess } from '../spawn/spawn-server.ts';\nimport type { ServersConfig } from '../spawn/spawn-servers.ts';\n\n/**\n * Minimal interface for connecting to servers.\n * Only needs config and servers map for connection logic.\n */\ninterface RegistryLike {\n  config: ServersConfig;\n  servers: Map<string, ServerProcess>;\n}\n\nimport type { McpServerEntry, TransportType } from '../types.ts';\nimport { logger as defaultLogger, type Logger } from '../utils/logger.ts';\nimport { ExistingProcessTransport } from './existing-process-transport.ts';\nimport { waitForHttpReady } from './wait-for-http-ready.ts';\n\n/**\n * Wrap promise with timeout - throws if promise takes too long\n * Clears timeout when promise completes to prevent hanging event loop\n * @param promise - Promise to wrap\n * @param ms - Timeout in milliseconds\n * @param operation - Description of operation for error message\n * @returns Promise result or timeout error\n */\nasync function withTimeout<T>(promise: Promise<T>, ms: number, operation: string): Promise<T> {\n  let timeoutId: NodeJS.Timeout;\n\n  return Promise.race([\n    promise.finally(() => clearTimeout(timeoutId)),\n    new Promise<T>((_, reject) => {\n      timeoutId = setTimeout(() => reject(new Error(`Timeout after ${ms}ms: ${operation}`)), ms);\n    }),\n  ]);\n}\n\n/**\n * Extract base URL from MCP server URL\n * @param mcpUrl - Full MCP endpoint URL (e.g., https://example.com/mcp)\n * @returns Base URL (e.g., https://example.com)\n */\nfunction extractBaseUrl(mcpUrl: string): string {\n  const url = new URL(mcpUrl);\n  return `${url.protocol}//${url.host}`;\n}\n\n/**\n * Infer transport type from server configuration with validation.\n *\n * Priority:\n * 1. Explicit type field (if present)\n * 2. URL protocol (if URL present): http://, https://\n * 3. Default to 'stdio' (if neither present)\n *\n * @param config - Server configuration\n * @returns Transport type\n * @throws Error if configuration is invalid or has conflicts\n */\nfunction inferTransportType(config: McpServerEntry): TransportType {\n  // Priority 1: Explicit type field\n  if (config.type) {\n    // Validate consistency with URL if both present\n    if (config.url) {\n      const url = new URL(config.url);\n      const protocol = url.protocol;\n\n      if ((protocol === 'http:' || protocol === 'https:') && config.type !== 'http' && config.type !== 'sse-ide') {\n        throw new Error(`Conflicting transport: URL protocol '${protocol}' requires type 'http', but got '${config.type}'`);\n      }\n    }\n\n    // Return normalized type\n    if (config.type === 'http' || config.type === 'sse-ide') return 'http';\n    if (config.type === 'stdio') return 'stdio';\n\n    throw new Error(`Unsupported transport type: ${config.type}`);\n  }\n\n  // Priority 2: Infer from URL protocol\n  if (config.url) {\n    const url = new URL(config.url);\n    const protocol = url.protocol;\n\n    if (protocol === 'http:' || protocol === 'https:') {\n      return 'http';\n    }\n    throw new Error(`Unsupported URL protocol: ${protocol}`);\n  }\n\n  // Priority 3: Default to stdio\n  return 'stdio';\n}\n\n/**\n * Connect MCP SDK client to server with full readiness handling.\n * @internal - Use registry.connect() instead\n *\n * **Completely handles readiness**: transport availability + MCP protocol handshake.\n *\n * Transport is intelligently inferred and handled:\n * - **Stdio servers**: Direct MCP connect (fast for spawned processes)\n * - **HTTP servers**: Transport polling (/mcp endpoint) + MCP connect\n * - **Registry result**: Handles both spawned and external servers\n *\n * Returns only when server is fully MCP-ready (initialize handshake complete).\n *\n * @param registryOrConfig - Result from createServerRegistry() or servers config object\n * @param serverName - Server name from servers config\n * @returns Connected MCP SDK Client (guaranteed ready)\n *\n * @example\n * // Using registry (recommended)\n * const registry = createServerRegistry({ echo: { command: 'node', args: ['server.ts'] } });\n * const client = await registry.connect('echo');\n * // Server is fully ready - transport available + MCP handshake complete\n *\n * @example\n * // HTTP server readiness (waits for /mcp polling + MCP handshake)\n * const registry = createServerRegistry(\n *   { http: { type: 'http', url: 'http://localhost:3000/mcp', start: {...} } },\n *   { dialects: ['start'] }\n * );\n * const client = await registry.connect('http');\n * // 1. Waits for HTTP server to respond on /mcp\n * // 2. Performs MCP initialize handshake\n * // 3. Returns ready client\n */\nexport async function connectMcpClient(\n  registryOrConfig: RegistryLike | ServersConfig,\n  serverName: string,\n  options?: {\n    dcrAuthenticator?: Partial<DcrAuthenticatorOptions>;\n    logger?: Logger;\n  }\n): Promise<Client> {\n  // Detect whether we have a RegistryLike instance or just config\n  const isRegistry = 'servers' in registryOrConfig && registryOrConfig.servers instanceof Map;\n  const serversConfig = isRegistry ? (registryOrConfig as RegistryLike).config : registryOrConfig;\n  const registry = isRegistry ? (registryOrConfig as RegistryLike) : undefined;\n  const logger = options?.logger ?? defaultLogger;\n\n  const serverConfig = serversConfig[serverName];\n\n  if (!serverConfig) {\n    const available = Object.keys(serversConfig).join(', ');\n    throw new Error(`Server '${serverName}' not found in config. Available servers: ${available || 'none'}`);\n  }\n\n  // Infer transport type with validation\n  const transportType = inferTransportType(serverConfig);\n\n  // Create MCP client\n  const client = new Client({ name: 'mcp-cli-client', version: '1.0.0' }, { capabilities: {} });\n\n  // Connect based on inferred transport\n  if (transportType === 'stdio') {\n    // Check if we have a spawned process in the registry\n    const serverHandle = registry?.servers.get(serverName);\n\n    if (serverHandle) {\n      // Reuse the already-spawned process\n      const transport = new ExistingProcessTransport(serverHandle.process);\n      await client.connect(transport);\n    } else {\n      // No registry or server not in registry - spawn new process directly\n      // This is the standard fallback when process management is not used\n      if (!serverConfig.command) {\n        throw new Error(`Server '${serverName}' has stdio transport but missing 'command' field`);\n      }\n\n      const transport = new StdioClientTransport({\n        command: serverConfig.command,\n        args: serverConfig.args || [],\n        env: serverConfig.env || {},\n      });\n\n      // client.connect() performs initialize handshake - when it resolves, server is ready\n      await client.connect(transport);\n    }\n  } else if (transportType === 'http') {\n    if (!('url' in serverConfig) || !serverConfig.url) {\n      throw new Error(`Server '${serverName}' has http transport but missing 'url' field`);\n    }\n\n    // Check if this is a freshly spawned HTTP server (from registry)\n    // that might not be ready yet - transport readiness check needed\n    const isSpawnedHttp = registry?.servers.has(serverName);\n\n    if (isSpawnedHttp) {\n      logger.debug(`[connectMcpClient] waiting for HTTP server '${serverName}' at ${serverConfig.url}`);\n      await waitForHttpReady(serverConfig.url);\n      logger.debug(`[connectMcpClient] HTTP server '${serverName}' ready`);\n    }\n\n    const url = new URL(serverConfig.url);\n\n    // Check for DCR support and handle authentication automatically\n    const baseUrl = extractBaseUrl(serverConfig.url);\n    const capabilities = await withTimeout(probeAuthCapabilities(baseUrl), 5000, 'DCR capability discovery');\n\n    let authToken: string | undefined;\n\n    if (capabilities.supportsDcr) {\n      logger.debug(`🔐 Server '${serverName}' supports DCR authentication`);\n\n      // Get available port and create the exact redirect URI to use\n      const port = await getPort();\n      const redirectUri = `http://localhost:${port}/callback`;\n\n      // Handle authentication using DcrAuthenticator with fully resolved redirectUri\n      const authenticator = new DcrAuthenticator({\n        headless: false,\n        redirectUri,\n        logger,\n        ...options?.dcrAuthenticator,\n      });\n\n      // Ensure we have valid tokens (performs DCR + OAuth if needed)\n      const tokens = await authenticator.ensureAuthenticated(baseUrl, capabilities);\n      authToken = tokens.accessToken;\n\n      logger.debug(`✅ Authentication complete for '${serverName}'`);\n    } else {\n      logger.debug(`ℹ️  Server '${serverName}' does not support DCR - connecting without authentication`);\n    }\n\n    try {\n      // Try modern Streamable HTTP first (protocol version 2025-03-26)\n      // Merge static headers from config with DCR auth headers (DCR Authorization takes precedence)\n      const staticHeaders = serverConfig.headers || {};\n      const dcrHeaders = authToken ? { Authorization: `Bearer ${authToken}` } : {};\n      const mergedHeaders = { ...staticHeaders, ...dcrHeaders };\n\n      const transportOptions =\n        Object.keys(mergedHeaders).length > 0\n          ? {\n              requestInit: {\n                headers: mergedHeaders,\n              },\n            }\n          : undefined;\n\n      const transport = new StreamableHTTPClientTransport(url, transportOptions);\n      // Type assertion: SDK transport has sessionId: string | undefined but Transport expects string\n      // This is safe at runtime - the undefined is valid per MCP spec\n      await withTimeout(client.connect(transport as unknown as Transport), 30000, 'StreamableHTTP connection');\n    } catch (error) {\n      // Fall back to SSE transport (MCP protocol version 2024-11-05)\n      // SSE is a standard MCP transport used by many servers (e.g., FastMCP ecosystem)\n      const errorMessage = error instanceof Error ? error.message : String(error);\n\n      // Fast-fail: Don't try SSE if connection was refused (server not running)\n      // Check error.cause.code for ECONNREFUSED (fetch errors wrap the actual error in cause)\n      const cause = error instanceof Error ? (error as Error & { cause?: { code?: string } }).cause : undefined;\n      const isConnectionRefused = cause?.code === 'ECONNREFUSED' || errorMessage.includes('Connection refused');\n\n      if (isConnectionRefused) {\n        // Clean up client resources before throwing\n        await client.close().catch(() => {});\n        throw new Error(`Server not running at ${url}`);\n      }\n\n      // Check for known errors that indicate SSE fallback is needed\n      const shouldFallback =\n        errorMessage.includes('Missing session ID') || // FastMCP specific\n        errorMessage.includes('404') || // Server doesn't have streamable HTTP endpoint\n        errorMessage.includes('405'); // Method not allowed\n\n      if (shouldFallback) {\n        logger.warn(`Streamable HTTP failed (${errorMessage}), falling back to SSE transport`);\n      } else {\n        logger.warn('Streamable HTTP connection failed, trying SSE transport as fallback');\n      }\n\n      // Create new client for SSE transport (required per SDK pattern)\n      const sseClient = new Client({ name: 'mcp-cli-client', version: '1.0.0' }, { capabilities: {} });\n\n      // SSE transport with merged headers (static + DCR auth)\n      // Reuse the same header merging logic as Streamable HTTP\n      const staticHeaders = serverConfig.headers || {};\n      const dcrHeaders = authToken ? { Authorization: `Bearer ${authToken}` } : {};\n      const mergedHeaders = { ...staticHeaders, ...dcrHeaders };\n\n      const sseTransportOptions =\n        Object.keys(mergedHeaders).length > 0\n          ? {\n              requestInit: {\n                headers: mergedHeaders,\n              },\n            }\n          : undefined;\n\n      const sseTransport = new SSEClientTransport(url, sseTransportOptions);\n\n      try {\n        await withTimeout(sseClient.connect(sseTransport), 30000, 'SSE connection');\n        // Return SSE client instead of original\n        return sseClient;\n      } catch (sseError) {\n        // SSE connection failed - clean up both clients before throwing\n        await Promise.all([client.close().catch(() => {}), sseClient.close().catch(() => {})]);\n        throw sseError;\n      }\n    }\n  }\n\n  return client; // Guaranteed ready when returned\n}\n"],"names":["connectMcpClient","withTimeout","promise","ms","operation","timeoutId","Promise","race","finally","clearTimeout","_","reject","setTimeout","Error","extractBaseUrl","mcpUrl","url","URL","protocol","host","inferTransportType","config","type","registryOrConfig","serverName","options","isRegistry","serversConfig","registry","logger","serverConfig","available","transportType","client","serverHandle","transport","isSpawnedHttp","baseUrl","capabilities","authToken","port","redirectUri","authenticator","tokens","staticHeaders","dcrHeaders","mergedHeaders","transportOptions","error","errorMessage","cause","isConnectionRefused","shouldFallback","sseClient","sseTransportOptions","sseTransport","sseError","servers","Map","undefined","defaultLogger","Object","keys","join","Client","name","version","get","ExistingProcessTransport","process","connect","command","StdioClientTransport","args","env","has","debug","waitForHttpReady","probeAuthCapabilities","supportsDcr","getPort","DcrAuthenticator","headless","dcrAuthenticator","ensureAuthenticated","accessToken","headers","Authorization","length","requestInit","StreamableHTTPClientTransport","message","String","code","includes","close","catch","warn","SSEClientTransport","all"],"mappings":"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"}

package/dist/cjs/connection/existing-process-transport.d.cts

@@ -0,0 +1,40 @@
+/**
+ * existing-process-transport.ts
+ *
+ * MCP transport that wraps an existing child process for stdio communication.
+ * Used when connecting to servers already spawned by initServers().
+ */
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { ChildProcess } from 'child_process';
+/**
+ * Transport that communicates with an existing child process via stdio.
+ * Does NOT spawn a new process - uses the one provided.
+ */
+export declare class ExistingProcessTransport implements Transport {
+    private _process;
+    private _readBuffer;
+    private _dataHandler;
+    private _errorHandler;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(process: ChildProcess);
+    /**
+     * Start the transport - sets up stdio listeners on existing process.
+     */
+    start(): Promise<void>;
+    /**
+     * Process buffered messages from stdout.
+     */
+    private processReadBuffer;
+    /**
+     * Close the transport - close without killing the shared process.
+     * The process is managed by the cluster and may have other active connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Send a message to the server via stdin.
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+}

package/dist/cjs/connection/existing-process-transport.d.ts

@@ -0,0 +1,40 @@
+/**
+ * existing-process-transport.ts
+ *
+ * MCP transport that wraps an existing child process for stdio communication.
+ * Used when connecting to servers already spawned by initServers().
+ */
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { ChildProcess } from 'child_process';
+/**
+ * Transport that communicates with an existing child process via stdio.
+ * Does NOT spawn a new process - uses the one provided.
+ */
+export declare class ExistingProcessTransport implements Transport {
+    private _process;
+    private _readBuffer;
+    private _dataHandler;
+    private _errorHandler;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(process: ChildProcess);
+    /**
+     * Start the transport - sets up stdio listeners on existing process.
+     */
+    start(): Promise<void>;
+    /**
+     * Process buffered messages from stdout.
+     */
+    private processReadBuffer;
+    /**
+     * Close the transport - close without killing the shared process.
+     * The process is managed by the cluster and may have other active connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Send a message to the server via stdin.
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+}