@cyanheads/pubmed-mcp-server 1.2.4 → 1.3.0

package/dist/mcp-server/transports/core/statefulTransportManager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Stateful Transport Manager implementation for MCP SDK.
+ * This manager handles multiple, persistent sessions, creating a dedicated
+ * McpServer and StreamableHTTPServerTransport instance for each one.
+ * This version is adapted for Hono by bridging the SDK's Node.js-style
+ * request handling with Hono's stream-based response model.
+ * @module src/mcp-server/transports/core/statefulTransportManager
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IncomingHttpHeaders } from "http";
+import { RequestContext } from "../../../utils/index.js";
+import { BaseTransportManager } from "./baseTransportManager.js";
+import { StatefulTransportManager as IStatefulTransportManager, TransportResponse, TransportSession } from "./transportTypes.js";
+/**
+ * Stateful Transport Manager that handles MCP SDK integration and session management
+ * for a Hono-based HTTP server.
+ */
+export declare class StatefulTransportManager extends BaseTransportManager implements IStatefulTransportManager {
+    private readonly transports;
+    private readonly servers;
+    private readonly sessions;
+    private readonly garbageCollector;
+    constructor(createServerInstanceFn: () => Promise<McpServer>);
+    initializeAndHandle(headers: IncomingHttpHeaders, body: unknown, context: RequestContext): Promise<TransportResponse>;
+    handleRequest(headers: IncomingHttpHeaders, body: unknown, context: RequestContext, sessionId?: string): Promise<TransportResponse>;
+    handleDeleteRequest(sessionId: string, context: RequestContext): Promise<TransportResponse>;
+    getSession(sessionId: string): TransportSession | undefined;
+    shutdown(): Promise<void>;
+    private closeSession;
+    private cleanupStaleSessions;
+}

