@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/utils/tool-args-parser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tool arguments parser
+ */
+export declare class ToolArgsParser {
+    /**
+     * Parses prefixed tool names (like mcp__mcp-hub-lite__xxx)
+     */
+    static parsePrefixedToolName(toolName: string): {
+        serverName: string;
+        toolName: string;
+    } | null;
+    /**
+     * Validates tool argument types
+     */
+    static validateToolArgs(): boolean;
+}
+//# sourceMappingURL=tool-args-parser.d.ts.map

package/dist/server/src/utils/tool-args-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-args-parser.d.ts","sourceRoot":"","sources":["../../../../src/utils/tool-args-parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAc;IACzB;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAyB/F;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,OAAO;CAInC"}

package/dist/server/src/utils/tool-args-parser.js

@@ -0,0 +1,34 @@
+/**
+ * Tool arguments parser
+ */
+export class ToolArgsParser {
+    /**
+     * Parses prefixed tool names (like mcp__mcp-hub-lite__xxx)
+     */
+    static parsePrefixedToolName(toolName) {
+        if (!toolName.includes('__')) {
+            return null;
+        }
+        const doubleUnderscoreIndex = toolName.indexOf('__');
+        const secondDoubleUnderscoreIndex = toolName.indexOf('__', doubleUnderscoreIndex + 2);
+        if (secondDoubleUnderscoreIndex === -1) {
+            return null;
+        }
+        const serverName = toolName.substring(doubleUnderscoreIndex + 2, secondDoubleUnderscoreIndex);
+        const parsedToolName = toolName.substring(secondDoubleUnderscoreIndex + 2);
+        if (!serverName || !parsedToolName) {
+            return null;
+        }
+        return {
+            serverName,
+            toolName: parsedToolName
+        };
+    }
+    /**
+     * Validates tool argument types
+     */
+    static validateToolArgs() {
+        // 可以根据工具名称验证参数类型
+        return true;
+    }
+}

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

