feat: add workspace management and multi-config support

- Support multiple --config files with intelligent merging
- Add global workspace cache to track active hub instances
- New /api/workspaces endpoint and workspaces_updated SSE event
- Enhanced /api/health with workspace information
- Foundation for project-specific hub instances

Author: ravitemer

CHANGELOG.md

@@ -6,6 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [4.1.0] - 2025-07-15
+
+### Added
+
+- **Workspace Management**: Global workspace cache to track active hub instances across different working directories
+  - New `/api/workspaces` endpoint to list all active workspace instances
+  - Real-time workspace updates via new `workspaces_updated` SSE subscription event
+  - XDG-compliant workspace cache storage (`~/.local/state/mcp-hub/workspaces.json`)
+  - Automatic cleanup of stale workspace entries
+
+- **Multi-Configuration File Support**: Enhanced configuration system with intelligent merging
+  - CLI now accepts multiple `--config` arguments: `--config global.json --config project.json`
+  - Later configuration files override earlier ones with smart merging rules
+  - Missing configuration files are gracefully skipped
+  - Enhanced file watching for all specified configuration files
+
+- **Global Environment Variable Injection**: `MCP_HUB_ENV` environment variable support
+  - Parse JSON string from `MCP_HUB_ENV` and inject key-value pairs into all MCP server environments
+  - Useful for passing shared secrets, tokens, or configuration to all servers
+  - Server-specific `env` fields always override global values
+
+### Enhanced
+
+- **Health Endpoint**: Now includes comprehensive workspace information showing current workspace and all active instances
+- **Configuration Management**: Enhanced ConfigManager with robust array-based config path handling
+- **File Watching**: Improved configuration file monitoring across multiple files with better change detection
+- **Error Handling**: Enhanced error handling and logging throughout the workspace management system
+- Updated all dependencies to latest versions for improved security and performance
+
 ## [4.0.0] - 2025-07-09
 
 ### Breaking Changes

README.md

@@ -105,6 +105,12 @@ The Hub automatically:
   - Proper cleanup of server connections
   - Error recovery and reconnection
 
+- **Workspace Management**:
+  - Track active MCP Hub instances across different working directories
+  - Global workspace cache in XDG-compliant state directory
+  - Real-time workspace updates via SSE events
+  - API endpoints to list and monitor active workspaces
+
 ### Components
 
 #### Hub Server
@@ -137,13 +143,16 @@ Start the hub server:
 
 ```bash
 mcp-hub --port 3000 --config path/to/config.json
+
+# Or with multiple config files (merged in order)
+mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json
 ```
 
 ### CLI Options
 ```bash
 Options:
   --port            Port to run the server on (required)
-  --config          Path to config file (required)
+  --config          Path to config file(s). Can be specified multiple times. Merged in order. (required)
   --watch           Watch config file for changes, only updates affected servers (default: false)
   --auto-shutdown   Whether to automatically shutdown when no clients are connected (default: false)
   --shutdown-delay  Delay in milliseconds before shutting down when auto-shutdown is enabled (default: 0)
@@ -152,7 +161,27 @@ Options:
 
 ## Configuration
 
-MCP Hub uses a JSON configuration file to define managed servers with **universal `${}` placeholder syntax** for environment variables and command execution.
+MCP Hub uses JSON configuration files to define managed servers with **universal `${}` placeholder syntax** for environment variables and command execution.
+
+### Multiple Configuration Files
+
+MCP Hub supports loading multiple configuration files that are merged in order. This enables flexible configuration management:
+
+- **Global Configuration**: System-wide settings (e.g., `~/.config/mcphub/global.json`)
+- **Project Configuration**: Project-specific settings (e.g., `./.mcphub/project.json`)
+- **Environment Configuration**: Environment-specific overrides
+
+When multiple config files are specified, they are merged with later files overriding earlier ones:
+
+```bash
+# Global config is loaded first, then project config overrides
+mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json
+```
+
+**Merge Behavior:**
+- `mcpServers` sections are merged (server definitions from later files override earlier ones)
+- Other top-level properties are completely replaced by later files
+- Missing config files are silently skipped
 
 ### Universal Placeholder Syntax
 
@@ -353,6 +382,16 @@ Response:
         "lastEventAt": "2024-02-20T05:55:00.000Z"
       }
     ]
+  },
+  "workspace": {
+    "current": "/path/to/current/project",
+    "allActive": {
+      "/path/to/project-a": {
+        "pid": 12345,
+        "port": 40123,
+        "startTime": "2025-01-01T12:00:00.000Z"
+      }
+    }
   }
 }
 ```
