@cyanheads/pubmed-mcp-server 1.2.1 → 1.2.2

package/README.md

@@ -1,8 +1,8 @@
 # PubMed MCP Server
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
-[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.12.1-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-1.2.1-blue.svg)](./CHANGELOG.md)
+[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-1.2.2-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/pubmed-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/pubmed-mcp-server?style=social)](https://github.com/cyanheads/pubmed-mcp-server)
@@ -62,7 +62,7 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 - **Input Validation/Sanitization**: Uses `zod` for schema validation and custom sanitization logic.
 - **Request Context**: Tracking and correlation of operations via unique request IDs using `AsyncLocalStorage`.
 - **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.
-- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management with garbage collection, CORS, and IP-based rate limiting.
+- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management with garbage collection and CORS support.
 - **Authentication**: Robust authentication layer supporting JWT and OAuth 2.1, with fine-grained scope enforcement.
 - **Deployment**: Multi-stage `Dockerfile` for creating small, secure production images with native dependency support.
 

package/dist/mcp-server/transports/{authentication → auth/core}/authContext.d.ts

@@ -5,10 +5,10 @@
  * from the middleware layer down to the tool and resource handlers without
  * drilling props.
  *
- * @module src/mcp-server/transports/authentication/authContext
+ * @module src/mcp-server/transports/auth/core/authContext
  */
 import { AsyncLocalStorage } from "async_hooks";
-import type { AuthInfo } from "./types.js";
+import type { AuthInfo } from "./authTypes.js";
 /**
  * Defines the structure of the store used within the AsyncLocalStorage.
  * It holds the authentication information for the current request context.

package/dist/mcp-server/transports/{authentication → auth/core}/authContext.js

@@ -5,7 +5,7 @@
  * from the middleware layer down to the tool and resource handlers without
  * drilling props.
  *
- * @module src/mcp-server/transports/authentication/authContext
+ * @module src/mcp-server/transports/auth/core/authContext
  */
 import { AsyncLocalStorage } from "async_hooks";
 /**

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

@@ -1,6 +1,6 @@
 /**
  * @fileoverview Shared types for authentication middleware.
- * @module src/mcp-server/transports/authentication/types
+ * @module src/mcp-server/transports/auth/core/auth.types
  */
 import type { AuthInfo as SdkAuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
 /**

package/dist/mcp-server/transports/{authentication/types.js → auth/core/authTypes.js}

@@ -1,5 +1,5 @@
 /**
  * @fileoverview Shared types for authentication middleware.
- * @module src/mcp-server/transports/authentication/types
+ * @module src/mcp-server/transports/auth/core/auth.types
  */
 export {};

package/dist/mcp-server/transports/{authentication → auth/core}/authUtils.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Provides utility functions for authorization, specifically for
  * checking token scopes against required permissions for a given operation.
- * @module src/mcp-server/transports/authentication/authUtils
+ * @module src/mcp-server/transports/auth/core/authUtils
  */
 /**
  * Checks if the current authentication context contains all the specified scopes.

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

@@ -1,10 +1,10 @@
 /**
  * @fileoverview Provides utility functions for authorization, specifically for
  * checking token scopes against required permissions for a given operation.
- * @module src/mcp-server/transports/authentication/authUtils
+ * @module src/mcp-server/transports/auth/core/authUtils
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { logger, requestContextService } from "../../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { logger, requestContextService } from "../../../../utils/index.js";
 import { authContext } from "./authContext.js";
 /**
  * Checks if the current authentication context contains all the specified scopes.

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

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Barrel file for the auth module.
+ * 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";

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel file for the auth module.
+ * 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";

package/dist/mcp-server/transports/{authentication/authMiddleware.d.ts → auth/strategies/jwt/jwtMiddleware.d.ts}

@@ -10,26 +10,18 @@
  * is attached to `c.env.incoming.auth`. This direct attachment to the raw Node.js
  * request object is for compatibility with the underlying SDK transport, which is
  * not Hono-context-aware.
- * If the token is missing, invalid, or expired, it returns an HTTP 401 Unauthorized response.
+ * If the token is missing, invalid, or expired, it throws an `McpError`, which is
+ * then handled by the centralized `httpErrorHandler`.
  *
  * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
- * @module src/mcp-server/transports/authentication/authMiddleware
+ * @module src/mcp-server/transports/auth/strategies/jwt/jwtMiddleware
  */
 import { HttpBindings } from "@hono/node-server";
 import { Context, Next } from "hono";
-/**
- * Validates the presence of the MCP_AUTH_SECRET_KEY at startup.
- * This should be called once when the application is initializing.
- */
-export declare function initializeAuthMiddleware(): void;
 /**
  * Hono middleware for verifying JWT Bearer token authentication.
  * It attaches authentication info to `c.env.incoming.auth` for SDK compatibility with the node server.
  */
 export declare function mcpAuthMiddleware(c: Context<{
     Bindings: HttpBindings;
-}>, next: Next): Promise<void | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 500, "json">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 401, "json">)>;
+}>, next: Next): Promise<void>;