@@ -0,0 +1,104 @@
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+/**
+ * SSE (Server-Sent Events) transport implementation for MCP protocol communication.
+ *
+ * This transport provides a unidirectional communication channel from server to client
+ * using the Server-Sent Events (SSE) protocol. It is designed for MCP servers that
+ * support SSE for streaming notifications and responses to the client.
+ *
+ * **Key Features:**
+ * - Automatic reconnection with exponential backoff strategy
+ * - JSON-RPC message parsing and validation
+ * - Configurable connection parameters (headers, reconnect interval, max attempts)
+ * - Built-in error handling and logging
+ * - Graceful shutdown and cleanup
+ *
+ * **Limitations:**
+ * - SSE is unidirectional (server-to-client only)
+ * - Client-to-server messages are not supported via this transport
+ * - For bidirectional communication, use stdio or HTTP transports instead
+ *
+ * **Usage Scenario:**
+ * Ideal for remote MCP servers that expose SSE endpoints for real-time updates,
+ * notifications, or streaming responses where the client primarily receives data
+ * from the server rather than sending requests.
+ *
+ * @implements {Transport}
+ */
+export declare class SseTransport implements Transport {
+    private url;
+    private headers;
+    private reconnectInterval;
+    private maxReconnectAttempts;
+    private eventSource;
+    private reconnectAttempts;
+    private isClosing;
+    onmessage?: (message: JSONRPCMessage) => void;
+    onerror?: (error: Error) => void;
+    onclose?: () => void;
+    /**
+     * Creates a new SSE transport instance.
+     *
+     * @param url - The SSE endpoint URL to connect to
+     * @param headers - Optional HTTP headers to include in the SSE connection request
+     * @param reconnectInterval - Time interval (in milliseconds) between reconnection attempts (default: 3000ms)
+     * @param maxReconnectAttempts - Maximum number of reconnection attempts before giving up (default: 5)
+     */
+    constructor(url: string, headers?: Record<string, string>, reconnectInterval?: number, maxReconnectAttempts?: number);
+    /**
+     * Initializes and starts the SSE connection to the specified URL.
+     *
+     * This method establishes a connection to the SSE endpoint, sets up event handlers
+     * for message processing, error handling, and connection lifecycle events.
+     * It also configures automatic reconnection logic for handling transient network issues.
+     *
+     * @throws {Error} If the transport is already started or if connection creation fails
+     * @returns {Promise<void>} Resolves when the connection is successfully established
+     */
+    start(): Promise<void>;
+    /**
+     * Restarts the SSE connection by closing the current connection and starting a new one.
+     *
+     * This method is used internally for automatic reconnection after connection failures.
+     * It ensures proper cleanup of the existing connection before attempting to establish
+     * a new one, preventing resource leaks or duplicate connections.
+     *
+     * @returns {Promise<void>} Resolves when the restart process is complete
+     */
+    private restart;
+    /**
+     * Gracefully closes the SSE connection and prevents further reconnection attempts.
+     *
+     * This method sets the closing flag to prevent automatic reconnection and then
+     * delegates to the internal close implementation for actual cleanup.
+     *
+     * @returns {Promise<void>} Resolves when the connection is fully closed
+     */
+    close(): Promise<void>;
+    /**
+     * Performs the actual cleanup of the SSE connection resources.
+     *
+     * This internal method handles the low-level closing of the EventSource connection,
+     * nullifies the reference, and triggers the onclose callback if defined.
+     * It is used by both the public close method and the restart method.
+     *
+     * @returns {Promise<void>} Resolves when internal cleanup is complete
+     */
+    private closeInternal;
+    /**
+     * Attempts to send a JSON-RPC message through the SSE transport.
+     *
+     * **Note**: This method always throws an error because SSE is a unidirectional
+     * protocol (server-to-client only). Client-to-server communication is not supported
+     * by the SSE protocol specification.
+     *
+     * For bidirectional MCP communication, use stdio or HTTP transports instead.
+     *
+     * @param message - The JSON-RPC message to send (will not be actually sent)
+     * @throws {Error} Always throws an error indicating that SSE transport does not support sending messages
+     * @returns {Promise<void>} Never resolves successfully due to the inherent limitation of SSE
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+}
+//# sourceMappingURL=sse-transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse-transport.d.ts","sourceRoot":"","sources":["../../../../../src/utils/transports/sse-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAM1E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,YAAa,YAAW,SAAS;IAkB1C,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,iBAAiB;IACzB,OAAO,CAAC,oBAAoB;IApB9B,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,SAAS,CAAS;IAEnB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAE5B;;;;;;;OAOG;gBAEO,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACpC,iBAAiB,GAAE,MAAa,EAChC,oBAAoB,GAAE,MAAU;IAG1C;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0D5B;;;;;;;;OAQG;YACW,OAAO;IAOrB;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;;;;;;OAQG;YACW,aAAa;IAQ3B;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBnD"}

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

@@ -0,0 +1,189 @@
+import { logger } from '../logger.js';
+// Use EventSource from the 'eventsource' package for Node.js compatibility
+import { EventSource } from 'eventsource';
+/**
+ * SSE (Server-Sent Events) transport implementation for MCP protocol communication.
+ *
+ * This transport provides a unidirectional communication channel from server to client
+ * using the Server-Sent Events (SSE) protocol. It is designed for MCP servers that
+ * support SSE for streaming notifications and responses to the client.
+ *
+ * **Key Features:**
+ * - Automatic reconnection with exponential backoff strategy
+ * - JSON-RPC message parsing and validation
+ * - Configurable connection parameters (headers, reconnect interval, max attempts)
+ * - Built-in error handling and logging
+ * - Graceful shutdown and cleanup
+ *
+ * **Limitations:**
+ * - SSE is unidirectional (server-to-client only)
+ * - Client-to-server messages are not supported via this transport
+ * - For bidirectional communication, use stdio or HTTP transports instead
+ *
+ * **Usage Scenario:**
+ * Ideal for remote MCP servers that expose SSE endpoints for real-time updates,
+ * notifications, or streaming responses where the client primarily receives data
+ * from the server rather than sending requests.
+ *
+ * @implements {Transport}
+ */
+export class SseTransport {
+    url;
+    headers;
+    reconnectInterval;
+    maxReconnectAttempts;
+    eventSource = null;
+    reconnectAttempts = 0;
+    isClosing = false;
+    onmessage;
+    onerror;
+    onclose;
+    /**
+     * Creates a new SSE transport instance.
+     *
+     * @param url - The SSE endpoint URL to connect to
+     * @param headers - Optional HTTP headers to include in the SSE connection request
+     * @param reconnectInterval - Time interval (in milliseconds) between reconnection attempts (default: 3000ms)
+     * @param maxReconnectAttempts - Maximum number of reconnection attempts before giving up (default: 5)
+     */
+    constructor(url, headers = {}, reconnectInterval = 3000, maxReconnectAttempts = 5) {
+        this.url = url;
+        this.headers = headers;
+        this.reconnectInterval = reconnectInterval;
+        this.maxReconnectAttempts = maxReconnectAttempts;
+    }
+    /**
+     * Initializes and starts the SSE connection to the specified URL.
+     *
+     * This method establishes a connection to the SSE endpoint, sets up event handlers
+     * for message processing, error handling, and connection lifecycle events.
+     * It also configures automatic reconnection logic for handling transient network issues.
+     *
+     * @throws {Error} If the transport is already started or if connection creation fails
+     * @returns {Promise<void>} Resolves when the connection is successfully established
+     */
+    async start() {
+        if (this.eventSource) {
+            throw new Error('SSE Transport already started!');
+        }
+        this.isClosing = false;
+        this.reconnectAttempts = 0;
+        // Note: The 'eventsource' package doesn't support custom headers directly,
+        // but we can pass them as options
+        try {
+            const options = {};
+            if (Object.keys(this.headers).length > 0) {
+                options.headers = this.headers;
+            }
+            this.eventSource = new EventSource(this.url, options);
+            this.eventSource.onmessage = (event) => {
+                try {
+                    const message = JSON.parse(event.data);
+                    this.onmessage?.(message);
+                    this.reconnectAttempts = 0; // Reset on successful message
+                }
+                catch (error) {
+                    logger.error('Failed to parse SSE message:', error);
+                    this.onerror?.(new Error(`Invalid JSON in SSE message: ${event.data}`));
+                }
+            };
+            this.eventSource.onerror = () => {
+                const error = new Error(`SSE connection error for ${this.url}`);
+                logger.error('SSE connection error:', error);
+                if (!this.isClosing) {
+                    this.reconnectAttempts++;
+                    if (this.reconnectAttempts <= this.maxReconnectAttempts) {
+                        logger.info(`Attempting to reconnect SSE (${this.reconnectAttempts}/${this.maxReconnectAttempts})...`);
+                        setTimeout(() => {
+                            this.restart();
+                        }, this.reconnectInterval);
+                    }
+                    else {
+                        logger.error('Max reconnection attempts reached for SSE');
+                        this.onerror?.(error);
+                        this.closeInternal();
+                    }
+                }
+            };
+            this.eventSource.onopen = () => {
+                logger.info(`SSE connection opened to ${this.url}`);
+            };
+        }
+        catch (error) {
+            logger.error('Failed to create SSE connection:', error);
+            throw error;
+        }
+    }
+    /**
+     * Restarts the SSE connection by closing the current connection and starting a new one.
+     *
+     * This method is used internally for automatic reconnection after connection failures.
+     * It ensures proper cleanup of the existing connection before attempting to establish
+     * a new one, preventing resource leaks or duplicate connections.
+     *
+     * @returns {Promise<void>} Resolves when the restart process is complete
+     */
+    async restart() {
+        await this.closeInternal();
+        if (!this.isClosing) {
+            await this.start();
+        }
+    }
+    /**
+     * Gracefully closes the SSE connection and prevents further reconnection attempts.
+     *
+     * This method sets the closing flag to prevent automatic reconnection and then
+     * delegates to the internal close implementation for actual cleanup.
+     *
+     * @returns {Promise<void>} Resolves when the connection is fully closed
+     */
+    async close() {
+        this.isClosing = true;
+        await this.closeInternal();
+    }
+    /**
+     * Performs the actual cleanup of the SSE connection resources.
+     *
+     * This internal method handles the low-level closing of the EventSource connection,
+     * nullifies the reference, and triggers the onclose callback if defined.
+     * It is used by both the public close method and the restart method.
+     *
+     * @returns {Promise<void>} Resolves when internal cleanup is complete
+     */
+    async closeInternal() {
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+            this.onclose?.();
+        }
+    }
+    /**
+     * Attempts to send a JSON-RPC message through the SSE transport.
+     *
+     * **Note**: This method always throws an error because SSE is a unidirectional
+     * protocol (server-to-client only). Client-to-server communication is not supported
+     * by the SSE protocol specification.
+     *
+     * For bidirectional MCP communication, use stdio or HTTP transports instead.
+     *
+     * @param message - The JSON-RPC message to send (will not be actually sent)
+     * @throws {Error} Always throws an error indicating that SSE transport does not support sending messages
+     * @returns {Promise<void>} Never resolves successfully due to the inherent limitation of SSE
+     */
+    async send(message) {
+        // SSE is unidirectional (server to client only)
+        // For bidirectional communication, we need a separate HTTP endpoint
+        // This is a limitation of SSE protocol
+        const error = new Error('SSE transport does not support sending messages. ' +
+            'SSE is a unidirectional protocol (server-to-client only). ' +
+            'For bidirectional MCP communication, use stdio or HTTP transports instead.');
+        // Type-safe way to access message properties
+        const messageId = 'id' in message ? String(message.id) : 'unknown';
+        const method = 'method' in message ? String(message.method) : 'unknown';
+        logger.warn('Attempted to send message via SSE transport', {
+            messageId,
+            method
+        });
+        throw error;
+    }
+}

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