@@ -479,6 +518,34 @@ Response:
 }
 ```
 
+### Workspace Management
+
+#### List Active Workspaces
+
+```bash
+GET /api/workspaces
+```
+
+Response:
+
+```json
+{
+  "workspaces": {
+    "/path/to/project-a": {
+      "pid": 12345,
+      "port": 40123,
+      "startTime": "2025-01-01T12:00:00.000Z"
+    },
+    "/path/to/project-b": {
+      "pid": 54321,
+      "port": 40567,
+      "startTime": "2025-01-01T12:05:00.000Z"
+    }
+  },
+  "timestamp": "2024-02-20T05:55:00.000Z"
+}
+```
+
 ### Marketplace Integration
 
 #### List Available Servers
@@ -766,6 +833,22 @@ MCP Hub emits several types of events:
   "timestamp": "2024-02-20T05:55:00.000Z"
 }
 ```
+
+7. **workspaces_updated** - Active workspaces changed
+```json
+{
+  "type": "workspaces_updated",
+  "workspaces": {
+    "/path/to/project-a": {
+      "pid": 12345,
+      "port": 40123,
+      "startTime": "2025-01-01T12:00:00.000Z"
+    }
+  },
+  "timestamp": "2024-02-20T05:55:00.000Z"
+}
+```
+
 ### Connection Management
 
 - Each SSE connection is assigned a unique ID
@@ -780,6 +863,15 @@ MCP Hub uses structured JSON logging for all events. Logs are written to both co
 - **XDG compliant**: `$XDG_STATE_HOME/mcp-hub/logs/mcp-hub.log` (typically `~/.local/state/mcp-hub/logs/mcp-hub.log`)
 - **Legacy fallback**: `~/.mcp-hub/logs/mcp-hub.log` (for backward compatibility)
 
+## Workspace Cache
+
+MCP Hub maintains a global workspace cache to track active instances across different working directories:
+
+- **Cache Location**: `$XDG_STATE_HOME/mcp-hub/workspaces.json` (typically `~/.local/state/mcp-hub/workspaces.json`)
+- **Purpose**: Prevents port conflicts and enables workspace discovery
+- **Content**: Maps workspace paths to their corresponding hub process information (PID, port, start time)
+- **Cleanup**: Automatically removes stale entries when processes are no longer running
+
 ```json
 {
   "type": "error",

src/MCPConnection.js

@@ -656,6 +656,7 @@ export class MCPConnection extends EventEmitter {
       lastStarted: this.lastStarted,
       authorizationUrl: this.authorizationUrl,
       serverInfo: this.serverInfo, // Include server's reported name/version
+      config_source: this.config.config_source, // Include which config file this server came from
     };
   }
 

src/MCPHub.js

@@ -16,7 +16,7 @@ export class MCPHub extends EventEmitter {
     this.port = port;
     this.hubServerUrl = `http://localhost:${port}`;
     this.configManager = new ConfigManager(configPathOrObject);
-    this.shouldWatchConfig = watch && typeof configPathOrObject === "string";
+    this.shouldWatchConfig = watch && (typeof configPathOrObject === "string" || Array.isArray(configPathOrObject));
     this.marketplace = marketplace;
   }
   async initialize(isRestarting) {
@@ -207,6 +207,7 @@ export class MCPHub extends EventEmitter {
         ...removePromises,
         ...modifiedPromises,
       ])
+      this.emit("importantConfigChangeHandled", changes);
     } catch (error) {
       logger.error(
         error.code || "CONFIG_UPDATE_ERROR",
@@ -217,7 +218,6 @@ export class MCPHub extends EventEmitter {
         },
         false
       )
-    } finally {
       this.emit("importantConfigChangeHandled", changes);
     }
   }

src/server.js

@@ -15,6 +15,7 @@ import {
 } from "./utils/errors.js";
 import { getMarketplace } from "./marketplace.js";
 import { MCPServerEndpoint } from "./mcp/server.js";
+import { WorkspaceCacheManager } from "./utils/workspace-cache.js";
 
 const SERVER_ID = "mcp-hub";
 
