@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/server/dev-server.js

@@ -0,0 +1,171 @@
+import { buildApp } from '../app.js';
+import { configManager } from '../config/config-manager.js';
+import { logger, LOG_MODULES } from '../utils/logger.js';
+import { mcpConnectionManager } from '../services/mcp-connection-manager.js';
+import { PidManager } from '../pid/manager.js';
+// Set log level to debug for development server
+logger.setLevel('debug');
+// Enable dev logging to file (this also enables communication debug logging)
+logger.enableDevLog();
+let app = null;
+/**
+ * Starts the MCP Hub Lite development server with enhanced debugging capabilities.
+ *
+ * This function initializes and starts a development-focused Fastify server instance
+ * with the following features:
+ * - Debug-level logging enabled for detailed development insights
+ * - Development log file output for persistent debugging information
+ * - Automatic connection to all enabled MCP servers configured in the system
+ * - OpenTelemetry tracing initialization for observability
+ * - PID file management for process tracking
+ * - Graceful shutdown handling for SIGTERM and SIGINT signals
+ *
+ * The development server differs from the production server by:
+ * - Using debug log level instead of info/warn
+ * - Enabling development-specific logging to file
+ * - Automatically connecting to all enabled servers on startup
+ * - Providing enhanced error reporting for development debugging
+ *
+ * Usage:
+ * - Called automatically when running `npm run dev` or `npm run dev:server`
+ * - Should only be used in development environments, not production
+ * - Handles its own process lifecycle including graceful shutdown
+ *
+ * Error Handling:
+ * - Catches and logs any startup errors with full stack traces
+ * - Cleans up PID file on startup failure
+ * - Exits process with code 1 on fatal errors
+ * - Provides graceful shutdown on termination signals
+ *
+ * @async
+ * @returns {Promise<void>} Resolves when server starts successfully and begins listening.
+ *                          Never resolves if server fails to start (process exits with code 1).
+ * @throws {Error} If server fails to initialize or start due to configuration errors,
+ *                 port conflicts, invalid server configurations, or other startup issues.
+ *                 Note: Errors are caught internally and cause process.exit(1), so the promise
+ *                 typically does not reject but rather the process terminates.
+ *
+ * @example
+ * ```typescript
+ * // Typically called automatically at module level
+ * startDevServer();
+ * ```
+ *
+ * @see {@link buildApp} - Creates the Fastify application instance
+ * @see {@link configManager} - Manages server configuration and MCP server instances
+ * @see {@link mcpConnectionManager} - Handles MCP server connections and communication
+ * @see {@link telemetryManager} - Manages OpenTelemetry tracing and observability
+ * @see {@link PidManager} - Handles PID file creation and cleanup
+ */
+async function startDevServer() {
+    try {
+        // Log startup separator
+        logger.info('------------------------------------------------', LOG_MODULES.DEV_SERVER);
+        logger.info('MCP Hub Lite Dev Server Starting...', LOG_MODULES.DEV_SERVER);
+        logger.info(`Start Time: ${new Date().toISOString()}`, LOG_MODULES.DEV_SERVER);
+        logger.info('------------------------------------------------', LOG_MODULES.DEV_SERVER);
+        app = await buildApp();
+        const config = configManager.getConfig();
+        // Auto-connect to enabled servers
+        logger.info('Initializing server connections...', LOG_MODULES.DEV_SERVER);
+        const serverConfigs = configManager.getServers();
+        for (const { name: serverName, config: serverConfig } of serverConfigs) {
+            if (serverConfig.enabled) {
+                // Check if there are existing instances
+                const existingInstances = configManager.getServerInstanceByName(serverName);
+                if (existingInstances.length === 0) {
+                    // Auto-create instance for enabled servers
+                    try {
+                        const newInstance = await configManager.addServerInstance(serverName, {});
+                        // Connect the new instance
+                        mcpConnectionManager.connect({ ...serverConfig, ...newInstance }).catch((err) => {
+                            logger.error(`Failed to auto-connect to ${serverName}:`, err, LOG_MODULES.DEV_SERVER);
+                        });
+                    }
+                    catch (err) {
+                        logger.error(`Failed to create instance for ${serverName}:`, err, LOG_MODULES.DEV_SERVER);
+                    }
+                }
+                else {
+                    // Connect existing instances
+                    existingInstances.forEach((instance) => {
+                        mcpConnectionManager.connect({ ...serverConfig, ...instance }).catch((err) => {
+                            logger.error(`Failed to auto-connect to ${serverName}:`, err, LOG_MODULES.DEV_SERVER);
+                        });
+                    });
+                }
+            }
+        }
+        // Listen on configured port
+        await app.listen({
+            port: config.system.port,
+            host: config.system.host
+        });
+        logger.info(`MCP Hub Lite Dev Server running at http://${config.system.host}:${config.system.port}`, LOG_MODULES.DEV_SERVER);
+        // Write PID file after server starts successfully
+        PidManager.writePid();
+    }
+    catch (err) {
+        logger.error('Failed to start dev server:', err, LOG_MODULES.DEV_SERVER);
+        // Clean up PID file if it exists
+        PidManager.removePid();
+        process.exit(1);
+    }
+}
+/**
+ * Handles graceful shutdown of the development server when receiving termination signals.
+ *
+ * This function performs a clean shutdown sequence to ensure:
+ * - All MCP server connections are properly disconnected
+ * - The Fastify HTTP server is closed gracefully
+ * - OpenTelemetry tracing resources are properly shut down
+ * - PID file is removed to prevent stale process detection
+ * - All resources are cleaned up before process exit
+ *
+ * It handles both SIGTERM (termination request) and SIGINT (interrupt/CTRL+C) signals,
+ * providing consistent shutdown behavior regardless of how the process is terminated.
+ *
+ * Error Handling:
+ * - Catches and logs any errors during shutdown process
+ * - Ensures PID file is always removed even if shutdown fails
+ * - Exits with code 0 on successful shutdown, or after logging errors
+ *
+ * @param signal - The termination signal that triggered shutdown ('SIGTERM' or 'SIGINT')
+ * @returns {Promise<void>} Resolves when shutdown sequence completes successfully
+ */
+// Handle graceful shutdown for better restart experience
+const shutdown = async (signal) => {
+    logger.info(`Received ${signal}, shutting down gracefully...`, LOG_MODULES.DEV_SERVER);
+    try {
+        await mcpConnectionManager.disconnectAll();
+        if (app) {
+            await app.close();
+        }
+        PidManager.removePid();
+        logger.info('Dev server stopped gracefully', LOG_MODULES.DEV_SERVER);
+    }
+    catch (error) {
+        logger.error('Error during shutdown:', error, LOG_MODULES.DEV_SERVER);
+        PidManager.removePid();
+    }
+    process.exit(0);
+};
+process.on('SIGTERM', () => shutdown('SIGTERM').catch((err) => {
+    logger.error('Shutdown failed:', err, LOG_MODULES.DEV_SERVER);
+    process.exit(1);
+}));
+process.on('SIGINT', () => shutdown('SIGINT').catch((err) => {
+    logger.error('Shutdown failed:', err, LOG_MODULES.DEV_SERVER);
+    process.exit(1);
+}));
+// Handle uncaught exceptions
+process.on('uncaughtException', (err) => {
+    logger.error('Uncaught Exception:', err, LOG_MODULES.DEV_SERVER);
+    process.exit(1);
+});
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (reason, promise) => {
+    logger.error('Unhandled Rejection at:', promise, 'reason:', reason, LOG_MODULES.DEV_SERVER);
+    process.exit(1);
+});
+startDevServer();