package/dist/mcp-server/transports/core/statefulTransportManager.js

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview Stateful Transport Manager implementation for MCP SDK.
+ * This manager handles multiple, persistent sessions, creating a dedicated
+ * McpServer and StreamableHTTPServerTransport instance for each one.
+ * This version is adapted for Hono by bridging the SDK's Node.js-style
+ * request handling with Hono's stream-based response model.
+ * @module src/mcp-server/transports/core/statefulTransportManager
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { randomUUID } from "node:crypto";
+import { Readable } from "stream";
+import { config } from "../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { BaseTransportManager } from "./baseTransportManager.js";
+import { HonoStreamResponse } from "./honoNodeBridge.js";
+/**
+ * Stateful Transport Manager that handles MCP SDK integration and session management
+ * for a Hono-based HTTP server.
+ */
+export class StatefulTransportManager extends BaseTransportManager {
+    constructor(createServerInstanceFn) {
+        super(createServerInstanceFn);
+        this.transports = new Map();
+        this.servers = new Map();
+        this.sessions = new Map();
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.constructor",
+        });
+        logger.info("Starting session garbage collector.", context);
+        this.garbageCollector = setInterval(() => this.cleanupStaleSessions(), config.mcpStatefulSessionStaleTimeoutMs);
+    }
+    async initializeAndHandle(headers, body, context) {
+        const operationName = "StatefulTransportManager.initializeAndHandle";
+        const opContext = { ...context, operation: operationName };
+        logger.debug("Initializing new stateful session.", opContext);
+        const server = await this.createServerInstanceFn();
+        const mockRes = new HonoStreamResponse();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sessionId) => {
+                const sessionContext = { ...opContext, sessionId };
+                this.transports.set(sessionId, transport);
+                this.servers.set(sessionId, server);
+                this.sessions.set(sessionId, {
+                    id: sessionId,
+                    createdAt: new Date(),
+                    lastAccessedAt: new Date(),
+                });
+                logger.info(`MCP Session created: ${sessionId}`, sessionContext);
+            },
+        });
+        transport.onclose = () => {
+            const sessionId = transport.sessionId;
+            if (sessionId) {
+                const closeContext = requestContextService.createRequestContext({
+                    operation: "StatefulTransportManager.transport.onclose",
+                    sessionId,
+                });
+                this.closeSession(sessionId, closeContext).catch((err) => logger.error(`Error during transport.onclose cleanup for session ${sessionId}`, err, closeContext));
+            }
+        };
+        await server.connect(transport);
+        logger.debug("Server connected to transport, handling initial request.", opContext);
+        const mockReq = {
+            headers,
+            method: "POST",
+            url: config.mcpHttpEndpointPath,
+        };
+        await transport.handleRequest(mockReq, mockRes, body);
+        const responseHeaders = new Headers();
+        for (const [key, value] of Object.entries(mockRes.getHeaders())) {
+            responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+        }
+        if (transport.sessionId) {
+            responseHeaders.set("Mcp-Session-Id", transport.sessionId);
+        }
+        const webStream = Readable.toWeb(mockRes);
+        return {
+            headers: responseHeaders,
+            statusCode: mockRes.statusCode,
+            stream: webStream,
+            sessionId: transport.sessionId,
+        };
+    }
+    async handleRequest(headers, body, context, sessionId) {
+        if (!sessionId) {
+            throw new McpError(BaseErrorCode.INVALID_INPUT, "Session ID is required for stateful requests.", context);
+        }
+        const sessionContext = {
+            ...context,
+            sessionId,
+            operation: "StatefulTransportManager.handleRequest",
+        };
+        logger.debug(`Handling request for session: ${sessionId}`, {
+            ...sessionContext,
+            method: headers["x-forwarded-proto"] || "http",
+        });
+        const transport = this.transports.get(sessionId);
+        if (!transport) {
+            logger.warning(`Request for non-existent session: ${sessionId}`, sessionContext);
+            return {
+                headers: new Headers({ "Content-Type": "application/json" }),
+                statusCode: 404,
+                body: {
+                    jsonrpc: "2.0",
+                    error: { code: -32601, message: "Session not found" },
+                },
+            };
+        }
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.lastAccessedAt = new Date();
+            logger.debug(`Updated lastAccessedAt for session ${sessionId}.`, sessionContext);
+        }
+        const mockReq = {
+            headers,
+            method: "POST",
+        };
+        const mockRes = new HonoStreamResponse();
+        await transport.handleRequest(mockReq, mockRes, body);
+        const responseHeaders = new Headers();
+        for (const [key, value] of Object.entries(mockRes.getHeaders())) {
+            responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+        }
+        const webStream = Readable.toWeb(mockRes);
+        return {
+            headers: responseHeaders,
+            statusCode: mockRes.statusCode,
+            stream: webStream,
+            sessionId: transport.sessionId,
+        };
+    }
+    async handleDeleteRequest(sessionId, context) {
+        const sessionContext = {
+            ...context,
+            sessionId,
+            operation: "StatefulTransportManager.handleDeleteRequest",
+        };
+        logger.info(`Attempting to delete session: ${sessionId}`, sessionContext);
+        const transport = this.transports.get(sessionId);
+        if (!transport) {
+            logger.warning(`Attempted to delete non-existent session: ${sessionId}`, sessionContext);
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.", sessionContext);
+        }
+        await this.closeSession(sessionId, sessionContext);
+        const headers = new Headers();
+        headers.set("Content-Type", "application/json");
+        return {
+            headers,
+            statusCode: 200,
+            body: { status: "session_closed", sessionId },
+        };
+    }
+    getSession(sessionId) {
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.getSession",
+            sessionId,
+        });
+        logger.debug(`Retrieving session: ${sessionId}`, context);
+        return this.sessions.get(sessionId);
+    }
+    async shutdown() {
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.shutdown",
+        });
+        logger.info("Shutting down stateful transport manager...", context);
+        clearInterval(this.garbageCollector);
+        logger.debug("Garbage collector stopped.", context);
+        const sessionIds = Array.from(this.transports.keys());
+        logger.info(`Closing ${sessionIds.length} active sessions.`, context);
+        const closePromises = sessionIds.map((sessionId) => this.closeSession(sessionId, context));
+        await Promise.all(closePromises);
+        this.transports.clear();
+        this.sessions.clear();
+        this.servers.clear();
+        logger.info("All active sessions closed and manager shut down.", context);
+    }
+    async closeSession(sessionId, context) {
+        const sessionContext = {
+            ...context,
+            sessionId,
+            operation: "StatefulTransportManager.closeSession",
+        };
+        logger.debug(`Closing session: ${sessionId}`, sessionContext);
+        const transport = this.transports.get(sessionId);
+        const server = this.servers.get(sessionId);
+        await ErrorHandler.tryCatch(async () => {
+            if (transport) {
+                await transport.close();
+                logger.debug(`Transport closed for session ${sessionId}.`, sessionContext);
+            }
+            if (server) {
+                await server.close();
+                logger.debug(`Server instance closed for session ${sessionId}.`, sessionContext);
+            }
+        }, {
+            operation: "closeSession.cleanup",
+            context: sessionContext,
+        });
+        this.transports.delete(sessionId);
+        this.servers.delete(sessionId);
+        this.sessions.delete(sessionId);
+        logger.info(`MCP Session closed and resources released: ${sessionId}`, sessionContext);
+    }
+    async cleanupStaleSessions() {
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.cleanupStaleSessions",
+        });
+        logger.debug("Running stale session cleanup...", context);
+        const now = Date.now();
+        const STALE_TIMEOUT_MS = config.mcpStatefulSessionStaleTimeoutMs;
+        let staleCount = 0;
+        for (const [sessionId, session] of this.sessions.entries()) {
+            if (now - session.lastAccessedAt.getTime() > STALE_TIMEOUT_MS) {
+                staleCount++;
+                const sessionContext = {
+                    ...context,
+                    sessionId,
+                    lastAccessed: session.lastAccessedAt.toISOString(),
+                };
+                logger.info(`Found stale session, closing: ${sessionId}`, sessionContext);
+                await this.closeSession(sessionId, sessionContext);
+            }
+        }
+        if (staleCount > 0) {
+            logger.info(`Stale session cleanup complete. Closed ${staleCount} sessions.`, context);
+        }
+        else {
+            logger.debug("No stale sessions found.", context);
+        }
+    }
+}

