@cyanheads/pubmed-mcp-server 1.1.4 → 1.2.2

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
@@ -13,12 +18,4 @@
 import { ServerType } from "@hono/node-server";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { RequestContext } from "../../utils/index.js";
-/**
- * Sets up and starts the Streamable HTTP transport layer for the MCP server.
- *
- * @param createServerInstanceFn - An asynchronous factory function that returns a new `McpServer` instance.
- * @param parentContext - Logging context from the main server startup process.
- * @returns A promise that resolves with the Node.js `http.Server` instance when the HTTP server is successfully listening.
- * @throws {Error} If the server fails to start after all port retries.
- */
 export declare function startHttpTransport(createServerInstanceFn: () => Promise<McpServer>, parentContext: RequestContext): Promise<ServerType>;