mcp-ts-template 1.4.8 → 1.5.0

package/README.md

@@ -3,7 +3,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-1.12.1-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--03--26-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.4.8-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.5.0-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/mcp-ts-template/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/mcp-ts-template?style=social)](https://github.com/cyanheads/mcp-ts-template)
@@ -91,7 +91,8 @@ Get the example server running in minutes:
 
 5.  **Run the Example Server:**
 
-    - **Via Stdio (Default):** Many MCP host applications will run this automatically using `stdio`. To run manually for testing:
+    - **Via Stdio (Default):** Many MCP host applications will run this automatically using `stdio`.
+      To run manually for testing:
       ```bash
       npm start
       # or 'npm run start:stdio'
@@ -120,13 +121,22 @@ Configure the MCP server's behavior using these environment variables:
 | `LOGS_DIR`                | Directory for log files.                                                                            | `logs/` (in project root)               |
 | `NODE_ENV`                | Runtime environment (`development`, `production`).                                                  | `development`                           |
 | `MCP_AUTH_SECRET_KEY`     | **Required for HTTP transport.** Secret key (min 32 chars) for signing/verifying auth tokens (JWT). | (none - **MUST be set in production**)  |
+| `MCP_AUTH_MODE`           | Authentication mode: `jwt` (default) or `oauth`.                                                    | `jwt`                                   |
+| `OAUTH_ISSUER_URL`        | **Required for `oauth` mode.** The issuer URL of your authorization server.                         | (none)                                  |
+| `OAUTH_AUDIENCE`          | **Required for `oauth` mode.** The audience identifier for this MCP server.                         | (none)                                  |
+| `OAUTH_JWKS_URI`          | **Optional for `oauth` mode.** The JWKS endpoint URL. If omitted, it's discovered from the issuer.  | (none)                                  |
 | `OPENROUTER_API_KEY`      | API key for OpenRouter.ai service. Optional, but service will be unconfigured without it.           | (none)                                  |
 | `LLM_DEFAULT_MODEL`       | Default model to use for LLM calls via OpenRouter.                                                  | `google/gemini-2.5-flash-preview-05-20` |
 | `LLM_DEFAULT_TEMPERATURE` | Default temperature for LLM calls (0-2). Optional.                                                  | (none)                                  |
 
 **Note on HTTP Port Retries:** If the `MCP_HTTP_PORT` is busy, the server automatically tries the next port (up to 15 times).
 
-**Security Note for HTTP Transport:** When using `MCP_TRANSPORT_TYPE=http`, authentication is **mandatory** as per the MCP specification. This template includes JWT-based authentication middleware (`src/mcp-server/transports/authentication/authMiddleware.ts`). You **MUST** set a strong, unique `MCP_AUTH_SECRET_KEY` in your production environment for this security mechanism to function correctly. Failure to do so will result in bypassed authentication checks in development and fatal errors in production.
+**Security Note for HTTP Transport:** When using `MCP_TRANSPORT_TYPE=http`, authentication is **mandatory** as per the MCP specification. This template supports two modes via `MCP_AUTH_MODE`:
+
+- **`jwt` (default):** A simple, self-contained JWT mode ideal for development. It requires the `MCP_AUTH_SECRET_KEY` to be set for signing and verifying tokens.
+- **`oauth`:** A production-ready OAuth 2.1 mode where the server validates Bearer tokens from an external Authorization Server. This requires `OAUTH_ISSUER_URL` and `OAUTH_AUDIENCE` to be configured.
+
+You **MUST** configure one of these modes for the security mechanism to function correctly when using the HTTP transport.
 
 ### 🔌 Client Configuration
 

package/dist/config/index.d.ts

@@ -44,6 +44,14 @@ export declare const config: {
     mcpAllowedOrigins: string[] | undefined;
     /** Auth secret key (JWTs, http transport). From `MCP_AUTH_SECRET_KEY`. CRITICAL. */
     mcpAuthSecretKey: string | undefined;
+    /** The authentication mode ('jwt' or 'oauth'). From `MCP_AUTH_MODE`. */
+    mcpAuthMode: "jwt" | "oauth";
+    /** OAuth 2.1 Issuer URL. From `OAUTH_ISSUER_URL`. */
+    oauthIssuerUrl: string | undefined;
+    /** OAuth 2.1 JWKS URI. From `OAUTH_JWKS_URI`. */
+    oauthJwksUri: string | undefined;
+    /** OAuth 2.1 Audience. From `OAUTH_AUDIENCE`. */
+    oauthAudience: string | undefined;
     /** OpenRouter App URL. From `OPENROUTER_APP_URL`. Default: "http://localhost:3000". */
     openrouterAppUrl: string;
     /** OpenRouter App Name. From `OPENROUTER_APP_NAME`. Defaults to `mcpServerName`. */

package/dist/config/index.js

@@ -95,6 +95,14 @@ const EnvSchema = z.object({
         .string()
         .min(32, "MCP_AUTH_SECRET_KEY must be at least 32 characters long for security reasons.")
         .optional(),
+    /** The authentication mode to use. 'jwt' for internal simple JWTs, 'oauth' for OAuth 2.1. Default: 'jwt'. */
+    MCP_AUTH_MODE: z.enum(["jwt", "oauth"]).default("jwt"),
+    /** The expected issuer URL for OAuth 2.1 access tokens. CRITICAL for validation. */
+    OAUTH_ISSUER_URL: z.string().url().optional(),
+    /** The JWKS (JSON Web Key Set) URI for the OAuth 2.1 provider. If not provided, it's often discoverable from the issuer URL. */
+    OAUTH_JWKS_URI: z.string().url().optional(),
+    /** The audience claim for the OAuth 2.1 access tokens. This server will reject tokens not intended for it. */
+    OAUTH_AUDIENCE: z.string().optional(),
     /** Optional. Application URL for OpenRouter integration. */
     OPENROUTER_APP_URL: z
         .string()
@@ -253,6 +261,14 @@ export const config = {
         .filter(Boolean),
     /** Auth secret key (JWTs, http transport). From `MCP_AUTH_SECRET_KEY`. CRITICAL. */
     mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
+    /** The authentication mode ('jwt' or 'oauth'). From `MCP_AUTH_MODE`. */
+    mcpAuthMode: env.MCP_AUTH_MODE,
+    /** OAuth 2.1 Issuer URL. From `OAUTH_ISSUER_URL`. */
+    oauthIssuerUrl: env.OAUTH_ISSUER_URL,
+    /** OAuth 2.1 JWKS URI. From `OAUTH_JWKS_URI`. */
+    oauthJwksUri: env.OAUTH_JWKS_URI,
+    /** OAuth 2.1 Audience. From `OAUTH_AUDIENCE`. */
+    oauthAudience: env.OAUTH_AUDIENCE,
     /** OpenRouter App URL. From `OPENROUTER_APP_URL`. Default: "http://localhost:3000". */
     openrouterAppUrl: env.OPENROUTER_APP_URL || "http://localhost:3000",
     /** OpenRouter App Name. From `OPENROUTER_APP_NAME`. Defaults to `mcpServerName`. */

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

@@ -33,6 +33,13 @@ export const registerCatFactFetcherTool = async (server) => {
                 inputSummary: { maxLength: params.maxLength },
             });
             logger.debug(`Handling '${toolName}' tool request.`, handlerContext);
+            // --- EXAMPLE: Scope-Based Authorization ---
+            // To protect this tool with OAuth 2.1 scopes, uncomment the following line.
+            // This requires the MCP_AUTH_MODE to be 'oauth' and the client's access token
+            // to contain the specified scope(s).
+            //
+            // withRequiredScopes(['facts:read']);
+            //
             return await ErrorHandler.tryCatch(async () => {
                 const responsePayload = await processCatFactFetcher(params, handlerContext);
                 logger.debug(`'${toolName}' tool processed successfully. Preparing result.`, handlerContext);

package/dist/mcp-server/transports/authentication/authContext.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Defines the AsyncLocalStorage context for authentication information.
+ * This module provides a mechanism to store and retrieve authentication details
+ * (like scopes and client ID) across asynchronous operations, making it available
+ * from the middleware layer down to the tool and resource handlers without
+ * drilling props.
+ *
+ * @module src/mcp-server/transports/authentication/authContext
+ */
+import { AsyncLocalStorage } from "async_hooks";
+import type { AuthInfo } from "./types.js";
+/**
+ * Defines the structure of the store used within the AsyncLocalStorage.
+ * It holds the authentication information for the current request context.
+ */
+interface AuthStore {
+    authInfo: AuthInfo;
+}
+/**
+ * An instance of AsyncLocalStorage to hold the authentication context (`AuthStore`).
+ * This allows `authInfo` to be accessible throughout the async call chain of a request
+ * after being set in the authentication middleware.
+ *
+ * @example
+ * // In middleware:
+ * await authContext.run({ authInfo }, next);
+ *
+ * // In a deeper handler:
+ * const store = authContext.getStore();
+ * const scopes = store?.authInfo.scopes;
+ */
+export declare const authContext: AsyncLocalStorage<AuthStore>;
+export {};

package/dist/mcp-server/transports/authentication/authContext.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Defines the AsyncLocalStorage context for authentication information.
+ * This module provides a mechanism to store and retrieve authentication details
+ * (like scopes and client ID) across asynchronous operations, making it available
+ * from the middleware layer down to the tool and resource handlers without
+ * drilling props.
+ *
+ * @module src/mcp-server/transports/authentication/authContext
+ */
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * An instance of AsyncLocalStorage to hold the authentication context (`AuthStore`).
+ * This allows `authInfo` to be accessible throughout the async call chain of a request
+ * after being set in the authentication middleware.
+ *
+ * @example
+ * // In middleware:
+ * await authContext.run({ authInfo }, next);
+ *
+ * // In a deeper handler:
+ * const store = authContext.getStore();
+ * const scopes = store?.authInfo.scopes;
+ */
+export const authContext = new AsyncLocalStorage();

package/dist/mcp-server/transports/authentication/authMiddleware.d.ts

@@ -16,14 +16,7 @@
  * @module src/mcp-server/transports/authentication/authMiddleware
  */
 import { HttpBindings } from "@hono/node-server";
-import { type AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
 import { Context, Next } from "hono";
-export type { AuthInfo };
-declare module "http" {
-    interface IncomingMessage {
-        auth?: AuthInfo;
-    }
-}
 /**
  * Hono middleware for verifying JWT Bearer token authentication.
  * It attaches authentication info to `c.env.incoming.auth` for SDK compatibility with the node server.

package/dist/mcp-server/transports/authentication/authMiddleware.js

@@ -18,6 +18,7 @@
 import jwt from "jsonwebtoken";
 import { config, environment } from "../../../config/index.js";
 import { logger, requestContextService } from "../../../utils/index.js";
+import { authContext } from "./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.");
@@ -47,11 +48,12 @@ export async function mcpAuthMiddleware(c, next) {
                 clientId: "dev-client-id",
                 scopes: ["dev-scope"],
             };
+            const authInfo = reqWithAuth.auth;
             logger.debug("Dev mode auth object created.", {
                 ...context,
-                authDetails: reqWithAuth.auth,
+                authDetails: authInfo,
             });
-            return await next();
+            return await authContext.run({ authInfo }, next);
         }
         else {
             logger.error("FATAL: MCP_AUTH_SECRET_KEY is missing in production. Cannot bypass auth.", context);
@@ -108,13 +110,14 @@ export async function mcpAuthMiddleware(c, next) {
             scopes: scopesFromToken,
         };
         const subClaimForLogging = typeof decoded.sub === "string" ? decoded.sub : undefined;
+        const authInfo = reqWithAuth.auth;
         logger.debug("JWT verified successfully. AuthInfo attached to request.", {
             ...context,
             mcpSessionIdContext: subClaimForLogging,
-            clientId: reqWithAuth.auth.clientId,
-            scopes: reqWithAuth.auth.scopes,
+            clientId: authInfo.clientId,
+            scopes: authInfo.scopes,
         });
-        await next();
+        await authContext.run({ authInfo }, next);
     }
     catch (error) {
         let errorMessage = "Invalid token";

package/dist/mcp-server/transports/authentication/authUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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
+ */
+/**
+ * Checks if the current authentication context contains all the specified scopes.
+ * This function is designed to be called within tool or resource handlers to
+ * enforce scope-based access control. It retrieves the authentication information
+ * from `authContext` (AsyncLocalStorage).
+ *
+ * @param requiredScopes - An array of scope strings that are mandatory for the operation.
+ * @throws {McpError} Throws an error with `BaseErrorCode.INTERNAL_ERROR` if the
+ *   authentication context is missing, which indicates a server configuration issue.
+ * @throws {McpError} Throws an error with `BaseErrorCode.FORBIDDEN` if one or
+ *   more required scopes are not present in the validated token.
+ */
+export declare function withRequiredScopes(requiredScopes: string[]): void;

package/dist/mcp-server/transports/authentication/authUtils.js

@@ -0,0 +1,45 @@
+/**
+ * @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
+ */
+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.
+ * This function is designed to be called within tool or resource handlers to
+ * enforce scope-based access control. It retrieves the authentication information
+ * from `authContext` (AsyncLocalStorage).
+ *
+ * @param requiredScopes - An array of scope strings that are mandatory for the operation.
+ * @throws {McpError} Throws an error with `BaseErrorCode.INTERNAL_ERROR` if the
+ *   authentication context is missing, which indicates a server configuration issue.
+ * @throws {McpError} Throws an error with `BaseErrorCode.FORBIDDEN` if one or
+ *   more required scopes are not present in the validated token.
+ */
+export function withRequiredScopes(requiredScopes) {
+    const store = authContext.getStore();
+    if (!store || !store.authInfo) {
+        // This is a server-side logic error; the auth middleware should always populate this.
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Authentication context is missing. This indicates a server configuration error.", requestContextService.createRequestContext({
+            operation: "withRequiredScopesCheck",
+            error: "AuthStore not found in AsyncLocalStorage.",
+        }));
+    }
+    const { scopes: grantedScopes, clientId } = store.authInfo;
+    const grantedScopeSet = new Set(grantedScopes);
+    const missingScopes = requiredScopes.filter((scope) => !grantedScopeSet.has(scope));
+    if (missingScopes.length > 0) {
+        const context = requestContextService.createRequestContext({
+            operation: "withRequiredScopesCheck",
+            required: requiredScopes,
+            granted: grantedScopes,
+            missing: missingScopes,
+            clientId: clientId,
+            subject: store.authInfo.subject,
+        });
+        logger.warning("Authorization failed: Missing required scopes.", context);
+        throw new McpError(BaseErrorCode.FORBIDDEN, `Insufficient permissions. Missing required scopes: ${missingScopes.join(", ")}`, { requiredScopes, missingScopes });
+    }
+}

package/dist/mcp-server/transports/authentication/oauthMiddleware.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Hono middleware for OAuth 2.1 Bearer Token validation.
+ * This middleware extracts a JWT from the Authorization header, validates it against
+ * a remote JWKS (JSON Web Key Set), and checks its issuer and audience claims.
+ * 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
+ */
+import { HttpBindings } from "@hono/node-server";
+import { Context, Next } from "hono";
+/**
+ * Hono middleware for verifying OAuth 2.1 JWT Bearer tokens.
+ * It validates the token and uses AsyncLocalStorage to pass auth info.
+ * @param c - The Hono context object.
+ * @param next - The function to call to proceed to the next middleware.
+ */
+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>;

package/dist/mcp-server/transports/authentication/oauthMiddleware.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Hono middleware for OAuth 2.1 Bearer Token validation.
+ * This middleware extracts a JWT from the Authorization header, validates it against
+ * a remote JWKS (JSON Web Key Set), and checks its issuer and audience claims.
+ * 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
+ */
+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";
+// --- Startup Validation ---
+// Ensures that necessary OAuth configuration is present when the mode is 'oauth'.
+if (config.mcpAuthMode === "oauth") {
+    if (!config.oauthIssuerUrl) {
+        throw new Error("OAUTH_ISSUER_URL must be set when MCP_AUTH_MODE is 'oauth'");
+    }
+    if (!config.oauthAudience) {
+        throw new Error("OAUTH_AUDIENCE must be set when MCP_AUTH_MODE is 'oauth'");
+    }
+    logger.info("OAuth 2.1 mode enabled. Verifying tokens against issuer.", requestContextService.createRequestContext({
+        issuer: config.oauthIssuerUrl,
+        audience: config.oauthAudience,
+    }));
+}
+// --- JWKS Client Initialization ---
+// The remote JWK set is fetched and cached to avoid network calls on every request.
+let jwks;
+if (config.mcpAuthMode === "oauth" && config.oauthIssuerUrl) {
+    try {
+        const jwksUrl = new URL(config.oauthJwksUri ||
+            `${config.oauthIssuerUrl.replace(/\/$/, "")}/.well-known/jwks.json`);
+        jwks = createRemoteJWKSet(jwksUrl, {
+            cooldownDuration: 300000, // 5 minutes
+            timeoutDuration: 5000, // 5 seconds
+        });
+        logger.info(`JWKS client initialized for URL: ${jwksUrl.href}`, requestContextService.createRequestContext({
+            operation: "oauthMiddlewareSetup",
+        }));
+    }
+    catch (error) {
+        logger.fatal("Failed to initialize JWKS client.", error, requestContextService.createRequestContext({
+            operation: "oauthMiddlewareSetup",
+        }));
+        // Prevent server from starting if JWKS setup fails in oauth mode
+        process.exit(1);
+    }
+}
+/**
+ * Hono middleware for verifying OAuth 2.1 JWT Bearer tokens.
+ * It validates the token and uses AsyncLocalStorage to pass auth info.
+ * @param c - The Hono context object.
+ * @param next - The function to call to proceed to the next middleware.
+ */
+export async function oauthMiddleware(c, next) {
+    const context = requestContextService.createRequestContext({
+        operation: "oauthMiddleware",
+        httpMethod: c.req.method,
+        httpPath: c.req.path,
+    });
+    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);
+    }
+    const authHeader = c.req.header("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        return c.json({ error: "Unauthorized: Missing or invalid token format." }, 401);
+    }
+    const token = authHeader.substring(7);
+    try {
+        const { payload } = await jwtVerify(token, jwks, {
+            issuer: config.oauthIssuerUrl,
+            audience: config.oauthAudience,
+        });
+        // The 'scope' claim is typically a space-delimited string in OAuth 2.1.
+        const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+        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);
+        }
+        const authInfo = {
+            token,
+            clientId,
+            scopes,
+            subject: typeof payload.sub === "string" ? payload.sub : undefined,
+        };
+        // Attach to the raw request for potential legacy compatibility and
+        // store in AsyncLocalStorage for modern, safe access in handlers.
+        c.env.incoming.auth = authInfo;
+        await authContext.run({ authInfo }, next);
+    }
+    catch (error) {
+        logger.warning("OAuth token validation failed", {
+            ...context,
+            errorName: error.name,
+            errorMessage: error.message,
+        });
+        // 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);
+    }
+}

package/dist/mcp-server/transports/authentication/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Shared types for authentication middleware.
+ * @module src/mcp-server/transports/authentication/types
+ */
+import type { AuthInfo as SdkAuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+/**
+ * Defines the structure for authentication information derived from a token.
+ * It extends the base SDK type to include common optional claims.
+ */
+export type AuthInfo = SdkAuthInfo & {
+    subject?: string;
+};
+declare module "http" {
+    interface IncomingMessage {
+        auth?: AuthInfo;
+    }
+}

package/dist/mcp-server/transports/authentication/types.js

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

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

@@ -20,7 +20,8 @@ import { randomUUID } from "node:crypto";
 import { config } from "../../config/index.js";
 import { BaseErrorCode, McpError } from "../../types-global/errors.js";
 import { logger, rateLimiter, requestContextService, } from "../../utils/index.js";
-import { mcpAuthMiddleware, } from "./authentication/authMiddleware.js";
+import { mcpAuthMiddleware } from "./authentication/authMiddleware.js";
+import { oauthMiddleware } from "./authentication/oauthMiddleware.js";
 /**
  * The port number for the HTTP transport, configured via `MCP_HTTP_PORT` environment variable.
  * Defaults to 3010 if not specified (default is managed by the config module).
@@ -57,6 +58,28 @@ const MAX_PORT_RETRIES = 15;
  * @private
  */
 const httpTransports = {};
+/**
+ * Stores the last activity timestamp for each session, keyed by session ID.
+ * Used for garbage collecting stale/abandoned sessions.
+ * @type {Record<string, number>}
+ * @private
+ */
+const sessionActivity = {};
+/**
+ * The timeout period in milliseconds for inactive sessions. If a session has no
+ * activity for this duration, it will be considered stale and garbage collected.
+ * Defaults to 30 minutes.
+ * @constant {number} SESSION_TIMEOUT_MS
+ * @private
+ */
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * The interval in milliseconds at which the session garbage collector runs to
+ * clean up stale sessions. Defaults to 1 minute.
+ * @constant {number} SESSION_GC_INTERVAL_MS
+ * @private
+ */
+const SESSION_GC_INTERVAL_MS = 60 * 1000; // 1 minute
 /**
  * Proactively checks if a specific network port is already in use.
  * @param port - The port number to check.
@@ -184,6 +207,24 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
         component: "HttpTransportSetup",
     });
     logger.debug("Setting up Hono app for HTTP transport...", transportContext);
+    // Start the session garbage collector
+    setInterval(() => {
+        const now = Date.now();
+        const gcContext = requestContextService.createRequestContext({
+            operation: "SessionGarbageCollector",
+        });
+        logger.debug("Running session garbage collector...", gcContext);
+        for (const sessionId in sessionActivity) {
+            if (now - sessionActivity[sessionId] > SESSION_TIMEOUT_MS) {
+                logger.info(`Session ${sessionId} timed out due to inactivity. Cleaning up.`, { ...gcContext, sessionId });
+                const transport = httpTransports[sessionId];
+                if (transport) {
+                    transport.close(); // This will trigger the onclose handler to delete it from httpTransports
+                }
+                delete sessionActivity[sessionId];
+            }
+        }
+    }, SESSION_GC_INTERVAL_MS);
     app.use("*", cors({
         origin: config.mcpAllowedOrigins || [],
         allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
@@ -211,9 +252,9 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
         await next();
     });
     app.use(MCP_ENDPOINT_PATH, async (c, next) => {
-        const rateLimitKey = c.req.header("x-forwarded-for") ||
-            c.req.header("host") ||
-            "unknown_ip_for_rate_limit";
+        const xff = c.req.header("x-forwarded-for");
+        const clientIp = xff ? xff.split(",")[0].trim() : "unknown_ip";
+        const rateLimitKey = clientIp || c.req.header("host") || "unknown_ip_for_rate_limit";
         const context = requestContextService.createRequestContext({
             operation: "httpRateLimitCheck",
             ipAddress: rateLimitKey,
@@ -248,7 +289,13 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
             }
         }
     });
-    app.use(MCP_ENDPOINT_PATH, mcpAuthMiddleware);
+    // Use the appropriate authentication middleware based on config
+    if (config.mcpAuthMode === "oauth") {
+        app.use(MCP_ENDPOINT_PATH, oauthMiddleware);
+    }
+    else {
+        app.use(MCP_ENDPOINT_PATH, mcpAuthMiddleware);
+    }
     app.post(MCP_ENDPOINT_PATH, async (c) => {
         const basePostContext = requestContextService.createRequestContext({
             ...transportContext,
@@ -269,6 +316,9 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
             sessionId,
         });
         let transport = sessionId ? httpTransports[sessionId] : undefined;
+        if (transport && sessionId) {
+            sessionActivity[sessionId] = Date.now(); // Update activity timestamp
+        }
         logger.debug(`Found existing transport for session ID: ${!!transport}`, {
             ...basePostContext,
             sessionId,
@@ -284,7 +334,7 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
                 if (transport) {
                     logger.warning("Received InitializeRequest on an existing session ID. Closing old session and creating new.", { ...basePostContext, sessionId });
                     await transport.close();
-                    delete httpTransports[sessionId];
+                    // onclose handler will delete from httpTransports and sessionActivity
                 }
                 logger.info("Handling Initialize Request: Creating new session...", {
                     ...basePostContext,
@@ -299,6 +349,7 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
                     onsessioninitialized: (newId) => {
                         logger.debug(`Session initialized callback triggered for ID: ${newId}`, { ...basePostContext, newSessionId: newId });
                         httpTransports[newId] = transport;
+                        sessionActivity[newId] = Date.now(); // Initialize activity timestamp
                         logger.info(`HTTP Session created: ${newId}`, {
                             ...basePostContext,
                             newSessionId: newId,
@@ -310,6 +361,7 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
                     if (closedSessionId) {
                         logger.debug(`onclose handler triggered for session ID: ${closedSessionId}`, { ...basePostContext, closedSessionId });
                         delete httpTransports[closedSessionId];
+                        delete sessionActivity[closedSessionId]; // Clean up activity tracker
                         logger.info(`HTTP Session closed: ${closedSessionId}`, {
                             ...basePostContext,
                             closedSessionId,
@@ -388,6 +440,9 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
             sessionId,
         });
         const transport = sessionId ? httpTransports[sessionId] : undefined;
+        if (transport && sessionId) {
+            sessionActivity[sessionId] = Date.now(); // Update activity timestamp
+        }
         logger.debug(`Found existing transport for session ID: ${!!transport}`, {
             ...baseSessionReqContext,
             sessionId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "1.4.8",
+  "version": "1.5.0",
   "description": "TypeScript template for building Model Context Protocol (MCP) Servers & Clients. Features extensive utilities (logger, requestContext, etc.), STDIO & Streamable HTTP (with authMiddleware), examples, and type safety. Ideal starting point for creating production-ready MCP Servers & Clients.",
   "main": "dist/index.js",
   "files": [
@@ -35,12 +35,12 @@
   },
   "dependencies": {
     "@duckdb/node-api": "^1.3.0-alpha.21",
-    "@hono/node-server": "^1.14.3",
+    "@hono/node-server": "^1.14.4",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@node-oauth/oauth2-server": "^5.2.0",
-    "@supabase/supabase-js": "^2.49.10",
+    "@supabase/supabase-js": "^2.50.0",
     "@types/jsonwebtoken": "^9.0.9",
-    "@types/node": "^22.15.30",
+    "@types/node": "^24.0.1",
     "@types/sanitize-html": "^2.16.0",
     "@types/validator": "13.15.1",
     "bcryptjs": "^3.0.2",
@@ -50,8 +50,9 @@
     "dotenv": "^16.5.0",
     "hono": "^4.7.11",
     "ignore": "^7.0.5",
+    "jose": "^6.0.11",
     "jsonwebtoken": "^9.0.2",
-    "openai": "^5.1.1",
+    "openai": "^5.3.0",
     "partial-json": "^0.1.7",
     "pg": "^8.16.0",
     "sanitize-html": "^2.17.0",
@@ -62,7 +63,7 @@
     "winston": "^3.17.0",
     "winston-daily-rotate-file": "^5.0.0",
     "yargs": "^18.0.0",
-    "zod": "^3.25.51"
+    "zod": "^3.25.62"
   },
   "keywords": [
     "typescript",