package/dist/mcp-server/transports/core/statelessTransportManager.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Stateless Transport Manager implementation for MCP SDK.
+ * This manager handles single-request operations without maintaining sessions.
+ * Each request creates a temporary server instance that is cleaned up immediately.
+ * This version is adapted for Hono by bridging the SDK's Node.js-style
+ * request handling with Hono's stream-based response model.
+ * @module src/mcp-server/transports/core/statelessTransportManager
+ */
+import type { IncomingHttpHeaders } from "http";
+import { RequestContext } from "../../../utils/index.js";
+import { BaseTransportManager } from "./baseTransportManager.js";
+import { TransportResponse } from "./transportTypes.js";
+/**
+ * Stateless Transport Manager that handles ephemeral MCP operations.
+ */
+export declare class StatelessTransportManager extends BaseTransportManager {
+    handleRequest(headers: IncomingHttpHeaders, body: unknown, context: RequestContext): Promise<TransportResponse>;
+    shutdown(): Promise<void>;
+    private cleanup;
+}

package/dist/mcp-server/transports/core/statelessTransportManager.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Stateless Transport Manager implementation for MCP SDK.
+ * This manager handles single-request operations without maintaining sessions.
+ * Each request creates a temporary server instance that is cleaned up immediately.
+ * This version is adapted for Hono by bridging the SDK's Node.js-style
+ * request handling with Hono's stream-based response model.
+ * @module src/mcp-server/transports/core/statelessTransportManager
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { Readable } from "stream";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { BaseTransportManager } from "./baseTransportManager.js";
+import { HonoStreamResponse } from "./honoNodeBridge.js";
+/**
+ * Stateless Transport Manager that handles ephemeral MCP operations.
+ */
+export class StatelessTransportManager extends BaseTransportManager {
+    async handleRequest(headers, body, context) {
+        const opContext = {
+            ...context,
+            operation: "StatelessTransportManager.handleRequest",
+        };
+        logger.debug("Creating ephemeral server instance for stateless request.", opContext);
+        let server;
+        let transport;
+        try {
+            server = await this.createServerInstanceFn();
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                onsessioninitialized: undefined,
+            });
+            await server.connect(transport);
+            logger.debug("Ephemeral server connected to transport.", opContext);
+            const mockReq = {
+                headers,
+                method: "POST",
+            };
+            const mockRes = new HonoStreamResponse();
+            await transport.handleRequest(mockReq, mockRes, body);
+            logger.info("Stateless request handled successfully.", opContext);
+            const responseHeaders = new Headers();
+            for (const [key, value] of Object.entries(mockRes.getHeaders())) {
+                responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+            }
+            // Bridge the Node.js stream (PassThrough) to a Web Stream (ReadableStream)
+            const webStream = Readable.toWeb(mockRes);
+            return {
+                headers: responseHeaders,
+                statusCode: mockRes.statusCode,
+                stream: webStream,
+            };
+        }
+        catch (error) {
+            throw ErrorHandler.handleError(error, {
+                operation: "StatelessTransportManager.handleRequest",
+                context: opContext,
+                rethrow: true,
+            });
+        }
+        finally {
+            if (server || transport) {
+                this.cleanup(server, transport, opContext);
+            }
+        }
+    }
+    async shutdown() {
+        const context = requestContextService.createRequestContext({
+            operation: "StatelessTransportManager.shutdown",
+        });
+        logger.info("Stateless transport manager shutdown - no persistent resources to clean up.", context);
+        return Promise.resolve();
+    }
+    cleanup(server, transport, context) {
+        const opContext = {
+            ...context,
+            operation: "StatelessTransportManager.cleanup",
+        };
+        logger.debug("Scheduling cleanup for ephemeral resources.", opContext);
+        Promise.all([transport?.close(), server?.close()])
+            .then(() => {
+            logger.debug("Ephemeral resources cleaned up successfully.", opContext);
+        })
+            .catch((cleanupError) => {
+            logger.warning("Error during stateless resource cleanup.", {
+                ...opContext,
+                error: cleanupError instanceof Error
+                    ? cleanupError.message
+                    : String(cleanupError),
+            });
+        });
+    }
+}

