@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/utils/transports/stdio-transport.js

@@ -0,0 +1,324 @@
+import { spawn } from 'child_process';
+import { PassThrough } from 'stream';
+import { logger } from '../logger.js';
+// Re-implement ReadBuffer as it is not exported from SDK root
+class ReadBuffer {
+    _buffer;
+    append(chunk) {
+        this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
+    }
+    readMessage() {
+        if (!this._buffer) {
+            return null;
+        }
+        const index = this._buffer.indexOf('\n');
+        if (index === -1) {
+            return null;
+        }
+        const line = this._buffer.toString('utf8', 0, index).replace(/\r$/, '');
+        this._buffer = this._buffer.subarray(index + 1);
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return JSON.parse(line);
+        }
+    }
+    clear() {
+        this._buffer = undefined;
+    }
+}
+/**
+ * A transport implementation for communicating with MCP (Model Context Protocol) servers
+ * via standard input/output streams. This transport spawns a child process and establishes
+ * bidirectional communication using stdin/stdout for JSON-RPC message exchange.
+ *
+ * The StdioTransport handles:
+ * - Cross-platform process spawning (including Windows batch file compatibility)
+ * - JSON-RPC message parsing and serialization
+ * - Proper process lifecycle management with graceful shutdown
+ * - Error handling and logging
+ * - Separate handling of stdout (for JSON-RPC) and stderr (for logging)
+ *
+ * This transport is primarily used for local MCP servers that communicate through
+ * standard I/O streams, such as those launched via npx, npm, or other package managers.
+ *
+ * @implements {Transport}
+ */
+export class StdioTransport {
+    _process;
+    _readBuffer = new ReadBuffer();
+    _stderrStream = null;
+    _serverParams;
+    _serverName;
+    _serverId;
+    _logStorage;
+    /**
+     * Gets the process ID of the spawned child process.
+     *
+     * @returns {number | undefined} The PID of the child process, or undefined if not started
+     */
+    get pid() {
+        return this._process?.pid;
+    }
+    onclose;
+    onerror;
+    onmessage;
+    onstdout;
+    onstderr;
+    /**
+     * Creates a new StdioTransport instance.
+     *
+     * @param {StdioServerParameters} server - Configuration parameters for the child process
+     * @param {string} [serverName] - Optional name for the server used in logging
+     * @param {StdioTransportOptions} [options] - Additional options for the transport
+     */
+    constructor(server, serverName, options) {
+        this._serverParams = server;
+        this._serverName = serverName;
+        this._serverId = options?.serverId;
+        this._logStorage = options?.logStorage;
+        if (server.stderr === 'pipe') {
+            this._stderrStream = new PassThrough();
+        }
+    }
+    /**
+     * Starts the transport by spawning the child process and establishing communication channels.
+     *
+     * This method handles platform-specific considerations:
+     * - On Windows, it automatically wraps batch commands (like npx, npm, etc.) with cmd.exe /c
+     * - Sets up proper stdio configuration based on the server parameters
+     * - Configures event listeners for process lifecycle events
+     * - Establishes data flow for stdout and stderr handling
+     *
+     * @returns {Promise<void>} Resolves when the child process is successfully spawned
+     * @throws {Error} If the transport is already started
+     */
+    async start() {
+        if (this._process) {
+            throw new Error('StdioTransport already started!');
+        }
+        let command = this._serverParams.command;
+        let args = this._serverParams.args ?? [];
+        // Windows compatibility: Batch files (npx, npm, etc.) need cmd.exe /c to run with shell: false
+        if (process.platform === 'win32') {
+            const knownBatchCommands = ['npx', 'npm', 'pnpm', 'yarn', 'uvx'];
+            if (knownBatchCommands.includes(command) ||
+                command.endsWith('.cmd') ||
+                command.endsWith('.bat')) {
+                // Use cmd.exe /c to execute the batch file
+                args = ['/c', command, ...args];
+                command = 'cmd.exe';
+            }
+        }
+        return new Promise((resolve, reject) => {
+            this._process = spawn(command, args, {
+                env: { ...process.env, ...this._serverParams.env },
+                stdio: [
+                    'pipe',
+                    'pipe',
+                    this._serverParams.stderr === 'pipe' ? 'pipe' : this._serverParams.stderr || 'inherit'
+                ],
+                shell: false,
+                windowsHide: true, // Force hide window on Windows
+                cwd: this._serverParams.cwd
+            });
+            this._process.on('error', (error) => {
+                reject(error);
+                this.onerror?.(error);
+            });
+            this._process.on('spawn', () => {
+                resolve();
+            });
+            this._process.on('close', () => {
+                this._process = undefined;
+                this.onclose?.();
+            });
+            this._process.stdin?.on('error', (error) => {
+                this.onerror?.(error);
+            });
+            this._process.stdout?.on('data', (chunk) => {
+                const dataStr = chunk.toString('utf8');
+                // Forward raw stdout data
+                this.onstdout?.(dataStr);
+                // Don't log raw JSON-RPC communication to avoid log noise
+                // Only need to view raw communication during development debugging
+                // Parse JSON-RPC messages
+                this._readBuffer.append(chunk);
+                this.processReadBuffer();
+            });
+            this._process.stdout?.on('error', (error) => {
+                this.onerror?.(error);
+            });
+            /**
+             * Handles stderr data with common processing logic.
+             *
+             * @param chunk - The stderr data chunk
+             * @param writeToStream - Whether to write data to the PassThrough stream
+             */
+            const handleStderrData = (chunk, writeToStream = false) => {
+                const dataStr = chunk.toString('utf8');
+                // Forward raw stderr data
+                this.onstderr?.(dataStr);
+                const trimmedData = dataStr.trim();
+                let logLevel = 'info';
+                // Identify log levels by keywords: only explicit error/warning markers
+                // use corresponding levels, everything else defaults to info
+                const lowerData = trimmedData.toLowerCase();
+                // Error level keywords
+                if (lowerData.includes('error') ||
+                    lowerData.includes('err') ||
+                    lowerData.includes('exception') ||
+                    lowerData.includes('fatal') ||
+                    lowerData.includes('critical')) {
+                    logLevel = 'error';
+                }
+                // Warn level keywords
+                else if (lowerData.includes('warn') ||
+                    lowerData.includes('wrn') ||
+                    lowerData.includes('warning') ||
+                    lowerData.includes('deprecation') ||
+                    lowerData.includes('deprecated')) {
+                    logLevel = 'warn';
+                }
+                if (this._serverName) {
+                    logger.serverLog(logLevel, this._serverName, trimmedData, {
+                        pid: this._process?.pid
+                    });
+                }
+                else {
+                    logger.serverLog(logLevel, 'Unknown Server', trimmedData, {
+                        pid: this._process?.pid
+                    });
+                }
+                // Store in logStorage for frontend display if available
+                if (this._logStorage && this._serverId) {
+                    this._logStorage.append(this._serverId, logLevel, `[${this._serverName || 'Unknown Server'}] [STDERR] ${trimmedData}`);
+                }
+                // Optionally write to PassThrough stream if configured
+                if (writeToStream) {
+                    this._stderrStream?.write(chunk);
+                }
+            };
+            if (this._stderrStream && this._process.stderr) {
+                this._process.stderr.on('data', (chunk) => {
+                    handleStderrData(chunk, true); // Write to PassThrough stream for piped stderr
+                });
+            }
+            else if (this._process.stderr) {
+                // If stderr is not in pipe mode, listen directly
+                this._process.stderr.on('data', (chunk) => {
+                    handleStderrData(chunk, false); // No PassThrough stream for non-piped stderr
+                });
+            }
+        });
+    }
+    /**
+     * Gets the stderr stream for the child process.
+     *
+     * Returns a PassThrough stream if stderr is configured as 'pipe', otherwise returns
+     * the actual stderr stream from the child process, or null if no stderr is available.
+     *
+     * @returns {PassThrough | NodeJS.ReadableStream | null} The stderr stream or null
+     */
+    get stderr() {
+        return this._stderrStream ?? this._process?.stderr ?? null;
+    }
+    /**
+     * Processes the internal read buffer to extract and dispatch JSON-RPC messages.
+     *
+     * This method continuously reads complete JSON-RPC messages from the buffer
+     * and dispatches them to the onmessage callback. It handles partial messages
+     * by leaving incomplete data in the buffer for future processing.
+     *
+     * The method uses a while loop to process all available complete messages
+     * in a single call, ensuring efficient message handling without blocking.
+     *
+     * @private
+     */
+    processReadBuffer() {
+        while (true) {
+            try {
+                const message = this._readBuffer.readMessage();
+                if (message === null) {
+                    break;
+                }
+                this.onmessage?.(message);
+            }
+            catch (error) {
+                this.onerror?.(error);
+            }
+        }
+    }
+    /**
+     * Closes the transport by gracefully terminating the child process.
+     *
+     * This method implements a graceful shutdown sequence:
+     * 1. Sends SIGTERM to allow the child process to clean up
+     * 2. Waits up to 5 seconds for graceful termination
+     * 3. Forces termination with SIGKILL if the process doesn't exit
+     * 4. Cleans up internal state and resolves the promise
+     *
+     * The method ensures proper cleanup of the read buffer and handles
+     * any errors that occur during the shutdown process.
+     *
+     * @returns {Promise<void>} Resolves when the transport is fully closed
+     */
+    async close() {
+        if (this._process) {
+            return new Promise((resolve) => {
+                // Listen for child process exit events
+                const cleanup = () => {
+                    this._process = undefined;
+                    this._readBuffer.clear();
+                    resolve();
+                };
+                if (this._process) {
+                    this._process.once('close', cleanup);
+                    this._process.once('exit', cleanup);
+                    // Send SIGTERM signal to give child process a chance to shut down gracefully
+                    try {
+                        this._process.kill('SIGTERM');
+                        // Set timeout protection to force kill if child process doesn't exit within 5 seconds
+                        const timeout = setTimeout(() => {
+                            if (this._process) {
+                                logger.warn('Child process did not exit gracefully, force killing...');
+                                this._process.kill('SIGKILL');
+                            }
+                        }, 5000);
+                        // Ensure timeout timer is cleared after process exits
+                        this._process.once('close', () => clearTimeout(timeout));
+                        this._process.once('exit', () => clearTimeout(timeout));
+                    }
+                    catch (error) {
+                        logger.error('Error closing stdio transport:', error);
+                        cleanup();
+                    }
+                }
+                else {
+                    // Process is already undefined, just resolve
+                    resolve();
+                }
+            });
+        }
+        this._readBuffer.clear();
+    }
+    /**
+     * Sends a JSON-RPC message to the child process via stdin.
+     *
+     * This method serializes the message to JSON, appends a newline character,
+     * and writes it to the child process's stdin stream. It validates that
+     * the transport is connected before attempting to send the message.
+     *
+     * @param {JSONRPCMessage} message - The JSON-RPC message to send
+     * @returns {Promise<void>} Resolves when the message is written to stdin
+     * @throws {Error} If the transport is not connected (no active child process)
+     */
+    async send(message) {
+        if (!this._process?.stdin) {
+            throw new Error('Not connected');
+        }
+        const json = JSON.stringify(message) + '\n';
+        this._process.stdin.write(json);
+    }
+}