package/dist/server/src/server/runner.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Starts the MCP Hub Lite server in either HTTP mode or stdio MCP gateway mode.
+ *
+ * This function is the main entry point for running the MCP Hub Lite server in production.
+ * It handles two distinct operational modes:
+ *
+ * 1. **HTTP Server Mode** (default): Runs a full Fastify HTTP server with REST API,
+ *    WebSocket support, and web interface on the specified host and port.
+ *
+ * 2. **Stdio MCP Gateway Mode**: Runs as an MCP (Model Context Protocol) gateway
+ *    that communicates via stdin/stdout streams, suitable for integration with
+ *    MCP-compatible clients like IDEs or AI assistants.
+ *
+ * The function performs the following key operations:
+ * - Validates and checks port availability (HTTP mode only)
+ * - Automatically connects to all enabled MCP servers from configuration
+ * - Sets up graceful shutdown handlers for SIGTERM and SIGINT signals
+ * - Manages PID file creation and cleanup for process tracking
+ * - Handles both successful startup and error scenarios with appropriate logging
+ *
+ * @param options - Configuration options for server startup
+ * @param options.stdio - When true, runs in stdio MCP gateway mode instead of HTTP server mode
+ * @param options.port - Override the configured port number (HTTP mode only)
+ * @param options.host - Override the configured host address (HTTP mode only)
+ *
+ * @returns Promise that resolves when the server is successfully started,
+ *          or rejects with an error if startup fails
+ *
+ * @throws {Error} If server startup fails due to port conflicts, configuration errors,
+ *                 or other critical issues. The process will exit with code 1 in such cases.
+ *
+ * @example
+ * // Start in default HTTP mode
+ * await runServer();
+ *
+ * @example
+ * // Start in stdio MCP gateway mode
+ * await runServer({ stdio: true });
+ *
+ * @example
+ * // Start HTTP server on custom port and host
+ * await runServer({ port: 8080, host: '0.0.0.0' });
+ *
+ * @remarks
+ * - In HTTP mode, the function will check if the specified port is already in use
+ *   and provide detailed error messages for port conflicts
+ * - In stdio mode, port checking is skipped as no network ports are used
+ * - The function automatically connects to all enabled servers configured in .mcp-hub.json
+ * - Graceful shutdown ensures proper cleanup of connections and PID files when receiving termination signals
+ * - This function is typically called from the CLI entry point (`src/index.ts`)
+ */
+export declare function runServer(options?: {
+    stdio?: boolean;
+    port?: number;
+    host?: string;
+}): Promise<void>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/server/src/server/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../../src/server/runner.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAsB,SAAS,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,iBA2G9F"}

