@cyanheads/pubmed-mcp-server 1.1.4 → 1.2.2

package/dist/mcp-server/tools/searchPubMedArticles/logic.js

@@ -61,14 +61,6 @@ export const SearchPubMedArticlesInputSchema = z.object({
         .default(0)
         .describe("Number of top PMIDs for which to fetch brief summaries using ESummary v2.0. Set to 0 to disable. Maximum is 50 for this tool. Default is 0."),
 });
-/**
- * Logic for the searchPubMedArticles tool.
- * Constructs and executes ESearch and optionally ESummary queries via NcbiService,
- * then formats the results into a CallToolResult.
- * @param input - Validated input arguments for the tool.
- * @param parentRequestContext - The parent request context for logging and correlation.
- * @returns A promise resolving to a CallToolResult.
- */
 export async function searchPubMedArticlesLogic(input, parentRequestContext) {
     const ncbiService = getNcbiService();
     const toolLogicContext = requestContextService.createRequestContext({
@@ -107,129 +99,79 @@ export async function searchPubMedArticlesLogic(input, parentRequestContext) {
         sort: input.sortBy,
         usehistory: currentFetchBriefSummaries > 0 ? "y" : "n",
     };
-    let eSearchUrl = "";
-    let eSummaryUrl = "";
-    try {
-        const eSearchResponse = await ncbiService.eSearch(eSearchParams, toolLogicContext);
-        const eSearchBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi";
-        const eSearchQueryStringParams = {};
-        for (const key in eSearchParams) {
-            if (eSearchParams[key] !== undefined) {
-                eSearchQueryStringParams[key] = String(eSearchParams[key]);
-            }
+    const eSearchResponse = await ncbiService.eSearch(eSearchParams, toolLogicContext);
+    const eSearchBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi";
+    const eSearchQueryStringParams = {};
+    for (const key in eSearchParams) {
+        if (eSearchParams[key] !== undefined) {
+            eSearchQueryStringParams[key] = String(eSearchParams[key]);
         }
-        const eSearchQueryString = new URLSearchParams(eSearchQueryStringParams).toString();
-        eSearchUrl = `${eSearchBase}?${eSearchQueryString}`;
-        if (!eSearchResponse || !eSearchResponse.eSearchResult) {
-            throw new McpError(BaseErrorCode.NCBI_PARSING_ERROR, "Invalid or empty ESearch response from NCBI.", {
-                responsePreview: sanitizeInputForLogging(JSON.stringify(eSearchResponse).substring(0, 200)),
-                requestId: toolLogicContext.requestId,
-            });
+    }
+    const eSearchQueryString = new URLSearchParams(eSearchQueryStringParams).toString();
+    const eSearchUrl = `${eSearchBase}?${eSearchQueryString}`;
+    if (!eSearchResponse || !eSearchResponse.eSearchResult) {
+        throw new McpError(BaseErrorCode.NCBI_PARSING_ERROR, "Invalid or empty ESearch response from NCBI.", {
+            ...toolLogicContext,
+            responsePreview: sanitizeInputForLogging(JSON.stringify(eSearchResponse).substring(0, 200)),
+        });
+    }
+    const esResult = eSearchResponse.eSearchResult;
+    const pmids = esResult.IdList?.Id || [];
+    const totalFound = parseInt(esResult.Count || "0", 10);
+    const retrievedPmidCount = pmids.length;
+    let briefSummaries = [];
+    let eSummaryUrl;
+    if (currentFetchBriefSummaries > 0 && pmids.length > 0) {
+        const eSummaryParams = {
+            db: "pubmed",
+            version: "2.0",
+            retmode: "xml",
+        };
+        if (esResult.WebEnv && esResult.QueryKey) {
+            eSummaryParams.WebEnv = esResult.WebEnv;
+            eSummaryParams.query_key = esResult.QueryKey;
+            eSummaryParams.retmax = currentFetchBriefSummaries;
         }
-        const esResult = eSearchResponse.eSearchResult;
-        const pmids = esResult.IdList?.Id || [];
-        const totalFound = parseInt(esResult.Count || "0", 10);
-        const retrievedPmidCount = pmids.length;
-        let briefSummaries = [];
-        if (currentFetchBriefSummaries > 0 && pmids.length > 0) {
-            const eSummaryParams = {
-                db: "pubmed",
-                version: "2.0",
-                retmode: "xml",
-            };
-            if (esResult.WebEnv && esResult.QueryKey) {
-                eSummaryParams.WebEnv = esResult.WebEnv;
-                eSummaryParams.query_key = esResult.QueryKey;
-                eSummaryParams.retmax = currentFetchBriefSummaries;
-            }
-            else {
-                const pmidsForSummary = pmids
-                    .slice(0, currentFetchBriefSummaries)
-                    .join(",");
-                eSummaryParams.id = pmidsForSummary;
-            }
-            const eSummaryBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi";
-            const eSummaryQueryStringParams = {};
-            for (const key in eSummaryParams) {
-                if (eSummaryParams[key] !== undefined) {
-                    eSummaryQueryStringParams[key] = String(eSummaryParams[key]);
-                }
+        else {
+            const pmidsForSummary = pmids
+                .slice(0, currentFetchBriefSummaries)
+                .join(",");
+            eSummaryParams.id = pmidsForSummary;
+        }
+        const eSummaryBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi";
+        const eSummaryQueryStringParams = {};
+        for (const key in eSummaryParams) {
+            if (eSummaryParams[key] !== undefined) {
+                eSummaryQueryStringParams[key] = String(eSummaryParams[key]);
             }
-            const eSummaryQueryString = new URLSearchParams(eSummaryQueryStringParams).toString();
-            eSummaryUrl = `${eSummaryBase}?${eSummaryQueryString}`;
-            const eSummaryResponseXml = await ncbiService.eSummary(eSummaryParams, toolLogicContext);
-            logger.debug("Raw ESummary Response (XML parsed by ncbiService):", {
+        }
+        const eSummaryQueryString = new URLSearchParams(eSummaryQueryStringParams).toString();
+        eSummaryUrl = `${eSummaryBase}?${eSummaryQueryString}`;
+        const eSummaryResponseXml = await ncbiService.eSummary(eSummaryParams, toolLogicContext);
+        if (eSummaryResponseXml && eSummaryResponseXml.eSummaryResult) {
+            briefSummaries = await extractBriefSummaries(eSummaryResponseXml.eSummaryResult, toolLogicContext);
+        }
+        else if (eSummaryResponseXml && eSummaryResponseXml.ERROR) {
+            logger.warning("ESummary returned a top-level error", {
                 ...toolLogicContext,
-                eSummaryResponse: sanitizeInputForLogging(eSummaryResponseXml),
+                errorDetails: eSummaryResponseXml.ERROR,
             });
-            if (eSummaryResponseXml && eSummaryResponseXml.eSummaryResult) {
-                briefSummaries = await extractBriefSummaries(eSummaryResponseXml.eSummaryResult, toolLogicContext);
-            }
-            else if (eSummaryResponseXml && eSummaryResponseXml.ERROR) {
-                logger.warning("ESummary returned a top-level error", {
-                    ...toolLogicContext,
-                    errorDetails: eSummaryResponseXml.ERROR,
-                });
-            }
         }
-        const resultPayload = {
-            searchParameters: {
-                queryTerm: input.queryTerm,
-                maxResults: input.maxResults,
-                sortBy: input.sortBy,
-                dateRange: input.dateRange,
-                filterByPublicationTypes: input.filterByPublicationTypes,
-                fetchBriefSummaries: currentFetchBriefSummaries,
-            },
-            effectiveESearchTerm: effectiveQuery,
-            totalFound,
-            retrievedPmidCount,
-            pmids,
-            briefSummaries,
-            eSearchUrl,
-            eSummaryUrl: currentFetchBriefSummaries > 0 && pmids.length > 0
-                ? eSummaryUrl
-                : undefined,
-        };
-        logger.notice("Successfully executed searchPubMedArticles tool.", {
-            ...toolLogicContext,
-            totalFound,
-            retrievedPmidCount,
-            summariesFetched: briefSummaries.length,
-        });
-        return {
-            content: [{ type: "text", text: JSON.stringify(resultPayload) }],
-            isError: false,
-        };
-    }
-    catch (error) {
-        logger.error("Error in searchPubMedArticlesLogic", error, toolLogicContext);
-        const mcpError = error instanceof McpError
-            ? error
-            : new McpError(BaseErrorCode.INTERNAL_ERROR, "Failed to search PubMed articles due to an unexpected error.", {
-                originalErrorName: error.name,
-                originalErrorMessage: error.message,
-                requestId: toolLogicContext.requestId,
-            });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        error: {
-                            code: mcpError.code,
-                            message: mcpError.message,
-                            details: mcpError.details,
-                        },
-                        searchParameters: sanitizeInputForLogging(input),
-                        eSearchUrl,
-                        eSummaryUrl: (input.fetchBriefSummaries ?? 0) > 0 && eSummaryUrl
-                            ? eSummaryUrl
-                            : undefined,
-                    }),
-                },
-            ],
-            isError: true,
-        };
     }
+    logger.notice("Successfully executed searchPubMedArticles tool.", {
+        ...toolLogicContext,
+        totalFound,
+        retrievedPmidCount,
+        summariesFetched: briefSummaries.length,
+    });
+    return {
+        searchParameters: input,
+        effectiveESearchTerm: effectiveQuery,
+        totalFound,
+        retrievedPmidCount,
+        pmids,
+        briefSummaries,
+        eSearchUrl,
+        eSummaryUrl,
+    };
 }

package/dist/mcp-server/tools/searchPubMedArticles/registration.js

@@ -2,7 +2,7 @@
  * @fileoverview Registration for the searchPubMedArticles MCP tool.
  * @module src/mcp-server/tools/searchPubMedArticles/registration
  */
-import { BaseErrorCode } from "../../../types-global/errors.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { SearchPubMedArticlesInputSchema, searchPubMedArticlesLogic, } from "./logic.js";
 /**
@@ -11,17 +11,57 @@ import { SearchPubMedArticlesInputSchema, searchPubMedArticlesLogic, } from "./l
  */
 export async function registerSearchPubMedArticlesTool(server) {
     const operation = "registerSearchPubMedArticlesTool";
+    const toolName = "search_pubmed_articles";
+    const toolDescription = "Searches PubMed for articles using a query term and optional filters (max results, sort, date range, publication types). Uses NCBI ESearch to find PMIDs and ESummary (optional) for brief summaries. Returns a JSON object with search parameters, ESearch term, result counts, PMIDs, optional summaries (PMID, title, authors, source, dates), and E-utility URLs.";
     const context = requestContextService.createRequestContext({ operation });
-    await ErrorHandler.tryCatch(() => {
-        server.tool("search_pubmed_articles", "Searches PubMed for articles using a query term and optional filters (max results, sort, date range, publication types). Uses NCBI ESearch to find PMIDs and ESummary (optional) for brief summaries. Returns a JSON object with search parameters, ESearch term, result counts, PMIDs, optional summaries (PMID, title, authors, source, dates), and E-utility URLs.", SearchPubMedArticlesInputSchema.shape, async (input, toolContext) => {
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(toolName, toolDescription, SearchPubMedArticlesInputSchema.shape, async (input, mcpProvidedContext) => {
             const richContext = requestContextService.createRequestContext({
                 parentRequestId: context.requestId,
                 operation: "searchPubMedArticlesToolHandler",
-                mcpToolContext: toolContext,
+                mcpToolContext: mcpProvidedContext,
+                input,
             });
-            return searchPubMedArticlesLogic(input, richContext);
+            try {
+                const result = await searchPubMedArticlesLogic(input, richContext);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                    isError: false,
+                };
+            }
+            catch (error) {
+                const handledError = ErrorHandler.handleError(error, {
+                    operation: "searchPubMedArticlesToolHandler",
+                    context: richContext,
+                    input,
+                    rethrow: false,
+                });
+                const mcpError = handledError instanceof McpError
+                    ? handledError
+                    : new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while searching PubMed articles.", {
+                        originalErrorName: handledError.name,
+                        originalErrorMessage: handledError.message,
+                    });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: {
+                                    code: mcpError.code,
+                                    message: mcpError.message,
+                                    details: mcpError.details,
+                                },
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
         });
-        logger.notice("Tool 'search_pubmed_articles' registered.", context);
+        logger.notice(`Tool '${toolName}' registered.`, context);
     }, {
         operation,
         context,

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