@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/api/mcp/debug-response-wrapper.js

@@ -0,0 +1,271 @@
+/**
+ * Debug Response Wrapper for MCP Gateway.
+ * Wraps Fastify reply to capture and log response content in development mode.
+ */
+import { logger, LOG_MODULES, isToolsListResponse, simplifyToolsListResponse, hasImageContent, simplifyImageContent } from '../../utils/logger.js';
+import { stringifyForLogging, getMcpCommDebugSetting } from '../../utils/json-utils.js';
+/**
+ * Wraps Fastify reply to capture and log response content in development mode.
+ *
+ * @param reply - Fastify reply object to wrap
+ * @param sessionId - Current session ID for logging
+ */
+export function wrapReplyForDebug(reply, sessionId) {
+    // Only wrap for debug logging if MCP_COMM_DEBUG is enabled
+    if (!getMcpCommDebugSetting()) {
+        return;
+    }
+    const originalWrite = reply.raw.write.bind(reply.raw);
+    const originalEnd = reply.raw.end.bind(reply.raw);
+    let responseBuffer = '';
+    let socketBuffer = '';
+    let hasLoggedResponse = false;
+    let socketWrapped = false;
+    logger.debug(`Wrapping response - writable: ${reply.raw.writable}, destroyed: ${reply.raw.destroyed}, socket: ${!!reply.raw.socket}`, LOG_MODULES.COMMUNICATION);
+    // Wrap socket write if socket exists (for transports that bypass http.ServerResponse.write/end)
+    const wrapSocket = () => {
+        if (socketWrapped || !reply.raw.socket) {
+            return;
+        }
+        const socket = reply.raw.socket;
+        const originalSocketWrite = socket.write.bind(socket);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        socket.write = function (data, encoding, callback) {
+            try {
+                if (typeof data === 'string') {
+                    socketBuffer += data;
+                }
+                else if (data instanceof Buffer) {
+                    socketBuffer += data.toString(encoding || 'utf8');
+                }
+                else if (data instanceof Uint8Array) {
+                    try {
+                        socketBuffer += new TextDecoder('utf-8').decode(data);
+                    }
+                    catch {
+                        socketBuffer += `[Binary data: ${data.length} bytes]`;
+                    }
+                }
+            }
+            catch (error) {
+                logger.debug(`MCP Gateway: Error processing socket write: ${error}`, LOG_MODULES.COMMUNICATION);
+            }
+            return originalSocketWrite(data, encoding, callback);
+        };
+        // Also listen for socket finish to log any remaining data
+        socket.once('finish', () => {
+            if (!hasLoggedResponse && (socketBuffer.length > 0 || responseBuffer.length > 0)) {
+                logFinalResponse();
+            }
+        });
+        socketWrapped = true;
+        logger.debug(`MCP Gateway: Socket wrapped successfully for session ${sessionId}`, LOG_MODULES.COMMUNICATION);
+    };
+    // Helper function to format and log response
+    const logFinalResponse = () => {
+        if (hasLoggedResponse) {
+            return;
+        }
+        hasLoggedResponse = true;
+        // Determine which buffer to use
+        const primaryBuffer = responseBuffer.length > 0 ? responseBuffer : socketBuffer;
+        const bufferSource = responseBuffer.length > 0 ? 'http.ServerResponse' : 'socket';
+        if (primaryBuffer.length === 0) {
+            logger.debug(`MCP Gateway response for ${sessionId}: [No response data captured - transport may have used direct socket operations]`, LOG_MODULES.COMMUNICATION);
+            return;
+        }
+        // Log response content, simplify tools/list responses and image content
+        let logResponse = primaryBuffer;
+        try {
+            if (isToolsListResponse(logResponse)) {
+                logResponse = simplifyToolsListResponse(logResponse);
+            }
+            else if (hasImageContent(logResponse)) {
+                // Simplify image content first
+                const simplified = simplifyImageContent(logResponse);
+                // Then format for logging
+                if (simplified.includes('event: message') && simplified.includes('data:')) {
+                    const dataMatch = simplified.match(/data: ([^\n]+)/);
+                    if (dataMatch) {
+                        const jsonData = dataMatch[1].trim();
+                        try {
+                            const parsed = JSON.parse(jsonData);
+                            const formattedData = stringifyForLogging(parsed);
+                            logResponse = `event: message\ndata: ${formattedData}`;
+                        }
+                        catch {
+                            logResponse = simplified;
+                        }
+                    }
+                    else {
+                        logResponse = simplified;
+                    }
+                }
+                else {
+                    const parsed = JSON.parse(simplified);
+                    logResponse = stringifyForLogging(parsed);
+                }
+            }
+            else {
+                // Handle SSE format responses (event: message followed by data: JSON)
+                if (primaryBuffer.includes('event: message') && primaryBuffer.includes('data:')) {
+                    const dataMatch = primaryBuffer.match(/data: ([^\n]+)/);
+                    if (dataMatch) {
+                        const jsonData = dataMatch[1].trim();
+                        try {
+                            const parsed = JSON.parse(jsonData);
+                            const formattedData = stringifyForLogging(parsed);
+                            logResponse = `event: message\ndata: ${formattedData}`;
+                        }
+                        catch {
+                            logResponse = primaryBuffer;
+                        }
+                    }
+                    else {
+                        logResponse = primaryBuffer;
+                    }
+                }
+                else {
+                    // Try to format other JSON responses to improve readability
+                    const parsed = JSON.parse(primaryBuffer);
+                    logResponse = stringifyForLogging(parsed);
+                }
+            }
+        }
+        catch {
+            // If not valid JSON, output as-is and truncate long content
+            logResponse =
+                primaryBuffer.length > 500 ? primaryBuffer.substring(0, 500) + '...' : primaryBuffer;
+        }
+        logger.debug(`MCP Gateway response for ${sessionId} (source: ${bufferSource}):\n${logResponse.trimEnd()}`, LOG_MODULES.COMMUNICATION);
+    };
+    // Try to wrap socket immediately
+    wrapSocket();
+    // Also try to wrap socket when it becomes available (in case it's not yet attached)
+    reply.raw.once('socket', () => {
+        wrapSocket();
+    });
+    // Wrap write method
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    reply.raw.write = function (chunk, encoding, callback) {
+        try {
+            let chunkStr = '';
+            if (typeof chunk === 'string') {
+                chunkStr = chunk;
+            }
+            else if (chunk instanceof Buffer) {
+                chunkStr = chunk.toString(encoding || 'utf8');
+            }
+            else if (chunk instanceof Uint8Array) {
+                // Try to convert Uint8Array to string (for SSE event streams)
+                try {
+                    chunkStr = new TextDecoder('utf-8').decode(chunk);
+                }
+                catch {
+                    // If unable to decode as text, provide binary summary
+                    chunkStr = `[Binary data: ${chunk.length} bytes]`;
+                }
+            }
+            else if (typeof chunk === 'object') {
+                chunkStr = JSON.stringify(chunk);
+            }
+            else {
+                chunkStr = String(chunk);
+            }
+            responseBuffer += chunkStr;
+        }
+        catch (error) {
+            logger.debug(`MCP Gateway: Error processing write chunk: ${error}`, LOG_MODULES.COMMUNICATION);
+        }
+        return originalWrite(chunk, encoding, callback);
+    };
+    // Wrap end method
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    reply.raw.end = function (chunk, encoding, callback) {
+        try {
+            if (chunk !== undefined && chunk !== null) {
+                let chunkStr = '';
+                if (typeof chunk === 'string') {
+                    chunkStr = chunk;
+                }
+                else if (chunk instanceof Buffer) {
+                    chunkStr = chunk.toString(encoding || 'utf8');
+                }
+                else if (chunk instanceof Uint8Array) {
+                    // Try to convert Uint8Array to string (for SSE event streams)
+                    try {
+                        chunkStr = new TextDecoder('utf-8').decode(chunk);
+                    }
+                    catch {
+                        // If unable to decode as text, provide binary summary
+                        chunkStr = `[Binary data: ${chunk.length} bytes]`;
+                    }
+                }
+                else if (typeof chunk === 'object') {
+                    chunkStr = JSON.stringify(chunk);
+                }
+                else {
+                    chunkStr = String(chunk);
+                }
+                responseBuffer += chunkStr;
+            }
+            // Log response before calling original end
+            logFinalResponse();
+        }
+        catch (error) {
+            logger.debug(`MCP Gateway: Error processing end chunk: ${error}`, LOG_MODULES.COMMUNICATION);
+        }
+        return originalEnd(chunk, encoding, callback);
+    };
+    // Also wrap writeHead method to capture error response headers
+    const originalWriteHead = reply.raw.writeHead.bind(reply.raw);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    reply.raw.writeHead = function (statusCode, ...args) {
+        try {
+            // Ensure socket is wrapped before any response is sent
+            wrapSocket();
+            // If it's an error response, log status code and headers
+            if (statusCode >= 400) {
+                let statusMessage;
+                let headers;
+                // Handle multiple parameter forms of Node.js writeHead
+                if (args.length === 1) {
+                    // writeHead(statusCode, headers)
+                    headers = args[0];
+                }
+                else if (args.length === 2) {
+                    // writeHead(statusCode, statusMessage, headers) or writeHead(statusCode, headers)
+                    if (typeof args[0] === 'string') {
+                        statusMessage = args[0];
+                        headers = args[1];
+                    }
+                    else {
+                        headers = args[0];
+                    }
+                }
+                if (headers) {
+                    logger.debug(`MCP Gateway error response: ${statusCode} ${statusMessage || ''} Headers: ${stringifyForLogging(headers)}`, LOG_MODULES.COMMUNICATION);
+                }
+                else {
+                    logger.debug(`MCP Gateway error response: ${statusCode} ${statusMessage || ''}`, LOG_MODULES.COMMUNICATION);
+                }
+            }
+        }
+        catch (error) {
+            logger.debug(`MCP Gateway: Error processing writeHead: ${error}`, LOG_MODULES.COMMUNICATION);
+        }
+        return originalWriteHead(statusCode, ...args);
+    };
+    // Set up fallback logging in case end() is never called
+    reply.raw.once('finish', () => {
+        if (!hasLoggedResponse) {
+            logFinalResponse();
+        }
+    });
+    // Also set up close event for fallback
+    reply.raw.once('close', () => {
+        if (!hasLoggedResponse) {
+            logFinalResponse();
+        }
+    });
+}