package/dist/server/src/server/runner.js

@@ -0,0 +1,163 @@
+import { buildApp } from '../app.js';
+import { configManager } from '../config/config-manager.js';
+import { logger, LOG_MODULES } from '../utils/logger.js';
+import { setJsonPrettyConfigGetter } from '../utils/json-utils.js';
+import { mcpConnectionManager } from '../services/mcp-connection-manager.js';
+import { gateway } from '../services/gateway.service.js';
+import { PidManager } from '../pid/manager.js';
+import { checkPort } from '../utils/port-checker.js';
+/**
+ * Starts the MCP Hub Lite server in either HTTP mode or stdio MCP gateway mode.
+ *
+ * This function is the main entry point for running the MCP Hub Lite server in production.
+ * It handles two distinct operational modes:
+ *
+ * 1. **HTTP Server Mode** (default): Runs a full Fastify HTTP server with REST API,
+ *    WebSocket support, and web interface on the specified host and port.
+ *
+ * 2. **Stdio MCP Gateway Mode**: Runs as an MCP (Model Context Protocol) gateway
+ *    that communicates via stdin/stdout streams, suitable for integration with
+ *    MCP-compatible clients like IDEs or AI assistants.
+ *
+ * The function performs the following key operations:
+ * - Validates and checks port availability (HTTP mode only)
+ * - Automatically connects to all enabled MCP servers from configuration
+ * - Sets up graceful shutdown handlers for SIGTERM and SIGINT signals
+ * - Manages PID file creation and cleanup for process tracking
+ * - Handles both successful startup and error scenarios with appropriate logging
+ *
+ * @param options - Configuration options for server startup
+ * @param options.stdio - When true, runs in stdio MCP gateway mode instead of HTTP server mode
+ * @param options.port - Override the configured port number (HTTP mode only)
+ * @param options.host - Override the configured host address (HTTP mode only)
+ *
+ * @returns Promise that resolves when the server is successfully started,
+ *          or rejects with an error if startup fails
+ *
+ * @throws {Error} If server startup fails due to port conflicts, configuration errors,
+ *                 or other critical issues. The process will exit with code 1 in such cases.
+ *
+ * @example
+ * // Start in default HTTP mode
+ * await runServer();
+ *
+ * @example
+ * // Start in stdio MCP gateway mode
+ * await runServer({ stdio: true });
+ *
+ * @example
+ * // Start HTTP server on custom port and host
+ * await runServer({ port: 8080, host: '0.0.0.0' });
+ *
+ * @remarks
+ * - In HTTP mode, the function will check if the specified port is already in use
+ *   and provide detailed error messages for port conflicts
+ * - In stdio mode, port checking is skipped as no network ports are used
+ * - The function automatically connects to all enabled servers configured in .mcp-hub.json
+ * - Graceful shutdown ensures proper cleanup of connections and PID files when receiving termination signals
+ * - This function is typically called from the CLI entry point (`src/index.ts`)
+ */
+export async function runServer(options = {}) {
+    try {
+        const isStdio = options.stdio || false;
+        if (isStdio) {
+            logger.setUseStderr(true);
+            logger.info('Starting in MCP Gateway mode (stdio)...', LOG_MODULES.SERVER);
+        }
+        const config = configManager.getConfig();
+        // Set config getter for json-utils to use config from configManager
+        setJsonPrettyConfigGetter(() => configManager.getConfig());
+        const app = isStdio ? null : await buildApp();
+        // Override config with options if provided
+        const host = options.host || config.system.host;
+        const port = options.port || config.system.port;
+        // Check if port is already in use (only for HTTP mode)
+        if (!isStdio) {
+            const portCheck = await checkPort(port);
+            if (portCheck.inUse) {
+                if (portCheck.isSelfProject) {
+                    // This project is already running
+                    logger.error(`MCP Hub Lite is already running on port ${port} (PID: ${portCheck.pid})`);
+                    logger.error(`Use 'npm run stop' or 'mcp-hub-lite stop' to stop the running instance.`);
+                    process.exit(1);
+                }
+                else {
+                    // Port is occupied by another application
+                    logger.error(`Port ${port} is already in use by another application:`);
+                    logger.error(`  Process: ${portCheck.processName} (PID: ${portCheck.pid})`);
+                    if (portCheck.commandLine) {
+                        logger.error(`  Command: ${portCheck.commandLine}`);
+                    }
+                    logger.error(`Please stop the conflicting application or use a different port.`);
+                    process.exit(1);
+                }
+            }
+        }
+        // Auto-connect to enabled servers
+        logger.info('Initializing server connections...', LOG_MODULES.SERVER);
+        const serverConfigs = configManager.getServers();
+        for (const { name: serverName, config: serverConfig } of serverConfigs) {
+            if (serverConfig.enabled) {
+                // Check if there are existing instances
+                const existingInstances = configManager.getServerInstanceByName(serverName);
+                if (existingInstances.length === 0) {
+                    // Auto-create instance for enabled servers
+                    try {
+                        const newInstance = await configManager.addServerInstance(serverName, {});
+                        // Connect the new instance
+                        mcpConnectionManager.connect({ ...serverConfig, ...newInstance }).catch((err) => {
+                            logger.error(`Failed to auto-connect to ${serverName}:`, err, LOG_MODULES.SERVER);
+                        });
+                    }
+                    catch (err) {
+                        logger.error(`Failed to create instance for ${serverName}:`, err, LOG_MODULES.SERVER);
+                    }
+                }
+                else {
+                    // Connect existing instances
+                    existingInstances.forEach((instance) => {
+                        mcpConnectionManager.connect({ ...serverConfig, ...instance }).catch((err) => {
+                            logger.error(`Failed to auto-connect to ${serverName}:`, err, LOG_MODULES.SERVER);
+                        });
+                    });
+                }
+            }
+        }
+        // Setup signal handlers for graceful shutdown
+        const shutdown = async (signal) => {
+            logger.info(`Received ${signal}, shutting down...`, LOG_MODULES.SERVER);
+            try {
+                await mcpConnectionManager.disconnectAll();
+                if (!isStdio && app) {
+                    await app.close();
+                }
+                PidManager.removePid();
+                logger.info('Server stopped gracefully', LOG_MODULES.SERVER);
+                process.exit(0);
+            }
+            catch (error) {
+                logger.error('Error during shutdown:', error, LOG_MODULES.SERVER);
+                process.exit(1);
+            }
+        };
+        process.on('SIGTERM', () => shutdown('SIGTERM'));
+        process.on('SIGINT', () => shutdown('SIGINT'));
+        if (isStdio) {
+            await gateway.start();
+            // Write PID after gateway starts successfully
+            PidManager.writePid();
+        }
+        else {
+            await app.listen({ port, host });
+            logger.info(`MCP Hub Lite Server running at http://${host}:${port}`, LOG_MODULES.SERVER);
+            // Write PID after server starts successfully
+            PidManager.writePid();
+        }
+    }
+    catch (err) {
+        logger.error('Failed to start server:', err, LOG_MODULES.SERVER);
+        // Clean up PID file if it exists
+        PidManager.removePid();
+        process.exit(1);
+    }
+}

