@mxf-dev/core 1.0.0

package/dist/protocols/mcp/services/ExternalMcpServerManager.js

@@ -0,0 +1,1174 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * ExternalMcpServerManager.ts
+ *
+ * Manages external MCP server processes for the hybrid MCP architecture.
+ * Provides process lifecycle management, health monitoring, and tool discovery
+ * for external MCP servers like calculator, sequential thinking, filesystem, etc.
+ */
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import { createStrictValidator } from '../../../utils/validation.js';
+import { Logger } from '../../../utils/Logger.js';
+import { McpEvents } from '../../../events/event-definitions/McpEvents.js';
+import { EventBus } from '../../../events/EventBus.js';
+import { createExternalMcpServerEventPayload, createExternalMcpServerErrorEventPayload, createExternalMcpServerHealthStatusEventPayload, createExternalMcpServerToolsDiscoveredEventPayload } from '../../../schemas/EventPayloadSchema.js';
+import { AutoCorrectionService } from '../../../services/AutoCorrectionService.js';
+import { Events } from '../../../events/EventNames.js';
+import { v4 as uuidv4 } from 'uuid';
+// Create logger and validator instances
+const logger = new Logger('info', 'ExternalMcpServerManager', 'server');
+const validator = createStrictValidator('ExternalMcpServerManager');
+/**
+ * Manages external MCP server processes and their lifecycle
+ */
+export class ExternalMcpServerManager extends EventEmitter {
+    servers = new Map();
+    // Scope tracking for channel/agent-scoped servers
+    serverScopes = new Map();
+    autoCorrectionService;
+    /** Injectable event emitter — decouples from direct EventBus.server dependency.
+     *  Server-side: uses default ServerToolEventEmitter (wraps EventBus.server).
+     *  Client-side: uses ClientToolEventEmitter (wraps EventBus.client + socketEmit). */
+    toolEventEmitter = null;
+    /**
+     * @param options.toolEventEmitter - Injectable event emitter for decoupling from EventBus.server
+     * @param options.skipServerEventHandlers - Skip setting up EventBus.server listeners (for client-side usage)
+     */
+    constructor(options) {
+        super();
+        this.autoCorrectionService = AutoCorrectionService.getInstance();
+        if (options?.toolEventEmitter) {
+            this.toolEventEmitter = options.toolEventEmitter;
+        }
+        // Set up event listeners for SDK-initiated server registration
+        // Skipped when running client-side (no EventBus.server listeners needed)
+        if (!options?.skipServerEventHandlers) {
+            this.setupEventHandlers();
+        }
+    }
+    /**
+     * Set up EventBus handlers for external server registration from SDK
+     */
+    setupEventHandlers() {
+        // Handle external server registration requests from SDK
+        EventBus.server.on(Events.Mcp.EXTERNAL_SERVER_REGISTER, async (payload) => {
+            try {
+                const serverConfig = {
+                    id: payload.data.id,
+                    name: payload.data.name,
+                    version: payload.data.version || '1.0.0',
+                    command: payload.data.command || '',
+                    args: payload.data.args || [],
+                    transport: (payload.data.transport || 'stdio'),
+                    url: payload.data.url,
+                    autoStart: payload.data.autoStart !== false,
+                    restartOnCrash: payload.data.restartOnCrash !== false,
+                    maxRestartAttempts: payload.data.maxRestartAttempts || 3,
+                    healthCheckInterval: payload.data.healthCheckInterval || 30000,
+                    startupTimeout: payload.data.startupTimeout || 10000,
+                    environmentVariables: payload.data.environmentVariables || {}
+                };
+                // Register the server
+                await this.registerServer(serverConfig);
+                // Emit success response
+                EventBus.server.emit(Events.Mcp.EXTERNAL_SERVER_REGISTERED, {
+                    eventId: uuidv4(),
+                    eventType: Events.Mcp.EXTERNAL_SERVER_REGISTERED,
+                    timestamp: Date.now(),
+                    agentId: payload.agentId,
+                    channelId: payload.channelId,
+                    data: {
+                        serverId: serverConfig.id,
+                        success: true,
+                        message: `Server ${serverConfig.name} registered successfully`
+                    }
+                });
+            }
+            catch (error) {
+                logger.error(`Error registering external server:`, error);
+                // Emit error response
+                EventBus.server.emit(Events.Mcp.EXTERNAL_SERVER_REGISTRATION_FAILED, {
+                    eventId: uuidv4(),
+                    eventType: Events.Mcp.EXTERNAL_SERVER_REGISTRATION_FAILED,
+                    timestamp: Date.now(),
+                    agentId: payload.agentId,
+                    channelId: payload.channelId,
+                    data: {
+                        serverId: payload.data?.id,
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error)
+                    }
+                });
+            }
+        });
+        // Handle external server unregistration requests from SDK
+        EventBus.server.on(Events.Mcp.EXTERNAL_SERVER_UNREGISTER, async (payload) => {
+            try {
+                const serverId = payload.data.serverId;
+                await this.stopServer(serverId);
+                this.servers.delete(serverId);
+                // Emit success response
+                EventBus.server.emit(Events.Mcp.EXTERNAL_SERVER_UNREGISTERED, {
+                    eventId: uuidv4(),
+                    eventType: Events.Mcp.EXTERNAL_SERVER_UNREGISTERED,
+                    timestamp: Date.now(),
+                    agentId: payload.agentId,
+                    channelId: payload.channelId,
+                    data: {
+                        serverId: serverId,
+                        success: true,
+                        message: `Server ${serverId} unregistered successfully`
+                    }
+                });
+            }
+            catch (error) {
+                logger.error(`Error unregistering external server:`, error);
+                // Emit error response
+                EventBus.server.emit(Events.Mcp.EXTERNAL_SERVER_UNREGISTERED, {
+                    eventId: uuidv4(),
+                    eventType: Events.Mcp.EXTERNAL_SERVER_UNREGISTERED,
+                    timestamp: Date.now(),
+                    agentId: payload.agentId,
+                    channelId: payload.channelId,
+                    data: {
+                        serverId: payload.data?.serverId,
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error)
+                    }
+                });
+            }
+        });
+        // Handle channel-scoped server registration requests
+        EventBus.server.on(Events.Mcp.CHANNEL_SERVER_REGISTER, async (payload) => {
+            try {
+                logger.info(`[CHANNEL_SERVER_REGISTER] Received registration request: ${JSON.stringify({ agentId: payload.agentId, channelId: payload.channelId, serverId: payload.data?.id })}`);
+                const channelId = payload.data.channelId || payload.channelId;
+                const serverId = `${channelId}:${payload.data.id}`;
+                const serverConfig = {
+                    id: serverId,
+                    name: payload.data.name,
+                    version: payload.data.version || '1.0.0',
+                    command: payload.data.command || '',
+                    args: payload.data.args || [],
+                    transport: (payload.data.transport || 'stdio'),
+                    url: payload.data.url,
+                    autoStart: payload.data.autoStart !== false,
+                    restartOnCrash: payload.data.restartOnCrash !== false,
+                    maxRestartAttempts: payload.data.maxRestartAttempts || 3,
+                    healthCheckInterval: payload.data.healthCheckInterval || 30000,
+                    startupTimeout: payload.data.startupTimeout || 10000,
+                    environmentVariables: payload.data.environmentVariables || {}
+                };
+                // Track scope BEFORE registration so we can store the registration context
+                // Note: connectedAgents starts empty - only actual game agents are counted, not the admin who registers
+                this.serverScopes.set(serverId, {
+                    scope: 'channel',
+                    scopeId: channelId,
+                    connectedAgents: new Set(),
+                    keepAliveMinutes: payload.data.keepAliveMinutes || 5,
+                    // Store registration context for deferred success emission
+                    registrationContext: {
+                        agentId: payload.agentId,
+                        channelId,
+                        originalServerId: payload.data.id,
+                        serverName: payload.data.name
+                    }
+                });
+                // Register the server (this starts the process and tool discovery)
+                // Success event will be emitted after tool discovery completes
+                await this.registerServer(serverConfig);
+                logger.info(`[CHANNEL_SERVER_REGISTER] Server ${serverId} registered, waiting for tool discovery before emitting success`);
+            }
+            catch (error) {
+                logger.error(`Error registering channel server:`, error);
+                // Emit error response
+                EventBus.server.emit(McpEvents.CHANNEL_SERVER_REGISTRATION_FAILED, createExternalMcpServerEventPayload(McpEvents.CHANNEL_SERVER_REGISTRATION_FAILED, payload.agentId, payload.data?.channelId || payload.channelId, {
+                    serverId: payload.data?.id,
+                    scope: 'channel',
+                    scopeId: payload.data?.channelId || payload.channelId,
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                }));
+            }
+        });
+        // Handle channel server unregistration requests
+        EventBus.server.on(Events.Mcp.CHANNEL_SERVER_UNREGISTER, async (payload) => {
+            try {
+                const channelId = payload.data.channelId || payload.channelId;
+                const serverId = `${channelId}:${payload.data.serverId}`;
+                await this.stopServer(serverId);
+                this.servers.delete(serverId);
+                this.serverScopes.delete(serverId);
+                // Emit success response
+                EventBus.server.emit(McpEvents.CHANNEL_SERVER_UNREGISTERED, createExternalMcpServerEventPayload(McpEvents.CHANNEL_SERVER_UNREGISTERED, payload.agentId, channelId, {
+                    serverId: payload.data.serverId,
+                    scope: 'channel',
+                    scopeId: channelId,
+                    success: true,
+                    message: `Channel server ${payload.data.serverId} unregistered successfully`
+                }));
+            }
+            catch (error) {
+                logger.error(`Error unregistering channel server:`, error);
+                // Emit error response
+                EventBus.server.emit(McpEvents.CHANNEL_SERVER_UNREGISTERED, createExternalMcpServerEventPayload(McpEvents.CHANNEL_SERVER_UNREGISTERED, payload.agentId, payload.data?.channelId || payload.channelId, {
+                    serverId: payload.data?.serverId,
+                    scope: 'channel',
+                    scopeId: payload.data?.channelId || payload.channelId,
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                }));
+            }
+        });
+    }
+    /**
+     * Register a new external server configuration
+     */
+    async registerServer(config) {
+        logger.info(`[REGISTER_SERVER] Registering server ${config.id}: command="${config.command}", args=${JSON.stringify(config.args)}, autoStart=${config.autoStart}`);
+        // Validate configuration
+        validator.assertIsNonEmptyString(config.id, 'Server ID must be a non-empty string');
+        validator.assertIsNonEmptyString(config.name, 'Server name must be a non-empty string');
+        validator.assertIsNonEmptyString(config.command, 'Server command must be a non-empty string');
+        validator.assertIsArray(config.args, 'Server args must be an array');
+        // Check if server already exists
+        if (this.servers.has(config.id)) {
+            throw new Error(`Server with ID ${config.id} is already registered`);
+        }
+        // Create initial status
+        const status = {
+            id: config.id,
+            name: config.name,
+            status: 'stopped',
+            restartCount: 0,
+            tools: []
+        };
+        // Store server configuration and status
+        this.servers.set(config.id, {
+            config,
+            status
+        });
+        // Auto-start if configured
+        if (config.autoStart) {
+            logger.info(`[REGISTER_SERVER] Auto-starting server ${config.id}`);
+            await this.startServer(config.id);
+        }
+    }
+    /**
+     * Start an external server process
+     */
+    async startServer(serverId, agentId, channelId) {
+        logger.info(`[START_SERVER] Starting server ${serverId}`);
+        const serverData = this.servers.get(serverId);
+        if (!serverData) {
+            // Server was unregistered (e.g., during cleanup) - log warning and return gracefully
+            logger.warn(`⚠️  Cannot start server ${serverId} - server not found (likely unregistered)`);
+            return;
+        }
+        const { config, status } = serverData;
+        if (status.status === 'running') {
+            logger.info(`[START_SERVER] Server ${serverId} already running`);
+            return;
+        }
+        // Update status
+        status.status = 'starting';
+        this.emitServerEvent(McpEvents.EXTERNAL_SERVER_SPAWN, serverId, agentId, channelId);
+        try {
+            // Spawn the process
+            const cwd = config.workingDirectory || process.cwd();
+            logger.info(`[START_SERVER] Spawning: ${config.command} ${config.args.join(' ')} in ${cwd}`);
+            // Least privilege: external servers get only what a child process
+            // needs to run plus their declared variables — never the full
+            // parent environment (which holds JWT/DB/API secrets).
+            const declaredEnv = config.environmentVariables ?? {};
+            for (const [name, value] of Object.entries(declaredEnv)) {
+                if (value === undefined || value === null || value === '') {
+                    throw new Error(`External MCP server '${serverId}' requires environment variable ${name} but it resolved empty — set it before starting this server`);
+                }
+            }
+            const childEnv = {
+                ...(process.env.PATH ? { PATH: process.env.PATH } : {}),
+                ...(process.env.HOME ? { HOME: process.env.HOME } : {}),
+                ...(process.env.NODE_ENV ? { NODE_ENV: process.env.NODE_ENV } : {}),
+                ...declaredEnv
+            };
+            const childProcess = spawn(config.command, config.args, {
+                cwd,
+                env: childEnv,
+                stdio: ['pipe', 'pipe', 'pipe']
+            });
+            // Store process reference — PID is assigned by the OS immediately but the
+            // process may not have started yet. The 'spawn' event in setupProcessEventHandlers
+            // confirms the process actually started; the 'error' event handles spawn failures.
+            serverData.process = childProcess;
+            status.pid = childProcess.pid;
+            logger.info(`[START_SERVER] Process created with PID ${childProcess.pid}, awaiting spawn confirmation...`);
+            // Set up process event handlers
+            this.setupProcessEventHandlers(serverId, childProcess);
+            // Set startup timeout
+            serverData.startupTimer = setTimeout(() => {
+                if (status.status === 'starting') {
+                    logger.error(`❌ Server ${config.name} startup timed out`);
+                    this.handleServerError(serverId, 'Startup timeout', agentId, channelId);
+                }
+            }, config.startupTimeout);
+            // Start health check monitoring
+            this.startHealthChecking(serverId);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`❌ Failed to start server ${config.name}: ${errorMessage}`);
+            this.handleServerError(serverId, errorMessage, agentId, channelId);
+        }
+    }
+    /**
+     * Handle agent joining a channel - start channel servers and track connection
+     */
+    async onAgentJoinChannel(agentId, channelId) {
+        logger.info(`Agent ${agentId} joining channel ${channelId} - checking for channel servers`);
+        // Find all channel-scoped servers for this channel
+        for (const [serverId, scopeData] of this.serverScopes.entries()) {
+            if (scopeData.scope === 'channel' && scopeData.scopeId === channelId) {
+                // Add agent to connected agents
+                scopeData.connectedAgents.add(agentId);
+                // Clear any pending keepAlive timer
+                if (scopeData.keepAliveTimer) {
+                    clearTimeout(scopeData.keepAliveTimer);
+                    scopeData.keepAliveTimer = undefined;
+                }
+                // Start server if not already running
+                const serverData = this.servers.get(serverId);
+                if (serverData && serverData.status.status !== 'running') {
+                    logger.info(`Starting channel server ${serverId} for agent ${agentId}`);
+                    await this.startServer(serverId);
+                }
+                logger.info(`Agent ${agentId} connected to channel server ${serverId} (${scopeData.connectedAgents.size} agents)`);
+            }
+        }
+    }
+    /**
+     * Handle agent leaving a channel - implement reference counting and keepAlive
+     */
+    async onAgentLeaveChannel(agentId, channelId) {
+        logger.info(`Agent ${agentId} leaving channel ${channelId} - checking channel servers`);
+        // Find all channel-scoped servers for this channel
+        for (const [serverId, scopeData] of this.serverScopes.entries()) {
+            if (scopeData.scope === 'channel' && scopeData.scopeId === channelId) {
+                // Remove agent from connected agents
+                scopeData.connectedAgents.delete(agentId);
+                logger.info(`Agent ${agentId} disconnected from channel server ${serverId} (${scopeData.connectedAgents.size} agents remaining)`);
+                // If no more agents connected, start keepAlive timer
+                if (scopeData.connectedAgents.size === 0) {
+                    const keepAliveMs = (scopeData.keepAliveMinutes || 5) * 60 * 1000;
+                    logger.info(`Last agent left channel server ${serverId}, starting ${scopeData.keepAliveMinutes}min keepAlive timer`);
+                    scopeData.keepAliveTimer = setTimeout(async () => {
+                        logger.info(`KeepAlive expired for server ${serverId}, stopping server`);
+                        try {
+                            await this.stopServer(serverId);
+                        }
+                        catch (error) {
+                            logger.error(`Error stopping server ${serverId} after keepAlive:`, error);
+                        }
+                    }, keepAliveMs);
+                }
+            }
+        }
+    }
+    /**
+     * Get servers by scope
+     */
+    getServersByScope(scope, scopeId) {
+        const servers = [];
+        for (const [serverId, scopeData] of this.serverScopes.entries()) {
+            if (scopeData.scope === scope) {
+                // For channel/agent scope, match scopeId
+                if ((scope === 'channel' || scope === 'agent') && scopeData.scopeId !== scopeId) {
+                    continue;
+                }
+                const serverData = this.servers.get(serverId);
+                if (serverData) {
+                    servers.push(serverData.status);
+                }
+            }
+        }
+        return servers;
+    }
+    /**
+     * Stop an external server process
+     */
+    async stopServer(serverId, agentId, channelId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData) {
+            throw new Error(`Server ${serverId} not found`);
+        }
+        const { config, status } = serverData;
+        if (status.status === 'stopped') {
+            return;
+        }
+        // Emit stop event
+        this.emitServerEvent(McpEvents.EXTERNAL_SERVER_STOP, serverId, agentId, channelId);
+        // Clear timers
+        if (serverData.healthCheckTimer) {
+            clearInterval(serverData.healthCheckTimer);
+            serverData.healthCheckTimer = undefined;
+        }
+        if (serverData.startupTimer) {
+            clearTimeout(serverData.startupTimer);
+            serverData.startupTimer = undefined;
+        }
+        // Terminate process
+        if (serverData.process) {
+            serverData.process.kill('SIGTERM');
+            // Force kill after timeout
+            setTimeout(() => {
+                if (serverData.process && !serverData.process.killed) {
+                    logger.warn(`🔪 Force killing server ${config.name}`);
+                    serverData.process.kill('SIGKILL');
+                }
+            }, 5000);
+        }
+        // Update status
+        status.status = 'stopped';
+        status.pid = undefined;
+        status.tools = [];
+        // Emit stopped event
+        this.emitServerEvent(McpEvents.EXTERNAL_SERVER_STOPPED, serverId, agentId, channelId);
+    }
+    /**
+     * Get status of all servers
+     */
+    getServerStatus() {
+        const statusMap = new Map();
+        for (const [id, serverData] of this.servers) {
+            statusMap.set(id, { ...serverData.status });
+        }
+        return statusMap;
+    }
+    /**
+     * Get status of a specific server
+     */
+    getServerStatusById(serverId) {
+        const serverData = this.servers.get(serverId);
+        return serverData ? { ...serverData.status } : undefined;
+    }
+    /**
+     * Get all discovered tools from external servers
+     */
+    getAllExternalTools() {
+        const tools = [];
+        for (const [serverId, serverData] of this.servers) {
+            for (const tool of serverData.status.tools) {
+                tools.push({
+                    ...tool,
+                    serverId
+                });
+            }
+        }
+        return tools;
+    }
+    /**
+     * Set up event handlers for a spawned process
+     */
+    setupProcessEventHandlers(serverId, process) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { config, status } = serverData;
+        // Handle process exit
+        process.on('exit', (code, signal) => {
+            status.status = 'stopped';
+            status.pid = undefined;
+            // Clear timers
+            if (serverData.healthCheckTimer) {
+                clearInterval(serverData.healthCheckTimer);
+                serverData.healthCheckTimer = undefined;
+            }
+            // Handle restart if configured
+            if (config.restartOnCrash && code !== 0 && status.restartCount < config.maxRestartAttempts) {
+                status.restartCount++;
+                setTimeout(() => {
+                    // Check if server still exists before attempting restart
+                    // (it may have been unregistered during the delay)
+                    if (this.servers.has(serverId)) {
+                        this.startServer(serverId);
+                    }
+                }, 2000); // Wait 2 seconds before restart
+            }
+            this.emitServerEvent(McpEvents.EXTERNAL_SERVER_STOPPED, serverId);
+        });
+        // Handle process errors
+        process.on('error', (error) => {
+            logger.error(`❌ Server ${config.name} process error: ${error.message}`);
+            this.handleServerError(serverId, error.message);
+        });
+        // Handle stdout for tool discovery and health checks
+        if (process.stdout) {
+            process.stdout.on('data', (data) => {
+                const output = data.toString();
+                this.handleServerOutput(serverId, output);
+            });
+        }
+        // Handle stderr — log non-warning output for debugging spawn failures
+        if (process.stderr) {
+            process.stderr.on('data', (data) => {
+                const errorOutput = data.toString().trim();
+                // Filter out harmless Node.js experimental warnings from npm
+                if (errorOutput.includes('ExperimentalWarning')) {
+                    return; // Ignore npm's CommonJS/ES Module warnings
+                }
+                if (errorOutput) {
+                    logger.debug(`[MCP-STDERR] ${serverId}: ${errorOutput}`);
+                }
+            });
+        }
+        // Mark as started when process is spawned successfully
+        process.on('spawn', () => {
+            logger.info(`[SPAWN] Server ${serverId} process spawned successfully`);
+            status.status = 'running';
+            // Clear startup timer
+            if (serverData.startupTimer) {
+                clearTimeout(serverData.startupTimer);
+                serverData.startupTimer = undefined;
+            }
+            this.emitServerEvent(McpEvents.EXTERNAL_SERVER_STARTED, serverId);
+            // Initialize MCP connection first, then discover tools
+            logger.info(`[SPAWN] Will initialize MCP connection for ${serverId} in 2 seconds...`);
+            setTimeout(() => {
+                this.initializeMcpConnection(serverId).catch((err) => {
+                    logger.error(`[MCP] Failed to initialize connection to ${serverId}: ${err.message}`);
+                    this.handleServerError(serverId, `MCP initialization failed: ${err.message}`);
+                });
+            }, 2000); // Wait 2 seconds for server to fully start
+        });
+    }
+    /**
+     * Start health check monitoring for a server
+     */
+    startHealthChecking(serverId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { config } = serverData;
+        serverData.healthCheckTimer = setInterval(() => {
+            this.performHealthCheck(serverId);
+        }, config.healthCheckInterval);
+    }
+    /**
+     * Perform health check for a server
+     */
+    async performHealthCheck(serverId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { config, status } = serverData;
+        // Emit health check event
+        this.emitServerEvent(McpEvents.EXTERNAL_SERVER_HEALTH_CHECK, serverId);
+        // Simple health check - process is running
+        const isHealthy = serverData.process && !serverData.process.killed;
+        status.lastHealthCheck = Date.now();
+        if (status.status === 'running') {
+            status.uptime = Date.now() - (status.lastHealthCheck - config.healthCheckInterval);
+        }
+        // Emit health status
+        this.emitServerHealthStatus(serverId, isHealthy ? 'healthy' : 'unhealthy');
+    }
+    /**
+     * Handle server output for tool discovery
+     *
+     * MCP protocol message parsing is handled in:
+     * - initializeMcpConnection(): Handles MCP initialize handshake
+     * - discoverRealToolsFromServer(): Handles tools/list JSON-RPC calls
+     * - executeToolOnServer(): Handles tools/call JSON-RPC calls
+     */
+    handleServerOutput(serverId, output) {
+        // Server stdout is processed by the MCP JSON-RPC handlers in initializeMcpConnection,
+        // discoverRealToolsFromServer, and executeToolOnServer methods.
+        // This handler is used for any additional output logging if needed.
+    }
+    /**
+     * Discover tools available from a server
+     */
+    async discoverServerTools(serverId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { config, process } = serverData;
+        // Emit discovery event
+        this.emitServerEvent(McpEvents.EXTERNAL_SERVER_DISCOVERY, serverId);
+        try {
+            // Real MCP tool discovery using JSON-RPC tools/list method
+            if (process && process.stdin && process.stdout && !process.killed) {
+                const realTools = await this.discoverRealToolsFromServer(serverId);
+                serverData.status.tools = realTools;
+                // Log discovered tool names for debugging
+                if (realTools.length > 0) {
+                    // Special logging for calculator server
+                    if (serverId === 'calculator') {
+                        //     name: t.name,
+                        //     description: t.description?.substring(0, 50) + '...'
+                        // })));
+                    }
+                    else {
+                    }
+                }
+                else {
+                    logger.warn(`⚠️ No tools found from ${config.name} - server may not support tools/list or have no tools`);
+                }
+            }
+            else {
+                logger.error(`❌ Server ${config.name} process not available for tool discovery`);
+                serverData.status.tools = [];
+            }
+        }
+        catch (error) {
+            logger.error(`❌ Failed to discover tools from ${config.name}: ${error instanceof Error ? error.message : String(error)}`);
+            logger.error(`🚫 No fallback - server ${config.name} will have no available tools until discovery succeeds`);
+            serverData.status.tools = [];
+        }
+        // Emit tools discovered event
+        this.emitServerToolsDiscovered(serverId, serverData.status.tools);
+        // Emit deferred CHANNEL_SERVER_REGISTERED for channel-scoped servers
+        const scopeData = this.serverScopes.get(serverId);
+        if (scopeData?.scope === 'channel' && scopeData.registrationContext) {
+            const ctx = scopeData.registrationContext;
+            logger.info(`[CHANNEL_SERVER_REGISTER] Tool discovery complete for ${serverId}, emitting CHANNEL_SERVER_REGISTERED with ${serverData.status.tools.length} tools`);
+            EventBus.server.emit(McpEvents.CHANNEL_SERVER_REGISTERED, createExternalMcpServerEventPayload(McpEvents.CHANNEL_SERVER_REGISTERED, ctx.agentId, ctx.channelId, {
+                serverId: ctx.originalServerId,
+                serverName: ctx.serverName,
+                scope: 'channel',
+                scopeId: ctx.channelId,
+                success: true,
+                tools: serverData.status.tools,
+                message: `Channel server ${ctx.serverName} registered with ${serverData.status.tools.length} tools`
+            }));
+            // Clear registration context after emission
+            scopeData.registrationContext = undefined;
+        }
+    }
+    /**
+     * Initialize MCP connection with server
+     */
+    async initializeMcpConnection(serverId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData || !serverData.process) {
+            throw new Error(`Server ${serverId} not found or not running`);
+        }
+        // Prevent duplicate initialization
+        if (serverData.status.initialized) {
+            logger.warn(`⚠️ MCP connection already initialized for server ${serverData.config.name}`);
+            return;
+        }
+        const { process, config } = serverData;
+        if (!process.stdin || !process.stdout) {
+            throw new Error('Process streams not available');
+        }
+        // Mark as initializing to prevent concurrent initialization
+        serverData.status.initializing = true;
+        // Send MCP initialize request with required parameters
+        const initializeRequest = {
+            jsonrpc: "2.0",
+            id: "initialize",
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {
+                    experimental: {},
+                    sampling: {}
+                },
+                clientInfo: {
+                    name: "MXF Framework",
+                    version: "0.32.0"
+                }
+            }
+        };
+        const requestJson = JSON.stringify(initializeRequest) + '\n';
+        process.stdin.write(requestJson);
+        // Wait for MCP initialize response
+        const responseBuffer = await this.waitForMcpResponse(process.stdout, "initialize");
+        const response = JSON.parse(responseBuffer);
+        if (response.error) {
+            logger.error(`❌ MCP initialize error: ${response.error.message}`);
+            throw new Error(`MCP initialize error: ${response.error.message}`);
+        }
+        // Discover tools after MCP connection is initialized
+        await this.discoverServerTools(serverId);
+        // Mark as successfully initialized
+        serverData.status.initialized = true;
+        serverData.status.initializing = false;
+    }
+    /**
+     * Wait for MCP response with specific ID
+     */
+    async waitForMcpResponse(stdout, requestId) {
+        return new Promise((resolve, reject) => {
+            let responseBuffer = '';
+            let timeoutId;
+            let resolved = false;
+            const responseHandler = (data) => {
+                if (resolved)
+                    return; // Prevent duplicate responses
+                responseBuffer += data.toString();
+                // Try to parse JSON response (MCP responses are line-delimited JSON)
+                const lines = responseBuffer.split('\n');
+                for (let i = 0; i < lines.length - 1; i++) {
+                    const line = lines[i].trim();
+                    if (line) {
+                        try {
+                            const response = JSON.parse(line.trim());
+                            // Check if this is our response
+                            if (response.id === requestId) {
+                                resolved = true;
+                                clearTimeout(timeoutId);
+                                stdout.removeListener('data', responseHandler);
+                                // Return the clean JSON line instead of the entire buffer
+                                resolve(line.trim());
+                                return;
+                            }
+                        }
+                        catch (parseError) {
+                            // Ignore JSON parse errors for incomplete lines
+                            continue;
+                        }
+                    }
+                }
+                // Keep the last incomplete line in buffer
+                responseBuffer = lines[lines.length - 1];
+            };
+            // Set up timeout (30 seconds for MCP response - some servers like n8n need more time)
+            timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    stdout.removeListener('data', responseHandler);
+                    reject(new Error(`Timeout waiting for MCP response after 30 seconds`));
+                }
+            }, 30000);
+            // Listen for response
+            stdout.on('data', responseHandler);
+        });
+    }
+    /**
+     * Discover tools from external MCP server using JSON-RPC tools/list method
+     */
+    async discoverRealToolsFromServer(serverId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData || !serverData.process) {
+            throw new Error(`Server ${serverId} not found or not running`);
+        }
+        const { process, config } = serverData;
+        return new Promise((resolve, reject) => {
+            if (!process.stdin || !process.stdout) {
+                reject(new Error('Process streams not available'));
+                return;
+            }
+            const requestId = `tools-list-${uuidv4()}`;
+            // Create MCP tool call request according to the protocol
+            const mcpRequest = {
+                jsonrpc: '2.0',
+                id: requestId,
+                method: 'tools/list',
+                params: {}
+            };
+            let responseData = '';
+            let timeoutId;
+            let resolved = false;
+            const handleData = (chunk) => {
+                if (resolved)
+                    return; // Prevent duplicate responses
+                responseData += chunk.toString();
+                // Look for complete JSON-RPC response
+                const lines = responseData.split('\n');
+                for (let i = 0; i < lines.length - 1; i++) {
+                    const line = lines[i].trim();
+                    if (line) {
+                        try {
+                            const response = JSON.parse(line.trim());
+                            // Check if this is our response
+                            if (response.id === requestId) {
+                                resolved = true;
+                                clearTimeout(timeoutId);
+                                process.stdout.off('data', handleData);
+                                if (response.error) {
+                                    reject(new Error(`MCP Error: ${response.error.message}`));
+                                    return;
+                                }
+                                if (response.result && response.result.tools) {
+                                    const tools = response.result.tools.map((tool) => ({
+                                        name: tool.name,
+                                        description: tool.description || `Tool from ${config.name}`,
+                                        inputSchema: tool.inputSchema || { type: 'object', properties: {}, required: [] }
+                                    }));
+                                    resolve(tools);
+                                }
+                                else {
+                                    logger.warn(`⚠️ No tools found in response from ${config.name}`);
+                                    resolve([]);
+                                }
+                                return;
+                            }
+                        }
+                        catch (parseError) {
+                            // Continue looking for valid JSON in other lines
+                        }
+                    }
+                }
+                // Keep the last incomplete line in buffer
+                responseData = lines[lines.length - 1];
+            };
+            // Set up timeout (15 seconds for tool execution)
+            timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    process.stdout.off('data', handleData);
+                    reject(new Error(`Timeout waiting for tools/list response from ${config.name} after 15 seconds`));
+                }
+            }, 15000);
+            // Listen for response
+            process.stdout.on('data', handleData);
+            // Send tools/list request
+            const requestLine = JSON.stringify(mcpRequest) + '\n';
+            process.stdin.write(requestLine);
+        });
+    }
+    /**
+     * Handle server errors
+     */
+    handleServerError(serverId, error, agentId, channelId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { status } = serverData;
+        status.status = 'error';
+        status.lastError = error;
+        logger.error(`❌ Server ${serverId} error: ${error}`);
+        // Emit error event
+        this.emitServerErrorEvent(serverId, error, agentId, channelId);
+    }
+    /**
+     * Emit server event with proper payload structure
+     */
+    emitServerEvent(eventType, serverId, agentId, channelId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { config } = serverData;
+        // Use default values if agentId/channelId not provided
+        const defaultAgentId = agentId || 'SYSTEM';
+        const defaultChannelId = channelId || 'SYSTEM';
+        // Determine scope from server ID
+        const scopeData = this.serverScopes.get(serverId);
+        const scope = scopeData?.scope || 'global';
+        const scopeId = scopeData?.scopeId;
+        // Use injectable emitter if available, otherwise direct EventBus.server
+        if (this.toolEventEmitter) {
+            this.toolEventEmitter.emitServerEvent(eventType, serverId, config.name, scope, scopeId, defaultAgentId, defaultChannelId);
+        }
+        else {
+            EventBus.server.emit(eventType, createExternalMcpServerEventPayload(eventType, defaultAgentId, defaultChannelId, {
+                serverId: serverId,
+                serverName: config.name,
+                scope: scope,
+                scopeId: scopeId,
+                status: 'running'
+            }));
+        }
+    }
+    /**
+     * Emit server error event with detailed error information
+     */
+    emitServerErrorEvent(serverId, error, agentId, channelId) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const defaultAgentId = agentId || 'SYSTEM';
+        const defaultChannelId = channelId || 'SYSTEM';
+        if (this.toolEventEmitter) {
+            this.toolEventEmitter.emitServerError(serverId, error, defaultAgentId, defaultChannelId);
+        }
+        else {
+            EventBus.server.emit(McpEvents.EXTERNAL_SERVER_ERROR, createExternalMcpServerErrorEventPayload(McpEvents.EXTERNAL_SERVER_ERROR, defaultAgentId, defaultChannelId, {
+                error,
+                code: 'EXTERNAL_SERVER_ERROR',
+                details: { serverId }
+            }));
+        }
+    }
+    /**
+     * Emit server health status event
+     */
+    emitServerHealthStatus(serverId, healthStatus) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { config } = serverData;
+        if (this.toolEventEmitter) {
+            this.toolEventEmitter.emitHealthStatus(serverId, config.name, config.version, healthStatus, config.description);
+        }
+        else {
+            EventBus.server.emit(McpEvents.EXTERNAL_SERVER_HEALTH_STATUS, createExternalMcpServerHealthStatusEventPayload(McpEvents.EXTERNAL_SERVER_HEALTH_STATUS, 'SYSTEM', 'SYSTEM', {
+                name: config.name,
+                version: config.version,
+                status: healthStatus,
+                description: config.description
+            }));
+        }
+    }
+    /**
+     * Emit tools discovered event
+     */
+    emitServerToolsDiscovered(serverId, tools) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData)
+            return;
+        const { config } = serverData;
+        if (this.toolEventEmitter) {
+            this.toolEventEmitter.emitToolsDiscovered(serverId, config.name, config.version, tools);
+            return;
+        }
+        EventBus.server.emit(McpEvents.EXTERNAL_SERVER_TOOLS_DISCOVERED, createExternalMcpServerToolsDiscoveredEventPayload(McpEvents.EXTERNAL_SERVER_TOOLS_DISCOVERED, 'SYSTEM', 'SYSTEM', {
+            name: config.name,
+            version: config.version,
+            tools
+        }));
+    }
+    /**
+     * Cleanup and shutdown all servers
+     */
+    async shutdown() {
+        const shutdownPromises = Array.from(this.servers.keys()).map(serverId => this.stopServer(serverId));
+        await Promise.allSettled(shutdownPromises);
+        this.servers.clear();
+        this.removeAllListeners();
+    }
+    /**
+     * Get list of running server IDs
+     */
+    getRunningServerIds() {
+        const runningServers = [];
+        for (const [serverId, serverData] of this.servers.entries()) {
+            if (serverData.status.status === 'running') {
+                runningServers.push(serverId);
+            }
+        }
+        return runningServers;
+    }
+    /**
+     * Get list of failed server IDs
+     */
+    getFailedServerIds() {
+        const failedServers = [];
+        for (const [serverId, serverData] of this.servers.entries()) {
+            if (serverData.status.status === 'error') {
+                failedServers.push(serverId);
+            }
+        }
+        return failedServers;
+    }
+    /**
+     * Get statuses of all servers
+     */
+    getServerStatuses() {
+        const statuses = {};
+        for (const [serverId, serverData] of this.servers.entries()) {
+            statuses[serverId] = { ...serverData.status };
+        }
+        return statuses;
+    }
+    /**
+     * Start a server using its configuration object
+     */
+    async startServerFromConfig(config) {
+        try {
+            // Register the server if not already registered
+            if (!this.servers.has(config.id)) {
+                await this.registerServer(config);
+            }
+            // Start the server process
+            await this.startServer(config.id);
+            return true;
+        }
+        catch (error) {
+            logger.error(`Failed to start server ${config.id}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Restart a server by ID
+     */
+    async restartServer(serverId) {
+        try {
+            // Stop the server first
+            await this.stopServer(serverId);
+            // Wait a bit before restarting
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            // Start the server again
+            await this.startServer(serverId);
+            return true;
+        }
+        catch (error) {
+            logger.error(`Failed to restart server ${serverId}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Execute a tool on an external MCP server via JSON-RPC with auto-correction support
+     */
+    async executeToolOnServer(serverId, toolName, input, agentId = 'system', channelId = 'default') {
+        // PROACTIVE CORRECTION: Apply known corrections before attempting execution
+        // NOTE: n8n-mcp server has built-in n8n_autofix_workflow and validation tools,
+        // so proactive correction is not needed for n8n_* tools. This is kept for
+        // potential future external tools that might benefit from it.
+        // Disabled for now since no tools currently need it.
+        const enableProactiveCorrection = false;
+        if (enableProactiveCorrection && (toolName === 'create_workflow' || toolName === 'update_workflow')) {
+            const proactiveCorrection = await this.autoCorrectionService.attemptCorrection(agentId, channelId, toolName, input, '', // No error yet - proactive check
+            undefined);
+            if (proactiveCorrection.corrected && proactiveCorrection.correctedParameters) {
+                input = proactiveCorrection.correctedParameters;
+            }
+        }
+        const maxAttempts = 2; // Original attempt + 1 retry with correction
+        let currentAttempt = 0;
+        let lastError = null;
+        while (currentAttempt < maxAttempts) {
+            try {
+                const result = await this.executeToolOnServerInternal(serverId, toolName, input);
+                return result;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                logger.error(`❌ External MCP tool ${toolName} failed on attempt ${currentAttempt + 1}: ${lastError.message}`);
+                // Only attempt correction if we have retries left
+                if (currentAttempt < maxAttempts - 1) {
+                    const correctionResult = await this.autoCorrectionService.attemptCorrection(agentId, channelId, toolName, input, lastError.message, undefined // tool schema not available for external tools
+                    );
+                    if (correctionResult.corrected && correctionResult.correctedParameters) {
+                        input = correctionResult.correctedParameters; // Use corrected params for retry
+                    }
+                    else {
+                        break; // No correction possible, don't retry
+                    }
+                }
+                currentAttempt++;
+            }
+        }
+        // All attempts exhausted
+        throw lastError || new Error(`Failed to execute ${toolName} after ${maxAttempts} attempts`);
+    }
+    /**
+     * Internal method to execute tool once (without retry logic)
+     */
+    async executeToolOnServerInternal(serverId, toolName, input) {
+        const serverData = this.servers.get(serverId);
+        if (!serverData) {
+            throw new Error(`Server ${serverId} not found`);
+        }
+        if (!serverData.process || serverData.status.status !== 'running') {
+            throw new Error(`Server ${serverId} is not running`);
+        }
+        // Verify tool exists on server
+        const tool = serverData.status.tools.find(t => t.name === toolName);
+        if (!tool) {
+            throw new Error(`Tool ${toolName} not found on server ${serverId}`);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const requestId = uuidv4();
+                // Create MCP tool call request according to the protocol
+                const mcpRequest = {
+                    jsonrpc: "2.0",
+                    id: requestId,
+                    method: "tools/call",
+                    params: {
+                        name: toolName,
+                        arguments: input
+                    }
+                };
+                let responseBuffer = '';
+                let timeoutId;
+                let resolved = false;
+                const responseHandler = (data) => {
+                    if (resolved)
+                        return; // Prevent duplicate responses
+                    responseBuffer += data.toString();
+                    // Try to parse JSON response (MCP responses are line-delimited JSON)
+                    const lines = responseBuffer.split('\n');
+                    for (let i = 0; i < lines.length - 1; i++) {
+                        const line = lines[i].trim();
+                        if (line) {
+                            try {
+                                const response = JSON.parse(line.trim());
+                                // Check if this is our response
+                                if (response.id === requestId) {
+                                    resolved = true;
+                                    clearTimeout(timeoutId);
+                                    serverData.process.stdout.removeListener('data', responseHandler);
+                                    if (response.error) {
+                                        const errorMessage = `MCP error: ${response.error.message || response.error}`;
+                                        logger.error(`❌ MCP tool call error: ${errorMessage}`);
+                                        reject(new Error(errorMessage));
+                                    }
+                                    else {
+                                        resolve(response.result);
+                                    }
+                                    return;
+                                }
+                            }
+                            catch (parseError) {
+                                // Ignore JSON parse errors for incomplete lines
+                                continue;
+                            }
+                        }
+                    }
+                    // Keep the last incomplete line in buffer
+                    responseBuffer = lines[lines.length - 1];
+                };
+                // Set up timeout (30 seconds for tool execution)
+                timeoutId = setTimeout(() => {
+                    if (!resolved) {
+                        resolved = true;
+                        serverData.process.stdout.removeListener('data', responseHandler);
+                        reject(new Error(`Timeout waiting for tool execution response from ${serverId} after 30 seconds`));
+                    }
+                }, 30000);
+                // Listen for response
+                if (!serverData.process || !serverData.process.stdout) {
+                    reject(new Error(`Server ${serverId} process stdout not available`));
+                    return;
+                }
+                serverData.process.stdout.on('data', responseHandler);
+                // Send the request
+                if (!serverData.process.stdin) {
+                    reject(new Error(`Server ${serverId} process stdin not available`));
+                    return;
+                }
+                const requestJson = JSON.stringify(mcpRequest) + '\n';
+                serverData.process.stdin.write(requestJson);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.error(`❌ Failed to execute tool ${toolName} on server ${serverId}: ${errorMessage}`);
+                reject(error);
+            }
+        });
+    }
+}
+//# sourceMappingURL=ExternalMcpServerManager.js.map