@cyanheads/pubmed-mcp-server 1.2.1 → 1.2.3

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.3-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/dist/utils/internal/logger.js

@@ -35,8 +35,11 @@ const mcpToWinstonLevel = {
     alert: "error",
     emerg: "error",
 };
+// The logsPath from config is already resolved and validated by src/config/index.ts
+const resolvedLogsDir = config.logsPath;
+const isLogsDirSafe = !!resolvedLogsDir; // If logsPath is set, it's considered safe by config logic.
 /**
- * Creates the Winston console log format for interactive TTY sessions.
+ * Creates the Winston console log format.
  * @returns The Winston log format for console output.
  * @private
  */
@@ -100,45 +103,47 @@ export class Logger {
             });
             return;
         }
+        // Set initialized to true at the beginning of the initialization process.
         this.initialized = true;
         this.currentMcpLevel = level;
         this.currentWinstonLevel = mcpToWinstonLevel[level];
+        // The logs directory (config.logsPath / resolvedLogsDir) is expected to be created and validated
+        // by the configuration module (src/config/index.ts) before logger initialization.
+        // If isLogsDirSafe is true, we assume resolvedLogsDir exists and is usable.
+        // No redundant directory creation logic here.
+        const fileFormat = winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json());
         const transports = [];
-        if (config.logOutputMode === "stdout") {
-            transports.push(new winston.transports.Console({
-                format: winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json()),
+        const fileTransportOptions = {
+            format: fileFormat,
+            maxsize: this.LOG_FILE_MAX_SIZE,
+            maxFiles: this.LOG_MAX_FILES,
+            tailable: true,
+        };
+        if (isLogsDirSafe) {
+            transports.push(new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "error.log"),
+                level: "error",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "warn.log"),
+                level: "warn",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "info.log"),
+                level: "info",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "debug.log"),
+                level: "debug",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "combined.log"),
+                ...fileTransportOptions,
             }));
         }
         else {
-            const resolvedLogsDir = config.logsPath;
-            if (resolvedLogsDir) {
-                const fileFormat = winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json());
-                const fileTransportOptions = {
-                    format: fileFormat,
-                    maxsize: this.LOG_FILE_MAX_SIZE,
-                    maxFiles: this.LOG_MAX_FILES,
-                    tailable: true,
-                };
-                transports.push(new winston.transports.File({
-                    filename: path.join(resolvedLogsDir, "error.log"),
-                    level: "error",
-                    ...fileTransportOptions,
-                }), new winston.transports.File({
-                    filename: path.join(resolvedLogsDir, "warn.log"),
-                    level: "warn",
-                    ...fileTransportOptions,
-                }), new winston.transports.File({
-                    filename: path.join(resolvedLogsDir, "info.log"),
-                    level: "info",
-                    ...fileTransportOptions,
-                }), new winston.transports.File({
-                    filename: path.join(resolvedLogsDir, "debug.log"),
-                    level: "debug",
-                    ...fileTransportOptions,
-                }), new winston.transports.File({
-                    filename: path.join(resolvedLogsDir, "combined.log"),
-                    ...fileTransportOptions,
-                }));
+            if (process.stdout.isTTY) {
+                console.warn("File logging disabled as logsPath is not configured or invalid.");
             }
         }
         this.winstonLogger = winston.createLogger({
@@ -146,20 +151,23 @@ export class Logger {
             transports,
             exitOnError: false,
         });
+        // Configure console transport after Winston logger is created
         const consoleStatus = this._configureConsoleTransport();
         const initialContext = {
             loggerSetup: true,
             requestId: "logger-init-deferred",
             timestamp: new Date().toISOString(),
         };
+        // Removed logging of logsDirCreatedMessage as it's no longer set
         if (consoleStatus.message) {
             this.info(consoleStatus.message, initialContext);
         }
-        this.info(`Logger initialized. Mode: ${config.logOutputMode}. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}.`, {
+        this.initialized = true; // Ensure this is set after successful setup
+        this.info(`Logger initialized. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${consoleStatus.enabled ? "enabled" : "disabled"}`, {
             loggerSetup: true,
             requestId: "logger-post-init",
             timestamp: new Date().toISOString(),
-            logsPathUsed: config.logsPath,
+            logsPathUsed: resolvedLogsDir,
         });
     }
     /**
@@ -199,6 +207,7 @@ export class Logger {
         this.currentMcpLevel = newLevel;
         this.currentWinstonLevel = mcpToWinstonLevel[newLevel];
         if (this.winstonLogger) {
+            // Ensure winstonLogger is defined
             this.winstonLogger.level = this.currentWinstonLevel;
         }
         const consoleStatus = this._configureConsoleTransport();
@@ -217,12 +226,6 @@ export class Logger {
      * @private
      */
     _configureConsoleTransport() {
-        if (config.logOutputMode === "stdout") {
-            return {
-                enabled: true,
-                message: "Stdout logging is enabled by configuration.",
-            };
-        }
         if (!this.winstonLogger) {
             return {
                 enabled: false,
@@ -235,19 +238,17 @@ export class Logger {
         if (shouldHaveConsole && !consoleTransport) {
             const consoleFormat = createWinstonConsoleFormat();
             this.winstonLogger.add(new winston.transports.Console({
-                level: "debug",
+                level: "debug", // Console always logs debug if enabled
                 format: consoleFormat,
             }));
-            message =
-                "Interactive console logging enabled (level: debug, stdout is TTY).";
+            message = "Console logging enabled (level: debug, stdout is TTY).";
         }
         else if (!shouldHaveConsole && consoleTransport) {
             this.winstonLogger.remove(consoleTransport);
-            message =
-                "Interactive console logging disabled (level not debug or stdout not TTY).";
+            message = "Console logging disabled (level not debug or stdout not TTY).";
         }
         else {
-            message = "Interactive console logging status unchanged.";
+            message = "Console logging status unchanged.";
         }
         return { enabled: shouldHaveConsole, message };
     }
@@ -287,7 +288,7 @@ export class Logger {
         if (!this.ensureInitialized())
             return;
         if (mcpLevelSeverity[level] > mcpLevelSeverity[this.currentMcpLevel]) {
-            return;
+            return; // Do not log if message level is less severe than currentMcpLevel
         }
         const logData = { ...context };
         const winstonLevel = mcpToWinstonLevel[level];
@@ -303,6 +304,7 @@ export class Logger {
                 mcpDataPayload.context = context;
             if (error) {
                 mcpDataPayload.error = { message: error.message };
+                // Include stack trace in debug mode for MCP notifications, truncated for brevity
                 if (this.currentMcpLevel === "debug" && error.stack) {
                     mcpDataPayload.error.stack = error.stack.substring(0, this.MCP_NOTIFICATION_STACK_TRACE_MAX_LENGTH);
                 }
@@ -319,7 +321,7 @@ export class Logger {
                     originalLevel: level,
                     originalMessage: msg,
                     sendError: errorMessage,
-                    mcpPayload: JSON.stringify(mcpDataPayload).substring(0, 500),
+                    mcpPayload: JSON.stringify(mcpDataPayload).substring(0, 500), // Log a preview
                 };
                 this.winstonLogger.error("Failed to send MCP log notification", internalErrorContext);
             }

package/dist/utils/security/idGenerator.d.ts

@@ -85,6 +85,7 @@ export declare class IdGenerator {
      * @param id - The ID string to validate.
      * @param entityType - The expected entity type of the ID.
      * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
      * @returns `true` if the ID is valid, `false` otherwise.
      */
     isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
@@ -112,7 +113,9 @@ export declare class IdGenerator {
     getEntityType(id: string, separator?: string): string;
     /**
      * Normalizes an entity ID to ensure the prefix matches the registered case
-     * and the random part is uppercase.
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
      * @param id - The ID to normalize (e.g., "proj_a6b3j0").
      * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
      * @returns The normalized ID (e.g., "PROJ_A6B3J0").

package/dist/utils/security/idGenerator.js

@@ -60,10 +60,18 @@ export class IdGenerator {
      * @returns The generated random string.
      */
     generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
-        const bytes = randomBytes(length);
         let result = "";
-        for (let i = 0; i < length; i++) {
-            result += charset[bytes[i] % charset.length];
+        // Determine the largest multiple of charset.length that is less than or equal to 256
+        // This is the threshold for rejection sampling to avoid bias.
+        const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
+        while (result.length < length) {
+            const byteBuffer = randomBytes(1); // Get one random byte
+            const byte = byteBuffer[0];
+            // If the byte is within the valid range (i.e., it won't introduce bias),
+            // use it to select a character from the charset. Otherwise, discard and try again.
+            if (byte < maxValidByteValue) {
+                result += charset[byte % charset.length];
+            }
         }
         return result;
     }
@@ -101,16 +109,21 @@ export class IdGenerator {
      * @param id - The ID string to validate.
      * @param entityType - The expected entity type of the ID.
      * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
      * @returns `true` if the ID is valid, `false` otherwise.
      */
     isValid(id, entityType, options = {}) {
         const prefix = this.entityPrefixes[entityType];
-        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, } = options;
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, // Use charset from options or default
+         } = options;
         if (!prefix) {
             return false;
         }
-        // Assumes default charset characters (uppercase letters and digits) for regex.
-        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}[A-Z0-9]{${length}}$`);
+        // Build regex character class from the charset
+        // Escape characters that have special meaning inside a regex character class `[]`
+        const escapedCharsetForClass = charset.replace(/[[\]\\^-]/g, "\\$&");
+        const charsetRegexPart = `[${escapedCharsetForClass}]`;
+        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}${charsetRegexPart}{${length}}$`);
         return pattern.test(id);
     }
     /**
@@ -153,7 +166,9 @@ export class IdGenerator {
     }
     /**
      * Normalizes an entity ID to ensure the prefix matches the registered case
-     * and the random part is uppercase.
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
      * @param id - The ID to normalize (e.g., "proj_a6b3j0").
      * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
      * @returns The normalized ID (e.g., "PROJ_A6B3J0").
@@ -164,6 +179,8 @@ export class IdGenerator {
         const registeredPrefix = this.entityPrefixes[entityType];
         const idParts = id.split(separator);
         const randomPart = idParts.slice(1).join(separator);
+        // Consider if randomPart.toUpperCase() is always correct for custom charsets.
+        // For now, maintaining existing behavior.
         return `${registeredPrefix}${separator}${randomPart.toUpperCase()}`;
     }
 }

package/dist/utils/security/rateLimiter.d.ts

@@ -28,10 +28,6 @@ export interface RateLimitEntry {
 /**
  * A generic rate limiter class using an in-memory store.
  * Controls frequency of operations based on unique keys.
- *
- * @scalability Note: This is an in-memory store. For horizontal scaling across
- * multiple processes or machines, this state would need to be moved to a shared,
- * distributed store like Redis or a database.
  */
 export declare class RateLimiter {
     private config;

package/dist/utils/security/rateLimiter.js

@@ -9,10 +9,6 @@ import { logger, requestContextService } from "../index.js";
 /**
  * A generic rate limiter class using an in-memory store.
  * Controls frequency of operations based on unique keys.
- *
- * @scalability Note: This is an in-memory store. For horizontal scaling across
- * multiple processes or machines, this state would need to be moved to a shared,
- * distributed store like Redis or a database.
  */
 export class RateLimiter {
     /**

package/dist/utils/security/sanitization.d.ts

@@ -148,6 +148,17 @@ export declare class Sanitization {
      * Sanitizes input for logging by redacting sensitive fields.
      * Creates a deep clone and replaces values of fields matching `this.sensitiveFields`
      * (case-insensitive substring match) with "[REDACTED]".
+     *
+     * It uses `structuredClone` if available for a high-fidelity deep clone.
+     * If `structuredClone` is not available (e.g., in older Node.js environments),
+     * it falls back to `JSON.parse(JSON.stringify(input))`. This fallback has limitations:
+     * - `Date` objects are converted to ISO date strings.
+     * - `undefined` values within objects are removed.
+     * - `Map`, `Set`, `RegExp` objects are converted to empty objects (`{}`).
+     * - Functions are removed.
+     * - `BigInt` values will throw an error during `JSON.stringify` unless a `toJSON` method is provided.
+     * - Circular references will cause `JSON.stringify` to throw an error.
+     *
      * @param input - The input data to sanitize for logging.
      * @returns A sanitized (deep cloned) version of the input, safe for logging.
      *   Returns original input if not object/array, or "[Log Sanitization Failed]" on error.

package/dist/utils/security/sanitization.js

@@ -204,8 +204,11 @@ export class Sanitization {
             })) {
                 throw new Error("Invalid URL format or protocol not in allowed list.");
             }
-            if (trimmedInput.toLowerCase().startsWith("javascript:")) {
-                throw new Error("JavaScript pseudo-protocol is not allowed in URLs.");
+            const lowercasedInput = trimmedInput.toLowerCase();
+            if (lowercasedInput.startsWith("javascript:") ||
+                lowercasedInput.startsWith("data:") ||
+                lowercasedInput.startsWith("vbscript:")) {
+                throw new Error("Disallowed pseudo-protocol (javascript:, data:, or vbscript:) in URL.");
             }
             return trimmedInput;
         }
@@ -377,6 +380,17 @@ export class Sanitization {
      * Sanitizes input for logging by redacting sensitive fields.
      * Creates a deep clone and replaces values of fields matching `this.sensitiveFields`
      * (case-insensitive substring match) with "[REDACTED]".
+     *
+     * It uses `structuredClone` if available for a high-fidelity deep clone.
+     * If `structuredClone` is not available (e.g., in older Node.js environments),
+     * it falls back to `JSON.parse(JSON.stringify(input))`. This fallback has limitations:
+     * - `Date` objects are converted to ISO date strings.
+     * - `undefined` values within objects are removed.
+     * - `Map`, `Set`, `RegExp` objects are converted to empty objects (`{}`).
+     * - Functions are removed.
+     * - `BigInt` values will throw an error during `JSON.stringify` unless a `toJSON` method is provided.
+     * - Circular references will cause `JSON.stringify` to throw an error.
+     *
      * @param input - The input data to sanitize for logging.
      * @returns A sanitized (deep cloned) version of the input, safe for logging.
      *   Returns original input if not object/array, or "[Log Sanitization Failed]" on error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/pubmed-mcp-server",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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",