@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/cli/commands/list.d.ts

@@ -0,0 +1,71 @@
+import { Command } from 'commander';
+/**
+ * CLI command to list all configured MCP (Model Context Protocol) servers.
+ *
+ * This command provides a comprehensive overview of all MCP servers that have been
+ * configured in the MCP Hub Lite system. It displays essential information about
+ * each server including its name, type, enabled status, and the number of active
+ * instances.
+ *
+ * The command supports two output formats:
+ * - **Table format** (default): Human-readable tabular display showing key server information
+ * - **JSON format**: Machine-readable JSON output containing complete server details
+ *
+ * ## Usage Examples
+ *
+ * ```bash
+ * # List servers in default table format
+ * mcp-hub-lite list
+ *
+ * # List servers in JSON format for programmatic processing
+ * mcp-hub-lite list --format json
+ *
+ * # List servers in table format (explicit)
+ * mcp-hub-lite list --format table
+ * ```
+ *
+ * ## Output Fields (Table Format)
+ *
+ * - **Name**: The unique identifier/name of the MCP server
+ * - **Instances**: Number of active instances running for this server
+ * - **Type**: The transport type of the server (e.g., 'http', 'stdio', 'sse')
+ * - **Enabled**: Boolean indicating whether the server is currently enabled
+ *
+ * ## Error Handling
+ *
+ * If the command fails to retrieve server information (e.g., due to configuration
+ * issues or file system errors), it will display an error message and exit with
+ * status code 1.
+ *
+ * ## Use Cases
+ *
+ * - **System Administration**: Quickly verify which MCP servers are configured
+ * - **Debugging**: Check server status and configuration during development
+ * - **Automation**: Use JSON output format for integration with other tools
+ * - **Monitoring**: Verify that expected servers are properly registered
+ *
+ * @example
+ * // Default table output
+ * MCP Servers:
+ * ┌─────────┬────────────┬────────┬─────────┐
+ * │ (index) │    Name    │Instances│  Type   │ Enabled │
+ * ├─────────┼────────────┼────────┼─────────┤
+ * │    0    │ 'my-server'│    1   │ 'http'  │  true   │
+ * └─────────┴────────────┴────────┴─────────┘
+ *
+ * @example
+ * // JSON output format
+ * [
+ *   {
+ *     "name": "my-server",
+ *     "config": {
+ *       "type": "http",
+ *       "enabled": true,
+ *       // ... other config properties
+ *     },
+ *     "instances": [...]
+ *   }
+ * ]
+ */
+export declare const listCommand: Command;
+//# sourceMappingURL=list.d.ts.map

package/dist/server/src/cli/commands/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,eAAO,MAAM,WAAW,SA2BpB,CAAC"}

package/dist/server/src/cli/commands/list.js

