@loop_ouroboros/mcp-hub-lite 1.2.9 → 1.3.1

package/dist/server/src/services/gateway/request-handlers/call-tool-handler.js

@@ -3,14 +3,13 @@
  */
 import { CallToolRequestSchema, ListToolsRequestSchema, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { logger, LOG_MODULES } from '../../../utils/index.js';
-import { stringifyForLogging } from '../../../utils/json-utils.js';
-import { mcpConnectionManager } from '../../mcp-connection-manager.js';
+import { hubToolsService } from '../../hub-tools.service.js';
 import { SystemToolHandler } from '../../system-tool-handler.js';
 import { ErrorHandler } from '../../../utils/error-handler.js';
 import { ToolArgsParser } from '../../../utils/tool-args-parser.js';
 import { SYSTEM_TOOL_NAMES, MCP_HUB_LITE_SERVER } from '../../../models/system-tools.constants.js';
 import { formatToolArgs, formatToolResponse } from '../log-formatter.js';
-import { generateGatewayToolsList } from '../tool-list-generator.js';
+import { getOrBuildGatewayToolMap, getOrBuildGatewayToolsList } from '../tool-list-generator.js';
 /**
  * Type guard to check if a result is a valid CallToolResult.
  *
@@ -37,7 +36,7 @@ async function executeSystemToolCall(toolName, toolArgs) {
             content: [
                 {
                     type: 'text',
-                    text: stringifyForLogging(result)
+                    text: JSON.stringify(result, null, 2)
                 }
             ]
         };
@@ -75,10 +74,10 @@ function getSystemToolName(toolName) {
  * @param server - MCP server instance to register handlers on
  * @param toolMap - Tool map for routing tool calls
  */
-export function registerCallToolHandler(server, toolMap) {
+export function registerCallToolHandler(server) {
     // Original list tools handler (for compatibility)
     server.server.setRequestHandler(ListToolsRequestSchema, async () => {
-        const gatewayTools = generateGatewayToolsList(toolMap);
+        const gatewayTools = getOrBuildGatewayToolsList();
         return {
             tools: gatewayTools
         };
@@ -88,26 +87,38 @@ export function registerCallToolHandler(server, toolMap) {
         const toolName = request.params.name;
         const toolArgs = request.params.arguments || {};
         const systemToolName = getSystemToolName(toolName);
+        const gwToolMap = getOrBuildGatewayToolMap();
         // Log incoming tool request with full context
         logger.info(`Tool call REQUEST received: toolName=${toolName}, args=${formatToolArgs(toolArgs)}`, LOG_MODULES.GATEWAY);
-        logger.debug(`Tool context: toolMap size=${toolMap.size}, available tools=${Array.from(toolMap.keys()).slice(0, 10).join(', ')}${toolMap.size > 10 ? '...' : ''}`, LOG_MODULES.GATEWAY);
+        logger.debug(`Tool context: toolMap size=${gwToolMap.size}, available tools=${Array.from(gwToolMap.keys()).slice(0, 10).join(', ')}${gwToolMap.size > 10 ? '...' : ''}`, LOG_MODULES.GATEWAY);
         // Handle system tools
         if (systemToolName) {
             logger.debug(`System tool called: ${systemToolName}, args=${formatToolArgs(toolArgs)}`, LOG_MODULES.GATEWAY);
             return await executeSystemToolCall(systemToolName, toolArgs);
         }
-        const target = toolMap.get(toolName);
+        const target = gwToolMap.get(toolName);
         logger.debug(`Tool lookup SUCCESS: toolName=${toolName} -> serverName=${target?.serverName}, serverIndex=${target?.serverIndex}, realToolName=${target?.realToolName}`, LOG_MODULES.GATEWAY);
         if (!target) {
-            logger.error(`Tool NOT FOUND: toolName=${toolName}, available tools=${Array.from(toolMap.keys()).join(', ')}`, LOG_MODULES.GATEWAY);
+            logger.error(`Tool NOT FOUND: toolName=${toolName}, available tools=${Array.from(gwToolMap.keys()).join(', ')}`, LOG_MODULES.GATEWAY);
             throw new McpError(-32801, `Tool ${toolName} not found`);
         }
+        // Extract wrapped arguments (LLM provides serverName/toolName per schema guidance)
+        const wrappedArgs = toolArgs;
+        const callServerName = wrappedArgs.serverName || target.serverName;
+        const callToolName = wrappedArgs.toolName || target.realToolName;
+        const callArgs = wrappedArgs.toolArgs || {};
+        const callOptions = wrappedArgs.requestOptions || {};
         const startTime = Date.now();
         try {
-            logger.debug(`Tool call EXECUTING: serverName=${target.serverName}, serverIndex=${target.serverIndex}, realToolName=${target.realToolName}, args=${formatToolArgs(toolArgs)}`, LOG_MODULES.GATEWAY);
-            const result = await mcpConnectionManager.callTool(target.serverName, target.serverIndex, target.realToolName, toolArgs);
+            logger.debug(`Tool call EXECUTING: serverName=${callServerName}, toolName=${callToolName}, args=${formatToolArgs(callArgs)}`, LOG_MODULES.GATEWAY);
+            const result = await hubToolsService.callTool({
+                serverName: callServerName,
+                toolName: callToolName,
+                toolArgs: callArgs,
+                requestOptions: callOptions
+            });
             const duration = Date.now() - startTime;
-            logger.info(`Tool call SUCCESS: serverName=${target.serverName}, serverIndex=${target.serverIndex}, realToolName=${target.realToolName}, duration=${duration}ms, response=${formatToolResponse(result)}`, LOG_MODULES.GATEWAY);
+            logger.info(`Tool call SUCCESS: serverName=${callServerName}, toolName=${callToolName}, duration=${duration}ms, response=${formatToolResponse(result)}`, LOG_MODULES.GATEWAY);
             // Wrap the result in a valid CallToolResult structure
             if (typeof result === 'object' && result !== null) {
                 return {
@@ -127,7 +138,7 @@ export function registerCallToolHandler(server, toolMap) {
             }
         }
         catch (error) {
-            ErrorHandler.handleToolCallError(`${target.serverName}-${target.serverIndex}`, target.realToolName, error);
+            ErrorHandler.handleToolCallError(callServerName, callToolName, error);
         }
     });
 }

package/dist/server/src/services/gateway/request-handlers/initialize-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initialize-handler.d.ts","sourceRoot":"","sources":["../../../../../../src/services/gateway/request-handlers/initialize-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYpE;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsElE"}
+{"version":3,"file":"initialize-handler.d.ts","sourceRoot":"","sources":["../../../../../../src/services/gateway/request-handlers/initialize-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAapE;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuFlE"}

package/dist/server/src/services/gateway/request-handlers/initialize-handler.js

@@ -1,7 +1,8 @@
 import { logger, LOG_MODULES } from '../../../utils/logger/index.js';
-import { getGatewayDebugSetting } from '../../../utils/json-utils.js';
+import { getGatewayDebugSetting, stringifyForLogging } from '../../../utils/json-utils.js';
 import { MCP_HUB_LITE_SERVER } from '../../../models/system-tools.constants.js';
 import { getAppVersion, getProtocolVersion } from '../../../utils/version.js';
+import { sessionManager } from '../../gateway/session-manager.js';
 import { InitializedNotificationSchema, InitializeRequestSchema, PingRequestSchema } from './initialize.constants.js';
 /**
  * Register initialize and ping handlers on the MCP server.
@@ -14,6 +15,11 @@ export function registerInitializeHandlers(server) {
             const { name, version } = request.params.clientInfo;
             const protocolVersion = request.params?.protocolVersion || getProtocolVersion();
             const clientCapabilities = request.params?.capabilities;
+            sessionManager.storePendingClientMetadata(server, {
+                clientName: name,
+                clientVersion: version,
+                protocolVersion
+            });
             if (getGatewayDebugSetting()) {
                 logger.debug(`Initialized client: Name=${name}, Version=${version}, ProtocolVersion=${protocolVersion}`, LOG_MODULES.GATEWAY);
             }
@@ -30,15 +36,25 @@ export function registerInitializeHandlers(server) {
             capabilities: {
                 tools: {
                     list: true,
-                    execute: true
+                    execute: true,
+                    listChanged: true
                 },
                 resources: {
                     list: true,
-                    read: true
+                    read: true,
+                    listChanged: true
                 },
                 logging: {},
                 experimental: {}
-            }
+            },
+            instructions: 'MCP Hub Lite is a lightweight MCP gateway that aggregates multiple backend MCP servers into a unified interface. ' +
+                'HOW TO USE: 1) Start with resources/list to discover available servers and the use guide. ' +
+                '2) Use list_servers to see all connected servers. ' +
+                '3) Preview a server’s tools via resources/read on hub://servers/{name}. ' +
+                '4) Use list_tools for the full tool list, get_tool when you need inputSchema, then call_tool to execute. ' +
+                '5) Use search_tools to find tools by name or description across all servers. ' +
+                'MULTI-INSTANCE SERVERS: Use list_tags to view available instance tags, then pass matching tags via requestOptions.tags when calling call_tool. ' +
+                'System tools (list_servers, list_tools, get_tool, call_tool, search_tools, list_tags, update_server_description) must be called directly, not through call_tool.'
         };
     });
     server.server.setRequestHandler(PingRequestSchema, async () => {
@@ -47,7 +63,7 @@ export function registerInitializeHandlers(server) {
     server.server.setNotificationHandler(InitializedNotificationSchema, async (notification) => {
         if (getGatewayDebugSetting()) {
             logger.debug('Received initialized notification from client', LOG_MODULES.GATEWAY);
-            logger.debug(`Initialized notification details: ${JSON.stringify(notification)}`, LOG_MODULES.GATEWAY);
+            logger.debug(`Initialized notification details: ${stringifyForLogging(notification)}`, LOG_MODULES.GATEWAY);
         }
         try {
             // Process the notification
@@ -58,7 +74,7 @@ export function registerInitializeHandlers(server) {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             logger.error(`Error processing initialized notification: ${errorMessage}`, LOG_MODULES.GATEWAY);
-            logger.error(`Notification that caused error: ${JSON.stringify(notification)}`, LOG_MODULES.GATEWAY);
+            logger.error(`Notification that caused error: ${stringifyForLogging(notification)}`, LOG_MODULES.GATEWAY);
             throw error; // Re-throw to see if this is the source of the problem
         }
     });

package/dist/server/src/services/gateway/request-handlers/resources-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources-handler.d.ts","sourceRoot":"","sources":["../../../../../../src/services/gateway/request-handlers/resources-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwCjE"}
+{"version":3,"file":"resources-handler.d.ts","sourceRoot":"","sources":["../../../../../../src/services/gateway/request-handlers/resources-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsDjE"}

package/dist/server/src/services/gateway/request-handlers/resources-handler.js

@@ -1,10 +1,9 @@
 /**
  * Resources-related request handlers for Gateway service.
  */
-import { ListResourcesRequestSchema, ReadResourceRequestSchema, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { logger } from '../../../utils/index.js';
 import { LOG_MODULES } from '../../../utils/logger/log-modules.js';
-import { stringifyForLogging } from '../../../utils/json-utils.js';
 import { hubToolsService } from '../../hub-tools.service.js';
 /**
  * Register resources-related handlers on the MCP server.
@@ -12,6 +11,10 @@ import { hubToolsService } from '../../hub-tools.service.js';
  * @param server - MCP server instance to register handlers on
  */
 export function registerResourcesHandlers(server) {
+    // Resource templates — gateway does not use templates, return empty list
+    server.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        return { resourceTemplates: [] };
+    });
     server.server.setRequestHandler(ListResourcesRequestSchema, async () => {
         try {
             const resources = await hubToolsService.listResources();
@@ -32,13 +35,18 @@ export function registerResourcesHandlers(server) {
         try {
             const { uri } = request.params;
             const content = await hubToolsService.readResource(uri);
+            // Preserve original mimeType if content is already in MCP ReadResourceResult format
+            const mcpResult = content && typeof content === 'object' && 'contents' in content
+                ? content
+                : null;
+            const mimeType = mcpResult?.contents?.[0]?.mimeType || 'application/json';
             // Convert to official MCP format: contents array with required uri field
             return {
                 contents: [
                     {
                         uri,
-                        mimeType: 'application/json',
-                        text: typeof content === 'string' ? content : stringifyForLogging(content)
+                        mimeType,
+                        text: typeof content === 'string' ? content : JSON.stringify(content, null, 2)
                     }
                 ]
             };

package/dist/server/src/services/gateway/session-manager.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Session Manager for stateful Streamable HTTP MCP transport.
+ *
+ * Each client session owns a StreamableHTTPServerTransport + McpServer pair.
+ * Sessions are identified by mcp-session-id header (generated by the SDK).
+ * Notifications are broadcast to all active sessions via their McpServer instances.
+ */
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+interface SessionState {
+    sessionId: string;
+    transport: StreamableHTTPServerTransport;
+    server: McpServer;
+    createdAt: number;
+    lastAccessedAt: number;
+    isClosing: boolean;
+    activeSseCount: number;
+    lastPingedAt: number;
+    pingPending: boolean;
+    clientName?: string;
+    clientVersion?: string;
+    protocolVersion?: string;
+    createdByMethod?: string;
+    lastMethod?: string;
+}
+export declare class SessionManager {
+    private sessions;
+    private cleanupTimer;
+    private pendingClientMetadata;
+    /**
+     * Registers a newly created session.
+     */
+    addSession(sessionId: string, transport: StreamableHTTPServerTransport, server: McpServer): void;
+    /**
+     * Looks up an existing session by ID and updates lastAccessedAt.
+     */
+    getSession(sessionId: string): SessionState | undefined;
+    /**
+     * Marks an SSE stream as opened for the given session.
+     * Prevents the session from being cleaned up while the stream is active.
+     */
+    markSseOpened(sessionId: string): void;
+    /**
+     * Marks an SSE stream as closed for the given session.
+     */
+    markSseClosed(sessionId: string): void;
+    /**
+     * Removes a session (called on DELETE or onsessionclosed).
+     */
+    removeSession(sessionId: string): void;
+    private pendingBroadcasts;
+    private readonly BROADCAST_DEBOUNCE_MS;
+    /**
+     * Broadcasts a notification to all active sessions.
+     * Debounced: same-type notifications within BROADCAST_DEBOUNCE_MS are coalesced.
+     * @param method - 'tools' for sendToolListChanged, 'resources' for sendResourceListChanged
+     */
+    broadcastNotification(method: 'tools' | 'resources'): void;
+    /**
+     * Removes sessions that have been idle longer than SESSION_TIMEOUT_MS.
+     */
+    private cleanupStaleSessions;
+    private ensureCleanupTimer;
+    /**
+     * Shuts down all sessions. Called on server shutdown.
+     */
+    shutdownAll(): void;
+    /** Returns the current session count (for diagnostics). */
+    get sessionCount(): number;
+    /**
+     * Stores client metadata against a McpServer instance so that
+     * addSession() can consume it when the session is registered later.
+     */
+    storePendingClientMetadata(server: McpServer, metadata: {
+        clientName: string;
+        clientVersion: string;
+        protocolVersion: string;
+    }): void;
+    /**
+     * Returns metadata for all active sessions. Does not expose internal
+     * transport or server references.
+     */
+    getAllSessions(): Array<{
+        sessionId: string;
+        clientName?: string;
+        clientVersion?: string;
+        protocolVersion?: string;
+        createdByMethod?: string;
+        lastMethod?: string;
+        createdAt: string;
+        lastAccessedAt: string;
+        isClosing: boolean;
+        activeSseCount: number;
+    }>;
+    /** Updates the last HTTP method seen for a session. */
+    updateSessionMethod(sessionId: string, method: string): void;
+}
+/** Singleton instance. */
+export declare const sessionManager: SessionManager;
+export {};
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/server/src/services/gateway/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/gateway/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACxG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,UAAU,YAAY;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,6BAA6B,CAAC;IACzC,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,YAAY,CAA+C;IAEnE,OAAO,CAAC,qBAAqB,CAGzB;IAEJ;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,6BAA6B,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IA6BhG;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IASvD;;;OAGG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAatC;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAatC;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAuBtC,OAAO,CAAC,iBAAiB,CAAoD;IAC7E,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IAE9C;;;;OAIG;IACH,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI;IA4B1D;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiE5B,OAAO,CAAC,kBAAkB;IAM1B;;OAEG;IACH,WAAW,IAAI,IAAI;IAenB,2DAA2D;IAC3D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,0BAA0B,CACxB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,GAC/E,IAAI;IAIP;;;OAGG;IACH,cAAc,IAAI,KAAK,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,OAAO,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IAmBF,uDAAuD;IACvD,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAM7D;AAED,0BAA0B;AAC1B,eAAO,MAAM,cAAc,gBAAuB,CAAC"}

package/dist/server/src/services/gateway/session-manager.js

@@ -0,0 +1,256 @@
+/**
+ * Session Manager for stateful Streamable HTTP MCP transport.
+ *
+ * Each client session owns a StreamableHTTPServerTransport + McpServer pair.
+ * Sessions are identified by mcp-session-id header (generated by the SDK).
+ * Notifications are broadcast to all active sessions via their McpServer instances.
+ */
+import { logger, LOG_MODULES } from '../../utils/logger/index.js';
+import { getGatewayDebugSetting } from '../../utils/json-utils.js';
+import { configManager } from '../../config/config-manager.js';
+const CLEANUP_INTERVAL_MS = 60 * 1000; // every minute
+const PING_COOLDOWN_MS = 30 * 1000; // min interval between pings
+const PING_TIMEOUT_MS = 10 * 1000; // per-ping timeout
+export class SessionManager {
+    sessions = new Map();
+    cleanupTimer = null;
+    pendingClientMetadata = new WeakMap();
+    /**
+     * Registers a newly created session.
+     */
+    addSession(sessionId, transport, server) {
+        const pendingMeta = this.pendingClientMetadata.get(server);
+        this.pendingClientMetadata.delete(server);
+        this.sessions.set(sessionId, {
+            sessionId,
+            transport,
+            server,
+            createdAt: Date.now(),
+            lastAccessedAt: Date.now(),
+            isClosing: false,
+            activeSseCount: 0,
+            lastPingedAt: 0,
+            pingPending: false,
+            clientName: pendingMeta?.clientName,
+            clientVersion: pendingMeta?.clientVersion,
+            protocolVersion: pendingMeta?.protocolVersion,
+            createdByMethod: 'POST',
+            lastMethod: 'POST'
+        });
+        if (getGatewayDebugSetting()) {
+            logger.debug(`Session registered: ${sessionId} (total: ${this.sessions.size}, activeSseCount: 0)`, LOG_MODULES.GATEWAY);
+        }
+        this.ensureCleanupTimer();
+    }
+    /**
+     * Looks up an existing session by ID and updates lastAccessedAt.
+     */
+    getSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session && !session.isClosing) {
+            session.lastAccessedAt = Date.now();
+            return session;
+        }
+        return undefined;
+    }
+    /**
+     * Marks an SSE stream as opened for the given session.
+     * Prevents the session from being cleaned up while the stream is active.
+     */
+    markSseOpened(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session && !session.isClosing) {
+            session.activeSseCount++;
+            if (getGatewayDebugSetting()) {
+                logger.debug(`Session ${sessionId} SSE opened (activeSseCount: ${session.activeSseCount})`, LOG_MODULES.GATEWAY);
+            }
+        }
+    }
+    /**
+     * Marks an SSE stream as closed for the given session.
+     */
+    markSseClosed(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.activeSseCount = Math.max(0, session.activeSseCount - 1);
+            if (getGatewayDebugSetting()) {
+                logger.debug(`Session ${sessionId} SSE closed (activeSseCount: ${session.activeSseCount})`, LOG_MODULES.GATEWAY);
+            }
+        }
+    }
+    /**
+     * Removes a session (called on DELETE or onsessionclosed).
+     */
+    removeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.isClosing)
+            return;
+        session.isClosing = true;
+        try {
+            session.transport.close().catch((err) => {
+                logger.debug(`Error closing transport for session ${sessionId}: ${err}`, LOG_MODULES.GATEWAY);
+            });
+        }
+        catch {
+            // transport may already be closed
+        }
+        this.sessions.delete(sessionId);
+        if (getGatewayDebugSetting()) {
+            logger.debug(`Session removed: ${sessionId} (total: ${this.sessions.size}, age: ${Date.now() - session.createdAt}ms, activeSseCount: ${session.activeSseCount})`, LOG_MODULES.GATEWAY);
+        }
+    }
+    pendingBroadcasts = new Map();
+    BROADCAST_DEBOUNCE_MS = 3000;
+    /**
+     * Broadcasts a notification to all active sessions.
+     * Debounced: same-type notifications within BROADCAST_DEBOUNCE_MS are coalesced.
+     * @param method - 'tools' for sendToolListChanged, 'resources' for sendResourceListChanged
+     */
+    broadcastNotification(method) {
+        // Skip if a debounce timer for this method type is already pending
+        if (this.pendingBroadcasts.has(method))
+            return;
+        this.pendingBroadcasts.set(method, setTimeout(() => {
+            this.pendingBroadcasts.delete(method);
+            if (this.sessions.size === 0)
+                return;
+            for (const [sessionId, state] of this.sessions) {
+                if (state.isClosing)
+                    continue;
+                try {
+                    if (method === 'tools') {
+                        state.server.sendToolListChanged();
+                    }
+                    else {
+                        state.server.sendResourceListChanged();
+                    }
+                }
+                catch (error) {
+                    logger.debug(`Failed to broadcast ${method} notification to session ${sessionId}: ${error}`, LOG_MODULES.GATEWAY);
+                }
+            }
+        }, this.BROADCAST_DEBOUNCE_MS));
+    }
+    /**
+     * Removes sessions that have been idle longer than SESSION_TIMEOUT_MS.
+     */
+    cleanupStaleSessions() {
+        const now = Date.now();
+        const staleIds = [];
+        let skippedClosing = 0;
+        let skippedSse = 0;
+        let pingFailed = 0;
+        for (const [id, state] of this.sessions) {
+            if (state.isClosing) {
+                skippedClosing++;
+                continue;
+            }
+            // Ping from last cycle timed out — session is dead
+            if (state.pingPending) {
+                state.pingPending = false;
+                pingFailed++;
+                staleIds.push(id);
+                continue;
+            }
+            if (state.activeSseCount > 0) {
+                if (now - state.lastPingedAt < PING_COOLDOWN_MS) {
+                    skippedSse++;
+                    continue;
+                }
+                state.lastPingedAt = now;
+                state.pingPending = true;
+                // Fire-and-forget concurrent ping with timeout
+                const pingWithTimeout = Promise.race([
+                    state.server.server.ping(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Ping timeout')), PING_TIMEOUT_MS))
+                ]);
+                pingWithTimeout.then(() => {
+                    const s = this.sessions.get(id);
+                    if (s) {
+                        s.pingPending = false;
+                        s.lastAccessedAt = Date.now();
+                    }
+                }, () => {
+                    // Keep pingPending=true so the next cycle cleans up this dead session
+                });
+                skippedSse++;
+                continue;
+            }
+            if (now - state.lastAccessedAt > configManager.getConfig().security.idleConnectionTimeout) {
+                staleIds.push(id);
+            }
+        }
+        if (getGatewayDebugSetting() && (staleIds.length > 0 || skippedSse > 0 || pingFailed > 0)) {
+            logger.debug(`Stale cleanup: total=${this.sessions.size} stale=${staleIds.length} skippedClosing=${skippedClosing} skippedSse=${skippedSse} pingFailed=${pingFailed}`, LOG_MODULES.GATEWAY);
+        }
+        for (const id of staleIds) {
+            logger.info(`Removing stale session: ${id}`, LOG_MODULES.GATEWAY);
+            this.removeSession(id);
+        }
+    }
+    ensureCleanupTimer() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => this.cleanupStaleSessions(), CLEANUP_INTERVAL_MS);
+        this.cleanupTimer.unref();
+    }
+    /**
+     * Shuts down all sessions. Called on server shutdown.
+     */
+    shutdownAll() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        for (const timer of this.pendingBroadcasts.values()) {
+            clearTimeout(timer);
+        }
+        this.pendingBroadcasts.clear();
+        for (const [id] of this.sessions) {
+            this.removeSession(id);
+        }
+        logger.info('All sessions shut down', LOG_MODULES.GATEWAY);
+    }
+    /** Returns the current session count (for diagnostics). */
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Stores client metadata against a McpServer instance so that
+     * addSession() can consume it when the session is registered later.
+     */
+    storePendingClientMetadata(server, metadata) {
+        this.pendingClientMetadata.set(server, metadata);
+    }
+    /**
+     * Returns metadata for all active sessions. Does not expose internal
+     * transport or server references.
+     */
+    getAllSessions() {
+        const result = [];
+        for (const state of this.sessions.values()) {
+            result.push({
+                sessionId: state.sessionId,
+                clientName: state.clientName,
+                clientVersion: state.clientVersion,
+                protocolVersion: state.protocolVersion,
+                createdByMethod: state.createdByMethod,
+                lastMethod: state.lastMethod,
+                createdAt: new Date(state.createdAt).toLocaleString(),
+                lastAccessedAt: new Date(state.lastAccessedAt).toLocaleString(),
+                isClosing: state.isClosing,
+                activeSseCount: state.activeSseCount
+            });
+        }
+        return result;
+    }
+    /** Updates the last HTTP method seen for a session. */
+    updateSessionMethod(sessionId, method) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.lastMethod = method;
+        }
+    }
+}
+/** Singleton instance. */
+export const sessionManager = new SessionManager();

package/dist/server/src/services/gateway/tool-list-generator.d.ts

@@ -1,23 +1,18 @@
 /**
- * Gateway tool list generator with collision resolution.
+ * Gateway tool list generator with collision resolution and global caching.
  */
 import type { ToolMapEntry, GatewayTool } from './types.js';
-/**
- * Generates a unified list of gateway tools with proper naming and collision resolution.
- *
- * This method creates a comprehensive tool list that includes both system tools and
- * aggregated tools from all connected MCP servers. It implements sophisticated
- * naming collision resolution by:
- * - Adding server hash suffixes to non-unique tool names
- * - Handling conflicts with system tool names
- * - Ensuring names don't exceed 60 characters
- * - Providing final uniqueness guarantees through counter suffixes
- *
- * The method also populates the provided toolMap with mappings from gateway tool names
- * to actual server IDs and real tool names for efficient routing during tool execution.
- *
- * @param {Map<string, ToolMapEntry>} toolMap - Map to populate with gateway tool name to actual tool mappings
- * @returns {Array<GatewayTool>} Array of gateway tools with resolved names and descriptions
- */
-export declare function generateGatewayToolsList(toolMap: Map<string, ToolMapEntry>): Array<GatewayTool>;
+export declare function generateGatewayToolsList(toolMap: Map<string, ToolMapEntry>): GatewayTool[];
+/** Lazy get — first-request fallback when cache hasn't been built yet */
+export declare function getOrBuildGatewayToolMap(): Map<string, ToolMapEntry>;
+/** Lazy get — first-request fallback when cache hasn't been built yet */
+export declare function getOrBuildGatewayToolsList(): GatewayTool[];
+/** Lazy get — returns only aggregated external tools (excludes system tools) */
+export declare function getExternalGatewayTools(): GatewayTool[];
+/** Full rebuild from global state — used by TOOLS_UPDATED / SERVER_DISCONNECTED */
+export declare function rebuildFromScratch(): void;
+/** Incremental add — update raw data layer, re-resolve names only */
+export declare function addToCache(serverName: string, toolNames: string[]): void;
+/** Incremental remove — update raw data layer, re-resolve names only */
+export declare function removeFromCache(serverName: string, toolNames: string[]): void;
 //# sourceMappingURL=tool-list-generator.d.ts.map

package/dist/server/src/services/gateway/tool-list-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-list-generator.d.ts","sourceRoot":"","sources":["../../../../../src/services/gateway/tool-list-generator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAkI/F"}
+{"version":3,"file":"tool-list-generator.d.ts","sourceRoot":"","sources":["../../../../../src/services/gateway/tool-list-generator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwM5D,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,WAAW,EAAE,CAG1F;AAID,yEAAyE;AACzE,wBAAgB,wBAAwB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAKpE;AAED,yEAAyE;AACzE,wBAAgB,0BAA0B,IAAI,WAAW,EAAE,CAK1D;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,IAAI,WAAW,EAAE,CAEvD;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,IAAI,IAAI,CASzC;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAoDxE;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAqC7E"}