feat(satellite): implement unified tool discovery manager for stdio and remote mcp

Author: Lasim

services/satellite/README.md

@@ -141,11 +141,13 @@ The satellite will **fail to start** with clear error messages if required varia
 ### System Prerequisites
 
 **Local Development:**
+
 - No special requirements - stdio MCP server process management works without isolation
 - Plain Node.js spawn() used for easy debugging
 - Works on macOS, Windows, and Linux
 
 **Production (Docker):**
+
 - nsjail automatically installed in Docker image for secure process isolation
 - See Dockerfile for configuration details
 

services/satellite/src/server.ts

@@ -10,6 +10,10 @@ import { BackendClient } from './services/backend-client';
 import { HeartbeatService } from './services/heartbeat-service';
 import { HttpProxyManager } from './services/http-proxy-manager';
 import { RemoteToolDiscoveryManager } from './services/remote-tool-discovery-manager';
+import { StdioToolDiscoveryManager } from './services/stdio-tool-discovery-manager';
+import { UnifiedToolDiscoveryManager } from './services/unified-tool-discovery-manager';
+import { ProcessManager } from './process/manager';
+import { RuntimeState } from './process/runtime-state';
 import { McpProtocolHandler } from './services/mcp-protocol-handler';
 import { CommandPollingService, ConfigurationUpdate } from './services/command-polling-service';
 import { DynamicConfigManager } from './services/dynamic-config-manager';