@@ -0,0 +1,122 @@
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { LogStorageService } from '../../services/log-storage.service.js';
+export interface StdioServerParameters {
+    command: string;
+    args?: string[];
+    env?: NodeJS.ProcessEnv;
+    stderr?: 'inherit' | 'pipe' | 'ignore';
+    cwd?: string;
+}
+export interface StdioTransportOptions {
+    serverId?: string;
+    logStorage?: LogStorageService;
+}
+/**
+ * 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 declare class StdioTransport implements Transport {
+    private _process?;
+    private _readBuffer;
+    private _stderrStream;
+    private _serverParams;
+    private _serverName?;
+    private _serverId?;
+    private _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(): number | undefined;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    onstdout?: (data: string) => void;
+    onstderr?: (data: string) => void;
+    /**
+     * 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: StdioServerParameters, serverName?: string, options?: StdioTransportOptions);
+    /**
+     * 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
+     */
+    start(): Promise<void>;
+    /**
+     * 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(): import("node:stream").Readable | 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(): void;
+    /**
+     * 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
+     */
+    close(): Promise<void>;
+    /**
+     * 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)
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+}
+//# sourceMappingURL=stdio-transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-transport.d.ts","sourceRoot":"","sources":["../../../../../src/utils/transports/stdio-transport.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAgC1E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,CAAe;IAChC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,aAAa,CAAwB;IAC7C,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAC,CAAoB;IAExC;;;;OAIG;IACH,IAAW,GAAG,IAAI,MAAM,GAAG,SAAS,CAEnC;IAEM,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEzC;;;;;;OAMG;gBACS,MAAM,EAAE,qBAAqB,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;IAU/F;;;;;;;;;;;OAWG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmJ5B;;;;;;;OAOG;IACH,IAAI,MAAM,0CAET;IAED;;;;;;;;;;;OAWG;IACH,iBAAiB;IAcjB;;;;;;;;;;;;;OAaG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0C5B;;;;;;;;;;OAUG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAOnD"}