package/dist/mcp-server/transports/{authentication/authMiddleware.js → auth/strategies/jwt/jwtMiddleware.js}

@@ -10,32 +10,25 @@
  * is attached to `c.env.incoming.auth`. This direct attachment to the raw Node.js
  * request object is for compatibility with the underlying SDK transport, which is
  * not Hono-context-aware.
- * If the token is missing, invalid, or expired, it returns an HTTP 401 Unauthorized response.
+ * If the token is missing, invalid, or expired, it throws an `McpError`, which is
+ * then handled by the centralized `httpErrorHandler`.
  *
  * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
- * @module src/mcp-server/transports/authentication/authMiddleware
+ * @module src/mcp-server/transports/auth/strategies/jwt/jwtMiddleware
  */
-import jwt from "jsonwebtoken";
-import { config, environment } from "../../../config/index.js";
-import { logger, requestContextService } from "../../../utils/index.js";
-import { authContext } from "./authContext.js";
-/**
- * Validates the presence of the MCP_AUTH_SECRET_KEY at startup.
- * This should be called once when the application is initializing.
- */
-export function initializeAuthMiddleware() {
-    const context = requestContextService.createRequestContext({
-        operation: "initializeAuthMiddleware",
-    });
+import { jwtVerify } from "jose";
+import { config, environment } from "../../../../../config/index.js";
+import { logger, requestContextService } from "../../../../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../../../types-global/errors.js";
+import { authContext } from "../../core/authContext.js";
+// Startup Validation: Validate secret key presence on module load.
+if (config.mcpAuthMode === "jwt") {
     if (environment === "production" && !config.mcpAuthSecretKey) {
-        logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment. Authentication cannot proceed securely.", context);
+        logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment for JWT auth. Authentication cannot proceed securely.");
         throw new Error("MCP_AUTH_SECRET_KEY must be set in production environment for JWT authentication.");
     }
     else if (!config.mcpAuthSecretKey) {
-        logger.warning("MCP_AUTH_SECRET_KEY is not set. Authentication middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.", context);
-    }
-    else {
-        logger.debug("Auth middleware secret key check passed.", context);
+        logger.warning("MCP_AUTH_SECRET_KEY is not set. JWT auth middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.");
     }
 }
 /**
@@ -50,6 +43,10 @@ export async function mcpAuthMiddleware(c, next) {
     });
     logger.debug("Running MCP Authentication Middleware (Bearer Token Validation)...", context);
     const reqWithAuth = c.env.incoming;
+    // If JWT auth is not enabled, skip the middleware.
+    if (config.mcpAuthMode !== "jwt") {
+        return await next();
+    }
     // Development Mode Bypass
     if (!config.mcpAuthSecretKey) {
         if (environment !== "production") {
@@ -68,28 +65,23 @@ export async function mcpAuthMiddleware(c, next) {
         }
         else {
             logger.error("FATAL: MCP_AUTH_SECRET_KEY is missing in production. Cannot bypass auth.", context);
-            return c.json({ error: "Server configuration error: Authentication key missing." }, 500);
+            throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Server configuration error: Authentication key missing.");
         }
     }
+    const secretKey = new TextEncoder().encode(config.mcpAuthSecretKey);
     const authHeader = c.req.header("Authorization");
     if (!authHeader || !authHeader.startsWith("Bearer ")) {
         logger.warning("Authentication failed: Missing or malformed Authorization header (Bearer scheme required).", context);
-        return c.json({
-            error: "Unauthorized: Missing or invalid authentication token format.",
-        }, 401);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid authentication token format.");
     }
     const tokenParts = authHeader.split(" ");
     if (tokenParts.length !== 2 || tokenParts[0] !== "Bearer" || !tokenParts[1]) {
         logger.warning("Authentication failed: Malformed Bearer token.", context);
-        return c.json({ error: "Unauthorized: Malformed authentication token." }, 401);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Malformed authentication token.");
     }
     const rawToken = tokenParts[1];
     try {
-        const decoded = jwt.verify(rawToken, config.mcpAuthSecretKey);
-        if (typeof decoded === "string") {
-            logger.warning("Authentication failed: JWT decoded to a string, expected an object payload.", context);
-            return c.json({ error: "Unauthorized: Invalid token payload format." }, 401);
-        }
+        const { payload: decoded } = await jwtVerify(rawToken, secretKey);
         const clientIdFromToken = typeof decoded.cid === "string"
             ? decoded.cid
             : typeof decoded.client_id === "string"
@@ -97,7 +89,7 @@ export async function mcpAuthMiddleware(c, next) {
                 : undefined;
         if (!clientIdFromToken) {
             logger.warning("Authentication failed: JWT 'cid' or 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
-            return c.json({ error: "Unauthorized: Invalid token, missing client identifier." }, 401);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token, missing client identifier.");
         }
         let scopesFromToken = [];
         if (Array.isArray(decoded.scp) &&
@@ -113,7 +105,7 @@ export async function mcpAuthMiddleware(c, next) {
         }
         if (scopesFromToken.length === 0) {
             logger.warning("Authentication failed: Token resulted in an empty scope array, and scopes are required.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
-            return c.json({ error: "Unauthorized: Token must contain valid, non-empty scopes." }, 401);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.");
         }
         reqWithAuth.auth = {
             token: rawToken,
@@ -131,26 +123,27 @@ export async function mcpAuthMiddleware(c, next) {
         await authContext.run({ authInfo }, next);
     }
     catch (error) {
-        let errorMessage = "Invalid token";
-        if (error instanceof jwt.TokenExpiredError) {
-            errorMessage = "Token expired";
+        let errorMessage = "Invalid token.";
+        let errorCode = BaseErrorCode.UNAUTHORIZED;
+        if (error instanceof Error && error.name === "JWTExpired") {
+            errorMessage = "Token expired.";
             logger.warning("Authentication failed: Token expired.", {
                 ...context,
-                expiredAt: error.expiredAt,
+                errorName: error.name,
             });
         }
-        else if (error instanceof jwt.JsonWebTokenError) {
-            errorMessage = `Invalid token: ${error.message}`;
-            logger.warning(`Authentication failed: ${errorMessage}`, { ...context });
-        }
         else if (error instanceof Error) {
-            errorMessage = `Verification error: ${error.message}`;
-            logger.error("Authentication failed: Unexpected error during token verification.", { ...context, error: error.message });
+            errorMessage = `Invalid token: ${error.message}`;
+            logger.warning(`Authentication failed: ${errorMessage}`, {
+                ...context,
+                errorName: error.name,
+            });
         }
         else {
-            errorMessage = "Unknown verification error";
+            errorMessage = "Unknown verification error.";
+            errorCode = BaseErrorCode.INTERNAL_ERROR;
             logger.error("Authentication failed: Unexpected non-error exception during token verification.", { ...context, error });
         }
-        return c.json({ error: `Unauthorized: ${errorMessage}.` }, 401);
+        throw new McpError(errorCode, errorMessage);
     }
 }

package/dist/mcp-server/transports/{authentication → auth/strategies/oauth}/oauthMiddleware.d.ts

@@ -5,7 +5,7 @@
  * On success, it populates an AuthInfo object and stores it in an AsyncLocalStorage
  * context for use in downstream handlers.
  *
- * @module src/mcp-server/transports/authentication/oauthMiddleware
+ * @module src/mcp-server/transports/auth/strategies/oauth/oauthMiddleware
  */
 import { HttpBindings } from "@hono/node-server";
 import { Context, Next } from "hono";
@@ -17,8 +17,4 @@ import { Context, Next } from "hono";
  */
 export declare function oauthMiddleware(c: Context<{
     Bindings: HttpBindings;
-}>, next: Next): Promise<(Response & import("hono").TypedResponse<{
-    error: string;
-}, 500, "json">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 401, "json">) | undefined>;
+}>, next: Next): Promise<void>;

