mcp-ts-template 1.7.2 → 1.7.3

package/README.md

@@ -1,41 +1,47 @@
-# 🚀 MCP TypeScript Template: Agent, Server & Client
-
-[![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.17.0-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
-[![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--06--18-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.7.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-Stable-green.svg)](https://github.com/cyanheads/mcp-ts-template/issues)
+<div align="center">
+
+# 🚀 Model Context Protocol (MCP) Server TypeScript Template
+
+**Build production-grade MCP servers with a powerful, type-safe, and extensible foundation.**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue?style=flat-square)](https://www.typescriptlang.org/)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.17.0-green?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--06--18-lightgrey?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx)
+[![Version](https://img.shields.io/badge/Version-1.7.3-blue?style=flat-square)](./CHANGELOG.md)
+[![Coverage](https://img.shields.io/badge/Coverage-62.4%25-yellow?style=flat-square)](./vitest.config.ts)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+[![Status](https://img.shields.io/badge/Status-Stable-green?style=flat-square)](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)
 
-**Jumpstart your [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) development with this comprehensive TypeScript Template for building autonomous agents, servers, and clients.**
+</div>
 
-This template provides a solid, beginner-friendly foundation for building all components of the MCP ecosystem, adhering to the **MCP 2025-06-18 specification**. It includes a powerful agent framework, a fully-featured server, a robust client, production-ready utilities, and clear documentation to get you up and running quickly.
+This template provides a comprehensive foundation for building rich Model Context Protocol servers, adhering to the **MCP 2025-06-18 specification** and modern best practices. It includes a fully-featured server, production-ready utilities, and clear documentation to get you up and running quickly.
 
-## 🏛️ Three-Part Architecture
+## 🤔 Why Use This Template?
 
-This template is organized into three primary, interconnected components:
+Building a robust server for AI agents is more than just writing code. It requires a solid architecture, consistent error handling, and secure, type-safe practices from the ground up. This template solves these challenges by providing:
 
-1.  **🤖 Agent (`src/agent/`)**: An autonomous agent framework. The agent can connect to multiple MCP servers, discover their tools, and use them to accomplish complex tasks based on a user's prompt. Use this as a starting point for your agents.
-2.  **🔌 MCP Server (`src/mcp-server/`)**: An extensible MCP server that can host custom tools and resources, making them available to agents and other clients.
-3.  **💻 MCP Client (`src/mcp-client/`)**: A robust client for connecting to and interacting with any MCP-compliant server. The agent uses this client to communicate with the outside world.
+- **Accelerated Development**: Skip the boilerplate and focus on your tool's core logic.
+- **Production-Ready Foundation**: Built-in logging, error handling, security, and testing.
+- **Best Practices by Default**: Enforces a clean, modular architecture that's easy to maintain and extend.
+- **AI-Ready**: Designed with LLM agents in mind, including detailed schemas and rich LLM developer-friendly resources (e.g. .clinerules).
+
+> **Note on src/mcp-client & src/agent:** The MCP client & Agent components have been enhanced and moved to the [**atlas-mcp-agent**](https://github.com/cyanheads/atlas-mcp-agent) repository. This template now focuses exclusively on providing a best-in-class server implementation and framework.
 
 ## ✨ Key Features
 
-| Feature Area                | Description                                                                                                                                         | Key Components / Location                                            |
-| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |
-| **🤖 Agent Framework**      | Core `Agent` class and CLI for running autonomous agents that connect to MCP servers and use their tools to achieve goals.                          | `src/agent/`                                                         |
-| **🔌 MCP Server**           | Functional server with example tools (`EchoTool`, `CatFactFetcher`) and an `EchoResource`. Supports `stdio` and **Streamable HTTP** transports.     | `src/mcp-server/`                                                    |
-| **💻 MCP Client**           | Working client aligned with **MCP 2025-03-26 spec**. Connects via `mcp-config.json`. Includes detailed comments and isolated connection management. | `src/mcp-client/`                                                    |
-| **🚀 Production Utilities** | Logging, Error Handling, ID Generation, Rate Limiting, Request Context tracking, Input Sanitization.                                                | `src/utils/`                                                         |
-| **🔒 Type Safety/Security** | Strong type checking via TypeScript & Zod validation. Built-in security utilities (sanitization, auth middleware for HTTP).                         | Throughout, `src/utils/security/`, `src/mcp-server/transports/auth/` |
-| **⚙️ Error Handling**       | Consistent error categorization (`BaseErrorCode`), detailed logging, centralized handling (`ErrorHandler`).                                         | `src/utils/internal/errorHandler.ts`, `src/types-global/`            |
-| **📚 Documentation**        | Comprehensive `README.md`, structured JSDoc comments, API references.                                                                               | `README.md`, Codebase, `tsdoc.json`, `docs/api-references/`          |
-| **🕵️ Interaction Logging**  | Captures raw requests and responses for all external LLM provider interactions to a dedicated `interactions.log` file for full traceability.        | `src/utils/internal/logger.ts`                                       |
-| **🤖 Agent Ready**          | Includes a [.clinerules](.clinerules) developer cheatsheet tailored for LLM coding agents.                                                          | `.clinerules`                                                        |
-| **🛠️ Utility Scripts**      | Scripts for cleaning builds, setting executable permissions, generating directory trees, and fetching OpenAPI specs.                                | `scripts/`                                                           |
-| **Services**                | Reusable modules for LLM (OpenRouter) and data storage (DuckDB) integration, with examples.                                                         | `src/services/`, `src/storage/duckdbExample.ts`                      |
-| **🧪 Unit Testing**         | Integrated with Vitest for fast and reliable unit testing. Includes example tests for core tool logic and a coverage reporter.                      | `vitest.config.ts`, `tests/`                                         |
+| Feature Area                | Description                                                                                                                                     | Key Components / Location                                            |
+| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |
+| **🔌 MCP Server**           | Functional server with example tools (`EchoTool`, `CatFactFetcher`) and an `EchoResource`. Supports `stdio` and **Streamable HTTP** transports. | `src/mcp-server/`                                                    |
+| **🚀 Production Utilities** | Logging, Error Handling, ID Generation, Rate Limiting, Request Context tracking, Input Sanitization.                                            | `src/utils/`                                                         |
+| **🔒 Type Safety/Security** | Strong type checking via TypeScript & Zod validation. Built-in security utilities (sanitization, auth middleware for HTTP).                     | Throughout, `src/utils/security/`, `src/mcp-server/transports/auth/` |
+| **⚙️ Error Handling**       | Consistent error categorization (`BaseErrorCode`), detailed logging, centralized handling (`ErrorHandler`).                                     | `src/utils/internal/errorHandler.ts`, `src/types-global/`            |
+| **📚 Documentation**        | Comprehensive `README.md`, structured JSDoc comments, API references.                                                                           | `README.md`, Codebase, `tsdoc.json`, `docs/api-references/`          |
+| **🕵️ Interaction Logging**  | Captures raw requests and responses for all external LLM provider interactions to a dedicated `interactions.log` file for full traceability.    | `src/utils/internal/logger.ts`                                       |
+| **🤖 Agent Ready**          | Includes a [.clinerules](.clinerules) developer cheatsheet tailored for LLM coding agents.                                                      | `.clinerules`                                                        |
+| **🛠️ Utility Scripts**      | Scripts for cleaning builds, setting executable permissions, generating directory trees, and fetching OpenAPI specs.                            | `scripts/`                                                           |
+| **🧩 Services**             | Reusable modules for LLM (OpenRouter) and data storage (DuckDB) integration, with examples.                                                     | `src/services/`, `src/storage/duckdbExample.ts`                      |
+| **🧪 Unit Testing**         | Integrated with Vitest for fast and reliable unit testing. Includes example tests for core tool logic and a coverage reporter.                  | `vitest.config.ts`, `tests/`                                         |
 
 ## 🌟 Projects Using This Template
 
@@ -74,11 +80,7 @@ npm run build
 # Or use 'npm run rebuild' for a clean install
 ```
 
-### 3. Running the Components
-
-#### Running the MCP Server
-
-You can run the included MCP server to make its tools available.
+### 3. Running the Server
 
 - **Via Stdio (Default):**
   ```bash
@@ -89,17 +91,6 @@ You can run the included MCP server to make its tools available.
   npm run start:server:http
   ```
 
-#### Running the Agent
-
-The agent can be run from the command line to perform tasks. It will automatically connect to the servers defined in `src/mcp-client/client-config/mcp-config.json`. If running the agent, you must have the MCP config set up correctly and your openrouter API key configured in .env.
-
-```bash
-npm run start:agent "Your prompt here"
-
-# Example:
-npm run start:agent "Use the echo tool to say hello world and then get a cat fact."
-```
-
 ### 4. Running Tests
 
 This template uses [Vitest](https://vitest.dev/) for unit testing. Tests are located in the `tests/` directory, mirroring the `src/` structure.
@@ -129,22 +120,14 @@ Configure the MCP server's behavior using these environment variables:
 | `MCP_HTTP_PORT`       | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                  | `3010`                                 |
 | `MCP_HTTP_HOST`       | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                          | `127.0.0.1`                            |
 | `MCP_ALLOWED_ORIGINS` | Comma-separated allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).                  | (none)                                 |
-| `MCP_AUTH_MODE`       | Authentication mode for HTTP: `jwt` (default) or `oauth`.                                 | `jwt`                                  |
+| `MCP_AUTH_MODE`       | Authentication mode for HTTP: `jwt`, `oauth`, or `none`.                                  | `none`                                 |
 | `MCP_AUTH_SECRET_KEY` | **Required for `jwt` mode.** Secret key (min 32 chars) for signing/verifying auth tokens. | (none - **MUST be set in production**) |
 | `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)                                 |
-| `OPENROUTER_API_KEY`  | API key for OpenRouter.ai service. Required for the agent to function.                    | (none)                                 |
-
-### Client & Agent Configuration
-
-The agent uses the MCP client to connect to servers. This is configured in `src/mcp-client/client-config/mcp-config.json`. You must list all MCP servers the agent should connect to in this file.
-
-For a detailed guide, see the [Client Configuration README](src/mcp-client/client-config/README.md).
+| `OPENROUTER_API_KEY`  | API key for OpenRouter.ai service.                                                        | (none)                                 |
 
 ## 🏗️ Project Structure
 
-- **`src/agent/`**: Contains the core agent framework, including the `Agent` class and a CLI for running the agent.
-- **`src/mcp-client/`**: Implements the MCP client logic for connecting to and interacting with external MCP servers.
 - **`src/mcp-server/`**: Contains the MCP server implementation, including example tools, resources, and transport handlers.
 - **`src/config/`**: Handles loading and validation of environment variables and application configuration.
 - **`src/services/`**: Provides reusable modules for integrating with external services (DuckDB, OpenRouter).
@@ -166,10 +149,6 @@ npm run tree
 
 For detailed guidance on how to add your own custom Tools and Resources to the MCP server, please see the [Server Extension Guide](src/mcp-server/README.md).
 
-### Modifying the Agent
-
-The agent's core logic is in `src/agent/agent-core/agent.ts`. You can modify its system prompt, the models it uses (`google/gemini-2.5-flash` by default), and its decision-making loop to change its behavior.
-
 ## 🌍 Explore More MCP Resources
 
 Looking for more examples, guides, and pre-built MCP servers? Check out the companion repository:

package/dist/config/index.d.ts

@@ -45,7 +45,7 @@ export declare const config: {
     /** 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";
+    mcpAuthMode: "jwt" | "oauth" | "none";
     /** OAuth 2.1 Issuer URL. From `OAUTH_ISSUER_URL`. */
     oauthIssuerUrl: string | undefined;
     /** OAuth 2.1 JWKS URI. From `OAUTH_JWKS_URI`. */

package/dist/config/index.js

@@ -96,8 +96,8 @@ 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 authentication mode to use. 'jwt' for internal simple JWTs, 'oauth' for OAuth 2.1, or 'none'. Default: 'none'. */
+    MCP_AUTH_MODE: z.enum(["jwt", "oauth", "none"]).default("none"),
     /** 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. */

package/dist/mcp-server/server.js

@@ -21,8 +21,8 @@ import { registerEchoResource } from "./resources/echoResource/index.js";
 import { registerCatFactFetcherTool } from "./tools/catFactFetcher/index.js";
 import { registerEchoTool } from "./tools/echoTool/index.js";
 import { registerFetchImageTestTool } from "./tools/imageTest/index.js";
-import { startHttpTransport } from "./transports/httpTransport.js";
-import { connectStdioTransport } from "./transports/stdioTransport.js";
+import { startHttpTransport } from "./transports/http/index.js";
+import { startStdioTransport } from "./transports/stdio/index.js";
 /**
  * Creates and configures a new instance of the `McpServer`.
  *
@@ -77,11 +77,12 @@ async function startTransport() {
     });
     logger.info(`Starting transport: ${transportType}`, context);
     if (transportType === "http") {
-        return startHttpTransport(createMcpServerInstance, context);
+        const { server } = await startHttpTransport(createMcpServerInstance, context);
+        return server;
     }
     if (transportType === "stdio") {
         const server = await createMcpServerInstance();
-        await connectStdioTransport(server, context);
+        await startStdioTransport(server, context);
         return server;
     }
     throw new Error(`Unsupported transport type: ${transportType}. Must be 'stdio' or 'http'.`);

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

@@ -15,8 +15,7 @@ export const ECHO_MODES = ["standard", "uppercase", "lowercase"];
  * Zod schema defining the input parameters for the `echo_message` tool.
  * This schema is used by the MCP SDK to validate the arguments provided when the tool is called.
  */
-export const EchoToolInputSchema = z
-    .object({
+export const EchoToolInputSchema = z.object({
     message: z
         .string()
         .min(1, "Message cannot be empty.")

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

@@ -14,7 +14,9 @@ export const FetchImageTestInputSchema = z.object({
 });
 export const FetchImageTestResponseSchema = z.object({
     data: z.string().describe("Base64 encoded image data."),
-    mimeType: z.string().describe("The MIME type of the image (e.g., 'image/jpeg')."),
+    mimeType: z
+        .string()
+        .describe("The MIME type of the image (e.g., 'image/jpeg')."),
 });
 const CAT_API_URL = "https://cataas.com/cat";
 export async function fetchImageTestLogic(input, parentRequestContext) {

package/dist/mcp-server/transports/auth/authFactory.d.ts

@@ -0,0 +1,10 @@
+import { AuthStrategy } from "./strategies/authStrategy.js";
+/**
+ * Creates and returns an authentication strategy instance based on the
+ * application's configuration (`config.mcpAuthMode`).
+ *
+ * @returns An instance of a class that implements the `AuthStrategy` interface,
+ *          or `null` if authentication is disabled (`none`).
+ * @throws {Error} If the auth mode is unknown or misconfigured.
+ */
+export declare function createAuthStrategy(): AuthStrategy | null;

package/dist/mcp-server/transports/auth/authFactory.js

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Factory for creating an authentication strategy based on configuration.
+ * This module centralizes the logic for selecting and instantiating the correct
+ * authentication strategy, promoting loose coupling and easy extensibility.
+ * @module src/mcp-server/transports/auth/authFactory
+ */
+import { config } from "../../../config/index.js";
+import { JwtStrategy } from "./strategies/jwtStrategy.js";
+import { OauthStrategy } from "./strategies/oauthStrategy.js";
+/**
+ * Creates and returns an authentication strategy instance based on the
+ * application's configuration (`config.mcpAuthMode`).
+ *
+ * @returns An instance of a class that implements the `AuthStrategy` interface,
+ *          or `null` if authentication is disabled (`none`).
+ * @throws {Error} If the auth mode is unknown or misconfigured.
+ */
+export function createAuthStrategy() {
+    switch (config.mcpAuthMode) {
+        case "jwt":
+            return new JwtStrategy();
+        case "oauth":
+            return new OauthStrategy();
+        case "none":
+            return null; // No authentication
+        default:
+            // This ensures that if a new auth mode is added to the config type
+            // but not to this factory, we get a compile-time or runtime error.
+            throw new Error(`Unknown authentication mode: ${config.mcpAuthMode}`);
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Defines a unified Hono middleware for authentication.
+ * This middleware is strategy-agnostic. It extracts a Bearer token,
+ * delegates verification to the provided authentication strategy, and
+ * populates the async-local storage context with the resulting auth info.
+ * @module src/mcp-server/transports/auth/authMiddleware
+ */
+import type { HttpBindings } from "@hono/node-server";
+import type { Context, Next } from "hono";
+import type { AuthInfo } from "./lib/authTypes.js";
+import type { AuthStrategy } from "./strategies/authStrategy.js";
+declare module "http" {
+    interface IncomingMessage {
+        auth?: AuthInfo;
+    }
+}
+/**
+ * Creates a Hono middleware function that enforces authentication using a given strategy.
+ *
+ * @param strategy - An instance of a class that implements the `AuthStrategy` interface.
+ * @returns A Hono middleware function.
+ */
+export declare function createAuthMiddleware(strategy: AuthStrategy): (c: Context<{
+    Bindings: HttpBindings;
+}>, next: Next) => Promise<void>;

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

@@ -0,0 +1,48 @@
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { logger, requestContextService } from "../../../utils/index.js";
+import { authContext } from "./lib/authContext.js";
+/**
+ * Creates a Hono middleware function that enforces authentication using a given strategy.
+ *
+ * @param strategy - An instance of a class that implements the `AuthStrategy` interface.
+ * @returns A Hono middleware function.
+ */
+export function createAuthMiddleware(strategy) {
+    return async function authMiddleware(c, next) {
+        const context = requestContextService.createRequestContext({
+            operation: "authMiddleware",
+            method: c.req.method,
+            path: c.req.path,
+        });
+        const authHeader = c.req.header("Authorization");
+        if (!authHeader || !authHeader.startsWith("Bearer ")) {
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid Authorization header. Bearer scheme required.", context);
+        }
+        const token = authHeader.substring(7);
+        if (!token) {
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Authentication token is missing.", context);
+        }
+        try {
+            const authInfo = await strategy.verify(token);
+            // For logging and potential legacy use, attach to the raw request.
+            // The primary mechanism for access should be authContext.
+            c.env.incoming.auth = authInfo;
+            logger.debug("Authentication successful. Auth context populated.", {
+                ...context,
+                clientId: authInfo.clientId,
+                scopes: authInfo.scopes,
+            });
+            // Run the next middleware in the chain within the populated auth context.
+            await authContext.run({ authInfo }, next);
+        }
+        catch (error) {
+            // The strategy is expected to throw an McpError.
+            // We re-throw it here to be caught by the global httpErrorHandler.
+            logger.warning("Authentication verification failed.", {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    };
+}

package/dist/mcp-server/transports/auth/index.d.ts

@@ -3,8 +3,11 @@
  * 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";
+export { authContext } from "./lib/authContext.js";
+export { withRequiredScopes } from "./lib/authUtils.js";
+export type { AuthInfo } from "./lib/authTypes.js";
+export { createAuthStrategy } from "./authFactory.js";
+export { createAuthMiddleware } from "./authMiddleware.js";
+export { AuthStrategy } from "./strategies/authStrategy.js";
+export { JwtStrategy } from "./strategies/jwtStrategy.js";
+export { OauthStrategy } from "./strategies/oauthStrategy.js";

package/dist/mcp-server/transports/auth/index.js

@@ -3,7 +3,9 @@
  * 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";
+export { authContext } from "./lib/authContext.js";
+export { withRequiredScopes } from "./lib/authUtils.js";
+export { createAuthStrategy } from "./authFactory.js";
+export { createAuthMiddleware } from "./authMiddleware.js";
+export { JwtStrategy } from "./strategies/jwtStrategy.js";
+export { OauthStrategy } from "./strategies/oauthStrategy.js";

package/dist/mcp-server/transports/auth/{core → lib}/authTypes.d.ts

@@ -10,8 +10,3 @@ import type { AuthInfo as SdkAuthInfo } from "@modelcontextprotocol/sdk/server/a
 export type AuthInfo = SdkAuthInfo & {
     subject?: string;
 };
-declare module "http" {
-    interface IncomingMessage {
-        auth?: AuthInfo;
-    }
-}

package/dist/mcp-server/transports/auth/lib/authTypes.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Shared types for authentication middleware.
+ * @module src/mcp-server/transports/auth/core/auth.types
+ */
+export {};
+// The declaration for `http.IncomingMessage` is no longer needed here,
+// as the new architecture avoids direct mutation where possible and handles
+// the attachment within the Hono context.

package/dist/mcp-server/transports/auth/strategies/authStrategy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Defines the interface for all authentication strategies.
+ * This interface establishes a contract for verifying authentication tokens,
+ * ensuring that any authentication method (JWT, OAuth, etc.) can be used
+ * interchangeably by the core authentication middleware.
+ * @module src/mcp-server/transports/auth/strategies/AuthStrategy
+ */
+import type { AuthInfo } from "../lib/authTypes.js";
+export interface AuthStrategy {
+    /**
+     * Verifies an authentication token.
+     * @param token The raw token string extracted from the request.
+     * @returns A promise that resolves with the AuthInfo on successful verification.
+     * @throws {McpError} if the token is invalid, expired, or fails verification for any reason.
+     */
+    verify(token: string): Promise<AuthInfo>;
+}

package/dist/mcp-server/transports/auth/strategies/authStrategy.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp-server/transports/auth/strategies/jwtStrategy.d.ts

@@ -0,0 +1,7 @@
+import type { AuthInfo } from "../lib/authTypes.js";
+import type { AuthStrategy } from "./authStrategy.js";
+export declare class JwtStrategy implements AuthStrategy {
+    private readonly secretKey;
+    constructor();
+    verify(token: string): Promise<AuthInfo>;
+}

package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Implements the JWT authentication strategy.
+ * This module provides a concrete implementation of the AuthStrategy for validating
+ * JSON Web Tokens (JWTs). It encapsulates all logic related to JWT verification,
+ * including secret key management and payload validation.
+ * @module src/mcp-server/transports/auth/strategies/JwtStrategy
+ */
+import { jwtVerify } from "jose";
+import { config, environment } from "../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { logger } from "../../../../utils/index.js";
+export class JwtStrategy {
+    constructor() {
+        if (config.mcpAuthMode === "jwt") {
+            if (environment === "production" && !config.mcpAuthSecretKey) {
+                logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production for JWT auth.");
+                throw new Error("MCP_AUTH_SECRET_KEY must be set for JWT auth.");
+            }
+            else if (!config.mcpAuthSecretKey) {
+                logger.warning("MCP_AUTH_SECRET_KEY is not set. JWT auth will be bypassed (DEV ONLY).");
+                this.secretKey = null;
+            }
+            else {
+                this.secretKey = new TextEncoder().encode(config.mcpAuthSecretKey);
+            }
+        }
+        else {
+            this.secretKey = null;
+        }
+    }
+    async verify(token) {
+        // Handle development mode bypass
+        if (!this.secretKey) {
+            if (environment !== "production") {
+                logger.warning("Bypassing JWT verification: No secret key (DEV ONLY).");
+                return {
+                    token: "dev-mode-placeholder-token",
+                    clientId: "dev-client-id",
+                    scopes: ["dev-scope"],
+                };
+            }
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "Auth secret key is missing in production.");
+        }
+        try {
+            const { payload: decoded } = await jwtVerify(token, this.secretKey);
+            const clientId = typeof decoded.cid === "string"
+                ? decoded.cid
+                : typeof decoded.client_id === "string"
+                    ? decoded.client_id
+                    : undefined;
+            if (!clientId) {
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token: missing 'cid' or 'client_id' claim.");
+            }
+            let scopes = [];
+            if (Array.isArray(decoded.scp) &&
+                decoded.scp.every((s) => typeof s === "string")) {
+                scopes = decoded.scp;
+            }
+            else if (typeof decoded.scope === "string" && decoded.scope.trim()) {
+                scopes = decoded.scope.split(" ").filter(Boolean);
+            }
+            if (scopes.length === 0) {
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.");
+            }
+            return { token, clientId, scopes };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            const message = error instanceof Error && error.name === "JWTExpired"
+                ? "Token has expired."
+                : "Token verification failed.";
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, message, {
+                originalError: error instanceof Error ? error.name : "Unknown",
+            });
+        }
+    }
+}

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts

@@ -0,0 +1,7 @@
+import type { AuthInfo } from "../lib/authTypes.js";
+import type { AuthStrategy } from "./authStrategy.js";
+export declare class OauthStrategy implements AuthStrategy {
+    private readonly jwks;
+    constructor();
+    verify(token: string): Promise<AuthInfo>;
+}

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Implements the OAuth 2.1 authentication strategy.
+ * This module provides a concrete implementation of the AuthStrategy for validating
+ * JWTs against a remote JSON Web Key Set (JWKS), as is common in OAuth 2.1 flows.
+ * @module src/mcp-server/transports/auth/strategies/OauthStrategy
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { config } from "../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { logger } from "../../../../utils/index.js";
+export class OauthStrategy {
+    constructor() {
+        if (config.mcpAuthMode !== "oauth") {
+            throw new Error("OauthStrategy instantiated for non-oauth auth mode.");
+        }
+        if (!config.oauthIssuerUrl || !config.oauthAudience) {
+            throw new Error("OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.");
+        }
+        try {
+            const jwksUrl = new URL(config.oauthJwksUri ||
+                `${config.oauthIssuerUrl.replace(/\/$/, "")}/.well-known/jwks.json`);
+            this.jwks = createRemoteJWKSet(jwksUrl, {
+                cooldownDuration: 300000, // 5 minutes
+                timeoutDuration: 5000, // 5 seconds
+            });
+            logger.info(`JWKS client initialized for URL: ${jwksUrl.href}`);
+        }
+        catch (error) {
+            logger.fatal("Failed to initialize JWKS client.", error);
+            throw new Error("Could not initialize JWKS client for OAuth strategy.");
+        }
+    }
+    async verify(token) {
+        try {
+            const { payload } = await jwtVerify(token, this.jwks, {
+                issuer: config.oauthIssuerUrl,
+                audience: config.oauthAudience,
+            });
+            const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+            if (scopes.length === 0) {
+                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) {
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain a 'client_id' claim.");
+            }
+            return {
+                token,
+                clientId,
+                scopes,
+                subject: typeof payload.sub === "string" ? payload.sub : undefined,
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            const message = error instanceof Error && error.name === "JWTExpired"
+                ? "Token has expired."
+                : "OAuth token verification failed.";
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, message, {
+                originalError: error instanceof Error ? error.name : "Unknown",
+            });
+        }
+    }
+}

package/dist/mcp-server/transports/core/mcpTransportManager.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview MCP Transport Manager implementation using the MCP SDK.
+ * @module src/mcp-server/transports/core/mcpTransportManager
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IncomingMessage, ServerResponse } from "http";
+import { RequestContext } from "../../../utils/index.js";
+import { TransportManager, TransportResponse, TransportSession } from "./transportTypes.js";
+/**
+ * MCP Transport Manager that handles MCP SDK integration and session management.
+ */
+export declare class McpTransportManager implements TransportManager {
+    private readonly transports;
+    private readonly sessions;
+    private readonly createServerInstanceFn;
+    constructor(createServerInstanceFn: () => Promise<McpServer>);
+    initializeSession(body: unknown, context: RequestContext): Promise<TransportResponse>;
+    handleRequest(sessionId: string, req: IncomingMessage, res: ServerResponse, context: RequestContext, body?: unknown): Promise<void>;
+    handleDeleteRequest(sessionId: string, context: RequestContext): Promise<TransportResponse>;
+    getSession(sessionId: string): TransportSession | undefined;
+    shutdown(): Promise<void>;
+    /**
+     * Helper method to close a specific session.
+     */
+    private closeSession;
+    /**
+     * Find existing session that should be closed for re-initialization.
+     * This is a simplified implementation - in reality you might want more
+     * sophisticated session management.
+     */
+    private findExistingSessionForReinit;
+}