package/dist/server/src/services/client-tracker.service.d.ts

@@ -0,0 +1,132 @@
+import type { ClientContext, ClientInfo, ClientRoot } from '../../shared/types/client.types.js';
+/**
+ * Client tracking service that manages client connections and their metadata.
+ *
+ * This service maintains a registry of connected clients (typically IDEs or other
+ * MCP clients) and tracks their connection state, metadata, and workspace roots.
+ * It provides automatic cleanup of stale clients after a timeout period and
+ * publishes connection/disconnection events via the event bus.
+ *
+ * The service is primarily used by the MCP session manager to track which clients
+ * are connected and maintain their context information for proper session management.
+ *
+ * @example
+ * // Update client information when a new connection is established
+ * clientTrackerService.updateClient({
+ *   sessionId: 'session-123',
+ *   clientName: 'VS Code',
+ *   clientVersion: '1.85.0',
+ *   cwd: '/home/user/project'
+ * });
+ *
+ * // Get all currently connected clients
+ * const clients = clientTrackerService.getClients();
+ */
+declare class ClientTrackerService {
+    private clients;
+    private get TIMEOUT_MS();
+    /**
+     * Creates a new client tracker service instance.
+     *
+     * Initializes the service with automatic periodic cleanup of stale clients
+     * every 60 seconds to prevent memory leaks from disconnected clients.
+     */
+    constructor();
+    /**
+     * Updates or creates a client entry with the provided context information.
+     *
+     * This method is called whenever a client sends a request with context information.
+     * It preserves existing client metadata that isn't provided in the new context,
+     * ensuring that clients don't lose their previously established information.
+     *
+     * If this is a new client (not previously tracked), it publishes a 'client-connected'
+     * event to notify other services about the new connection.
+     *
+     * @param context - The client context containing session ID and optional metadata
+     * @param context.sessionId - Unique identifier for the client session
+     * @param context.clientName - Optional name of the client application
+     * @param context.clientVersion - Optional version of the client application
+     * @param context.protocolVersion - Optional MCP protocol version
+     * @param context.project - Optional project identifier
+     * @param context.cwd - Optional current working directory
+     * @param context.userAgent - Optional user agent string
+     * @param context.ip - Optional client IP address
+     *
+     * @example
+     * clientTrackerService.updateClient({
+     *   sessionId: 'session-123',
+     *   clientName: 'VS Code',
+     *   clientVersion: '1.85.0',
+     *   cwd: '/home/user/project'
+     * });
+     */
+    updateClient(context: ClientContext): void;
+    /**
+     * Updates the workspace roots for a specific client session.
+     *
+     * This method is typically called when a client provides its workspace root
+     * directories, which helps determine the client's working directory context.
+     * If the client doesn't have a current working directory (cwd) set, it will
+     * attempt to infer one from the first root URI in the list.
+     *
+     * For file:// URIs, it converts them to local file paths using Node.js's
+     * fileURLToPath utility. For other URI schemes, it uses the URI directly.
+     *
+     * @param sessionId - The unique session identifier for the client
+     * @param roots - Array of client root objects containing URI information
+     *
+     * @example
+     * clientTrackerService.updateClientRoots('session-123', [
+     *   { uri: 'file:///home/user/project' },
+     *   { uri: 'file:///home/user/other-project' }
+     * ]);
+     */
+    updateClientRoots(sessionId: string, roots: ClientRoot[]): void;
+    /**
+     * Retrieves all currently tracked client information.
+     *
+     * Returns an array of all active client info objects, including their metadata
+     * and connection state. This is useful for monitoring all connected clients
+     * or displaying client information in administrative interfaces.
+     *
+     * @returns Array of ClientInfo objects representing all tracked clients
+     *
+     * @example
+     * const allClients = clientTrackerService.getClients();
+     * console.log(`Currently tracking ${allClients.length} clients`);
+     */
+    getClients(): ClientInfo[];
+    /**
+     * Retrieves client information for a specific session ID.
+     *
+     * Returns the complete client info object for the given session ID, or undefined
+     * if no client with that session ID is currently being tracked.
+     *
+     * @param sessionId - The unique session identifier to look up
+     * @returns ClientInfo object if found, undefined otherwise
+     *
+     * @example
+     * const client = clientTrackerService.getClient('session-123');
+     * if (client) {
+     *   console.log(`Client ${client.clientName} is connected`);
+     * }
+     */
+    getClient(sessionId: string): ClientInfo | undefined;
+    /**
+     * Cleans up stale client entries that haven't been seen recently.
+     *
+     * This private method is called periodically to remove clients that haven't
+     * sent any requests within the timeout period (5 minutes by default). When
+     * a client is removed, it publishes a 'client-disconnected' event to notify
+     * other services about the disconnection.
+     *
+     * This prevents memory leaks from accumulating disconnected clients and ensures
+     * that the client registry only contains active connections.
+     *
+     * @private
+     */
+    private cleanup;
+}
+export declare const clientTrackerService: ClientTrackerService;
+export {};
+//# sourceMappingURL=client-tracker.service.d.ts.map

package/dist/server/src/services/client-tracker.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tracker.service.d.ts","sourceRoot":"","sources":["../../../../src/services/client-tracker.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAO3F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,cAAM,oBAAoB;IACxB,OAAO,CAAC,OAAO,CAAsC;IAErD,OAAO,KAAK,UAAU,GAErB;IAED;;;;;OAKG;;IAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACI,YAAY,CAAC,OAAO,EAAE,aAAa;IA2B1C;;;;;;;;;;;;;;;;;;;OAmBG;IACI,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE;IAwB/D;;;;;;;;;;;;OAYG;IACI,UAAU,IAAI,UAAU,EAAE;IAIjC;;;;;;;;;;;;;;OAcG;IACI,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI3D;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO;CAiBhB;AAED,eAAO,MAAM,oBAAoB,sBAA6B,CAAC"}