package/dist/mcp-server/transports/core/transportTypes.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Core types and interfaces for the transport layer abstraction.
+ * @module src/mcp-server/transports/core/transportTypes
+ */
+import type { IncomingHttpHeaders } from "http";
+import { RequestContext } from "../../../utils/index.js";
+/**
+ * Valid HTTP status codes for transport responses.
+ */
+export type HttpStatusCode = 200 | 201 | 400 | 401 | 403 | 404 | 409 | 429 | 500 | 502 | 503;
+/**
+ * Represents the result of a transport operation.
+ */
+export interface TransportResponse {
+    sessionId?: string;
+    headers: Headers;
+    statusCode: HttpStatusCode;
+    body?: unknown;
+    stream?: ReadableStream<Uint8Array>;
+}
+/**
+ * Represents an active transport session.
+ */
+export interface TransportSession {
+    id: string;
+    createdAt: Date;
+    lastAccessedAt: Date;
+}
+/**
+ * Abstract interface for managing MCP transport operations.
+ * This interface separates transport logic from HTTP routing concerns.
+ */
+export interface TransportManager {
+    /**
+     * Handles an incoming request.
+     * @param headers The request headers.
+     * @param body The parsed body of the request.
+     * @param context Request context for logging and tracing.
+     * @param sessionId Optional session identifier for stateful operations.
+     * @returns A promise resolving to a TransportResponse.
+     */
+    handleRequest(headers: IncomingHttpHeaders, body: unknown, context: RequestContext, sessionId?: string): Promise<TransportResponse>;
+    /**
+     * Clean up resources.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Extends the base TransportManager with session-specific operations.
+ */
+export interface StatefulTransportManager extends TransportManager {
+    /**
+     * Initializes a new session and handles the request.
+     * @param headers The request headers.
+     * @param body The parsed body of the request.
+     * @param context Request context for logging and tracing.
+     * @returns A promise resolving to a TransportResponse.
+     */
+    initializeAndHandle(headers: IncomingHttpHeaders, body: unknown, context: RequestContext): Promise<TransportResponse>;
+    /**
+     * Handles a DELETE request to close a session.
+     */
+    handleDeleteRequest(sessionId: string, context: RequestContext): Promise<TransportResponse>;
+    /**
+     * Retrieves session information.
+     */
+    getSession(sessionId: string): TransportSession | undefined;
+}

package/dist/mcp-server/transports/core/transportTypes.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Core types and interfaces for the transport layer abstraction.
+ * @module src/mcp-server/transports/core/transportTypes
+ */
+export {};

package/dist/mcp-server/transports/{httpErrorHandler.d.ts → http/httpErrorHandler.d.ts}

@@ -6,7 +6,7 @@
  * @module src/mcp-server/transports/httpErrorHandler
  */
 import { Context } from "hono";
-import { BaseErrorCode } from "../../types-global/errors.js";
+import { HonoNodeBindings } from "./httpTypes.js";
 /**
  * A centralized error handling middleware for Hono.
  * This function is registered with `app.onError()` and will catch any errors
@@ -16,11 +16,6 @@ import { BaseErrorCode } from "../../types-global/errors.js";
  * @param c - The Hono context object for the request.
  * @returns A Response object containing the formatted JSON-RPC error.
  */
-export declare const httpErrorHandler: (err: Error, c: Context) => Promise<Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    error: {
-        code: number | BaseErrorCode;
-        message: string;
-    };
-    id: string | number | null;
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+export declare const httpErrorHandler: (err: Error, c: Context<{
+    Bindings: HonoNodeBindings;
+}>) => Promise<Response>;

package/dist/mcp-server/transports/{httpErrorHandler.js → http/httpErrorHandler.js}

@@ -5,8 +5,8 @@
  * formats them into a consistent JSON-RPC error response.
  * @module src/mcp-server/transports/httpErrorHandler
  */
-import { BaseErrorCode, McpError } from "../../types-global/errors.js";
-import { ErrorHandler, requestContextService } from "../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 /**
  * A centralized error handling middleware for Hono.
  * This function is registered with `app.onError()` and will catch any errors
@@ -22,6 +22,7 @@ export const httpErrorHandler = async (err, c) => {
         path: c.req.path,
         method: c.req.method,
     });
