@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/utils/logger/logger.js

@@ -0,0 +1,350 @@
+/**
+ * Advanced structured logger with color support, file output, and context-aware logging.
+ *
+ * This logger provides comprehensive logging capabilities with the following features:
+ * - ANSI color-coded console output with different colors for each log level
+ * - Structured context information including PID, server name, trace ID, span ID
+ * - File output with plain text formatting (no colors) for log analysis
+ * - Development mode with automatic log file creation and clearing
+ * - Context-aware logging with module, traceId, and spanId support
+ * - Error formatting with stack trace truncation to prevent overly verbose logs
+ * - MCP server-specific logging with serverName context
+ * - Log rotation with date-based file naming and automatic cleanup
+ *
+ * The logger supports four log levels: debug, info, warn, and error, with configurable
+ * minimum log level threshold.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * logger.info('Server started', { port: 7788 });
+ *
+ * // With context
+ * logger.error('Connection failed', { error: err.message, serverName: 'my-server' });
+ *
+ * // Development mode
+ * logger.enableDevLog();
+ * ```
+ */
+import { DevLogger } from './dev-logger.js';
+import { LOG_MODULES } from './log-modules.js';
+import { createColoredLogMessage, createLogMessage, formatError, formatTimestamp, formatLogLevel, formatPid } from './log-formatter.js';
+import { setDevModeEnabled } from '../json-utils.js';
+export class Logger {
+    level = 'info';
+    useStderr = false;
+    useColor = true;
+    devLogger = new DevLogger();
+    constructor(level = 'info') {
+        this.level = level;
+        const devLogFileEnv = process.env.DEV_LOG_FILE;
+        if (devLogFileEnv === 'true' || devLogFileEnv === '1') {
+            this.enableDevLog();
+        }
+        const noColorEnv = process.env.NO_COLOR;
+        if (noColorEnv === 'true' || noColorEnv === '1' || noColorEnv === '') {
+            this.setUseColor(false);
+        }
+    }
+    /**
+     * Enables development logging mode with file output and enhanced debugging.
+     *
+     * @param rotatorConfig - Optional custom rotation configuration (default: 7 days retention)
+     * @example
+     * ```typescript
+     * const logger = new Logger();
+     * logger.enableDevLog(); // Logs will be written to logs/dev-server.2026-02-27.log
+     *
+     * // With custom retention period
+     * logger.enableDevLog({ rotationAge: '14d' });
+     * ```
+     */
+    enableDevLog(rotatorConfig) {
+        setDevModeEnabled(true);
+        this.devLogger.enableDevLog(rotatorConfig, (logFile) => {
+            this.debug(`Writing logs to: ${logFile}`, LOG_MODULES.DEV_SERVER);
+        });
+    }
+    setUseStderr(use) {
+        this.useStderr = use;
+    }
+    /**
+     * Enable or disable ANSI color output.
+     * When disabled, logs will be plain text without color codes.
+     *
+     * @param use - Whether to use color in output
+     * @example
+     * ```typescript
+     * logger.setUseColor(false); // Plain text output for files
+     * ```
+     */
+    setUseColor(use) {
+        this.useColor = use;
+    }
+    /**
+     * Check if a message should be logged at the current level.
+     * @internal Public for testing only
+     */
+    shouldLog(messageLevel) {
+        const levels = ['debug', 'info', 'warn', 'error'];
+        return levels.indexOf(messageLevel) >= levels.indexOf(this.level);
+    }
+    /**
+     * Generic logging method to eliminate code duplication.
+     */
+    log(level, message, args, options) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        let fullMessage = message;
+        if (args.length > 0) {
+            const formattedArgs = args.map((arg) => formatError(arg)).join(' ');
+            fullMessage = `${message} ${formattedArgs}`;
+        }
+        const context = options
+            ? {
+                module: options.module,
+                traceId: options.traceId,
+                spanId: options.spanId
+            }
+            : undefined;
+        const coloredLogMsg = createColoredLogMessage(level, fullMessage, context);
+        const plainLogMsg = createLogMessage(level, fullMessage, context);
+        const consoleLogMsg = this.useColor ? coloredLogMsg : plainLogMsg;
+        if (this.useStderr) {
+            console.error(consoleLogMsg);
+        }
+        else {
+            switch (level) {
+                case 'debug':
+                    console.debug(consoleLogMsg);
+                    break;
+                case 'info':
+                    console.info(consoleLogMsg);
+                    break;
+                case 'warn':
+                    console.warn(consoleLogMsg);
+                    break;
+                case 'error':
+                    console.error(consoleLogMsg);
+                    break;
+            }
+        }
+        const logFileStream = this.devLogger.stream;
+        if (logFileStream) {
+            logFileStream.write(plainLogMsg + '\n');
+        }
+    }
+    /**
+     * Logs a debug message with optional context and additional arguments.
+     *
+     * @param message - The primary log message
+     * @param args - Additional arguments to include in the log
+     *
+     * @example
+     * ```typescript
+     * // Basic debug message
+     * logger.debug('Processing request');
+     *
+     * // With context
+     * logger.debug('Tool called', { module: 'Gateway', traceId: 'abc123' }, toolName, args);
+     * ```
+     */
+    debug(message, ...args) {
+        const [options, ...restArgs] = this.extractOptionsAndArgs(args);
+        this.log('debug', message, restArgs, options);
+    }
+    /**
+     * Logs an informational message with optional context and additional arguments.
+     *
+     * @param message - The primary log message
+     * @param args - Additional arguments to include in the log
+     *
+     * @example
+     * ```typescript
+     * // Basic info message
+     * logger.info('Server started successfully');
+     *
+     * // With context and additional data
+     * logger.info('Request processed', { module: 'API' }, { duration: 150, statusCode: 200 });
+     * ```
+     */
+    info(message, ...args) {
+        const [options, ...restArgs] = this.extractOptionsAndArgs(args);
+        this.log('info', message, restArgs, options);
+    }
+    /**
+     * Logs a warning message with optional context and additional arguments.
+     *
+     * @param message - The primary log message
+     * @param args - Additional arguments to include in the log
+     *
+     * @example
+     * ```typescript
+     * // Basic warning message
+     * logger.warn('Deprecated API usage detected');
+     *
+     * // With context and error details
+     * logger.warn('Connection timeout', { module: 'Network' }, { server: 'api.example.com', timeout: 5000 });
+     * ```
+     */
+    warn(message, ...args) {
+        const [options, ...restArgs] = this.extractOptionsAndArgs(args);
+        this.log('warn', message, restArgs, options);
+    }
+    /**
+     * Logs an error message with optional context and additional arguments.
+     *
+     * @param message - The primary log message
+     * @param args - Additional arguments to include in the log
+     *
+     * @example
+     * ```typescript
+     * // Basic error message
+     * logger.error('Database connection failed');
+     *
+     * // With error object and context
+     * logger.error('Request processing failed', { module: 'API' }, error, { requestId: '123' });
+     * ```
+     */
+    error(message, ...args) {
+        const [options, ...restArgs] = this.extractOptionsAndArgs(args);
+        this.log('error', message, restArgs, options);
+    }
+    extractOptionsAndArgs(args) {
+        const optionsIndex = args.findIndex((arg) => typeof arg === 'object' &&
+            arg !== null &&
+            !Array.isArray(arg) &&
+            ('module' in arg || 'traceId' in arg || 'spanId' in arg));
+        if (optionsIndex !== -1) {
+            const options = args[optionsIndex];
+            const restArgs = [...args.slice(0, optionsIndex), ...args.slice(optionsIndex + 1)];
+            return [options, restArgs];
+        }
+        return [undefined, args];
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    /**
+     * Method specifically for MCP Server logging.
+     * Handles multi-line messages by splitting them into individual log entries.
+     */
+    serverLog(level, serverName, message, context) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        // Check if message contains newlines
+        if (message.includes('\n')) {
+            // Split by newline characters, supporting both \n and \r\n
+            const lines = message.split(/\r?\n/);
+            // Log each non-empty line individually
+            for (const line of lines) {
+                const trimmedLine = line.trim();
+                if (trimmedLine) {
+                    this.logSingleServerLine(level, serverName, trimmedLine, context);
+                }
+            }
+        }
+        else {
+            // Single line message, log as is
+            this.logSingleServerLine(level, serverName, message, context);
+        }
+    }
+    /**
+     * Internal helper to log a single line for serverLog.
+     * Contains the core logging logic originally in serverLog.
+     */
+    logSingleServerLine(level, serverName, message, context) {
+        const logContext = {
+            ...context,
+            serverName
+        };
+        const coloredLogMsg = createColoredLogMessage(level, message, logContext);
+        const plainLogMsg = createLogMessage(level, message, logContext);
+        const consoleLogMsg = this.useColor ? coloredLogMsg : plainLogMsg;
+        if (this.useStderr) {
+            console.error(consoleLogMsg);
+        }
+        else {
+            switch (level) {
+                case 'debug':
+                    console.debug(consoleLogMsg);
+                    break;
+                case 'info':
+                    console.info(consoleLogMsg);
+                    break;
+                case 'warn':
+                    console.warn(consoleLogMsg);
+                    break;
+                case 'error':
+                    console.error(consoleLogMsg);
+                    break;
+            }
+        }
+        const logFileStream = this.devLogger.stream;
+        if (logFileStream) {
+            logFileStream.write(plainLogMsg + '\n');
+        }
+    }
+    // ========================================================================
+    // Test-only accessors - These are public for testing but marked @internal
+    // to indicate they should not be used in production code.
+    // ========================================================================
+    /**
+     * Internal accessor for testing and legacy compatibility.
+     * @internal
+     */
+    get logFileStream() {
+        return this.devLogger.stream;
+    }
+    /**
+     * Internal accessor for testing and legacy compatibility.
+     * @internal
+     */
+    get devLogRotator() {
+        return this.devLogger.rotator;
+    }
+    /**
+     * Internal method for testing and legacy compatibility.
+     * @internal
+     */
+    createColoredLogMessage(level, message, context) {
+        return createColoredLogMessage(level, message, context);
+    }
+    /**
+     * Internal method for testing and legacy compatibility.
+     * @internal
+     */
+    createLogMessage(level, message, context) {
+        return createLogMessage(level, message, context);
+    }
+    /**
+     * Internal method for testing and legacy compatibility.
+     * @internal
+     */
+    formatError(error) {
+        return formatError(error);
+    }
+    /**
+     * Internal method for testing and legacy compatibility.
+     * @internal
+     */
+    formatTimestamp(date) {
+        return formatTimestamp(date);
+    }
+    /**
+     * Internal method for testing and legacy compatibility.
+     * @internal
+     */
+    formatLogLevel(level) {
+        return formatLogLevel(level);
+    }
+    /**
+     * Internal method for testing and legacy compatibility.
+     * @internal
+     */
+    formatPid(pid) {
+        return formatPid(pid);
+    }
+}

