mcp-ts-template 2.2.0 → 2.2.2

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-2.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--06--18-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.18.2-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/mcp-ts-template/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.22-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-83.55%25-brightgreen.svg?style=flat-square)](./coverage/lcov-report/)
+[![Version](https://img.shields.io/badge/Version-2.2.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--06--18-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.18.2-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/mcp-ts-template/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.22-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Code Coverage](https://img.shields.io/badge/Coverage-87.86%25-brightgreen.svg?style=flat-square)](./coverage/lcov-report/)
 
 </div>
 
@@ -30,18 +30,20 @@
 
 ### Installation
 
-1.
-**Clone the repository:**
+1.  **Clone the repository:**
+
 ```sh
 git clone https://github.com/cyanheads/mcp-ts-template.git
 ```
-2.
-**Navigate into the directory:**
+
+2.  **Navigate into the directory:**
+
 ```sh
 cd mcp-ts-template
 ```
-3.
-**Install dependencies:**
+
+3.  **Install dependencies:**
+
 ```sh
 bun install
 ```
@@ -60,7 +62,10 @@ This tool echoes back a message with optional formatting. You can find the full
 ```ts
 // Located at: src/mcp-server/tools/definitions/template-echo-message.tool.ts
 import { z } from 'zod';
-import type { SdkContext, ToolDefinition } from '@/mcp-server/tools/utils/toolDefinition.js';
+import type {
+  SdkContext,
+  ToolDefinition,
+} from '@/mcp-server/tools/utils/toolDefinition.js';
 import { withToolAuth } from '@/mcp-server/transports/auth/lib/withAuth.js';
 import { type RequestContext, logger } from '@/utils/index.js';
 
@@ -180,14 +185,14 @@ Like the tool, `echoResourceDefinition` is registered in `src/mcp-server/resourc
 
 All configuration is centralized and validated at startup in `src/config/index.ts`. Key environment variables in your `.env` file include:
 
-| Variable | Description | Default |
-| :--- | :--- | :--- |
-| `MCP_TRANSPORT_TYPE` | The transport to use: `stdio` or `http`. | `http` |
-| `MCP_HTTP_PORT` | The port for the HTTP server. | `3010` |
-| `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
+| Variable                | Description                                                                    | Default     |
+| :---------------------- | :----------------------------------------------------------------------------- | :---------- |
+| `MCP_TRANSPORT_TYPE`    | The transport to use: `stdio` or `http`.                                       | `http`      |
+| `MCP_HTTP_PORT`         | The port for the HTTP server.                                                  | `3010`      |
+| `MCP_AUTH_MODE`         | Authentication mode: `none`, `jwt`, or `oauth`.                                | `none`      |
 | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |
-| `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
-| `LOG_LEVEL` | The minimum level for logging. | `info` |
+| `OTEL_ENABLED`          | Set to `true` to enable OpenTelemetry.                                         | `false`     |
+| `LOG_LEVEL`             | The minimum level for logging.                                                 | `info`      |
 
 ### Authentication & Authorization
 
@@ -229,36 +234,36 @@ All configuration is centralized and validated at startup in `src/config/index.t
 
 ### Cloudflare Workers
 
-1.
-**Build the Worker bundle**:
+1.  **Build the Worker bundle**:
+
 ```sh
 bun build:worker
 ```
-2.
-**Run locally with Wrangler**:
+
+2.  **Run locally with Wrangler**:
+
 ```sh
 bun deploy:dev
 ```
-3.
-**Deploy to Cloudflare**:
-`sh
+
+3.  **Deploy to Cloudflare**:
+    `sh
 bun deploy:prod
-`
-> **Note**: The `wrangler.toml` file is pre-configured to enable `nodejs_compat` for best results.
+` > **Note**: The `wrangler.toml` file is pre-configured to enable `nodejs_compat` for best results.
 
 ## 📂 Project Structure
 
-| Directory | Purpose & Contents |
-| :--- | :--- |
-| `src/mcp-server/tools/definitions` | Your tool definitions (`*.tool.ts`). This is where you add new capabilities. |
+| Directory                              | Purpose & Contents                                                                   |
+| :------------------------------------- | :----------------------------------------------------------------------------------- |
+| `src/mcp-server/tools/definitions`     | Your tool definitions (`*.tool.ts`). This is where you add new capabilities.         |
 | `src/mcp-server/resources/definitions` | Your resource definitions (`*.resource.ts`). This is where you add new data sources. |
-| `src/mcp-server/transports` | Implementations for HTTP and STDIO transports, including auth middleware. |
-| `src/storage` | The `StorageService` abstraction and all storage provider implementations. |
-| `src/services` | Integrations with external services (e.g., the default OpenRouter LLM provider). |
-| `src/container` | Dependency injection container registrations and tokens. |
-| `src/utils` | Core utilities for logging, error handling, performance, security, and telemetry. |
-| `src/config` | Environment variable parsing and validation with Zod. |
-| `tests/` | Unit and integration tests, mirroring the `src/` directory structure. |
+| `src/mcp-server/transports`            | Implementations for HTTP and STDIO transports, including auth middleware.            |
+| `src/storage`                          | The `StorageService` abstraction and all storage provider implementations.           |
+| `src/services`                         | Integrations with external services (e.g., the default OpenRouter LLM provider).     |
+| `src/container`                        | Dependency injection container registrations and tokens.                             |
+| `src/utils`                            | Core utilities for logging, error handling, performance, security, and telemetry.    |
+| `src/config`                           | Environment variable parsing and validation with Zod.                                |
+| `tests/`                               | Unit and integration tests, mirroring the `src/` directory structure.                |
 
 ## 🧑‍💻 Agent Development Guide
 

package/dist/index.js

@@ -117226,10 +117226,55 @@ var z = /* @__PURE__ */ Object.freeze({
   quotelessJson,
   ZodError
 });
+
+// src/types-global/errors.ts
+var JsonRpcErrorCode;
+((JsonRpcErrorCode2) => {
+  JsonRpcErrorCode2[JsonRpcErrorCode2["ParseError"] = -32700] = "ParseError";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["InvalidRequest"] = -32600] = "InvalidRequest";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["MethodNotFound"] = -32601] = "MethodNotFound";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["InvalidParams"] = -32602] = "InvalidParams";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["InternalError"] = -32603] = "InternalError";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["ServiceUnavailable"] = -32000] = "ServiceUnavailable";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["NotFound"] = -32001] = "NotFound";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["Conflict"] = -32002] = "Conflict";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["RateLimited"] = -32003] = "RateLimited";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["Timeout"] = -32004] = "Timeout";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["Forbidden"] = -32005] = "Forbidden";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["Unauthorized"] = -32006] = "Unauthorized";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["ValidationError"] = -32007] = "ValidationError";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["ConfigurationError"] = -32008] = "ConfigurationError";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["InitializationFailed"] = -32009] = "InitializationFailed";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["DatabaseError"] = -32010] = "DatabaseError";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["SerializationError"] = -32070] = "SerializationError";
+  JsonRpcErrorCode2[JsonRpcErrorCode2["UnknownError"] = -32099] = "UnknownError";
+})(JsonRpcErrorCode ||= {});
+
+class McpError extends Error {
+  code;
+  data;
+  constructor(code, message, data, options) {
+    super(message, options);
+    this.code = code;
+    if (data) {
+      this.data = data;
+    }
+    this.name = "McpError";
+    Object.setPrototypeOf(this, McpError.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, McpError);
+    }
+  }
+}
+var ErrorSchema = z.object({
+  code: z.nativeEnum(JsonRpcErrorCode).describe("Standardized error code from JsonRpcErrorCode enum"),
+  message: z.string().min(1, "Error message cannot be empty.").describe("Detailed human-readable error message"),
+  data: z.record(z.string(), z.unknown()).optional().describe("Optional structured data providing more context about the error")
+}).describe("Schema for validating structured error objects, ensuring consistency in error reporting.");
 // package.json
 var package_default = {
   name: "mcp-ts-template",
-  version: "2.1.8",
+  version: "2.2.1",
   mcpName: "io.github.cyanheads/mcp-ts-template",
   description: "The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven architecture.",
   main: "dist/index.js",
@@ -117285,7 +117330,7 @@ var package_default = {
     inspector: "bunx mcp-inspector --config mcp.json --server mcp-ts-template",
     "db:duckdb-example": "MCP_LOG_LEVEL=debug tsc && node dist/storage/duckdbExample.js",
     test: "bun test --config vitest.config.ts",
-    "test:coverage": "bun test --coverage --config vitest.config.ts",
+    "test:coverage": "bun test --coverage",
     audit: "bun audit",
     "audit:fix": "bun audit --fix",
     "publish-mcp": "bun scripts/validate-mcp-publish-schema.ts"
@@ -117383,6 +117428,7 @@ var package_default = {
     "mcp",
     "model-context-protocol",
     "mcp-server",
+    "elicitation",
     "observability",
     "opentelemetry",
     "otel",
@@ -117420,7 +117466,7 @@ var package_default = {
 // src/config/index.ts
 var packageManifest = package_default;
 var hasFileSystemAccess = typeof process !== "undefined" && typeof process.versions === "object" && process.versions !== null && typeof process.versions.node === "string";
-import_dotenv.default.config();
+import_dotenv.default.config({ quiet: true });
 var emptyStringAsUndefined = (val) => {
   if (typeof val === "string" && val.trim() === "") {
     return;
@@ -117639,7 +117685,9 @@ var parseConfig = () => {
     if (process.stdout.isTTY) {
       console.error("❌ Invalid configuration found. Please check your environment variables.", parsedConfig.error.flatten().fieldErrors);
     }
-    process.exit(1);
+    throw new McpError(-32008 /* ConfigurationError */, "Invalid application configuration.", {
+      validationErrors: parsedConfig.error.flatten().fieldErrors
+    });
   }
   return parsedConfig.data;
 };
@@ -117728,54 +117776,9 @@ async function shutdownOpenTelemetry() {
 // src/index.ts
 var import_reflect_metadata2 = __toESM(require_Reflect(), 1);
 
-// src/utils/internal/errorHandler.ts
+// src/utils/internal/error-handler/errorHandler.ts
 var import_api3 = __toESM(require_src(), 1);
 
-// src/types-global/errors.ts
-var JsonRpcErrorCode;
-((JsonRpcErrorCode2) => {
-  JsonRpcErrorCode2[JsonRpcErrorCode2["ParseError"] = -32700] = "ParseError";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["InvalidRequest"] = -32600] = "InvalidRequest";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["MethodNotFound"] = -32601] = "MethodNotFound";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["InvalidParams"] = -32602] = "InvalidParams";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["InternalError"] = -32603] = "InternalError";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["ServiceUnavailable"] = -32000] = "ServiceUnavailable";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["NotFound"] = -32001] = "NotFound";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["Conflict"] = -32002] = "Conflict";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["RateLimited"] = -32003] = "RateLimited";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["Timeout"] = -32004] = "Timeout";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["Forbidden"] = -32005] = "Forbidden";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["Unauthorized"] = -32006] = "Unauthorized";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["ValidationError"] = -32007] = "ValidationError";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["ConfigurationError"] = -32008] = "ConfigurationError";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["InitializationFailed"] = -32009] = "InitializationFailed";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["DatabaseError"] = -32010] = "DatabaseError";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["SerializationError"] = -32070] = "SerializationError";
-  JsonRpcErrorCode2[JsonRpcErrorCode2["UnknownError"] = -32099] = "UnknownError";
-})(JsonRpcErrorCode ||= {});
-
-class McpError extends Error {
-  code;
-  data;
-  constructor(code, message, data, options) {
-    super(message, options);
-    this.code = code;
-    if (data) {
-      this.data = data;
-    }
-    this.name = "McpError";
-    Object.setPrototypeOf(this, McpError.prototype);
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, McpError);
-    }
-  }
-}
-var ErrorSchema = z.object({
-  code: z.nativeEnum(JsonRpcErrorCode).describe("Standardized error code from JsonRpcErrorCode enum"),
-  message: z.string().min(1, "Error message cannot be empty.").describe("Detailed human-readable error message"),
-  data: z.record(z.string(), z.unknown()).optional().describe("Optional structured data providing more context about the error")
-}).describe("Schema for validating structured error objects, ensuring consistency in error reporting.");
-
 // src/utils/internal/logger.ts
 var import_pino = __toESM(require_pino(), 1);
 
@@ -118461,7 +118464,7 @@ class Logger {
 }
 var logger = Logger.getInstance();
 
-// src/utils/internal/errorHandler.ts
+// src/utils/internal/error-handler/mappings.ts
 var ERROR_TYPE_MAPPINGS = {
   SyntaxError: -32007 /* ValidationError */,
   TypeError: -32007 /* ValidationError */,
@@ -118513,6 +118516,8 @@ var COMMON_ERROR_PATTERNS = [
     errorCode: -32007 /* ValidationError */
   }
 ];
+
+// src/utils/internal/error-handler/helpers.ts
 function createSafeRegex(pattern) {
   if (pattern instanceof RegExp) {
     let flags = pattern.flags.replace("g", "");
@@ -118539,23 +118544,23 @@ function getErrorName(error) {
   return `${typeof error}Encountered`;
 }
 function getErrorMessage(error) {
-  if (error instanceof Error) {
-    if ("errors" in error && Array.isArray(error.errors)) {
-      const inner = error.errors.map((e) => e instanceof Error ? e.message : String(e)).filter(Boolean).slice(0, 3).join("; ");
-      return inner ? `${error.message}: ${inner}` : error.message;
-    }
-    return error.message;
-  }
-  if (error === null) {
-    return "Null value encountered as error";
-  }
-  if (error === undefined) {
-    return "Undefined value encountered as error";
-  }
-  if (typeof error === "string") {
-    return error;
-  }
   try {
+    if (error instanceof Error) {
+      if ("errors" in error && Array.isArray(error.errors)) {
+        const inner = error.errors.map((e) => e instanceof Error ? e.message : String(e)).filter(Boolean).slice(0, 3).join("; ");
+        return inner ? `${error.message}: ${inner}` : error.message;
+      }
+      return error.message;
+    }
+    if (error === null) {
+      return "Null value encountered as error";
+    }
+    if (error === undefined) {
+      return "Undefined value encountered as error";
+    }
+    if (typeof error === "string") {
+      return error;
+    }
     if (typeof error === "number" || typeof error === "boolean") {
       return String(error);
     }
@@ -118578,11 +118583,12 @@ function getErrorMessage(error) {
       return error.toString();
     }
     return "[unrepresentable error]";
-  } catch (e) {
-    return `Error converting error to string: ${e instanceof Error ? e.message : "Unknown conversion error"}`;
+  } catch (conversionError) {
+    return `Error converting error to string: ${conversionError instanceof Error ? conversionError.message : "Unknown conversion error"}`;
   }
 }
 
+// src/utils/internal/error-handler/errorHandler.ts
 class ErrorHandler {
   static determineErrorCode(error) {
     if (error instanceof McpError) {
@@ -118730,12 +118736,14 @@ class ErrorHandler {
   static async tryCatch(fn, options) {
     try {
       return await Promise.resolve(fn());
-    } catch (error) {
-      throw ErrorHandler.handleError(error, { ...options, rethrow: true });
+    } catch (caughtError) {
+      throw ErrorHandler.handleError(caughtError, {
+        ...options,
+        rethrow: true
+      });
     }
   }
 }
-
 // src/utils/internal/runtime.ts
 var safeHas = (key) => {
   try {
@@ -118781,15 +118789,20 @@ var ATTR_MCP_TOOL_MEMORY_HEAP_USED_DELTA = "mcp.tool.memory_heap_used_bytes.delt
 
 // src/utils/internal/performance.ts
 var performanceNow = () => Date.now();
+async function loadPerfHooks() {
+  return import("perf_hooks");
+}
 async function initializePerformance_Hrt() {
   const globalWithPerf = globalThis;
   if (typeof globalWithPerf.performance?.now === "function") {
-    performanceNow = () => globalWithPerf.performance.now();
+    const perf = globalWithPerf.performance;
+    performanceNow = () => perf?.now() ?? Date.now();
   } else {
     try {
-      const { performance: nodePerformance } = await import("perf_hooks");
+      const { performance: nodePerformance } = await loadPerfHooks();
       performanceNow = () => nodePerformance.now();
     } catch (_e) {
+      performanceNow = () => Date.now();
       logger.warning("Could not import perf_hooks, falling back to Date.now() for performance timing.");
     }
   }
@@ -118801,7 +118814,8 @@ var toBytes = (payload) => {
   try {
     const json = JSON.stringify(payload);
     if (typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function") {
-      return Buffer.byteLength(json, "utf8");
+      const bytes = Buffer.byteLength(json, "utf8");
+      return bytes;
     }
     if (typeof TextEncoder !== "undefined") {
       return new TextEncoder().encode(json).length;
@@ -119228,9 +119242,12 @@ async function fetchWithTimeout(url, timeoutMs, context, options) {
   }
 }
 
+// src/index.ts
+var import_reflect_metadata3 = __toESM(require_Reflect(), 1);
+
 // src/container/index.ts
 var import_reflect_metadata = __toESM(require_Reflect(), 1);
-var import_tsyringe14 = __toESM(require_cjs3(), 1);
+var import_tsyringe15 = __toESM(require_cjs3(), 1);
 
 // src/container/registrations/core.ts
 var import_tsyringe6 = __toESM(require_cjs3(), 1);
@@ -125473,7 +125490,7 @@ var registerCoreServices = () => {
 };
 
 // src/container/registrations/mcp.ts
-var import_tsyringe13 = __toESM(require_cjs3(), 1);
+var import_tsyringe14 = __toESM(require_cjs3(), 1);
 
 // src/mcp-server/resources/resource-registration.ts
 var import_tsyringe7 = __toESM(require_cjs3(), 1);
@@ -128884,7 +128901,7 @@ var registerResources = (container3) => {
 };
 
 // src/mcp-server/server.ts
-var import_tsyringe12 = __toESM(require_cjs3(), 1);
+var import_tsyringe9 = __toESM(require_cjs3(), 1);
 
 // src/mcp-server/tools/tool-registration.ts
 var import_tsyringe8 = __toESM(require_cjs3(), 1);
@@ -129140,7 +129157,7 @@ var imageTestTool = {
   responseFormatter: responseFormatter3
 };
 
-// src/mcp-server/tools/definitions/template_madlibs_elicitation.tool.ts
+// src/mcp-server/tools/definitions/template-madlibs-elicitation.tool.ts
 var TOOL_NAME4 = "template_madlibs_elicitation";
 var TOOL_TITLE4 = "Mad Libs Elicitation Game";
 var TOOL_DESCRIPTION4 = "Plays a game of Mad Libs. If any parts of speech (noun, verb, adjective) are missing, it will use elicitation to ask the user for them.";
@@ -129178,7 +129195,10 @@ async function elicitAndValidate(partOfSpeech, sdkContext) {
   return validation.data;
 }
 async function madlibsToolLogic(input, appContext, sdkContext) {
-  logger.debug("Processing Mad Libs logic.", { ...appContext, toolInput: input });
+  logger.debug("Processing Mad Libs logic.", {
+    ...appContext,
+    toolInput: input
+  });
   const noun = input.noun ?? await elicitAndValidate("noun", sdkContext);
   const verb = input.verb ?? await elicitAndValidate("verb", sdkContext);
   const adjective = input.adjective ?? await elicitAndValidate("adjective", sdkContext);
@@ -129333,6 +129353,50 @@ var registerTools = (container3) => {
   }
 };
 
+// src/mcp-server/server.ts
+async function createMcpServerInstance() {
+  const context = requestContextService.createRequestContext({
+    operation: "createMcpServerInstance"
+  });
+  logger.info("Initializing MCP server instance", context);
+  requestContextService.configure({
+    appName: config.mcpServerName,
+    appVersion: config.mcpServerVersion,
+    environment: config.environment
+  });
+  const server = new McpServer({
+    name: config.mcpServerName,
+    version: config.mcpServerVersion,
+    description: config.mcpServerDescription
+  }, {
+    capabilities: {
+      logging: {},
+      resources: { listChanged: true },
+      tools: { listChanged: true },
+      elicitation: {}
+    }
+  });
+  try {
+    logger.debug("Registering resources and tools via registries...", context);
+    const toolRegistry = import_tsyringe9.container.resolve(ToolRegistry);
+    await toolRegistry.registerAll(server);
+    const resourceRegistry = import_tsyringe9.container.resolve(ResourceRegistry);
+    await resourceRegistry.registerAll(server);
+    logger.info("Resources and tools registered successfully", context);
+  } catch (err) {
+    logger.error("Failed to register resources/tools", {
+      ...context,
+      error: err instanceof Error ? err.message : String(err),
+      stack: err instanceof Error ? err.stack : undefined
+    });
+    throw err;
+  }
+  return server;
+}
+
+// src/mcp-server/transports/manager.ts
+var import_tsyringe13 = __toESM(require_cjs3(), 1);
+
 // node_modules/hono/dist/http-exception.js
 var HTTPException = class extends Error {
   res;
@@ -131995,7 +132059,7 @@ var cors = (options) => {
 import http from "http";
 import { randomUUID } from "node:crypto";
 // src/mcp-server/transports/auth/authFactory.ts
-var import_tsyringe11 = __toESM(require_cjs3(), 1);
+var import_tsyringe12 = __toESM(require_cjs3(), 1);
 
 // node_modules/jose/dist/webapi/lib/buffer_utils.js
 var encoder = new TextEncoder;
@@ -133513,7 +133577,7 @@ function createRemoteJWKSet(url, options) {
   return remoteJWKSet;
 }
 // src/mcp-server/transports/auth/strategies/jwtStrategy.ts
-var import_tsyringe9 = __toESM(require_cjs3(), 1);
+var import_tsyringe10 = __toESM(require_cjs3(), 1);
 class JwtStrategy {
   config;
   logger;
@@ -133616,9 +133680,9 @@ class JwtStrategy {
   }
 }
 JwtStrategy = __legacyDecorateClassTS([
-  import_tsyringe9.injectable(),
-  __legacyDecorateParamTS(0, import_tsyringe9.inject(AppConfig)),
-  __legacyDecorateParamTS(1, import_tsyringe9.inject(Logger2)),
+  import_tsyringe10.injectable(),
+  __legacyDecorateParamTS(0, import_tsyringe10.inject(AppConfig)),
+  __legacyDecorateParamTS(1, import_tsyringe10.inject(Logger2)),
   __legacyMetadataTS("design:paramtypes", [
     Object,
     Object
@@ -133626,7 +133690,7 @@ JwtStrategy = __legacyDecorateClassTS([
 ], JwtStrategy);
 
 // src/mcp-server/transports/auth/strategies/oauthStrategy.ts
-var import_tsyringe10 = __toESM(require_cjs3(), 1);
+var import_tsyringe11 = __toESM(require_cjs3(), 1);
 class OauthStrategy {
   config;
   logger;
@@ -133723,9 +133787,9 @@ class OauthStrategy {
   }
 }
 OauthStrategy = __legacyDecorateClassTS([
-  import_tsyringe10.injectable(),
-  __legacyDecorateParamTS(0, import_tsyringe10.inject(AppConfig)),
-  __legacyDecorateParamTS(1, import_tsyringe10.inject(Logger2)),
+  import_tsyringe11.injectable(),
+  __legacyDecorateParamTS(0, import_tsyringe11.inject(AppConfig)),
+  __legacyDecorateParamTS(1, import_tsyringe11.inject(Logger2)),
   __legacyMetadataTS("design:paramtypes", [
     Object,
     Object
@@ -133733,8 +133797,8 @@ OauthStrategy = __legacyDecorateClassTS([
 ], OauthStrategy);
 
 // src/mcp-server/transports/auth/authFactory.ts
-import_tsyringe11.container.register(JwtStrategy, { useClass: JwtStrategy });
-import_tsyringe11.container.register(OauthStrategy, { useClass: OauthStrategy });
+import_tsyringe12.container.register(JwtStrategy, { useClass: JwtStrategy });
+import_tsyringe12.container.register(OauthStrategy, { useClass: OauthStrategy });
 function createAuthStrategy() {
   const context = requestContextService.createRequestContext({
     operation: "createAuthStrategy",
@@ -133744,10 +133808,10 @@ function createAuthStrategy() {
   switch (config.mcpAuthMode) {
     case "jwt":
       logger.debug("Resolving JWT strategy from container.", context);
-      return import_tsyringe11.container.resolve(JwtStrategy);
+      return import_tsyringe12.container.resolve(JwtStrategy);
     case "oauth":
       logger.debug("Resolving OAuth strategy from container.", context);
-      return import_tsyringe11.container.resolve(OauthStrategy);
+      return import_tsyringe12.container.resolve(OauthStrategy);
     case "none":
       logger.info("Authentication is disabled ('none' mode).", context);
       return null;
@@ -133756,6 +133820,53 @@ function createAuthStrategy() {
       throw new Error(`Unknown authentication mode: ${String(config.mcpAuthMode)}`);
   }
 }
+// src/mcp-server/transports/auth/authMiddleware.ts
+function createAuthMiddleware(strategy) {
+  return async function authMiddleware(c, next) {
+    const context = requestContextService.createRequestContext({
+      operation: "authMiddleware",
+      additionalContext: {
+        method: c.req.method,
+        path: c.req.path
+      }
+    });
+    logger.debug("Initiating authentication check.", context);
+    const authHeader = c.req.header("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      logger.warning("Authorization header missing or invalid.", context);
+      throw new McpError(-32006 /* Unauthorized */, "Missing or invalid Authorization header. Bearer scheme required.", context);
+    }
+    const token = authHeader.substring(7);
+    if (!token) {
+      logger.warning("Bearer token is missing from Authorization header.", context);
+      throw new McpError(-32006 /* Unauthorized */, "Authentication token is missing.", context);
+    }
+    logger.debug("Extracted Bearer token, proceeding to verification.", context);
+    try {
+      const authInfo = await strategy.verify(token);
+      const authLogContext = {
+        ...context,
+        ...authInfo.tenantId ? { tenantId: authInfo.tenantId } : {},
+        clientId: authInfo.clientId,
+        subject: authInfo.subject,
+        scopes: authInfo.scopes
+      };
+      logger.info("Authentication successful. Auth context populated.", authLogContext);
+      await authContext.run({ authInfo }, next);
+    } catch (error2) {
+      logger.warning("Authentication verification failed.", {
+        ...context,
+        error: error2 instanceof Error ? error2.message : String(error2)
+      });
+      throw ErrorHandler.handleError(error2, {
+        operation: "authMiddlewareVerification",
+        context,
+        rethrow: true,
+        errorCode: -32006 /* Unauthorized */
+      });
+    }
+  };
+}
 // src/mcp-server/transports/http/httpErrorHandler.ts
 var httpErrorHandler = async (err, c) => {
   const context = requestContextService.createRequestContext({
@@ -133841,6 +133952,13 @@ var httpErrorHandler = async (err, c) => {
 };
 
 // src/mcp-server/transports/http/httpTransport.ts
+class McpSessionTransport extends StreamableHTTPTransport {
+  sessionId;
+  constructor(sessionId) {
+    super();
+    this.sessionId = sessionId;
+  }
+}
 function createHttpApp(mcpServer, parentContext) {
   const app = new Hono2;
   const transportContext = {
@@ -133875,14 +133993,22 @@ function createHttpApp(mcpServer, parentContext) {
       }
     });
   });
+  const authStrategy = createAuthStrategy();
+  if (authStrategy) {
+    const authMiddleware = createAuthMiddleware(authStrategy);
+    app.use(config.mcpHttpEndpointPath, authMiddleware);
+    logger.info("Authentication middleware enabled for MCP endpoint.", transportContext);
+  } else {
+    logger.info("Authentication is disabled; MCP endpoint is unprotected.", transportContext);
+  }
   app.all(config.mcpHttpEndpointPath, async (c) => {
     logger.debug("Handling MCP request.", {
       ...transportContext,
       path: c.req.path,
       method: c.req.method
     });
-    const transport = new StreamableHTTPTransport;
-    transport.sessionId = c.req.header("mcp-session-id") ?? randomUUID();
+    const sessionId = c.req.header("mcp-session-id") ?? randomUUID();
+    const transport = new McpSessionTransport(sessionId);
     const handleRpc = async () => {
       await mcpServer.connect(transport);
       const response = await transport.handleRequest(c);
@@ -133891,30 +134017,12 @@ function createHttpApp(mcpServer, parentContext) {
       }
       return c.body(null, 204);
     };
-    const protectRpc = config.mcpAuthMode !== "none";
     try {
-      if (!protectRpc) {
-        return await handleRpc();
-      }
-      const authHeader = c.req.header("Authorization");
-      if (!authHeader || !authHeader.startsWith("Bearer ")) {
-        logger.warning("Authorization header missing or invalid (HTTP JSON-RPC).", {
-          ...transportContext,
-          method: c.req.method,
-          path: c.req.path
-        });
-        throw new McpError(-32006 /* Unauthorized */, "Missing or invalid Authorization header. Bearer scheme required.", transportContext);
-      }
-      const strategy = createAuthStrategy();
-      if (!strategy) {
-        logger.warning("Auth mode indicates protection, but no strategy was created. Proceeding unauthenticated.", transportContext);
-        return await handleRpc();
+      const store = authContext.getStore();
+      if (store) {
+        return await authContext.run(store, handleRpc);
       }
-      const token = authHeader.substring(7);
-      const authInfo = await strategy.verify(token);
-      return await authContext.run({ authInfo }, async () => {
-        return await handleRpc();
-      });
+      return await handleRpc();
     } catch (err) {
       await transport.close?.();
       throw err instanceof Error ? err : new Error(String(err));
@@ -133985,7 +134093,25 @@ async function startHttpTransport(mcpServer, parentContext) {
   const app = createHttpApp(mcpServer, transportContext);
   const server = await startHttpServerWithRetry(app, config.mcpHttpPort, config.mcpHttpHost, config.mcpHttpMaxPortRetries, transportContext);
   logger.info("HTTP transport started successfully.", transportContext);
-  return { app, server };
+  return server;
+}
+async function stopHttpTransport(server, parentContext) {
+  const operationContext = {
+    ...parentContext,
+    operation: "stopHttpTransport",
+    transportType: "Http"
+  };
+  logger.info("Attempting to stop http transport...", operationContext);
+  return new Promise((resolve, reject) => {
+    server.close((err) => {
+      if (err) {
+        logger.error("Error closing HTTP server.", err, operationContext);
+        return reject(err);
+      }
+      logger.info("HTTP server closed successfully.", operationContext);
+      resolve();
+    });
+  });
 }
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
@@ -134102,6 +134228,7 @@ async function startStdioTransport(server, parentContext) {
    (MCP Spec: 2025-03-26 Stdio Transport)
 `);
     }
