@cyanheads/pubmed-mcp-server 1.2.3 → 1.3.0

package/dist/mcp-server/transports/auth/authMiddleware.js

@@ -0,0 +1,57 @@
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { authContext } from "./lib/authContext.js";
+/**
+ * Creates a Hono middleware function that enforces authentication using a given strategy.
+ *
+ * @param strategy - An instance of a class that implements the `AuthStrategy` interface.
+ * @returns A Hono middleware function.
+ */
+export function createAuthMiddleware(strategy) {
+    return async function authMiddleware(c, next) {
+        const context = requestContextService.createRequestContext({
+            operation: "authMiddleware",
+            method: c.req.method,
+            path: c.req.path,
+        });
+        logger.debug("Initiating authentication check.", context);
+        const authHeader = c.req.header("Authorization");
+        if (!authHeader || !authHeader.startsWith("Bearer ")) {
+            logger.warning("Authorization header missing or invalid.", context);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid Authorization header. Bearer scheme required.", context);
+        }
+        const token = authHeader.substring(7);
+        if (!token) {
+            logger.warning("Bearer token is missing from Authorization header.", context);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Authentication token is missing.", context);
+        }
+        logger.debug("Extracted Bearer token, proceeding to verification.", context);
+        try {
+            const authInfo = await strategy.verify(token);
+            const authLogContext = {
+                ...context,
+                clientId: authInfo.clientId,
+                subject: authInfo.subject,
+                scopes: authInfo.scopes,
+            };
+            logger.info("Authentication successful. Auth context populated.", authLogContext);
+            // Run the next middleware in the chain within the populated auth context.
+            await authContext.run({ authInfo }, next);
+        }
+        catch (error) {
+            // The strategy is expected to throw an McpError.
+            // We re-throw it here to be caught by the global httpErrorHandler.
+            logger.warning("Authentication verification failed.", {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Ensure consistent error handling
+            throw ErrorHandler.handleError(error, {
+                operation: "authMiddlewareVerification",
+                context,
+                rethrow: true, // Rethrow to be caught by Hono's global error handler
+                errorCode: BaseErrorCode.UNAUTHORIZED, // Default to unauthorized if not more specific
+            });
+        }
+    };
+}

package/dist/mcp-server/transports/auth/index.d.ts

@@ -3,8 +3,11 @@
  * Exports core utilities and middleware strategies for easier imports.
  * @module src/mcp-server/transports/auth/index
  */
-export { authContext } from "./core/authContext.js";
-export { withRequiredScopes } from "./core/authUtils.js";
-export type { AuthInfo } from "./core/authTypes.js";
-export { mcpAuthMiddleware as jwtAuthMiddleware } from "./strategies/jwt/jwtMiddleware.js";
-export { oauthMiddleware } from "./strategies/oauth/oauthMiddleware.js";
+export { authContext } from "./lib/authContext.js";
+export { withRequiredScopes } from "./lib/authUtils.js";
+export type { AuthInfo } from "./lib/authTypes.js";
+export { createAuthStrategy } from "./authFactory.js";
+export { createAuthMiddleware } from "./authMiddleware.js";
+export { AuthStrategy } from "./strategies/authStrategy.js";
+export { JwtStrategy } from "./strategies/jwtStrategy.js";
+export { OauthStrategy } from "./strategies/oauthStrategy.js";

package/dist/mcp-server/transports/auth/index.js

@@ -3,7 +3,9 @@
  * Exports core utilities and middleware strategies for easier imports.
  * @module src/mcp-server/transports/auth/index
  */
-export { authContext } from "./core/authContext.js";
-export { withRequiredScopes } from "./core/authUtils.js";
-export { mcpAuthMiddleware as jwtAuthMiddleware } from "./strategies/jwt/jwtMiddleware.js";
-export { oauthMiddleware } from "./strategies/oauth/oauthMiddleware.js";
+export { authContext } from "./lib/authContext.js";
+export { withRequiredScopes } from "./lib/authUtils.js";
+export { createAuthStrategy } from "./authFactory.js";
+export { createAuthMiddleware } from "./authMiddleware.js";
+export { JwtStrategy } from "./strategies/jwtStrategy.js";
+export { OauthStrategy } from "./strategies/oauthStrategy.js";

package/dist/mcp-server/transports/auth/{core → lib}/authTypes.d.ts

@@ -10,8 +10,3 @@ import type { AuthInfo as SdkAuthInfo } from "@modelcontextprotocol/sdk/server/a
 export type AuthInfo = SdkAuthInfo & {
     subject?: string;
 };
-declare module "http" {
-    interface IncomingMessage {
-        auth?: AuthInfo;
-    }
-}

package/dist/mcp-server/transports/auth/lib/authTypes.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Shared types for authentication middleware.
+ * @module src/mcp-server/transports/auth/core/auth.types
+ */
+export {};
+// The declaration for `http.IncomingMessage` is no longer needed here,
+// as the new architecture avoids direct mutation where possible and handles
+// the attachment within the Hono context.

package/dist/mcp-server/transports/auth/{core → lib}/authUtils.js

@@ -19,27 +19,34 @@ import { authContext } from "./authContext.js";
  *   more required scopes are not present in the validated token.
  */
 export function withRequiredScopes(requiredScopes) {
+    const operationName = "withRequiredScopesCheck";
+    const initialContext = requestContextService.createRequestContext({
+        operation: operationName,
+        requiredScopes,
+    });
+    logger.debug("Performing scope authorization check.", initialContext);
     const store = authContext.getStore();
     if (!store || !store.authInfo) {
+        logger.crit("Authentication context is missing in withRequiredScopes. This is a server configuration error.", initialContext);
         // This is a server-side logic error; the auth middleware should always populate this.
-        throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Authentication context is missing. This indicates a server configuration error.", requestContextService.createRequestContext({
-            operation: "withRequiredScopesCheck",
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Authentication context is missing. This indicates a server configuration error.", {
+            ...initialContext,
             error: "AuthStore not found in AsyncLocalStorage.",
-        }));
+        });
     }