package/dist/mcp-server/transports/{authentication → auth/strategies/oauth}/oauthMiddleware.js

@@ -5,14 +5,14 @@
  * On success, it populates an AuthInfo object and stores it in an AsyncLocalStorage
  * context for use in downstream handlers.
  *
- * @module src/mcp-server/transports/authentication/oauthMiddleware
+ * @module src/mcp-server/transports/auth/strategies/oauth/oauthMiddleware
  */
 import { createRemoteJWKSet, jwtVerify } from "jose";
-import { config } from "../../../config/index.js";
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { ErrorHandler } from "../../../utils/internal/errorHandler.js";
-import { logger, requestContextService } from "../../../utils/index.js";
-import { authContext } from "./authContext.js";
+import { config } from "../../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../../types-global/errors.js";
+import { logger, requestContextService } from "../../../../../utils/index.js";
+import { ErrorHandler } from "../../../../../utils/internal/errorHandler.js";
+import { authContext } from "../../core/authContext.js";
 // --- Startup Validation ---
 // Ensures that necessary OAuth configuration is present when the mode is 'oauth'.
 if (config.mcpAuthMode === "oauth") {
@@ -57,6 +57,10 @@ if (config.mcpAuthMode === "oauth" && config.oauthIssuerUrl) {
  * @param next - The function to call to proceed to the next middleware.
  */
 export async function oauthMiddleware(c, next) {
+    // If OAuth is not the configured auth mode, skip this middleware.
+    if (config.mcpAuthMode !== "oauth") {
+        return await next();
+    }
     const context = requestContextService.createRequestContext({
         operation: "oauthMiddleware",
         httpMethod: c.req.method,
@@ -64,13 +68,12 @@ export async function oauthMiddleware(c, next) {
     });
     if (!jwks) {
         // This should not happen if startup validation is correct, but it's a safeguard.
-        const error = new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAuth middleware is active, but JWKS client is not initialized.", context);
-        ErrorHandler.handleError(error, { operation: "oauthMiddleware", context });
-        return c.json({ error: "Server configuration error." }, 500);
+        // This should not happen if startup validation is correct, but it's a safeguard.
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAuth middleware is active, but JWKS client is not initialized.", context);
     }
     const authHeader = c.req.header("Authorization");
     if (!authHeader || !authHeader.startsWith("Bearer ")) {
-        return c.json({ error: "Unauthorized: Missing or invalid token format." }, 401);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid token format.");
     }
     const token = authHeader.substring(7);
     try {
@@ -80,10 +83,14 @@ export async function oauthMiddleware(c, next) {
         });
         // The 'scope' claim is typically a space-delimited string in OAuth 2.1.
         const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+        if (scopes.length === 0) {
+            logger.warning("Authentication failed: Token contains no scopes, but scopes are required.", { ...context, jwtPayloadKeys: Object.keys(payload) });
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.");
+        }
         const clientId = typeof payload.client_id === "string" ? payload.client_id : undefined;
         if (!clientId) {
             logger.warning("Authentication failed: OAuth token 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(payload) });
-            return c.json({ error: "Unauthorized: Invalid token, missing client identifier." }, 401);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token, missing client identifier.");
         }
         const authInfo = {
             token,
@@ -97,13 +104,21 @@ export async function oauthMiddleware(c, next) {
         await authContext.run({ authInfo }, next);
     }
     catch (error) {
-        logger.warning("OAuth token validation failed", {
-            ...context,
-            errorName: error.name,
-            errorMessage: error.message,
+        if (error instanceof Error && error.name === "JWTExpired") {
+            logger.warning("Authentication failed: OAuth token expired.", context);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token expired.");
+        }
+        const handledError = ErrorHandler.handleError(error, {
+            operation: "oauthMiddleware",
+            context,
+            rethrow: false, // We will throw a new McpError below
         });
-        // The `jose` library provides specific error codes like 'ERR_JWT_EXPIRED' or 'ERR_JWS_INVALID'
-        const message = `Unauthorized: ${error.message || "Invalid token"}`;
-        return c.json({ error: message }, 401);
+        // Ensure we always throw an McpError for consistency
+        if (handledError instanceof McpError) {
+            throw handledError;
+        }
+        else {
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, `Unauthorized: ${handledError.message || "Invalid token"}`, { originalError: handledError.name });
+        }
     }
 }

package/dist/mcp-server/transports/httpErrorHandler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Centralized error handler for the Hono HTTP transport.
+ * This middleware intercepts errors that occur during request processing,
+ * standardizes them using the application's ErrorHandler utility, and
+ * formats them into a consistent JSON-RPC error response.
+ * @module src/mcp-server/transports/httpErrorHandler
+ */
+import { Context } from "hono";
+import { BaseErrorCode } from "../../types-global/errors.js";
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * @param err - The error that was thrown.
+ * @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">>;

package/dist/mcp-server/transports/httpErrorHandler.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Centralized error handler for the Hono HTTP transport.
+ * This middleware intercepts errors that occur during request processing,
+ * standardizes them using the application's ErrorHandler utility, and
+ * 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";
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * @param err - The error that was thrown.
+ * @param c - The Hono context object for the request.
+ * @returns A Response object containing the formatted JSON-RPC error.
+ */
+export const httpErrorHandler = async (err, c) => {
+    const context = requestContextService.createRequestContext({
+        operation: "httpErrorHandler",
+        path: c.req.path,
+        method: c.req.method,
+    });
+    const handledError = ErrorHandler.handleError(err, {
+        operation: "httpTransport",
+        context,
+    });
+    let status = 500;
+    if (handledError instanceof McpError) {
+        switch (handledError.code) {
+            case BaseErrorCode.NOT_FOUND:
+                status = 404;
+                break;
+            case BaseErrorCode.UNAUTHORIZED:
+                status = 401;
+                break;
+            case BaseErrorCode.FORBIDDEN:
+                status = 403;
+                break;
+            case BaseErrorCode.VALIDATION_ERROR:
+                status = 400;
+                break;
+            case BaseErrorCode.CONFLICT:
+                status = 409;
+                break;
+            case BaseErrorCode.RATE_LIMITED:
+                status = 429;
+                break;
+            default:
+                status = 500;
+        }
+    }
+    // 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;
+    }
+    catch {
+        // Ignore parsing errors, requestId will remain null
+    }
+    const errorCode = handledError instanceof McpError ? handledError.code : -32603;
+    c.status(status);
+    return c.json({
+        jsonrpc: "2.0",
+        error: {
+            code: errorCode,
+            message: handledError.message,
+        },
+        id: requestId,
+    });
+};

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

@@ -1,10 +1,15 @@
 /**
- * @fileoverview Handles the setup and management of the Streamable HTTP MCP transport using Hono.
- * Implements the MCP Specification 2025-03-26 for Streamable HTTP.
- * This includes creating a Hono server, configuring middleware (CORS, Authentication),
- * defining request routing for the single MCP endpoint (POST/GET/DELETE),
- * managing server-side sessions, handling Server-Sent Events (SSE) for streaming,
- * and binding to a network port with retry logic for port conflicts.
+ * @fileoverview Configures and starts the Streamable HTTP MCP transport using Hono.
+ * This module integrates the `@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport`
+ * into a Hono web server. Its responsibilities include:
+ * - Creating a Hono server instance.
+ * - Applying and configuring middleware for CORS, rate limiting, and authentication (JWT/OAuth).
+ * - Defining the routes (`/mcp` endpoint for POST, GET, DELETE) to handle the MCP lifecycle.
+ * - Orchestrating session management by mapping session IDs to SDK transport instances.
+ * - Implementing port-binding logic with automatic retry on conflicts.
+ *
+ * The underlying implementation of the MCP Streamable HTTP specification, including
+ * Server-Sent Events (SSE) for streaming, is handled by the SDK's transport class.
  *
  * Specification Reference:
  * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#streamable-http

package/dist/mcp-server/transports/httpTransport.js

@@ -1,10 +1,15 @@
 /**
- * @fileoverview Handles the setup and management of the Streamable HTTP MCP transport using Hono.
- * Implements the MCP Specification 2025-03-26 for Streamable HTTP.
- * This includes creating a Hono server, configuring middleware (CORS, Authentication),
- * defining request routing for the single MCP endpoint (POST/GET/DELETE),
- * managing server-side sessions, handling Server-Sent Events (SSE) for streaming,
- * and binding to a network port with retry logic for port conflicts.
+ * @fileoverview Configures and starts the Streamable HTTP MCP transport using Hono.
+ * This module integrates the `@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport`
+ * into a Hono web server. Its responsibilities include:
+ * - Creating a Hono server instance.
+ * - Applying and configuring middleware for CORS, rate limiting, and authentication (JWT/OAuth).
+ * - Defining the routes (`/mcp` endpoint for POST, GET, DELETE) to handle the MCP lifecycle.
+ * - Orchestrating session management by mapping session IDs to SDK transport instances.
+ * - Implementing port-binding logic with automatic retry on conflicts.
+ *
+ * The underlying implementation of the MCP Streamable HTTP specification, including
+ * Server-Sent Events (SSE) for streaming, is handled by the SDK's transport class.
  *
  * Specification Reference:
  * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#streamable-http
@@ -19,17 +24,19 @@ import http from "http";
 import { randomUUID } from "node:crypto";
 import { config } from "../../config/index.js";
 import { BaseErrorCode, McpError } from "../../types-global/errors.js";
-import { ErrorHandler, logger, rateLimiter, requestContextService, } from "../../utils/index.js";
-import { initializeAuthMiddleware, mcpAuthMiddleware, } from "./authentication/authMiddleware.js";
-import { oauthMiddleware } from "./authentication/oauthMiddleware.js";
+import { logger, rateLimiter, requestContextService, } from "../../utils/index.js";
+import { jwtAuthMiddleware, oauthMiddleware, } from "./auth/index.js";
+import { httpErrorHandler } from "./httpErrorHandler.js";
 const HTTP_PORT = config.mcpHttpPort;
 const HTTP_HOST = config.mcpHttpHost;
 const MCP_ENDPOINT_PATH = "/mcp";
 const MAX_PORT_RETRIES = 15;
-const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
-const SESSION_GC_INTERVAL_MS = 60 * 1000;
-const httpTransports = {};
-const sessionActivity = {};
+// The transports map will store active sessions, keyed by session ID.
+// NOTE: This is an in-memory session store, which is a known limitation for scalability.
+// It will not work in a multi-process (clustered) or serverless environment.
+// For a scalable deployment, this would need to be replaced with a distributed
+// store like Redis or Memcached.
+const transports = {};
 async function isPortInUse(port, host, parentContext) {
     const checkContext = requestContextService.createRequestContext({
         ...parentContext,
@@ -57,7 +64,11 @@ function startHttpServerWithRetry(app, initialPort, host, maxRetries, parentCont
     return new Promise(async (resolve, reject) => {
         for (let i = 0; i <= maxRetries; i++) {
             const currentPort = initialPort + i;
-            const attemptContext = { ...startContext, port: currentPort, attempt: i + 1 };
+            const attemptContext = {
+                ...startContext,
+                port: currentPort,
+                attempt: i + 1,
+            };
             if (await isPortInUse(currentPort, host, attemptContext)) {
                 logger.warning(`Port ${currentPort} is in use, retrying...`, attemptContext);
                 continue;
@@ -65,7 +76,10 @@ function startHttpServerWithRetry(app, initialPort, host, maxRetries, parentCont
             try {
                 const serverInstance = serve({ fetch: app.fetch, port: currentPort, hostname: host }, (info) => {
                     const serverAddress = `http://${info.address}:${info.port}${MCP_ENDPOINT_PATH}`;
-                    logger.info(`HTTP transport listening at ${serverAddress}`, { ...attemptContext, address: serverAddress });
+                    logger.info(`HTTP transport listening at ${serverAddress}`, {
+                        ...attemptContext,
+                        address: serverAddress,
+                    });
                     if (process.stdout.isTTY) {
                         console.log(`\n🚀 MCP Server running at: ${serverAddress}\n`);
                     }
@@ -84,27 +98,20 @@ function startHttpServerWithRetry(app, initialPort, host, maxRetries, parentCont
     });
 }
 export async function startHttpTransport(createServerInstanceFn, parentContext) {
-    initializeAuthMiddleware();
     const app = new Hono();
     const transportContext = requestContextService.createRequestContext({
         ...parentContext,
         component: "HttpTransportSetup",
     });
-    setInterval(() => {
-        const now = Date.now();
-        const gcContext = requestContextService.createRequestContext({ operation: "SessionGarbageCollector" });
-        for (const sessionId in sessionActivity) {
-            if (now - sessionActivity[sessionId] > SESSION_TIMEOUT_MS) {
-                logger.info(`Session ${sessionId} timed out. Cleaning up.`, { ...gcContext, sessionId });
-                httpTransports[sessionId]?.close();
-                delete sessionActivity[sessionId];
-            }
-        }
-    }, SESSION_GC_INTERVAL_MS);
     app.use("*", cors({
         origin: config.mcpAllowedOrigins || [],
         allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
-        allowHeaders: ["Content-Type", "Mcp-Session-Id", "Last-Event-ID", "Authorization"],
+        allowHeaders: [
+            "Content-Type",
+            "Mcp-Session-Id",
+            "Last-Event-ID",
+            "Authorization",
+        ],
         credentials: true,
     }));
     app.use("*", async (c, next) => {
@@ -112,98 +119,90 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
         await next();
     });
     app.use(MCP_ENDPOINT_PATH, async (c, next) => {
+        // NOTE (Security): The 'x-forwarded-for' header is used for rate limiting.
+        // This is only secure if the server is run behind a trusted proxy that
+        // correctly sets or validates this header.
         const clientIp = c.req.header("x-forwarded-for")?.split(",")[0].trim() || "unknown_ip";
-        const context = requestContextService.createRequestContext({ operation: "httpRateLimitCheck", ipAddress: clientIp });
-        try {
-            rateLimiter.check(clientIp, context);
-            await next();
-        }
-        catch (error) {
-            const handledError = ErrorHandler.handleError(error, { operation: "rateLimitMiddleware", context });
-            return c.json({
-                jsonrpc: "2.0",
-                error: { code: -32000, message: handledError.message },
-                id: (await c.req.json().catch(() => ({})))?.id || null,
-            }, 429);
-        }
+        const context = requestContextService.createRequestContext({
+            operation: "httpRateLimitCheck",
+            ipAddress: clientIp,
+        });
+        // Let the centralized error handler catch rate limit errors
+        rateLimiter.check(clientIp, context);
+        await next();
     });
     if (config.mcpAuthMode === "oauth") {
         app.use(MCP_ENDPOINT_PATH, oauthMiddleware);
     }
     else {
-        app.use(MCP_ENDPOINT_PATH, mcpAuthMiddleware);
+        app.use(MCP_ENDPOINT_PATH, jwtAuthMiddleware);
     }
+    // Centralized Error Handling
+    app.onError(httpErrorHandler);
     app.post(MCP_ENDPOINT_PATH, async (c) => {
-        const postContext = requestContextService.createRequestContext({ ...transportContext, operation: "handlePost" });
-        let transport;
-        try {
-            const body = await c.req.json();
-            const sessionId = c.req.header("mcp-session-id");
-            transport = sessionId ? httpTransports[sessionId] : undefined;
-            if (transport && sessionId)
-                sessionActivity[sessionId] = Date.now();
-            if (isInitializeRequest(body)) {
-                if (transport) {
-                    logger.warning("Re-initializing existing session.", { ...postContext, sessionId });
-                    await transport.close();
-                }
-                transport = new StreamableHTTPServerTransport({
-                    sessionIdGenerator: () => randomUUID(),
-                    onsessioninitialized: (newId) => {
-                        httpTransports[newId] = transport;
-                        sessionActivity[newId] = Date.now();
-                        logger.info(`HTTP Session created: ${newId}`, { ...postContext, newSessionId: newId });
-                    },
+        const postContext = requestContextService.createRequestContext({
+            ...transportContext,
+            operation: "handlePost",
+        });
+        const body = await c.req.json();
+        const sessionId = c.req.header("mcp-session-id");
+        let transport = sessionId
+            ? transports[sessionId]
+            : undefined;
+        if (isInitializeRequest(body)) {
+            // If a transport already exists for a session, it's a re-initialization.
+            if (transport) {
+                logger.warning("Re-initializing existing session.", {
+                    ...postContext,
+                    sessionId,
                 });
-                transport.onclose = () => {
-                    const closedSessionId = transport.sessionId;
-                    if (closedSessionId) {
-                        delete httpTransports[closedSessionId];
-                        delete sessionActivity[closedSessionId];
-                        logger.info(`HTTP Session closed: ${closedSessionId}`, { ...postContext, closedSessionId });
-                    }
-                };
-                const server = await createServerInstanceFn();
-                await server.connect(transport);
-            }
-            else if (!transport) {
-                throw new McpError(BaseErrorCode.NOT_FOUND, "Invalid or expired session ID.");
+                await transport.close(); // This will trigger the onclose handler.
             }
-            return await transport.handleRequest(c.env.incoming, c.env.outgoing, body);
+            // Create a new transport for a new session.
+            const newTransport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (newId) => {
+                    transports[newId] = newTransport;
+                    logger.info(`HTTP Session created: ${newId}`, {
+                        ...postContext,
+                        newSessionId: newId,
+                    });
+                },
+            });
+            // Set up cleanup logic for when the transport is closed.
+            newTransport.onclose = () => {
+                const closedSessionId = newTransport.sessionId;
+                if (closedSessionId && transports[closedSessionId]) {
+                    delete transports[closedSessionId];
+                    logger.info(`HTTP Session closed: ${closedSessionId}`, {
+                        ...postContext,
+                        closedSessionId,
+                    });
+                }
+            };
+            // Connect the new transport to a new server instance.
+            const server = await createServerInstanceFn();
+            await server.connect(newTransport);
+            transport = newTransport;
         }
-        catch (err) {
-            const handledError = ErrorHandler.handleError(err, { operation: "handlePost", context: postContext });
-            const requestId = (await c.req.json().catch(() => ({})))?.id || null;
-            return c.json({
-                jsonrpc: "2.0",
-                error: { code: -32603, message: handledError.message },
-                id: requestId,
-            }, handledError instanceof McpError && handledError.code === BaseErrorCode.NOT_FOUND ? 404 : 500);
+        else if (!transport) {
+            // If it's not an initialization request and no transport was found, it's an error.
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Invalid or expired session ID.");
         }
+        // Pass the request to the transport to handle.
+        return await transport.handleRequest(c.env.incoming, c.env.outgoing, body);
     });
-    const handleSessionReq = async (c) => {
-        const method = c.req.method;
-        const sessionReqContext = requestContextService.createRequestContext({ ...transportContext, operation: `handle${method}` });
-        try {
-            const sessionId = c.req.header("mcp-session-id");
-            const transport = sessionId ? httpTransports[sessionId] : undefined;
-            if (!transport) {
-                throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.");
-            }
-            if (sessionId)
-                sessionActivity[sessionId] = Date.now();
-            return await transport.handleRequest(c.env.incoming, c.env.outgoing);
-        }
-        catch (err) {
-            const handledError = ErrorHandler.handleError(err, { operation: `handle${method}`, context: sessionReqContext });
-            return c.json({
-                jsonrpc: "2.0",
-                error: { code: -32603, message: handledError.message },
-                id: null,
-            }, handledError instanceof McpError && handledError.code === BaseErrorCode.NOT_FOUND ? 404 : 500);
+    // A reusable handler for GET and DELETE requests which operate on existing sessions.
+    const handleSessionRequest = async (c) => {
+        const sessionId = c.req.header("mcp-session-id");
+        const transport = sessionId ? transports[sessionId] : undefined;
+        if (!transport) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.");
         }
+        // Let the transport handle the streaming (GET) or termination (DELETE) request.
+        return await transport.handleRequest(c.env.incoming, c.env.outgoing);
     };
-    app.get(MCP_ENDPOINT_PATH, handleSessionReq);
-    app.delete(MCP_ENDPOINT_PATH, handleSessionReq);
+    app.get(MCP_ENDPOINT_PATH, handleSessionRequest);
+    app.delete(MCP_ENDPOINT_PATH, handleSessionRequest);
     return startHttpServerWithRetry(app, HTTP_PORT, HTTP_HOST, MAX_PORT_RETRIES, transportContext);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/pubmed-mcp-server",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "A Model Context Protocol (MCP) server enabling AI agents to intelligently search, retrieve, and analyze biomedical literature from PubMed via NCBI E-utilities. Built on the mcp-ts-template for robust, production-ready performance.",
   "main": "dist/index.js",
   "files": [
@@ -33,19 +33,19 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.14.4",
-    "@modelcontextprotocol/sdk": "^1.12.3",
-    "@types/jsonwebtoken": "^9.0.9",
-    "@types/node": "^24.0.1",
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^24.0.3",
     "@types/sanitize-html": "^2.16.0",
-    "@types/validator": "13.15.1",
+    "@types/validator": "13.15.2",
     "axios": "^1.10.0",
     "chrono-node": "^2.8.3",
     "dotenv": "^16.5.0",
     "fast-xml-parser": "^5.2.5",
-    "hono": "^4.7.11",
+    "hono": "^4.8.2",
     "jose": "^6.0.11",
     "jsonwebtoken": "^9.0.2",
-    "openai": "^5.3.0",
+    "openai": "^5.6.0",
     "partial-json": "^0.1.7",
     "sanitize-html": "^2.17.0",
     "tiktoken": "^1.0.21",
@@ -56,7 +56,7 @@
     "chartjs-node-canvas": "^5.0.0",
     "winston": "^3.17.0",
     "winston-transport": "^4.9.0",
-    "zod": "^3.25.64"
+    "zod": "^3.25.67"
   },
   "keywords": [
     "mcp",