+    logger.debug("HTTP error handler invoked.", context);
     const handledError = ErrorHandler.handleError(err, {
         operation: "httpTransport",
         context,
@@ -39,6 +40,7 @@ export const httpErrorHandler = async (err, c) => {
                 status = 403;
                 break;
             case BaseErrorCode.VALIDATION_ERROR:
+            case BaseErrorCode.INVALID_INPUT:
                 status = 400;
                 break;
             case BaseErrorCode.CONFLICT:
@@ -51,23 +53,46 @@ export const httpErrorHandler = async (err, c) => {
                 status = 500;
         }
     }
+    logger.debug(`Mapping error to HTTP status ${status}.`, {
+        ...context,
+        status,
+        errorCode: handledError.code,
+    });
     // Attempt to get the request ID from the body, but don't fail if it's not there or unreadable.
     let requestId = null;
-    try {
-        const body = await c.req.json();
-        requestId = body?.id || null;
+    // Only attempt to read the body if it hasn't been consumed already.
+    if (c.req.raw.bodyUsed === false) {
+        try {
+            const body = await c.req.json();
+            requestId = body?.id || null;
+            logger.debug("Extracted JSON-RPC request ID from body.", {
+                ...context,
+                jsonRpcId: requestId,
+            });
+        }
+        catch {
+            logger.warning("Could not parse request body to extract JSON-RPC ID.", context);
+            // Ignore parsing errors, requestId will remain null
+        }
     }
-    catch {
-        // Ignore parsing errors, requestId will remain null
+    else {
+        logger.debug("Request body already consumed, cannot extract JSON-RPC ID.", context);
     }
     const errorCode = handledError instanceof McpError ? handledError.code : -32603;
     c.status(status);
-    return c.json({
+    const errorResponse = {
         jsonrpc: "2.0",
         error: {
             code: errorCode,
             message: handledError.message,
         },
         id: requestId,
+    };
+    logger.info(`Sending formatted error response for request.`, {
+        ...context,
+        status,
+        errorCode,
+        jsonRpcId: requestId,
     });
+    return c.json(errorResponse);
 };

package/dist/mcp-server/transports/http/httpTransport.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Configures and starts the HTTP MCP transport using Hono.
+ * This file has been refactored to correctly integrate Hono's streaming
+ * capabilities with the Model Context Protocol SDK's transport layer.
+ * @module src/mcp-server/transports/http/httpTransport
+ */
+import { ServerType } from "@hono/node-server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Hono } from "hono";
+import { RequestContext } from "../../../utils/index.js";
+import { TransportManager } from "../core/transportTypes.js";
+import { HonoNodeBindings } from "./httpTypes.js";
+export declare function createHttpApp(transportManager: TransportManager, createServerInstanceFn: () => Promise<McpServer>, parentContext: RequestContext): Hono<{
+    Bindings: HonoNodeBindings;
+}>;
+export declare function startHttpTransport(createServerInstanceFn: () => Promise<McpServer>, parentContext: RequestContext): Promise<{
+    app: Hono<{
+        Bindings: HonoNodeBindings;
+    }>;
+    server: ServerType;
+    transportManager: TransportManager;
+}>;