-    const { scopes: grantedScopes, clientId } = store.authInfo;
+    const { scopes: grantedScopes, clientId, subject } = store.authInfo;
     const grantedScopeSet = new Set(grantedScopes);
     const missingScopes = requiredScopes.filter((scope) => !grantedScopeSet.has(scope));
+    const finalContext = {
+        ...initialContext,
+        grantedScopes,
+        clientId,
+        subject,
+    };
     if (missingScopes.length > 0) {
-        const context = requestContextService.createRequestContext({
-            operation: "withRequiredScopesCheck",
-            required: requiredScopes,
-            granted: grantedScopes,
-            missing: missingScopes,
-            clientId: clientId,
-            subject: store.authInfo.subject,
-        });
-        logger.warning("Authorization failed: Missing required scopes.", context);
-        throw new McpError(BaseErrorCode.FORBIDDEN, `Insufficient permissions. Missing required scopes: ${missingScopes.join(", ")}`, { requiredScopes, missingScopes });
+        const errorContext = { ...finalContext, missingScopes };
+        logger.warning("Authorization failed: Missing required scopes.", errorContext);
+        throw new McpError(BaseErrorCode.FORBIDDEN, `Insufficient permissions. Missing required scopes: ${missingScopes.join(", ")}`, errorContext);
     }
+    logger.debug("Scope authorization successful.", finalContext);
 }

package/dist/mcp-server/transports/auth/strategies/authStrategy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Defines the interface for all authentication strategies.
+ * This interface establishes a contract for verifying authentication tokens,
+ * ensuring that any authentication method (JWT, OAuth, etc.) can be used
+ * interchangeably by the core authentication middleware.
+ * @module src/mcp-server/transports/auth/strategies/AuthStrategy
+ */
+import type { AuthInfo } from "../lib/authTypes.js";
+export interface AuthStrategy {
+    /**
+     * Verifies an authentication token.
+     * @param token The raw token string extracted from the request.
+     * @returns A promise that resolves with the AuthInfo on successful verification.
+     * @throws {McpError} if the token is invalid, expired, or fails verification for any reason.
+     */
+    verify(token: string): Promise<AuthInfo>;
+}

package/dist/mcp-server/transports/auth/strategies/authStrategy.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp-server/transports/auth/strategies/jwtStrategy.d.ts