package/dist/server/src/api/mcp/gateway.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP Gateway endpoint using Streamable HTTP Transport
+ * Handles all MCP protocol requests at /mcp endpoint
+ *
+ * This is a thin wrapper around modular utilities for better maintainability.
+ */
+import type { FastifyInstance } from 'fastify';
+/**
+ * MCP Gateway routes registration.
+ *
+ * @param fastify - Fastify instance to register routes on
+ */
+export declare function mcpGatewayRoutes(fastify: FastifyInstance): Promise<void>;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/server/src/api/mcp/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../../../src/api/mcp/gateway.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAU7E;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,iBAmI9D"}

package/dist/server/src/api/mcp/gateway.js

@@ -0,0 +1,116 @@
+/**
+ * MCP Gateway endpoint using Streamable HTTP Transport
+ * Handles all MCP protocol requests at /mcp endpoint
+ *
+ * This is a thin wrapper around modular utilities for better maintainability.
+ */
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+import { stringifyForLogging } from '../../utils/json-utils.js';
+import { requestContext } from '../../utils/request-context.js';
+import { clientTrackerService } from '../../services/client-tracker.service.js';
+import { mcpSessionManager } from '../../services/mcp-session-manager.js';
+import { cleanupStaleSseStreams } from './sse-stream-manager.js';
+import { extractSessionContext } from './session-context-extractor.js';
+import { wrapReplyForDebug } from './debug-response-wrapper.js';
+/**
+ * MCP Gateway routes registration.
+ *
+ * @param fastify - Fastify instance to register routes on
+ */
+export async function mcpGatewayRoutes(fastify) {
+    const handleMcpRequest = async (request, reply) => {
+        // First, log that we received the request (before extracting session context)
+        let initialLogMsg = `MCP Gateway ${request.method} ${request.url}`;
+        // Combine headers and body into one log block
+        initialLogMsg += `\n  Request headers: ${stringifyForLogging(request.headers)}`;
+        if (request.body) {
+            try {
+                const preview = stringifyForLogging(request.body);
+                initialLogMsg += `\n  Body: ${preview}`;
+            }
+            catch {
+                initialLogMsg += `\n  Body: [Unserializable]`;
+            }
+        }
+        logger.debug(initialLogMsg, LOG_MODULES.GATEWAY);
+        const { sessionId, clientContext } = extractSessionContext(request);
+        logger.info(`MCP Gateway ${request.method} ${request.url} [Session: ${sessionId}]`, LOG_MODULES.GATEWAY);
+        // Update client tracking information
+        clientTrackerService.updateClient(clientContext);
+        // Log the session context after extraction
+        let sessionLogMsg = `MCP Gateway Session Context [Session: ${sessionId}]`;
+        if (clientContext.cwd)
+            sessionLogMsg += ` [CWD: ${clientContext.cwd}]`;
+        if (clientContext.clientName)
+            sessionLogMsg += ` [Client: ${clientContext.clientName}]`;
+        logger.debug(sessionLogMsg, LOG_MODULES.GATEWAY);
+        reply.header('Content-Type', 'application/json');
+        if (!request.headers['accept']) {
+            request.headers['accept'] = 'application/json, text/event-stream';
+        }
+        wrapReplyForDebug(reply, sessionId);
+        reply.hijack();
+        const startTime = Date.now();
+        try {
+            // Determine if initialize request is needed
+            // Only explicit initialize requests require SDK initialization handling
+            // For all other requests (tools/list, etc.), skip initialization checks
+            const isInitializeRequest = request.body?.method === 'initialize';
+            const hasRestoredState = !!mcpSessionManager.getSessionState(sessionId);
+            const requireInitialize = isInitializeRequest;
+            logger.debug(`Request for session: ${sessionId}, method: ${request.body?.method || 'GET'}, isInitialize: ${isInitializeRequest}, hasRestoredState: ${hasRestoredState}, requireInitialize: ${requireInitialize}`, LOG_MODULES.GATEWAY);
+            const session = await mcpSessionManager.getSession(sessionId, requireInitialize);
+            // Proactive cleanup: For GET requests (SSE connections), clean up stale streams first
+            // This prevents "Only one SSE stream is allowed per session" errors
+            if (request.method === 'GET') {
+                logger.debug(`Proactive SSE stream cleanup for session ${sessionId} before handling request`, LOG_MODULES.GATEWAY);
+                cleanupStaleSseStreams(session.transport, sessionId);
+            }
+            await requestContext.run(clientContext, async () => {
+                await session.transport.handleRequest(request.raw, reply.raw, request.body);
+            });
+            const duration = Date.now() - startTime;
+            logger.info(`MCP Gateway response for ${sessionId}: handled in ${duration}ms`, LOG_MODULES.GATEWAY);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`Error handling MCP request for session ${sessionId}: ${errorMessage}`, error, LOG_MODULES.GATEWAY);
+            if (!reply.raw.headersSent) {
+                reply.raw.writeHead(500, { 'Content-Type': 'application/json' });
+                reply.raw.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Internal Server Error',
+                        data: { sessionId }
+                    },
+                    id: null
+                }));
+            }
+        }
+    };
+    // Handle root /mcp endpoint (GET for SSE, POST for messages)
+    fastify.all('/mcp', {
+        bodyLimit: 10 * 1024 * 1024, // 10MB limit
+        preHandler: (request, _reply, done) => {
+            // Ensure we don't parse the body for SSE (GET) requests
+            if (request.method === 'GET') {
+                request.body = null;
+            }
+            done();
+        },
+        handler: handleMcpRequest
+    });
+    // Handle any subpaths if client appends them (e.g. session-specific URLs)
+    fastify.all('/mcp/*', {
+        bodyLimit: 10 * 1024 * 1024, // 10MB limit
+        preHandler: (request, _reply, done) => {
+            // Ensure we don't parse the body for SSE (GET) requests
+            if (request.method === 'GET') {
+                request.body = null;
+            }
+            done();
+        },
+        handler: handleMcpRequest
+    });
+}