@@ -204,8 +208,31 @@ export async function createServer() {
   const httpProxyManager = new HttpProxyManager(server, server.log);
   httpProxyManager.setConfigManager(dynamicConfigManager);
 
-  // Initialize Remote Tool Discovery Manager with dynamic config
-  const toolDiscoveryManager = new RemoteToolDiscoveryManager(server.log);
+  // Initialize Process Manager and Runtime State for stdio subprocess servers
+  const runtimeState = new RuntimeState();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const processManager = new ProcessManager(server.log as any); // Fastify logger is compatible with pino Logger
+
+  // Initialize Remote Tool Discovery Manager for HTTP/SSE remote servers
+  const remoteToolDiscoveryManager = new RemoteToolDiscoveryManager(server.log);
+  remoteToolDiscoveryManager.setConfigManager(dynamicConfigManager);
+
+  // Initialize Stdio Tool Discovery Manager for stdio subprocess servers
+  const stdioToolDiscoveryManager = new StdioToolDiscoveryManager(
+    processManager,
+    runtimeState,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.log as any // Fastify logger is compatible with pino Logger
+  );
+
+  // Initialize Unified Tool Discovery Manager to coordinate both transport types
+  const toolDiscoveryManager = new UnifiedToolDiscoveryManager(
+    remoteToolDiscoveryManager,
+    stdioToolDiscoveryManager,
+    processManager,
+    runtimeState,
+    server.log
+  );
   toolDiscoveryManager.setConfigManager(dynamicConfigManager);
 
   // Set up configuration change handler for tool discovery
@@ -236,6 +263,8 @@ export async function createServer() {
   server.decorate('mcpProtocolHandler', mcpProtocolHandler);
   server.decorate('dynamicConfigManager', dynamicConfigManager);
   server.decorate('commandProcessor', commandProcessor);
+  server.decorate('processManager', processManager);
+  server.decorate('runtimeState', runtimeState);
 
   server.log.info({
     operation: 'handlers_initialized',

services/satellite/src/services/mcp-protocol-handler.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { FastifyBaseLogger } from 'fastify';
 import { HttpProxyManager } from './http-proxy-manager';
-import { RemoteToolDiscoveryManager } from './remote-tool-discovery-manager';
+import { UnifiedToolDiscoveryManager } from './unified-tool-discovery-manager';
 import { ProxyRequestContext } from '../types/mcp-server';
 
 /**
@@ -11,9 +11,9 @@ import { ProxyRequestContext } from '../types/mcp-server';
 export class McpProtocolHandler {
   private logger: FastifyBaseLogger;
   private httpProxyManager: HttpProxyManager;
-  private toolDiscoveryManager: RemoteToolDiscoveryManager;
+  private toolDiscoveryManager: UnifiedToolDiscoveryManager;
 
-  constructor(httpProxyManager: HttpProxyManager, toolDiscoveryManager: RemoteToolDiscoveryManager, logger: FastifyBaseLogger) {
+  constructor(httpProxyManager: HttpProxyManager, toolDiscoveryManager: UnifiedToolDiscoveryManager, logger: FastifyBaseLogger) {
     this.httpProxyManager = httpProxyManager;
     this.toolDiscoveryManager = toolDiscoveryManager;
     this.logger = logger.child({ component: 'McpProtocolHandler' });
@@ -126,14 +126,14 @@ export class McpProtocolHandler {
   }
 
   /**
-   * Handle tools/list request - returns cached discovered tools from remote MCP servers
+   * Handle tools/list request - returns cached discovered tools from both stdio and remote MCP servers
    */
   private async handleToolsList(): Promise<any> {
     this.logger.debug({
       operation: 'mcp_tools_list'
-    }, 'Listing cached discovered tools from remote MCP servers');
+    }, 'Listing cached discovered tools from stdio and remote MCP servers');
 
-    const cachedTools = this.toolDiscoveryManager.getCachedTools();
+    const cachedTools = this.toolDiscoveryManager.getAllTools();
 
     const tools = cachedTools.map(tool => ({
       name: tool.namespacedName,
@@ -149,7 +149,7 @@ export class McpProtocolHandler {
       tools: tools.map(t => t.name),
       discovery_ready: this.toolDiscoveryManager.isReady(),
       result_object: result
-    }, `Returning ${tools.length} cached tools from remote MCP servers`);
+    }, `Returning ${tools.length} cached tools from stdio and remote MCP servers`);
 
     this.logger.debug({
       operation: 'mcp_tools_list_debug',
@@ -188,11 +188,11 @@ export class McpProtocolHandler {
     const serverSlug = namespacedToolName.substring(0, dashIndex);
 
     // Find the cached tool to get the original tool name and verify it exists
-    const cachedTools = this.toolDiscoveryManager.getCachedTools();
-    const cachedTool = cachedTools.find(tool => tool.namespacedName === namespacedToolName);
+    const cachedTool = this.toolDiscoveryManager.getTool(namespacedToolName);
 
     if (!cachedTool) {
-      throw new Error(`Tool not found: ${namespacedToolName}. Available tools: ${cachedTools.map(t => t.namespacedName).join(', ')}`);
+      const allTools = this.toolDiscoveryManager.getAllTools();
+      throw new Error(`Tool not found: ${namespacedToolName}. Available tools: ${allTools.map(t => t.namespacedName).join(', ')}`);
     }
 
     // Use OAuth team context to find the correct server instance

services/satellite/src/services/team-aware-mcp-handler.ts

@@ -2,7 +2,7 @@
 import { FastifyBaseLogger } from 'fastify';
 import { McpProtocolHandler } from './mcp-protocol-handler';
 import { DynamicConfigManager } from './dynamic-config-manager';
-import { RemoteToolDiscoveryManager } from './remote-tool-discovery-manager';
+import { UnifiedToolDiscoveryManager } from './unified-tool-discovery-manager';
 
 /**
  * Team-Aware MCP Protocol Handler
@@ -12,12 +12,12 @@ export class TeamAwareMcpHandler {
   private logger: FastifyBaseLogger;
   private baseHandler: McpProtocolHandler;
   private configManager: DynamicConfigManager;
-  private toolDiscoveryManager: RemoteToolDiscoveryManager;
+  private toolDiscoveryManager: UnifiedToolDiscoveryManager;
 
   constructor(
     baseHandler: McpProtocolHandler, 
     configManager: DynamicConfigManager,
-    toolDiscoveryManager: RemoteToolDiscoveryManager,
+    toolDiscoveryManager: UnifiedToolDiscoveryManager,
     logger: FastifyBaseLogger
   ) {
     this.baseHandler = baseHandler;
@@ -141,8 +141,8 @@ export class TeamAwareMcpHandler {
       return { tools: [] };
     }
 
-    // Get all cached tools from tool discovery
-    const allCachedTools = this.toolDiscoveryManager.getCachedTools();
+    // Get all cached tools from tool discovery (both stdio and remote)
+    const allCachedTools = this.toolDiscoveryManager.getAllTools();
 
     // Get team's allowed MCP servers from configuration
     const teamAllowedServers = this.getTeamAllowedServers(teamId);
@@ -207,11 +207,11 @@ export class TeamAwareMcpHandler {
     }, `Team-aware tool call: ${namespacedToolName} for team ${teamId}`);
 
     // Find the cached tool to get the actual server name and verify team access
-    const allCachedTools = this.toolDiscoveryManager.getCachedTools();
-    const cachedTool = allCachedTools.find(tool => tool.namespacedName === namespacedToolName);
+    const cachedTool = this.toolDiscoveryManager.getTool(namespacedToolName);
 
     if (!cachedTool) {
-      throw new Error(`Tool not found: ${namespacedToolName}. Available tools: ${allCachedTools.map(t => t.namespacedName).join(', ')}`);
+      const allTools = this.toolDiscoveryManager.getAllTools();
+      throw new Error(`Tool not found: ${namespacedToolName}. Available tools: ${allTools.map(t => t.namespacedName).join(', ')}`);
     }
 
     // Use the actual server name from the cached tool (e.g., "context7-john-R36no6FGoMFEZO9nWJJLT")
@@ -362,7 +362,7 @@ export class TeamAwareMcpHandler {
     let teamStats = {};
     if (teamId) {
       const teamAllowedServers = this.getTeamAllowedServers(teamId);
-      const allCachedTools = this.toolDiscoveryManager.getCachedTools();
+      const allCachedTools = this.toolDiscoveryManager.getAllTools();
       const teamFilteredTools = allCachedTools.filter(tool => 
         teamAllowedServers.includes(tool.serverName)
       );