package/dist/server/src/utils/transports/streamable-http-transport.d.ts

@@ -0,0 +1,146 @@
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+/**
+ * Streamable HTTP Transport implementation for MCP (Model Context Protocol)
+ *
+ * This transport enables communication with MCP servers that support the Streamable HTTP protocol,
+ * which provides bidirectional communication over HTTP using a combination of POST requests for
+ * sending messages and Server-Sent Events (SSE) for receiving streamed responses.
+ *
+ * The Streamable HTTP protocol is particularly useful for:
+ * - Remote MCP servers accessible via HTTP/HTTPS
+ * - Scenarios requiring streaming responses from tools
+ * - Environments where WebSocket connections are restricted
+ * - Integration with existing HTTP infrastructure
+ *
+ * Protocol Details:
+ * - **Outbound Messages**: Sent via HTTP POST requests with JSON-RPC 2.0 formatted payloads
+ * - **Inbound Messages**: Received via HTTP GET requests using Server-Sent Events (SSE) for real-time streaming
+ * - **Headers**: Custom headers can be provided for authentication, authorization, or other HTTP requirements
+ * - **Timeout**: Configurable request timeout to prevent hanging connections
+ *
+ * This transport wraps the official MCP SDK's StreamableHTTPClientTransport and provides
+ * consistent error handling, logging, and lifecycle management integrated with the MCP Hub Lite system.
+ *
+ * @implements {Transport}
+ * @see {@link https://modelcontextprotocol.io/transports/streamable-http} - Official MCP Streamable HTTP specification
+ */
+export declare class StreamableHttpTransport implements Transport {
+    private url;
+    private headers;
+    private timeout;
+    /**
+     * Internal reference to the underlying MCP SDK transport instance
+     * @private
+     */
+    private transport;
+    /**
+     * Flag indicating whether the transport is in the process of closing
+     * Prevents sending messages during shutdown and handles unexpected closures
+     * @private
+     */
+    private isClosing;
+    /**
+     * Event handler called when a JSON-RPC message is received from the server
+     * @public
+     */
+    onmessage?: (message: JSONRPCMessage) => void;
+    /**
+     * Event handler called when an error occurs in the transport connection
+     * @public
+     */
+    onerror?: (error: Error) => void;
+    /**
+     * Event handler called when the transport connection is closed
+     * @public
+     */
+    onclose?: () => void;
+    /**
+     * Creates a new Streamable HTTP Transport instance
+     *
+     * @param url - The base URL of the MCP server endpoint (e.g., "https://api.example.com/mcp")
+     * @param headers - Optional HTTP headers to include with all requests (default: {})
+     *                 Commonly used for authentication tokens, API keys, or custom headers
+     * @param timeout - Request timeout in milliseconds (default: 30000 = 30 seconds)
+     *                  Controls how long to wait for HTTP responses before timing out
+     */
+    constructor(url: string, headers?: Record<string, string>, timeout?: number);
+    /**
+     * Initializes and starts the Streamable HTTP transport connection
+     *
+     * This method establishes the connection to the MCP server by:
+     * 1. Validating that the transport hasn't already been started
+     * 2. Creating a new StreamableHTTPClientTransport instance from the MCP SDK
+     * 3. Configuring HTTP request options including headers and timeout
+     * 4. Setting up event handlers for message, error, and close events
+     * 5. Starting the underlying transport connection
+     *
+     * The transport will automatically handle:
+     * - Message routing to the onmessage handler
+     * - Error logging and propagation to the onerror handler
+     * - Connection lifecycle management with proper cleanup
+     *
+     * @returns {Promise<void>} Resolves when the transport is successfully started
+     * @throws {Error} If the transport is already started or if connection fails
+     *
+     * @example
+     * ```typescript
+     * const transport = new StreamableHttpTransport('https://api.example.com/mcp', {
+     *   'Authorization': 'Bearer your-token'
+     * });
+     * await transport.start();
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Gracefully closes the Streamable HTTP transport connection
+     *
+     * This method performs a clean shutdown of the transport by:
+     * 1. Setting the closing flag to prevent new message sends
+     * 2. Closing the underlying MCP SDK transport connection
+     * 3. Cleaning up the internal transport reference
+     * 4. Triggering the onclose event handler
+     *
+     * The method is idempotent and can be called multiple times safely.
+     * It ensures proper resource cleanup and prevents memory leaks.
+     *
+     * @returns {Promise<void>} Resolves when the transport is successfully closed
+     *
+     * @example
+     * ```typescript
+     * await transport.close();
+     * // Transport is now closed and cannot send/receive messages
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Sends a JSON-RPC message to the connected MCP server
+     *
+     * This method transmits the provided JSON-RPC message to the server using the
+     * Streamable HTTP protocol. The message is sent as an HTTP POST request with
+     * the appropriate Content-Type header and any configured custom headers.
+     *
+     * The method includes comprehensive validation and error handling:
+     * - Prevents sending messages when the transport is closing
+     * - Ensures the transport has been properly initialized
+     * - Logs transmission errors for debugging purposes
+     * - Re-throws errors to allow caller error handling
+     *
+     * @param message - The JSON-RPC 2.0 formatted message to send to the server
+     * @returns {Promise<void>} Resolves when the message is successfully sent
+     * @throws {Error} If the transport is closing, not started, or if sending fails
+     *
+     * @example
+     * ```typescript
+     * const request: JSONRPCMessage = {
+     *   jsonrpc: '2.0',
+     *   id: 1,
+     *   method: 'textDocument/completion',
+     *   params: { /* completion parameters *\/ }
+     * };
+     * await transport.send(request);
+     * ```
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+}
+//# sourceMappingURL=streamable-http-transport.d.ts.map

package/dist/server/src/utils/transports/streamable-http-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamable-http-transport.d.ts","sourceRoot":"","sources":["../../../../../src/utils/transports/streamable-http-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAK1E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,uBAAwB,YAAW,SAAS;IA0CrD,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;IA3CjB;;;OAGG;IACH,OAAO,CAAC,SAAS,CAA8C;IAE/D;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;IACI,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAErD;;;OAGG;IACI,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACI,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAE5B;;;;;;;;OAQG;gBAEO,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACpC,OAAO,GAAE,MAAc;IAGjC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwD5B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAoBnD"}

package/dist/server/src/utils/transports/streamable-http-transport.js

@@ -0,0 +1,212 @@
+import { logger, LOG_MODULES } from '../logger.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { URL } from 'url';
+/**
+ * Streamable HTTP Transport implementation for MCP (Model Context Protocol)
+ *
+ * This transport enables communication with MCP servers that support the Streamable HTTP protocol,
+ * which provides bidirectional communication over HTTP using a combination of POST requests for
+ * sending messages and Server-Sent Events (SSE) for receiving streamed responses.
+ *
+ * The Streamable HTTP protocol is particularly useful for:
+ * - Remote MCP servers accessible via HTTP/HTTPS
+ * - Scenarios requiring streaming responses from tools
+ * - Environments where WebSocket connections are restricted
+ * - Integration with existing HTTP infrastructure
+ *
+ * Protocol Details:
+ * - **Outbound Messages**: Sent via HTTP POST requests with JSON-RPC 2.0 formatted payloads
+ * - **Inbound Messages**: Received via HTTP GET requests using Server-Sent Events (SSE) for real-time streaming
+ * - **Headers**: Custom headers can be provided for authentication, authorization, or other HTTP requirements
+ * - **Timeout**: Configurable request timeout to prevent hanging connections
+ *
+ * This transport wraps the official MCP SDK's StreamableHTTPClientTransport and provides
+ * consistent error handling, logging, and lifecycle management integrated with the MCP Hub Lite system.
+ *
+ * @implements {Transport}
+ * @see {@link https://modelcontextprotocol.io/transports/streamable-http} - Official MCP Streamable HTTP specification
+ */
+export class StreamableHttpTransport {
+    url;
+    headers;
+    timeout;
+    /**
+     * Internal reference to the underlying MCP SDK transport instance
+     * @private
+     */
+    transport = null;
+    /**
+     * Flag indicating whether the transport is in the process of closing
+     * Prevents sending messages during shutdown and handles unexpected closures
+     * @private
+     */
+    isClosing = false;
+    /**
+     * Event handler called when a JSON-RPC message is received from the server
+     * @public
+     */
+    onmessage;
+    /**
+     * Event handler called when an error occurs in the transport connection
+     * @public
+     */
+    onerror;
+    /**
+     * Event handler called when the transport connection is closed
+     * @public
+     */
+    onclose;
+    /**
+     * Creates a new Streamable HTTP Transport instance
+     *
+     * @param url - The base URL of the MCP server endpoint (e.g., "https://api.example.com/mcp")
+     * @param headers - Optional HTTP headers to include with all requests (default: {})
+     *                 Commonly used for authentication tokens, API keys, or custom headers
+     * @param timeout - Request timeout in milliseconds (default: 30000 = 30 seconds)
+     *                  Controls how long to wait for HTTP responses before timing out
+     */
+    constructor(url, headers = {}, timeout = 30000) {
+        this.url = url;
+        this.headers = headers;
+        this.timeout = timeout;
+    }
+    /**
+     * Initializes and starts the Streamable HTTP transport connection
+     *
+     * This method establishes the connection to the MCP server by:
+     * 1. Validating that the transport hasn't already been started
+     * 2. Creating a new StreamableHTTPClientTransport instance from the MCP SDK
+     * 3. Configuring HTTP request options including headers and timeout
+     * 4. Setting up event handlers for message, error, and close events
+     * 5. Starting the underlying transport connection
+     *
+     * The transport will automatically handle:
+     * - Message routing to the onmessage handler
+     * - Error logging and propagation to the onerror handler
+     * - Connection lifecycle management with proper cleanup
+     *
+     * @returns {Promise<void>} Resolves when the transport is successfully started
+     * @throws {Error} If the transport is already started or if connection fails
+     *
+     * @example
+     * ```typescript
+     * const transport = new StreamableHttpTransport('https://api.example.com/mcp', {
+     *   'Authorization': 'Bearer your-token'
+     * });
+     * await transport.start();
+     * ```
+     */
+    async start() {
+        if (this.transport) {
+            throw new Error('Streamable HTTP Transport already started!');
+        }
+        this.isClosing = false;
+        try {
+            const url = new URL(this.url);
+            const requestInit = {
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.headers
+                },
+                signal: AbortSignal.timeout(this.timeout)
+            };
+            this.transport = new StreamableHTTPClientTransport(url, {
+                requestInit
+            });
+            // Set up event handlers
+            this.transport.onmessage = (message) => {
+                this.onmessage?.(message);
+            };
+            this.transport.onerror = (error) => {
+                logger.error('Streamable HTTP transport error:', error, LOG_MODULES.HTTP_TRANSPORT);
+                this.onerror?.(error);
+            };
+            this.transport.onclose = () => {
+                logger.info('Streamable HTTP transport closed', LOG_MODULES.HTTP_TRANSPORT);
+                if (!this.isClosing) {
+                    // Unexpected close, trigger error
+                    const error = new Error('Streamable HTTP transport closed unexpectedly');
+                    this.onerror?.(error);
+                }
+                this.onclose?.();
+            };
+            await this.transport.start();
+            logger.info(`Streamable HTTP transport initialized for ${this.url}`, LOG_MODULES.HTTP_TRANSPORT);
+        }
+        catch (error) {
+            logger.error('Failed to create Streamable HTTP transport:', error, LOG_MODULES.HTTP_TRANSPORT);
+            throw error;
+        }
+    }
+    /**
+     * Gracefully closes the Streamable HTTP transport connection
+     *
+     * This method performs a clean shutdown of the transport by:
+     * 1. Setting the closing flag to prevent new message sends
+     * 2. Closing the underlying MCP SDK transport connection
+     * 3. Cleaning up the internal transport reference
+     * 4. Triggering the onclose event handler
+     *
+     * The method is idempotent and can be called multiple times safely.
+     * It ensures proper resource cleanup and prevents memory leaks.
+     *
+     * @returns {Promise<void>} Resolves when the transport is successfully closed
+     *
+     * @example
+     * ```typescript
+     * await transport.close();
+     * // Transport is now closed and cannot send/receive messages
+     * ```
+     */
+    async close() {
+        this.isClosing = true;
+        if (this.transport) {
+            await this.transport.close();
+            this.transport = null;
+        }
+        this.onclose?.();
+    }
+    /**
+     * Sends a JSON-RPC message to the connected MCP server
+     *
+     * This method transmits the provided JSON-RPC message to the server using the
+     * Streamable HTTP protocol. The message is sent as an HTTP POST request with
+     * the appropriate Content-Type header and any configured custom headers.
+     *
+     * The method includes comprehensive validation and error handling:
+     * - Prevents sending messages when the transport is closing
+     * - Ensures the transport has been properly initialized
+     * - Logs transmission errors for debugging purposes
+     * - Re-throws errors to allow caller error handling
+     *
+     * @param message - The JSON-RPC 2.0 formatted message to send to the server
+     * @returns {Promise<void>} Resolves when the message is successfully sent
+     * @throws {Error} If the transport is closing, not started, or if sending fails
+     *
+     * @example
+     * ```typescript
+     * const request: JSONRPCMessage = {
+     *   jsonrpc: '2.0',
+     *   id: 1,
+     *   method: 'textDocument/completion',
+     *   params: { /* completion parameters *\/ }
+     * };
+     * await transport.send(request);
+     * ```
+     */
+    async send(message) {
+        if (this.isClosing) {
+            throw new Error('Transport is closing');
+        }
+        if (!this.transport) {
+            throw new Error('Streamable HTTP transport not started');
+        }
+        try {
+            await this.transport.send(message);
+        }
+        catch (error) {
+            logger.error('Failed to send message via Streamable HTTP:', error, LOG_MODULES.HTTP_TRANSPORT);
+            throw error;
+        }
+    }
+}