package/dist/server/src/api/mcp/session-context-extractor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Session Context Extractor for MCP Gateway.
+ * Extracts and resolves session context from incoming requests.
+ */
+import type { FastifyRequest } from 'fastify';
+import type { ClientContext } from '../../../shared/types/client.types.js';
+export interface RequestBody {
+    method?: string;
+    params?: {
+        clientInfo?: {
+            name: string;
+            version: string;
+        };
+        protocolVersion?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Extracts session context from incoming MCP requests to establish client identity and session management.
+ *
+ * This function implements a simplified session ID resolution strategy with clear priority:
+ * 1. Header parameter mcp-session-id/Mcp-Session-Id (highest priority)
+ * 2. Query parameter sessionId (for SSE connections)
+ * 3. URL pattern match for sessionId
+ * 4. Initialize request: generate from clientInfo (only for initialize requests without sessionId)
+ * 5. Generate new unique session ID (fallback for non-initialize requests)
+ *
+ * The function also extracts and enriches client context including name, version, working directory,
+ * project information, IP address, and user agent for comprehensive session tracking.
+ *
+ * @param {FastifyRequest<{ Body: RequestBody | null }>} request - Incoming Fastify request object
+ * @returns {{ sessionId: string; clientContext: ClientContext }} Object containing resolved session ID and enriched client context
+ *
+ * @example
+ * ```typescript
+ * const { sessionId, clientContext } = extractSessionContext(request);
+ * console.log(`Session: ${sessionId}, Client: ${clientContext.clientName}`);
+ * ```
+ */
+export declare function extractSessionContext(request: FastifyRequest<{
+    Body: RequestBody | null;
+}>): {
+    sessionId: string;
+    clientContext: ClientContext;
+};
+//# sourceMappingURL=session-context-extractor.d.ts.map

package/dist/server/src/api/mcp/session-context-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context-extractor.d.ts","sourceRoot":"","sources":["../../../../../src/api/mcp/session-context-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAInE,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE;YACX,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;SACjB,CAAC;QACF,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,CAAC;IAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;CAC9B,CAoHA"}

package/dist/server/src/api/mcp/session-context-extractor.js

@@ -0,0 +1,127 @@
+/**
+ * Session Context Extractor for MCP Gateway.
+ * Extracts and resolves session context from incoming requests.
+ */
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+import { randomUUID } from 'crypto';
+import { mcpSessionManager } from '../../services/mcp-session-manager.js';
+/**
+ * Extracts session context from incoming MCP requests to establish client identity and session management.
+ *
+ * This function implements a simplified session ID resolution strategy with clear priority:
+ * 1. Header parameter mcp-session-id/Mcp-Session-Id (highest priority)
+ * 2. Query parameter sessionId (for SSE connections)
+ * 3. URL pattern match for sessionId
+ * 4. Initialize request: generate from clientInfo (only for initialize requests without sessionId)
+ * 5. Generate new unique session ID (fallback for non-initialize requests)
+ *
+ * The function also extracts and enriches client context including name, version, working directory,
+ * project information, IP address, and user agent for comprehensive session tracking.
+ *
+ * @param {FastifyRequest<{ Body: RequestBody | null }>} request - Incoming Fastify request object
+ * @returns {{ sessionId: string; clientContext: ClientContext }} Object containing resolved session ID and enriched client context
+ *
+ * @example
+ * ```typescript
+ * const { sessionId, clientContext } = extractSessionContext(request);
+ * console.log(`Session: ${sessionId}, Client: ${clientContext.clientName}`);
+ * ```
+ */
+export function extractSessionContext(request) {
+    const headers = request.headers;
+    // Priority 1: Session ID from Header (highest priority)
+    let sessionId = headers['mcp-session-id'] || headers['Mcp-Session-Id'];
+    if (sessionId) {
+        logger.debug(`Extracted sessionId from header: ${sessionId}`, LOG_MODULES.CONTEXT);
+    }
+    // Priority 2: Session ID from Query (Standard MCP SSE)
+    if (!sessionId) {
+        sessionId = request.query?.sessionId;
+        if (sessionId) {
+            logger.debug(`Extracted sessionId from query: ${sessionId}`, LOG_MODULES.CONTEXT);
+        }
+    }
+    // Priority 3: URL pattern match for sessionId
+    if (!sessionId && request.url.includes('sessionId=')) {
+        const match = request.url.match(/sessionId=([^&]+)/);
+        if (match) {
+            sessionId = match[1];
+            logger.debug(`Extracted sessionId from URL: ${sessionId}`, LOG_MODULES.CONTEXT);
+        }
+    }
+    // If sessionId was extracted, check if it exists in persisted sessions (for debugging)
+    if (sessionId) {
+        const persistedSession = mcpSessionManager.getSessionState(sessionId);
+        if (persistedSession) {
+            logger.debug(`Session ${sessionId} found in persisted sessions`, LOG_MODULES.CONTEXT);
+        }
+        else {
+            logger.debug(`Session ${sessionId} not found in persisted sessions (will create new)`, LOG_MODULES.CONTEXT);
+        }
+    }
+    // Extract client info from headers and request body
+    let clientName = headers['x-mcp-client-id'] || headers['x-client-id'];
+    let clientVersion;
+    let protocolVersion;
+    // Priority 4: For initialize requests without sessionId, generate from clientInfo
+    const isInitializeRequest = request.body?.method === 'initialize';
+    if (!sessionId && isInitializeRequest && request.body?.params?.clientInfo) {
+        const { name, version } = request.body.params.clientInfo;
+        protocolVersion = request.body.params.protocolVersion;
+        const cwd = headers['x-mcp-cwd'] || headers['x-cwd'];
+        // Generate sessionId from client info
+        let baseId = `${name.replace(/[^a-zA-Z0-9-]/g, '')}-${version.replace(/[^a-zA-Z0-9-]/g, '')}`;
+        if (cwd) {
+            const cwdHash = cwd
+                .split('')
+                .reduce((acc, char) => {
+                acc = (acc << 5) - acc + char.charCodeAt(0);
+                return acc & acc;
+            }, 0)
+                .toString(16)
+                .replace('-', '');
+            baseId = `${baseId}-${cwdHash}`;
+        }
+        else {
+            const randomHash = randomUUID().substring(0, 8);
+            baseId = `${baseId}-${randomHash}`;
+        }
+        sessionId = baseId;
+        logger.debug(`Generated sessionId from initialize params: ${sessionId}`, LOG_MODULES.CONTEXT);
+        // Save client version and protocol version information
+        clientVersion = version;
+        protocolVersion = request.body.params.protocolVersion;
+        // Set clientName directly since we get more accurate information from the initialize request
+        clientName = name;
+    }
+    // Priority 5: Generate new unique session ID for non-initialize requests
+    if (!sessionId) {
+        const prefix = clientName ? `${clientName.replace(/[^a-zA-Z0-9-]/g, '')}-` : 'session-';
+        sessionId = `${prefix}${randomUUID().substring(0, 8)}`;
+        if (!clientName && !request.body) {
+            logger.debug(`Initial StreamableHttp connection - created new sessionId: ${sessionId}`, LOG_MODULES.CONTEXT);
+        }
+        else {
+            logger.debug(`Generated new sessionId: ${sessionId}`, LOG_MODULES.CONTEXT);
+        }
+    }
+    // Add consistency check before returning session information
+    if (sessionId && mcpSessionManager.getSessionState(sessionId)) {
+        const hasSessionObject = mcpSessionManager.hasSession(sessionId);
+        if (!hasSessionObject) {
+            logger.warn(`Session state exists but session object missing for ${sessionId}`, LOG_MODULES.CONTEXT);
+        }
+    }
+    const clientContext = {
+        sessionId,
+        clientName,
+        clientVersion,
+        protocolVersion,
+        cwd: headers['x-mcp-cwd'] || headers['x-cwd'],
+        project: headers['x-mcp-project'] || headers['x-project'],
+        ip: request.ip,
+        userAgent: headers['user-agent'],
+        timestamp: Date.now()
+    };
+    return { sessionId, clientContext };
+}

package/dist/server/src/api/mcp/sse-stream-manager.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SSE Stream Management Utilities for MCP Gateway.
+ * Handles cleanup and management of Server-Sent Events streams.
+ */
+/**
+ * Helper to clean up stale SSE streams before handling new requests.
+ * This preserves sessionId and only cleans up SDK-internal stream state.
+ *
+ * @param transport - The StreamableHTTPServerTransport instance from MCP SDK
+ * @param sessionId - The current session ID for logging purposes
+ */
+export declare function cleanupStaleSseStreams(transport: unknown, sessionId: string): void;
+//# sourceMappingURL=sse-stream-manager.d.ts.map

package/dist/server/src/api/mcp/sse-stream-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-stream-manager.d.ts","sourceRoot":"","sources":["../../../../../src/api/mcp/sse-stream-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CA8ClF"}

package/dist/server/src/api/mcp/sse-stream-manager.js

@@ -0,0 +1,40 @@
+/**
+ * SSE Stream Management Utilities for MCP Gateway.
+ * Handles cleanup and management of Server-Sent Events streams.
+ */
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+/**
+ * Helper to clean up stale SSE streams before handling new requests.
+ * This preserves sessionId and only cleans up SDK-internal stream state.
+ *
+ * @param transport - The StreamableHTTPServerTransport instance from MCP SDK
+ * @param sessionId - The current session ID for logging purposes
+ */
+export function cleanupStaleSseStreams(transport, sessionId) {
+    try {
+        // Access internal SDK structures to clean up stream mapping
+        // The transport wraps a WebStandardStreamableHTTPServerTransport internally
+        const webTransport = transport._webStandardTransport;
+        if (webTransport?._streamMapping) {
+            const streamId = webTransport._standaloneSseStreamId || '_GET_stream';
+            const existingStream = webTransport._streamMapping.get(streamId);
+            if (existingStream) {
+                logger.debug(`Cleaning up stale SSE stream for session ${sessionId} (preserving session state)`, LOG_MODULES.GATEWAY);
+                // Try to call cleanup if available on the stream object
+                const streamWithCleanup = existingStream;
+                if (typeof streamWithCleanup.cleanup === 'function') {
+                    streamWithCleanup.cleanup();
+                }
+                else {
+                    // Fallback: directly delete from mapping
+                    webTransport._streamMapping.delete(streamId);
+                }
+                logger.debug(`Successfully cleaned up SSE stream mapping for session ${sessionId}`, LOG_MODULES.GATEWAY);
+            }
+        }
+    }
+    catch (error) {
+        // Non-critical error - if we can't clean up, just continue
+        logger.debug(`Error cleaning up SSE streams (non-critical, continuing): ${error}`, LOG_MODULES.GATEWAY);
+    }
+}

package/dist/server/src/api/web/clients.d.ts

@@ -0,0 +1,30 @@
+import { FastifyInstance } from 'fastify';
+/**
+ * Registers web API routes for client management endpoints.
+ *
+ * This function sets up the HTTP routes that allow external clients to retrieve
+ * information about currently connected clients tracked by the system. The client
+ * tracking service maintains real-time information about all active connections,
+ * including session details, client metadata, and connection status.
+ *
+ * Primary Use Cases:
+ * - Monitoring dashboard to display active client connections
+ * - Debugging and diagnostics for client connectivity issues
+ * - Integration with external monitoring systems
+ * - Client lifecycle management and auditing
+ *
+ * The registered endpoint provides read-only access to client data and includes
+ * proper error handling with appropriate HTTP status codes and logging.
+ *
+ * @param fastify - The Fastify instance to register routes on
+ * @returns Promise<void> - Resolves when routes are registered
+ *
+ * @example
+ * // Register client routes
+ * await webClientRoutes(app);
+ *
+ * // Client can then make GET request to /api/clients
+ * // Returns: Array of ClientContext objects with session and connection details
+ */
+export declare function webClientRoutes(fastify: FastifyInstance): Promise<void>;
+//# sourceMappingURL=clients.d.ts.map