@@ -0,0 +1,7 @@
+import type { AuthInfo } from "../lib/authTypes.js";
+import type { AuthStrategy } from "./authStrategy.js";
+export declare class JwtStrategy implements AuthStrategy {
+    private readonly secretKey;
+    constructor();
+    verify(token: string): Promise<AuthInfo>;
+}

package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Implements the JWT authentication strategy.
+ * This module provides a concrete implementation of the AuthStrategy for validating
+ * JSON Web Tokens (JWTs). It encapsulates all logic related to JWT verification,
+ * including secret key management and payload validation.
+ * @module src/mcp-server/transports/auth/strategies/JwtStrategy
+ */
+import { jwtVerify } from "jose";
+import { config, environment } from "../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../../utils/index.js";
+export class JwtStrategy {
+    constructor() {
+        const context = requestContextService.createRequestContext({
+            operation: "JwtStrategy.constructor",
+        });
+        logger.debug("Initializing JwtStrategy...", context);
+        if (config.mcpAuthMode === "jwt") {
+            if (environment === "production" && !config.mcpAuthSecretKey) {
+                logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production for JWT auth.", context);
+                throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "MCP_AUTH_SECRET_KEY must be set for JWT auth in production.", context);
+            }
+            else if (!config.mcpAuthSecretKey) {
+                logger.warning("MCP_AUTH_SECRET_KEY is not set. JWT auth will be bypassed (DEV ONLY).", context);
+                this.secretKey = null;
+            }
+            else {
+                logger.info("JWT secret key loaded successfully.", context);
+                this.secretKey = new TextEncoder().encode(config.mcpAuthSecretKey);
+            }
+        }
+        else {
+            this.secretKey = null;
+        }
+    }
+    async verify(token) {
+        const context = requestContextService.createRequestContext({
+            operation: "JwtStrategy.verify",
+        });
+        logger.debug("Attempting to verify JWT.", context);
+        // Handle development mode bypass
+        if (!this.secretKey) {
+            if (environment !== "production") {
+                logger.warning("Bypassing JWT verification: No secret key (DEV ONLY).", context);
+                return {
+                    token: "dev-mode-placeholder-token",
+                    clientId: config.devMcpClientId || "dev-client-id",
+                    scopes: config.devMcpScopes || ["dev-scope"],
+                };
+            }
+            // This path is defensive. The constructor should prevent this state in production.
+            logger.crit("Auth secret key is missing in production.", context);
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "Auth secret key is missing in production. This indicates a server configuration error.", context);
+        }
+        try {
+            const { payload: decoded } = await jwtVerify(token, this.secretKey);
+            logger.debug("JWT signature verified successfully.", {
+                ...context,
+                claims: decoded,
+            });
+            const clientId = typeof decoded.cid === "string"
+                ? decoded.cid
+                : typeof decoded.client_id === "string"
+                    ? decoded.client_id
+                    : undefined;
+            if (!clientId) {
+                logger.warning("Invalid token: missing 'cid' or 'client_id' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token: missing 'cid' or 'client_id' claim.", context);
+            }
+            let scopes = [];
+            if (Array.isArray(decoded.scp) &&
+                decoded.scp.every((s) => typeof s === "string")) {
+                scopes = decoded.scp;
+            }
+            else if (typeof decoded.scope === "string" && decoded.scope.trim()) {
+                scopes = decoded.scope.split(" ").filter(Boolean);
+            }
+            if (scopes.length === 0) {
+                logger.warning("Invalid token: missing or empty 'scp' or 'scope' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.", context);
+            }
+            const authInfo = {
+                token,
+                clientId,
+                scopes,
+                subject: decoded.sub,
+            };
+            logger.info("JWT verification successful.", {
+                ...context,
+                clientId,
+                scopes,
+            });
+            return authInfo;
+        }
+        catch (error) {
+            const message = error instanceof Error && error.name === "JWTExpired"
+                ? "Token has expired."
+                : "Token verification failed.";
+            logger.warning(`JWT verification failed: ${message}`, {
+                ...context,
+                errorName: error instanceof Error ? error.name : "Unknown",
+            });
+            throw ErrorHandler.handleError(error, {
+                operation: "JwtStrategy.verify",
+                context,
+                rethrow: true,
+                errorCode: BaseErrorCode.UNAUTHORIZED,
+                errorMapper: () => new McpError(BaseErrorCode.UNAUTHORIZED, message, context),
+            });
+        }
+    }
+}

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts

@@ -0,0 +1,7 @@
+import type { AuthInfo } from "../lib/authTypes.js";
+import type { AuthStrategy } from "./authStrategy.js";
+export declare class OauthStrategy implements AuthStrategy {
+    private readonly jwks;
+    constructor();
+    verify(token: string): Promise<AuthInfo>;
+}

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Implements the OAuth 2.1 authentication strategy.
+ * This module provides a concrete implementation of the AuthStrategy for validating
+ * JWTs against a remote JSON Web Key Set (JWKS), as is common in OAuth 2.1 flows.
+ * @module src/mcp-server/transports/auth/strategies/OauthStrategy
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { config } from "../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../../utils/index.js";
+export class OauthStrategy {
+    constructor() {
+        const context = requestContextService.createRequestContext({
+            operation: "OauthStrategy.constructor",
+        });
+        logger.debug("Initializing OauthStrategy...", context);
+        if (config.mcpAuthMode !== "oauth") {
+            // This check is for internal consistency, so a standard Error is acceptable here.
+            throw new Error("OauthStrategy instantiated for non-oauth auth mode.");
+        }
+        if (!config.oauthIssuerUrl || !config.oauthAudience) {
+            logger.fatal("CRITICAL: OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.", context);
+            // This is a user-facing configuration error, so McpError is appropriate.
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.", context);
+        }
+        try {
+            const jwksUrl = new URL(config.oauthJwksUri ||
+                `${config.oauthIssuerUrl.replace(/\/$/, "")}/.well-known/jwks.json`);
+            this.jwks = createRemoteJWKSet(jwksUrl, {
+                cooldownDuration: 300000, // 5 minutes
+                timeoutDuration: 5000, // 5 seconds
+            });
+            logger.info(`JWKS client initialized for URL: ${jwksUrl.href}`, context);
+        }
+        catch (error) {
+            logger.fatal("Failed to initialize JWKS client.", {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // This is a critical startup failure, so a specific McpError is warranted.
+            throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, "Could not initialize JWKS client for OAuth strategy.", {
+                ...context,
+                originalError: error instanceof Error ? error.message : "Unknown",
+            });
+        }
+    }
+    async verify(token) {
+        const context = requestContextService.createRequestContext({
+            operation: "OauthStrategy.verify",
+        });
+        logger.debug("Attempting to verify OAuth token via JWKS.", context);
+        try {
+            const { payload } = await jwtVerify(token, this.jwks, {
+                issuer: config.oauthIssuerUrl,
+                audience: config.oauthAudience,
+            });
+            logger.debug("OAuth token signature verified successfully.", {
+                ...context,
+                claims: payload,
+            });
+            const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+            if (scopes.length === 0) {
+                logger.warning("Invalid token: missing or empty 'scope' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.", context);
+            }
+            const clientId = typeof payload.client_id === "string" ? payload.client_id : undefined;
+            if (!clientId) {
+                logger.warning("Invalid token: missing 'client_id' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain a 'client_id' claim.", context);
+            }
+            const authInfo = {
+                token,
+                clientId,
+                scopes,
+                subject: typeof payload.sub === "string" ? payload.sub : undefined,
+            };
+            logger.info("OAuth token verification successful.", {
+                ...context,
+                clientId,
+                scopes,
+            });
+            return authInfo;
+        }
+        catch (error) {
+            const message = error instanceof Error && error.name === "JWTExpired"
+                ? "Token has expired."
+                : "OAuth token verification failed.";
+            logger.warning(`OAuth token verification failed: ${message}`, {
+                ...context,
+                errorName: error instanceof Error ? error.name : "Unknown",
+            });
+            throw ErrorHandler.handleError(error, {
+                operation: "OauthStrategy.verify",
+                context,
+                rethrow: true,
+                errorCode: BaseErrorCode.UNAUTHORIZED,
+                errorMapper: () => new McpError(BaseErrorCode.UNAUTHORIZED, message, context),
+            });
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Abstract base class for transport managers.
+ * @module src/mcp-server/transports/core/baseTransportManager
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IncomingHttpHeaders } from "http";
+import { RequestContext } from "../../../utils/index.js";
+import { TransportManager, TransportResponse } from "./transportTypes.js";
+/**
+ * Abstract base class for transport managers, providing common functionality.
+ */
+export declare abstract class BaseTransportManager implements TransportManager {
+    protected readonly createServerInstanceFn: () => Promise<McpServer>;
+    constructor(createServerInstanceFn: () => Promise<McpServer>);
+    abstract handleRequest(headers: IncomingHttpHeaders, body: unknown, context: RequestContext, sessionId?: string): Promise<TransportResponse>;
+    abstract shutdown(): Promise<void>;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Abstract base class for transport managers.
+ * @module src/mcp-server/transports/core/baseTransportManager
+ */
+import { logger, requestContextService, } from "../../../utils/index.js";
+/**
+ * Abstract base class for transport managers, providing common functionality.
+ */
+export class BaseTransportManager {
+    constructor(createServerInstanceFn) {
+        const context = requestContextService.createRequestContext({
+            operation: "BaseTransportManager.constructor",
+            managerType: this.constructor.name,
+        });
+        logger.debug("Initializing transport manager.", context);
+        this.createServerInstanceFn = createServerInstanceFn;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Provides a bridge between the MCP SDK's Node.js-style
+ * streamable HTTP transport and Hono's Web Standards-based streaming response.
+ * @module src/mcp-server/transports/core/honoNodeBridge
+ */
+import { PassThrough } from "stream";
+/**
+ * A mock ServerResponse that pipes writes to a PassThrough stream.
+ * This is the bridge between Model Context Protocol's SDK's Node.js-style response handling
+ * and Hono's stream-based body. It captures status and headers.
+ */
+export declare class HonoStreamResponse extends PassThrough {
+    statusCode: number;
+    headers: Record<string, string | number | string[]>;
+    constructor();
+    writeHead(statusCode: number, headers?: Record<string, string | number | string[]>): this;
+    setHeader(name: string, value: string | number | string[]): this;
+    getHeader(name: string): string | number | string[] | undefined;
+    getHeaders(): Record<string, string | number | string[]>;
+    removeHeader(name: string): void;
+    write(chunk: unknown, encodingOrCallback?: BufferEncoding | ((error: Error | null | undefined) => void), callback?: (error: Error | null | undefined) => void): boolean;
+    end(chunk?: unknown, encodingOrCallback?: BufferEncoding | (() => void), callback?: () => void): this;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Provides a bridge between the MCP SDK's Node.js-style
+ * streamable HTTP transport and Hono's Web Standards-based streaming response.
+ * @module src/mcp-server/transports/core/honoNodeBridge
+ */
+import { PassThrough } from "stream";
+/**
+ * A mock ServerResponse that pipes writes to a PassThrough stream.
+ * This is the bridge between Model Context Protocol's SDK's Node.js-style response handling
+ * and Hono's stream-based body. It captures status and headers.
+ */
+export class HonoStreamResponse extends PassThrough {
+    constructor() {
+        super();
+        this.statusCode = 200;
+        this.headers = {};
+    }
+    writeHead(statusCode, headers) {
+        this.statusCode = statusCode;
+        if (headers) {
+            this.headers = { ...this.headers, ...headers };
+        }
+        return this;
+    }
+    setHeader(name, value) {
+        this.headers[name.toLowerCase()] = value;
+        return this;
+    }
+    getHeader(name) {
+        return this.headers[name.toLowerCase()];
+    }
+    getHeaders() {
+        return this.headers;
+    }
+    removeHeader(name) {
+        delete this.headers[name.toLowerCase()];
+    }
+    write(chunk, encodingOrCallback, callback) {
+        const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
+        const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return super.write(chunk, encoding, cb);
+    }
+    end(chunk, encodingOrCallback, callback) {
+        const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
+        const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        super.end(chunk, encoding, cb);
+        return this;
+    }
+}

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;
+}