@@ -48,6 +49,7 @@ class ServiceManager {
     this.mcpHub = null;
     this.server = null;
     this.sseManager = new SSEManager(options);
+    this.workspaceCache = new WorkspaceCacheManager();
     this.state = 'starting';
     // Connect logger to SSE manager
     logger.setSseManager(this.sseManager);
@@ -93,7 +95,18 @@ class ServiceManager {
   }
 
   async initializeMCPHub() {
-    // Initialize marketplace first
+    // Initialize workspace cache first
+    logger.info("Initializing workspace cache");
+    await this.workspaceCache.initialize();
+    await this.workspaceCache.register(this.port);
+    await this.workspaceCache.startWatching();
+
+    // Setup workspace cache event handlers
+    this.workspaceCache.on('workspacesUpdated', (workspaces) => {
+      this.broadcastSubscriptionEvent(SubscriptionTypes.WORKSPACES_UPDATED, { workspaces });
+    });
+
+    // Initialize marketplace second
     logger.info("Initializing marketplace catalog");
     marketplace = getMarketplace();
     await marketplace.initialize();
@@ -287,7 +300,17 @@ class ServiceManager {
       }
     }
 
-    await Promise.allSettled([this.stopMCPHub(), this.sseManager.shutdown(), this.stopServer()]);
+    //INFO:Sometimes this might take some time, keeping the process alive, this might cause issue when restarting 
+    //INFO: MUST catch the error here to avoid unhandled rejection, which will again call shutdown() leading to infinite loop
+    this.stopServer().catch((error) => {
+      // Mostly happens when the server is already stopped (race condition)
+      logger.debug(`Error stopping HTTP server: ${error.message}`);
+    })
+    await Promise.allSettled([
+      this.stopMCPHub(),
+      this.sseManager.shutdown(),
+      this.workspaceCache.shutdown()
+    ]);
     this.setState(HubState.STOPPED)
   }
 }
@@ -301,7 +324,7 @@ registerRoute("GET", "/events", "Subscribe to server events", (req, res) => {
     // Add client connection
     const connection = serviceManager.sseManager.addConnection(req, res);
     // Send initial state
-    serviceManager.broadcastHubState();
+    connection.send(EventTypes.HUB_STATE, serviceManager.getState());
   } catch (error) {
     logger.error('SSE_SETUP_ERROR', 'Failed to setup SSE connection', {
       error: error.message,
@@ -399,6 +422,26 @@ registerRoute(
   }
 );
 
+// Register workspaces endpoint
+registerRoute(
+  "GET",
+  "/workspaces",
+  "Get all active workspaces",
+  async (req, res) => {
+    try {
+      const workspaces = await serviceManager.workspaceCache.getActiveWorkspaces();
+      res.json({
+        workspaces,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      throw wrapError(error, "WORKSPACE_ERROR", {
+        operation: "list_workspaces",
+      });
+    }
+  }
+);
+
 // Register server start endpoint
 registerRoute(
   "POST",
@@ -462,7 +505,7 @@ registerRoute(
 );
 
 // Register health check endpoint
-registerRoute("GET", "/health", "Check server health", (req, res) => {
+registerRoute("GET", "/health", "Check server health", async (req, res) => {
   const healthData = {
     status: "ok",
     state: serviceManager?.state || HubState.STARTING,
@@ -478,6 +521,18 @@ registerRoute("GET", "/health", "Check server health", (req, res) => {
     healthData.mcpEndpoint = mcpServerEndpoint.getStats();
   }
 
+  // Add workspace information if available
+  if (serviceManager?.workspaceCache) {
+    try {
+      healthData.workspace = {
+        current: serviceManager.workspaceCache.getWorkspaceKey(),
+        allActive: await serviceManager.workspaceCache.getActiveWorkspaces()
+      };
+    } catch (error) {
+      logger.debug(`Failed to get workspace info for health check: ${error.message}`);
+    }
+  }
+
   res.json(healthData);
 });
 

src/utils/cli.js

@@ -58,8 +58,8 @@ async function run() {
       },
       config: {
         alias: "c",
-        describe: "Path to config file",
-        type: "string",
+        describe: "Path to config file(s). Can be specified multiple times. Merged in order.",
+        type: "array",
         demandOption: true,
       },
       watch: {
@@ -80,15 +80,15 @@ async function run() {
         default: 0,
       },
     })
-    .example("mcp-hub --port 3000 --config ./mcp-servers.json")
+    .example("mcp-hub --port 3000 --config ./global.json --config ./project.json")
     .help("h")
     .alias("h", "help")
     .fail(handleParseError).argv;
 
   try {
     await startServer({
       port: argv.port,
-      config: argv.config,
+      config: argv.config, // This will now be an array of paths
       watch: argv.watch,
       autoShutdown: argv["auto-shutdown"],
       shutdownDelay: argv["shutdown-delay"],