+    return server;
   } catch (err) {
     throw ErrorHandler.handleError(err, {
       operation: "connectStdioTransport",
@@ -134111,100 +134238,89 @@ async function startStdioTransport(server, parentContext) {
     });
   }
 }
-// src/mcp-server/server.ts
-async function createMcpServerInstance() {
-  const context = requestContextService.createRequestContext({
-    operation: "createMcpServerInstance"
-  });
-  logger.info("Initializing MCP server instance", context);
-  requestContextService.configure({
-    appName: config.mcpServerName,
-    appVersion: config.mcpServerVersion,
-    environment: config.environment
-  });
-  const server = new McpServer({
-    name: config.mcpServerName,
-    version: config.mcpServerVersion,
-    description: config.mcpServerDescription
-  }, {
-    capabilities: {
-      logging: {},
-      resources: { listChanged: true },
-      tools: { listChanged: true },
-      elicitation: {}
-    }
-  });
-  try {
-    logger.debug("Registering resources and tools via registries...", context);
-    const toolRegistry = import_tsyringe12.container.resolve(ToolRegistry);
-    await toolRegistry.registerAll(server);
-    const resourceRegistry = import_tsyringe12.container.resolve(ResourceRegistry);
-    await resourceRegistry.registerAll(server);
-    logger.info("Resources and tools registered successfully", context);
-  } catch (err) {
-    logger.error("Failed to register resources/tools", {
-      ...context,
-      error: err instanceof Error ? err.message : String(err),
-      stack: err instanceof Error ? err.stack : undefined
-    });
-    throw err;
+async function stopStdioTransport(server, parentContext) {
+  const operationContext = {
+    ...parentContext,
+    operation: "stopStdioTransport",
+    transportType: "Stdio"
+  };
+  logger.info("Attempting to stop stdio transport...", operationContext);
+  if (server) {
+    await server.close();
+    logger.info("Stdio transport stopped successfully.", operationContext);
   }
-  return server;
 }
-async function startTransport() {
-  const transportType = config.mcpTransportType;
-  const context = requestContextService.createRequestContext({
-    operation: "startTransport",
-    transport: transportType
-  });
-  logger.info(`Starting transport: ${transportType}`, context);
-  if (transportType === "http") {
-    const mcpServer = await createMcpServerInstance();
-    const { server } = await startHttpTransport(mcpServer, context);
-    return { server };
-  }
-  if (transportType === "stdio") {
-    const server = await createMcpServerInstance();
-    await startStdioTransport(server, context);
-    return { server };
-  }
-  logger.crit(`Unsupported transport type configured: ${transportType}`, context);
-  throw new Error(`Unsupported transport type: ${transportType}. Must be 'stdio' or 'http'.`);
-}
-async function initializeAndStartServer() {
-  const context = requestContextService.createRequestContext({
-    operation: "initializeAndStartServer"
-  });
-  logger.info("MCP Server initialization sequence started.", context);
-  try {
-    const result = await startTransport();
-    logger.info("MCP Server initialization sequence completed successfully.", context);
-    return result;
-  } catch (err) {
-    logger.crit("Critical error during MCP server initialization.", {
-      ...context,
-      error: err instanceof Error ? err.message : String(err),
-      stack: err instanceof Error ? err.stack : undefined
-    });
-    ErrorHandler.handleError(err, {
-      ...context,
-      operation: "initializeAndStartServer_Catch",
-      critical: true
+
+// src/mcp-server/transports/manager.ts
+class TransportManager {
+  config;
+  logger;
+  createMcpServer;
+  serverInstance = null;
+  constructor(config2, logger2, createMcpServer) {
+    this.config = config2;
+    this.logger = logger2;
+    this.createMcpServer = createMcpServer;
+  }
+  async start() {
+    const context = requestContextService.createRequestContext({
+      operation: "TransportManager.start",
+      transport: this.config.mcpTransportType
+    });
+    this.logger.info(`Starting transport: ${this.config.mcpTransportType}`, context);
+    const mcpServer = await this.createMcpServer();
+    if (this.config.mcpTransportType === "http") {
+      this.serverInstance = await startHttpTransport(mcpServer, context);
+    } else if (this.config.mcpTransportType === "stdio") {
+      this.serverInstance = await startStdioTransport(mcpServer, context);
+    } else {
+      const transportType = String(this.config.mcpTransportType);
+      const error2 = new Error(`Unsupported transport type: ${transportType}`);
+      this.logger.crit(error2.message, context);
+      throw error2;
+    }
+  }
+  async stop(signal) {
+    const context = requestContextService.createRequestContext({
+      operation: "TransportManager.stop",
+      signal
     });
-    logger.info("Exiting process due to critical initialization error.", context);
-    process.exit(1);
+    if (!this.serverInstance) {
+      this.logger.warning("Stop called but no active server instance found.", context);
+      return;
+    }
+    if (this.config.mcpTransportType === "http") {
+      await stopHttpTransport(this.serverInstance, context);
+    } else if (this.config.mcpTransportType === "stdio") {
+      await stopStdioTransport(this.serverInstance, context);
+    }
+  }
+  getServer() {
+    return this.serverInstance;
   }
 }
+TransportManager = __legacyDecorateClassTS([
+  import_tsyringe13.injectable(),
+  __legacyDecorateParamTS(0, import_tsyringe13.inject(AppConfig)),
+  __legacyDecorateParamTS(1, import_tsyringe13.inject(Logger2)),
+  __legacyDecorateParamTS(2, import_tsyringe13.inject(CreateMcpServerInstance)),
+  __legacyMetadataTS("design:paramtypes", [
+    typeof AppConfigType === "undefined" ? Object : AppConfigType,
+    Object,
+    Function
+  ])
+], TransportManager);
 
 // src/container/registrations/mcp.ts
 var registerMcpServices = () => {
-  import_tsyringe13.container.registerSingleton(ToolRegistry);
-  import_tsyringe13.container.registerSingleton(ResourceRegistry);
-  registerTools(import_tsyringe13.container);
-  registerResources(import_tsyringe13.container);
-  import_tsyringe13.container.register(CreateMcpServerInstance, {
+  import_tsyringe14.container.registerSingleton(ToolRegistry);
+  import_tsyringe14.container.registerSingleton(ResourceRegistry);
+  registerTools(import_tsyringe14.container);
+  registerResources(import_tsyringe14.container);
+  import_tsyringe14.container.register(CreateMcpServerInstance, {
     useValue: createMcpServerInstance
   });
+  import_tsyringe14.container.registerSingleton(TransportManagerToken, TransportManager);
   logger.info("MCP services and factories registered with the DI container.");
 };
 
@@ -134218,12 +134334,11 @@ function composeContainer() {
   registerMcpServices();
   isContainerComposed = true;
 }
-var container_default = import_tsyringe14.container;
+var container_default = import_tsyringe15.container;
 
 // src/index.ts
 var config2;
-var mcpStdioServer;
-var actualHttpServer;
+var transportManager;
 var isShuttingDown = false;
 var shutdown = async (signal) => {
   if (isShuttingDown) {
@@ -134236,25 +134351,9 @@ var shutdown = async (signal) => {
   });
   logger.info(`Received ${signal}. Initiating graceful shutdown...`, shutdownContext);
   try {
-    let closePromise = Promise.resolve();
-    const transportType = config2.mcpTransportType;
-    if (transportType === "stdio" && mcpStdioServer) {
-      logger.info("Attempting to close main MCP server (STDIO)...", shutdownContext);
-      closePromise = mcpStdioServer.close();
-    } else if (transportType === "http" && actualHttpServer) {
-      logger.info("Attempting to close HTTP server...", shutdownContext);
-      closePromise = new Promise((resolve, reject) => {
-        actualHttpServer.close((err) => {
-          if (err) {
-            logger.error("Error closing HTTP server.", err, shutdownContext);
-            return reject(err);
-          }
-          logger.info("HTTP server closed successfully.", shutdownContext);
-          resolve();
-        });
-      });
+    if (transportManager) {
+      await transportManager.stop(signal);
     }
-    await closePromise;
     logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
     await shutdownOpenTelemetry();
     await logger.close();
@@ -134268,8 +134367,16 @@ var shutdown = async (signal) => {
   }
 };
 var start = async () => {
-  composeContainer();
-  config2 = container_default.resolve(AppConfig);
+  try {
+    composeContainer();
+    config2 = container_default.resolve(AppConfig);
+  } catch (_error) {
+    if (process.stdout.isTTY) {
+      console.error("Halting due to critical configuration error.");
+    }
+    await shutdownOpenTelemetry();
+    process.exit(1);
+  }
   await initializePerformance_Hrt();
   const validMcpLogLevels = [
     "debug",
@@ -134293,21 +134400,16 @@ var start = async () => {
   await logger.initialize(validatedMcpLogLevel);
   logger.info(`Logger initialized. Effective MCP logging level: ${validatedMcpLogLevel}.`, requestContextService.createRequestContext({ operation: "LoggerInit" }));
   logger.info(`Storage service initialized with provider: ${config2.storage.providerType}`, requestContextService.createRequestContext({ operation: "StorageInit" }));
-  const transportType = config2.mcpTransportType;
+  transportManager = container_default.resolve(TransportManagerToken);
   const startupContext = requestContextService.createRequestContext({
-    operation: `ServerStartupSequence_${transportType}`,
+    operation: "ServerStartup",
     applicationName: config2.mcpServerName,
     applicationVersion: config2.mcpServerVersion,
     nodeEnvironment: config2.environment
   });
-  logger.info(`Starting ${config2.mcpServerName} (Version: ${config2.mcpServerVersion}, Transport: ${transportType}, Env: ${config2.environment})...`, startupContext);
+  logger.info(`Starting ${config2.mcpServerName} (v${config2.mcpServerVersion})...`, startupContext);
   try {
-    const { server } = await initializeAndStartServer();
-    if (transportType === "http") {
-      actualHttpServer = server;
-    } else if (transportType === "stdio") {
-      mcpStdioServer = server;
-    }
+    await transportManager.start();
     logger.info(`${config2.mcpServerName} is now running and ready.`, startupContext);
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
     process.on("SIGINT", () => void shutdown("SIGINT"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "mcpName": "io.github.cyanheads/mcp-ts-template",
   "description": "The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven architecture.",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     "inspector": "bunx mcp-inspector --config mcp.json --server mcp-ts-template",
     "db:duckdb-example": "MCP_LOG_LEVEL=debug tsc && node dist/storage/duckdbExample.js",
     "test": "bun test --config vitest.config.ts",
-    "test:coverage": "bun test --coverage --config vitest.config.ts",
+    "test:coverage": "bun test --coverage",
     "audit": "bun audit",
     "audit:fix": "bun audit --fix",
     "publish-mcp": "bun scripts/validate-mcp-publish-schema.ts"