clinicaltrialsgov-mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -1,15 +1,15 @@
 # ClinicalTrials.gov 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.3-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-1.0.0-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.0.2-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-beta-orange.svg)](https://github.com/cyanheads/clinicaltrialsgov-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/clinicaltrialsgov-mcp-server?style=social)](https://github.com/cyanheads/clinicaltrialsgov-mcp-server)
 
 **Empower your AI agents with direct access to the official ClinicalTrials.gov database!**
 
-An MCP (Model Context Protocol) server providing a robust, developer-friendly interface to the official [ClinicalTrials.gov v2 API](https://clinicaltrials.gov/api/v2/docs). Enables LLMs and AI agents to search, retrieve, and analyze clinical study data programmatically.
+An MCP (Model Context Protocol) server providing a robust, developer-friendly interface to the official [ClinicalTrials.gov v2 API](https://clinicaltrials.gov/data-api/api). Enables LLMs and AI agents to search, retrieve, and analyze clinical study data programmatically.
 
 Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), this server follows a modular architecture with robust error handling, logging, and security features.
 
@@ -59,7 +59,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 authentication 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.
 
@@ -80,12 +80,31 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 
 - [Node.js (>=18.0.0)](https://nodejs.org/)
 - [npm](https://www.npmjs.com/) (comes with Node.js)
-- [Docker](https://www.docker.com/) (optional, for containerized deployment)
 
-### Install via npm (recommended)
+### MCP Client Settings
+
+Add the following to your MCP client's configuration file (e.g., `cline_mcp_settings.json`). This configuration uses `npx` to run the server, which will automatically install the package if not already present:
+
+```json
+{
+  "mcpServers": {
+    "clinicaltrialsgov-mcp-server": {
+      "command": "npx",
+      "args": ["clinicaltrialsgov-mcp-server"],
+      "env": {
+        "MCP_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+## If running manually (not via MCP client for development or testing)
+
+### Install via npm
 
 ```bash
-npm install @cyanheads/clinicaltrialsgov-mcp-server
+npm install clinicaltrialsgov-mcp-server
 ```
 
 ### Alternatively Install from Source
@@ -129,26 +148,6 @@ Configure the server using environment variables. These environmental variables
 | `LOGS_DIR`                 | Directory for log file storage (if `LOG_OUTPUT_MODE=file`).                              | `logs/`                   |
 | `NODE_ENV`                 | Runtime environment (`development`, `production`).                                       | `development`             |
 
-### MCP Client Settings
-
-Add the following to your MCP client's configuration file (e.g., `cline_mcp_settings.json`). This configuration uses `npx` to run the server, which will automatically install the package if not already present:
-
-```json
-{
-  "mcpServers": {
-    "clinicaltrialsgov-mcp-server": {
-      "command": "npx",
-      "args": ["@cyanheads/clinicaltrialsgov-mcp-server"],
-      "env": {
-        "MCP_LOG_LEVEL": "info"
-      },
-      "disabled": false,
-      "autoApprove": []
-    }
-  }
-}
-```
-
 ## Project Structure
 
 The codebase follows a modular structure within the `src/` directory:

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

@@ -38,19 +38,10 @@ export async function getStudyLogic(params, context) {
         toolInput: params,
     });
     const service = new ClinicalTrialsGovService();
-    try {
-        const study = await service.fetchStudy(params.nctId, context);
-        if (!study) {
-            throw new McpError(BaseErrorCode.NOT_FOUND, `Study with NCT ID '${params.nctId}' not found.`, { nctId: params.nctId });
-        }
-        logger.info(`Successfully fetched study ${params.nctId}`, { ...context });
-        return cleanStudy(study);
-    }
-    catch (error) {
-        // Re-throw service errors or wrap unexpected errors
-        if (error instanceof McpError) {
-            throw error;
-        }
-        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `An unexpected error occurred while fetching study ${params.nctId}.`, { originalError: error });
+    const study = await service.fetchStudy(params.nctId, context);
+    if (!study) {
+        throw new McpError(BaseErrorCode.NOT_FOUND, `Study with NCT ID '${params.nctId}' not found.`, { nctId: params.nctId });
     }
+    logger.info(`Successfully fetched study ${params.nctId}`, { ...context });
+    return cleanStudy(study);
 }

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

@@ -4,7 +4,6 @@
  */
 import { z } from "zod";
 import { ClinicalTrialsGovService, Status, } from "../../../services/clinical-trials-gov/index.js";
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { cleanStudy } from "../../../utils/clinicaltrials/jsonCleaner.js";
 import { logger } from "../../../utils/index.js";
 /**
@@ -90,18 +89,10 @@ export const ListStudiesInputSchema = z.object({
 export async function listStudiesLogic(params, context) {
     logger.debug("Executing listStudiesLogic", { ...context, toolInput: params });
     const service = new ClinicalTrialsGovService();
-    try {
-        const pagedStudies = await service.listStudies(params, context);
-        logger.info("Successfully listed studies.", { ...context });
-        if (pagedStudies.studies) {
-            pagedStudies.studies = pagedStudies.studies.map(cleanStudy);
-        }
-        return pagedStudies;
-    }
-    catch (error) {
-        if (error instanceof McpError) {
-            throw error;
-        }
-        throw new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while listing studies.", { originalError: error });
+    const pagedStudies = await service.listStudies(params, context);
+    logger.info("Successfully listed studies.", { ...context });
+    if (pagedStudies.studies) {
+        pagedStudies.studies = pagedStudies.studies.map(cleanStudy);
     }
+    return pagedStudies;
 }

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,10 +10,11 @@
  * 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";
@@ -23,8 +24,4 @@ import { Context, Next } from "hono";
  */
 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,22 +10,26 @@
  * 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";
+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 (environment === "production" && !config.mcpAuthSecretKey) {
-    logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment. 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.");
+if (config.mcpAuthMode === "jwt") {
+    if (environment === "production" && !config.mcpAuthSecretKey) {
+        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. JWT auth middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.");
+    }
 }
 /**
  * Hono middleware for verifying JWT Bearer token authentication.
@@ -39,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") {
@@ -57,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"
@@ -86,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) &&
@@ -102,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,
@@ -120,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 { 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,
@@ -96,22 +103,6 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
         ...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"],
@@ -128,131 +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);
-        }
+        // 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.", {
+        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,
+                });
+                await transport.close(); // This will trigger the onclose handler.
+            }
+            // 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,
-                        sessionId,
+                        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,
                     });
-                    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,
-                        });
-                    },
-                });
-                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.");
-            }
-            return await transport.handleRequest(c.env.incoming, c.env.outgoing, body);
+            };
+            // Connect the new transport to a new server instance.
+            const server = await createServerInstanceFn();
+            await server.connect(newTransport);
+            transport = newTransport;
         }
-        catch (err) {
-            const handledError = ErrorHandler.handleError(err, {
-                operation: "handlePost",
-                context: postContext,
-            });
-            const requestId = (await c.req.json().catch(() => ({})))?.id || null;
-            return c.json({
-                jsonrpc: "2.0",
-                error: { code: -32603, message: handledError.message },
-                id: requestId,
-            }, handledError instanceof McpError &&
-                handledError.code === BaseErrorCode.NOT_FOUND
-                ? 404
-                : 500);
+        else if (!transport) {
+            // If it's not an initialization request and no transport was found, it's an error.
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Invalid or expired session ID.");
         }
+        // Pass the request to the transport to handle.
+        return await transport.handleRequest(c.env.incoming, c.env.outgoing, body);
     });
-    const handleSessionReq = async (c) => {
-        const method = c.req.method;
-        const sessionReqContext = requestContextService.createRequestContext({
-            ...transportContext,
-            operation: `handle${method}`,
-        });
-        try {
-            const sessionId = c.req.header("mcp-session-id");
-            const transport = sessionId ? httpTransports[sessionId] : undefined;
-            if (!transport) {
-                throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.");
-            }
-            if (sessionId)
-                sessionActivity[sessionId] = Date.now();
-            return await transport.handleRequest(c.env.incoming, c.env.outgoing);
-        }
-        catch (err) {
-            const handledError = ErrorHandler.handleError(err, {
-                operation: `handle${method}`,
-                context: sessionReqContext,
-            });
-            return c.json({
-                jsonrpc: "2.0",
-                error: { code: -32603, message: handledError.message },
-                id: null,
-            }, handledError instanceof McpError &&
-                handledError.code === BaseErrorCode.NOT_FOUND
-                ? 404
-                : 500);
+    // A reusable handler for GET and DELETE requests which operate on existing sessions.
+    const handleSessionRequest = async (c) => {
+        const sessionId = c.req.header("mcp-session-id");
+        const transport = sessionId ? transports[sessionId] : undefined;
+        if (!transport) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.");
         }
+        // Let the transport handle the streaming (GET) or termination (DELETE) request.
+        return await transport.handleRequest(c.env.incoming, c.env.outgoing);
     };
-    app.get(MCP_ENDPOINT_PATH, handleSessionReq);
-    app.delete(MCP_ENDPOINT_PATH, handleSessionReq);
+    app.get(MCP_ENDPOINT_PATH, handleSessionRequest);
+    app.delete(MCP_ENDPOINT_PATH, handleSessionRequest);
     return startHttpServerWithRetry(app, HTTP_PORT, HTTP_HOST, MAX_PORT_RETRIES, transportContext);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clinicaltrialsgov-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A Model Context Protocol (MCP) Server providing LLM tools for the official ClinicalTrials.gov REST API. Search and retrieve clinical trial data, including study details and more",
   "main": "dist/index.js",
   "files": [
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.14.4",
-    "@modelcontextprotocol/sdk": "^1.12.3",
+    "@modelcontextprotocol/sdk": "^1.13.0",
     "@supabase/supabase-js": "^2.50.0",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^24.0.3",
@@ -44,11 +44,12 @@
     "@types/validator": "13.15.2",
     "chrono-node": "^2.8.0",
     "dotenv": "^16.5.0",
-    "hono": "^4.7.11",
+    "hono": "^4.8.2",
     "ignore": "^7.0.5",
     "jose": "^6.0.11",
     "jsonwebtoken": "^9.0.2",
-    "openai": "^5.5.0",
+    "npm": "^11.4.2",
+    "openai": "^5.6.0",
     "partial-json": "^0.1.7",
     "sanitize-html": "^2.17.0",
     "tiktoken": "^1.0.21",