package/dist/server/src/utils/logger.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Logger module - Thin wrapper for backward compatibility.
+ *
+ * This file has been refactored into a modular structure under src/utils/logger/.
+ * This wrapper maintains backward compatibility while allowing gradual migration.
+ *
+ * New code should import directly from '../../src/utils/logger/index.js' or specific submodules.
+ *
+ * @deprecated New imports should use 'src/utils/logger/index.js'
+ */
+export * from './logger/index.js';
+//# sourceMappingURL=logger.d.ts.map

package/dist/server/src/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,cAAc,mBAAmB,CAAC"}

package/dist/server/src/utils/logger.js

@@ -0,0 +1,12 @@
+/**
+ * Logger module - Thin wrapper for backward compatibility.
+ *
+ * This file has been refactored into a modular structure under src/utils/logger/.
+ * This wrapper maintains backward compatibility while allowing gradual migration.
+ *
+ * New code should import directly from '../../src/utils/logger/index.js' or specific submodules.
+ *
+ * @deprecated New imports should use 'src/utils/logger/index.js'
+ */
+// Re-export everything from the new modular logger
+export * from './logger/index.js';

package/dist/server/src/utils/mcp-error-handler.d.ts

@@ -0,0 +1,162 @@
+import { CMDError } from '../models/types.js';
+/**
+ * Represents a standard MCP (Model Context Protocol) error response.
+ * This interface follows the MCP specification for error responses,
+ * including optional extended metadata in the 'x-mcp' field.
+ */
+export interface MCPError {
+    /** The numeric error code following JSON-RPC 2.0 and MCP standards */
+    code: number;
+    /** Human-readable error message describing the issue */
+    message: string;
+    /** Optional additional error data or context */
+    data?: unknown;
+    /** Extended MCP-specific metadata (optional) */
+    'x-mcp'?: {
+        /** Detailed error context and debugging information */
+        details?: Record<string, unknown>;
+        /** Suggested actions for the client to resolve the error */
+        suggestedActions?: string[];
+        /** URL to additional documentation or help resources */
+        moreInfoUrl?: string;
+    };
+}
+/**
+ * MCP Hub Lite's error code mapping from internal gateway error codes
+ * to standard MCP protocol error codes. This mapping ensures compliance
+ * with the MCP specification while maintaining internal error categorization.
+ *
+ * The mapping follows these conventions:
+ * - 6001: Gateway internal error → Service unavailable (-32001)
+ * - 6002: Connection timeout → Request timeout (-32002)
+ * - 6003: Tool not found → MCP tool not found (-32801)
+ * - 6004: Tool execution failed → MCP execution failed (-32802)
+ * - 6005: Initialization failed → MCP initialization failed (-32803)
+ */
+export declare const MCPHubLiteErrorMap: {
+    readonly 6001: -32001;
+    readonly 6002: -32002;
+    readonly 6003: -32801;
+    readonly 6004: -32802;
+    readonly 6005: -32803;
+};
+/**
+ * MCPErrorHandler provides standardized error handling and conversion for the MCP Hub Lite system.
+ * This class is responsible for converting internal application errors (both native JavaScript Error
+ * objects and custom CMDError objects) into standardized MCP protocol error responses that comply
+ * with the Model Context Protocol specification.
+ *
+ * The handler ensures consistent error formatting across the entire system, providing appropriate
+ * error codes, messages, and extended metadata that clients can use for proper error handling
+ * and user feedback. It supports both generic JavaScript errors and structured CMDError objects
+ * with categorized error codes.
+ *
+ * Usage scenarios include:
+ * - Converting backend server errors to MCP-compliant responses
+ * - Standardizing error responses from different MCP server implementations
+ * - Providing consistent error metadata for client-side error handling
+ * - Maintaining compatibility with the MCP protocol specification
+ */
+export declare class MCPErrorHandler {
+    /**
+     * Converts internal errors to standardized MCP error responses.
+     * This method handles both native JavaScript Error objects and custom CMDError objects,
+     * mapping them to appropriate MCP error codes and formatting them according to the
+     * MCP protocol specification.
+     *
+     * For native Error objects, it creates a standard MCP error with service unavailable
+     * code (-32001) and includes debugging information like stack trace and error name.
+     * For CMDError objects, it maps the internal error code ranges to appropriate MCP
+     * standard error codes based on error categories (system, security, business, etc.).
+     *
+     * @param error - The error to convert, either a native Error or CMDError object
+     * @returns A standardized MCPError object compliant with the MCP protocol
+     *
+     * @example
+     * ```typescript
+     * // Converting a native Error
+     * const mcpError = MCPErrorHandler.toMCPError(new Error('Connection failed'));
+     *
+     * // Converting a CMDError
+     * const cmdError: CMDError = { code: 6003, message: 'Tool not found', data: {} };
+     * const mcpError = MCPErrorHandler.toMCPError(cmdError);
+     * ```
+     */
+    static toMCPError(error: Error | CMDError): MCPError;
+    /**
+     * Maps internal CMD error codes to standardized MCP error codes.
+     * This private method implements the core logic for converting categorized
+     * internal error codes to appropriate MCP standard error codes based on
+     * error type ranges:
+     *
+     * - 1000-1999: System errors → Service unavailable (-32001)
+     * - 2000-2999: Security errors → Authentication/Authorization failed (-32806/-32807)
+     * - 3000-3999: Business errors → Invalid parameter (-32602)
+     * - 5000-5999: MCP protocol errors → Direct mapping or service unavailable
+     * - 6000-6999: Gateway-specific errors → Specific MCP error codes via switch
+     *
+     * The mapping ensures that internal error categorization is preserved while
+     * maintaining compliance with the external MCP protocol standard.
+     *
+     * @param cmdCode - The internal CMD error code to map
+     * @returns The corresponding standardized MCP error code
+     *
+     * @private
+     */
+    private static mapCMDToMCPErrorCode;
+}
+/**
+ * MCPErrorsMiddleware provides middleware functionality for handling and normalizing
+ * error responses from backend MCP servers. This class acts as an intermediary layer
+ * that ensures all error responses conform to the standard MCP protocol format,
+ * regardless of how the backend server originally formatted its errors.
+ *
+ * The middleware intercepts JSON-RPC responses containing errors and validates
+ * whether they already comply with the MCP error standard. If they don't, it
+ * converts them using the MCPErrorHandler to ensure consistent error formatting
+ * across all connected MCP servers.
+ *
+ * This is particularly useful when integrating with various MCP server implementations
+ * that may have different error handling conventions, ensuring that clients receive
+ * standardized error responses regardless of the underlying server implementation.
+ */
+export declare class MCPErrorsMiddleware {
+    /**
+     * Handles and normalizes error responses from backend MCP servers.
+     * This method processes JSON-RPC responses and ensures that any error objects
+     * are converted to the standard MCP error format if they aren't already compliant.
+     *
+     * The method performs the following steps:
+     * 1. Checks if the response contains an error field
+     * 2. Validates if the error is already in standard MCP format
+     * 3. If not standard, converts the error to MCP format using MCPErrorHandler
+     * 4. Returns the normalized response with standardized error formatting
+     *
+     * Non-error responses are returned unchanged to maintain performance.
+     *
+     * @param response - The raw response from a backend MCP server
+     * @returns The response with standardized error formatting if applicable, otherwise the original response
+     *
+     * @example
+     * ```typescript
+     * // Handle a response with a non-standard error
+     * const rawResponse = { jsonrpc: '2.0', id: 1, error: new Error('Connection failed') };
+     * const normalizedResponse = MCPErrorsMiddleware.handleBackendMCPErrors(rawResponse);
+     * // normalizedResponse.error will be in standard MCP format
+     * ```
+     */
+    static handleBackendMCPErrors(response: unknown): unknown;
+    /**
+     * Type guard function to check if an error object conforms to the standard MCP error format.
+     * This private method validates that the error object has the required properties
+     * (code as number, message as string) and optional data property according to
+     * the MCP specification.
+     *
+     * @param error - The error object to validate
+     * @returns True if the error conforms to MCP standard format, false otherwise
+     *
+     * @private
+     */
+    private static isStandardMCPError;
+}
+//# sourceMappingURL=mcp-error-handler.d.ts.map

package/dist/server/src/utils/mcp-error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-error-handler.d.ts","sourceRoot":"","sources":["../../../../src/utils/mcp-error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE;QACR,uDAAuD;QACvD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,4DAA4D;QAC5D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC5B,wDAAwD;QACxD,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAoCD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;;;CAOrB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ;IA0CpD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;CAyCpC;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAmB;IAC9B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,sBAAsB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO;IAkCzD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;CAWlC"}