@@ -0,0 +1,97 @@
+import { Command } from 'commander';
+import { listServers } from '../server.js';
+/**
+ * CLI command to list all configured MCP (Model Context Protocol) servers.
+ *
+ * This command provides a comprehensive overview of all MCP servers that have been
+ * configured in the MCP Hub Lite system. It displays essential information about
+ * each server including its name, type, enabled status, and the number of active
+ * instances.
+ *
+ * The command supports two output formats:
+ * - **Table format** (default): Human-readable tabular display showing key server information
+ * - **JSON format**: Machine-readable JSON output containing complete server details
+ *
+ * ## Usage Examples
+ *
+ * ```bash
+ * # List servers in default table format
+ * mcp-hub-lite list
+ *
+ * # List servers in JSON format for programmatic processing
+ * mcp-hub-lite list --format json
+ *
+ * # List servers in table format (explicit)
+ * mcp-hub-lite list --format table
+ * ```
+ *
+ * ## Output Fields (Table Format)
+ *
+ * - **Name**: The unique identifier/name of the MCP server
+ * - **Instances**: Number of active instances running for this server
+ * - **Type**: The transport type of the server (e.g., 'http', 'stdio', 'sse')
+ * - **Enabled**: Boolean indicating whether the server is currently enabled
+ *
+ * ## Error Handling
+ *
+ * If the command fails to retrieve server information (e.g., due to configuration
+ * issues or file system errors), it will display an error message and exit with
+ * status code 1.
+ *
+ * ## Use Cases
+ *
+ * - **System Administration**: Quickly verify which MCP servers are configured
+ * - **Debugging**: Check server status and configuration during development
+ * - **Automation**: Use JSON output format for integration with other tools
+ * - **Monitoring**: Verify that expected servers are properly registered
+ *
+ * @example
+ * // Default table output
+ * MCP Servers:
+ * ┌─────────┬────────────┬────────┬─────────┐
+ * │ (index) │    Name    │Instances│  Type   │ Enabled │
+ * ├─────────┼────────────┼────────┼─────────┤
+ * │    0    │ 'my-server'│    1   │ 'http'  │  true   │
+ * └─────────┴────────────┴────────┴─────────┘
+ *
+ * @example
+ * // JSON output format
+ * [
+ *   {
+ *     "name": "my-server",
+ *     "config": {
+ *       "type": "http",
+ *       "enabled": true,
+ *       // ... other config properties
+ *     },
+ *     "instances": [...]
+ *   }
+ * ]
+ */
+export const listCommand = new Command('list')
+    .description('List all configured MCP servers')
+    .option('--format <format>', 'Output format (json, table)', 'table')
+    .action(async (options) => {
+    try {
+        const servers = await listServers();
+        if (options.format === 'json') {
+            console.log(JSON.stringify(servers, null, 2));
+        }
+        else {
+            // Table format
+            console.log('MCP Servers:');
+            console.table(servers.map((server) => ({
+                Name: server.name,
+                // Now need to display server instance information
+                Instances: server.instances?.length || 0,
+                Type: server.config.type,
+                Enabled: server.config.enabled
+            })));
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Failed to list servers:', error);
+        process.exit(1);
+    }
+});

package/dist/server/src/cli/commands/restart.d.ts

@@ -0,0 +1,42 @@
+import { Command } from 'commander';
+/**
+ * CLI command for restarting the MCP Hub Lite server.
+ *
+ * This command provides a convenient way to stop the currently running MCP Hub Lite
+ * service and start it again with the same or modified configuration. It handles
+ * the graceful shutdown of the existing process and initiates a new server instance.
+ *
+ * The restart operation follows these steps:
+ * 1. Validates the provided command-line options
+ * 2. Sends a termination signal to the currently running server process (if any)
+ * 3. Waits for the process to gracefully shut down
+ * 4. Starts a new server instance with the specified configuration
+ * 5. Provides feedback on the restart operation status
+ *
+ * @remarks
+ * - If no server is currently running, the command will simply start a new instance
+ * - The command uses the PID file mechanism to identify and manage the server process
+ * - All configuration options are passed through to the underlying server restart function
+ * - Error handling ensures proper exit codes and user-friendly error messages
+ *
+ * @example
+ * ```bash
+ * # Basic restart with default settings
+ * mcp-hub-lite restart
+ *
+ * # Restart with custom port and host
+ * mcp-hub-lite restart --port 8080 --host 0.0.0.0
+ *
+ * # Restart with custom configuration file
+ * mcp-hub-lite restart --config ./custom-config.json
+ *
+ * # Combined options
+ * mcp-hub-lite restart --port 9000 --host localhost --config /path/to/config.json
+ * ```
+ *
+ * @see {@link restartServer} - The underlying server restart implementation
+ * @see {@link src/config/config-manager.ts} - Configuration management system
+ * @see {@link src/pid/manager.ts} - Process ID management utilities
+ */
+export declare const restartCommand: Command;
+//# sourceMappingURL=restart.d.ts.map

package/dist/server/src/cli/commands/restart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/restart.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,cAAc,SAkBvB,CAAC"}

package/dist/server/src/cli/commands/restart.js

@@ -0,0 +1,61 @@
+import { Command } from 'commander';
+import { restartServer } from '../server.js';
+/**
+ * CLI command for restarting the MCP Hub Lite server.
+ *
+ * This command provides a convenient way to stop the currently running MCP Hub Lite
+ * service and start it again with the same or modified configuration. It handles
+ * the graceful shutdown of the existing process and initiates a new server instance.
+ *
+ * The restart operation follows these steps:
+ * 1. Validates the provided command-line options
+ * 2. Sends a termination signal to the currently running server process (if any)
+ * 3. Waits for the process to gracefully shut down
+ * 4. Starts a new server instance with the specified configuration
+ * 5. Provides feedback on the restart operation status
+ *
+ * @remarks
+ * - If no server is currently running, the command will simply start a new instance
+ * - The command uses the PID file mechanism to identify and manage the server process
+ * - All configuration options are passed through to the underlying server restart function
+ * - Error handling ensures proper exit codes and user-friendly error messages
+ *
+ * @example
+ * ```bash
+ * # Basic restart with default settings
+ * mcp-hub-lite restart
+ *
+ * # Restart with custom port and host
+ * mcp-hub-lite restart --port 8080 --host 0.0.0.0
+ *
+ * # Restart with custom configuration file
+ * mcp-hub-lite restart --config ./custom-config.json
+ *
+ * # Combined options
+ * mcp-hub-lite restart --port 9000 --host localhost --config /path/to/config.json
+ * ```
+ *
+ * @see {@link restartServer} - The underlying server restart implementation
+ * @see {@link src/config/config-manager.ts} - Configuration management system
+ * @see {@link src/pid/manager.ts} - Process ID management utilities
+ */
+export const restartCommand = new Command('restart')
+    .description('Restart the MCP Hub Lite server')
+    .option('-p, --port <port>', 'Port to run on', '3000')
+    .option('-h, --host <host>', 'Host to bind to', 'localhost')
+    .option('--config <path>', 'Path to config file')
+    .action(async (options) => {
+    try {
+        await restartServer({
+            port: parseInt(options.port),
+            host: options.host,
+            configPath: options.config
+        });
+        console.log('MCP Hub Lite server restarted successfully');
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Failed to restart server:', error);
+        process.exit(1);
+    }
+});

package/dist/server/src/cli/commands/start.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Start command implementation for MCP Hub Lite CLI.
+ *
+ * This command handles the startup of the MCP Hub Lite server with various
+ * configuration options including port, host, and config file path.
+ * It supports both foreground and background execution modes.
+ *
+ * @module cli/commands/start
+ */
+import { Command } from 'commander';
+/**
+ * Creates and configures the start command for the CLI.
+ *
+ * The start command initializes and runs the MCP Hub Lite server with the specified
+ * configuration options. It handles error cases gracefully and provides appropriate
+ * exit codes for automation scripts.
+ *
+ * Available options:
+ * - `--port, -p`: Specify the port to bind to (default: 3000)
+ * - `--host, -h`: Specify the host to bind to (default: localhost)
+ * - `--config`: Path to custom configuration file
+ * - `--foreground, -f`: Run in foreground mode (no daemon)
+ * - `--stdio`: Run in stdio mode for MCP protocol integration
+ *
+ * @returns {Command} Configured Commander.js command instance
+ *
+ * @example
+ * ```bash
+ * # Start server with default settings (background mode)
+ * mcp-hub-lite start
+ *
+ * # Start server on custom port and host
+ * mcp-hub-lite start --port 8080 --host 0.0.0.0
+ *
+ * # Start with custom config file
+ * mcp-hub-lite start --config ./custom-config.json
+ *
+ * # Start in foreground mode for debugging
+ * mcp-hub-lite start --foreground
+ * ```
+ */
+export declare const startCommand: Command;
+//# sourceMappingURL=start.d.ts.map

package/dist/server/src/cli/commands/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/start.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,YAAY,SA4HrB,CAAC"}

package/dist/server/src/cli/commands/start.js

@@ -0,0 +1,160 @@
+/**
+ * Start command implementation for MCP Hub Lite CLI.
+ *
+ * This command handles the startup of the MCP Hub Lite server with various
+ * configuration options including port, host, and config file path.
+ * It supports both foreground and background execution modes.
+ *
+ * @module cli/commands/start
+ */
+import { Command } from 'commander';
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { startServer } from '../server.js';
+import { parsePort, parseHost, validateConfigPath } from '../parse-args.js';
+import { LogRotator } from '../../utils/log-rotator.js';
+import { PidManager } from '../../pid/manager.js';
+import { getConfigManager } from '../../config/config-manager.js';
+/**
+ * Creates and configures the start command for the CLI.
+ *
+ * The start command initializes and runs the MCP Hub Lite server with the specified
+ * configuration options. It handles error cases gracefully and provides appropriate
+ * exit codes for automation scripts.
+ *
+ * Available options:
+ * - `--port, -p`: Specify the port to bind to (default: 3000)
+ * - `--host, -h`: Specify the host to bind to (default: localhost)
+ * - `--config`: Path to custom configuration file
+ * - `--foreground, -f`: Run in foreground mode (no daemon)
+ * - `--stdio`: Run in stdio mode for MCP protocol integration
+ *
+ * @returns {Command} Configured Commander.js command instance
+ *
+ * @example
+ * ```bash
+ * # Start server with default settings (background mode)
+ * mcp-hub-lite start
+ *
+ * # Start server on custom port and host
+ * mcp-hub-lite start --port 8080 --host 0.0.0.0
+ *
+ * # Start with custom config file
+ * mcp-hub-lite start --config ./custom-config.json
+ *
+ * # Start in foreground mode for debugging
+ * mcp-hub-lite start --foreground
+ * ```
+ */
+export const startCommand = new Command('start')
+    .description('Start the MCP Hub Lite server')
+    .option('-p, --port <port>', 'Port to run on', parsePort)
+    .option('-h, --host <host>', 'Host to bind to', parseHost)
+    .option('--config <path>', 'Path to config file', validateConfigPath)
+    .option('-f, --foreground', 'Run in foreground (blocking)')
+    .option('--stdio', 'Run in stdio mode for MCP protocol')
+    .action(async (options) => {
+    // Get config manager to read actual config values
+    const configManager = getConfigManager();
+    const config = configManager.getConfig();
+    // Priority: command line options > environment variables > config file > defaults
+    const actualHost = options.host || process.env.HOST || config.system.host || 'localhost';
+    const actualPort = options.port ||
+        (process.env.PORT ? Number(process.env.PORT) : undefined) ||
+        config.system.port ||
+        7788;
+    // Daemon mode by default unless --foreground or --stdio is specified
+    if (!options.foreground && !options.stdio) {
+        const args = [process.argv[1], 'start', '--foreground'];
+        if (options.port)
+            args.push('--port', String(options.port));
+        if (options.host)
+            args.push('--host', options.host);
+        if (options.config)
+            args.push('--config', options.config);
+        const logDir = path.join(os.homedir(), '.mcp-hub-lite', 'logs');
+        const logRotator = new LogRotator(logDir, 'mcp-hub', undefined, () => getConfigManager().getConfig());
+        // Rotate old logs before starting
+        logRotator.rotateLogs();
+        const logFile = logRotator.createNewLogFilePath();
+        const logStream = fs.openSync(logFile, 'a');
+        console.log(`Starting server in background...`);
+        console.log(`Logs: ${logFile}`);
+        const subprocess = spawn(process.argv[0], args, {
+            detached: true,
+            stdio: ['ignore', logStream, logStream],
+            env: {
+                ...process.env,
+                NO_COLOR: '1'
+            }
+        });
+        subprocess.unref();
+        // Wait for server to initialize and write PID file
+        const startTime = Date.now();
+        const maxWaitTime = 5000; // 5 seconds max wait
+        const checkInterval = 200; // Check every 200ms
+        await new Promise((resolve) => {
+            const checkPid = setInterval(() => {
+                const elapsed = Date.now() - startTime;
+                // Check if PID file exists
+                if (PidManager.pidFileExists()) {
+                    clearInterval(checkPid);
+                    const pid = PidManager.getPid();
+                    console.log(`✓ Server started successfully (PID: ${pid})`);
+                    console.log(`\nAccess the web UI at: http://${actualHost}:${actualPort}`);
+                    resolve();
+                    return;
+                }
+                // Timeout - check if subprocess is still running
+                if (elapsed > maxWaitTime) {
+                    clearInterval(checkPid);
+                    console.error(`\n✗ Server failed to start within ${maxWaitTime}ms`);
+                    // Try to read the last few lines of log to provide helpful error message
+                    try {
+                        const logContent = fs.readFileSync(logFile, 'utf-8');
+                        const logLines = logContent.trim().split('\n');
+                        const recentLines = logLines.slice(-10); // Last 10 lines
+                        // Check for common error patterns
+                        const portInUsePattern = /EADDRINUSE.*:(\d+)/;
+                        const alreadyRunningPattern = /MCP Hub Lite is already running/;
+                        for (const line of recentLines) {
+                            if (alreadyRunningPattern.test(line)) {
+                                console.error(`\n⚠️  MCP Hub Lite is already running!`);
+                                console.error(`   Use 'npm run stop' to stop the existing instance.`);
+                                break;
+                            }
+                            else if (portInUsePattern.test(line)) {
+                                const match = line.match(portInUsePattern);
+                                const port = match ? match[1] : 'unknown';
+                                console.error(`\n⚠️  Port ${port} is already in use by another application.`);
+                                console.error(`   Solutions:`);
+                                console.error(`   1. Stop the application using port ${port}`);
+                                console.error(`   2. Use a different port: npm run start -- --port <PORT>`);
+                                break;
+                            }
+                        }
+                    }
+                    catch {
+                        // Ignore log read errors
+                    }
+                    console.error(`\n📄 Check full logs for details: ${logFile}\n`);
+                    process.exit(1);
+                }
+            }, checkInterval);
+        });
+        process.exit(0);
+    }
+    try {
+        await startServer({
+            port: actualPort,
+            host: actualHost,
+            configPath: options.config
+        });
+    }
+    catch (error) {
+        console.error('Failed to start server:', error);
+        process.exit(1);
+    }
+});

package/dist/server/src/cli/commands/status.d.ts

@@ -0,0 +1,39 @@
+import { Command } from 'commander';
+/**
+ * CLI command for retrieving the current status of the MCP Hub Lite server.
+ *
+ * This command provides comprehensive information about the running MCP Hub Lite instance,
+ * including process details, configuration status, and managed MCP servers. It is designed
+ * to help users monitor their MCP gateway service and troubleshoot any operational issues.
+ *
+ * The status command performs the following functions:
+ * - Checks if the MCP Hub Lite process is currently running
+ * - Retrieves the process ID (PID) from the PID file
+ * - Displays the configured host and port settings
+ * - Shows the current MCP integration endpoint configuration
+ * - Lists all managed MCP servers and their connection status
+ * - Provides detailed operational status information
+ *
+ * Usage scenarios:
+ * - Verifying that the MCP Hub Lite service is running correctly
+ * - Debugging connection issues with managed MCP servers
+ * - Monitoring system health and resource usage
+ * - Validating configuration after changes or updates
+ * - Checking the status before performing maintenance operations
+ *
+ * The command supports an optional --pid parameter to check a specific process ID,
+ * which is useful when multiple instances might be running or when the PID file
+ * is unavailable or corrupted.
+ *
+ * @example
+ * // Basic usage - check default instance
+ * mcp-hub-lite status
+ *
+ * @example
+ * // Check specific process ID
+ * mcp-hub-lite status --pid 12345
+ *
+ * @returns {Command} The configured status command instance for registration with Commander.js
+ */
+export declare const statusCommand: Command;
+//# sourceMappingURL=status.d.ts.map

package/dist/server/src/cli/commands/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,aAAa,SAYtB,CAAC"}