mcp-ts-template 1.8.0 → 1.9.0

package/README.md

@@ -5,10 +5,10 @@
 **Build production-grade Model Context Protocol (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.1-green?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.17.4-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.8.0-blue?style=flat-square)](./CHANGELOG.md)
-[![Coverage](https://img.shields.io/badge/Coverage-65.8%25-brightgreen?style=flat-square)](./vitest.config.ts)
+[![Version](https://img.shields.io/badge/Version-1.9.0-blue?style=flat-square)](./CHANGELOG.md)
+[![Coverage](https://img.shields.io/badge/Coverage-46.52%25-brightgreen?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)
@@ -26,17 +26,18 @@ Building a robust server for AI agents is more than just writing code. It requir
 - **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.
+> **Note on src/mcp-client & src/agent:** The MCP client & Agent components have been enhanced and moved to the (Coming Soon)[**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                                            |
 | :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |
 | **🔌 MCP Server**           | A functional server with example tools and resources. Supports `stdio` and a **Streamable HTTP** transport built with [**Hono**](https://hono.dev/). | `src/mcp-server/`, `src/mcp-server/transports/`                      |
-| **🚀 Production Utilities** | Logging, Error Handling, ID Generation, Rate Limiting, Request Context tracking, Input Sanitization.                                                 | `src/utils/`                                                         |
+| **🔭 Observability**        | Built-in **OpenTelemetry** for distributed tracing and metrics. Auto-instrumentation for core modules and custom tracing for all tool executions.    | `src/utils/telemetry/`                                               |
+| **🚀 Production Utilities** | High-performance logging (Pino), Error Handling, ID Generation, Rate Limiting, Async Request Context, 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/`          |
+| **⚙️ Error Handling**       | Consistent error categorization (`JsonRpcErrorCode`), detailed logging, centralized handling (`ErrorHandler`).                                       | `src/utils/internal/errorHandler.ts`, `src/types-global/`            |
+| **📚 Documentation**        | Comprehensive `README.md`, structured JSDoc comments, API references, and a detailed [Migration Guide](./docs/migrations/v1.9.0.md).                 | `README.md`, Codebase, `tsdoc.json`, `docs/`                         |
 | **🕵️ 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/clinerules.md) 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/`                                                           |
@@ -48,12 +49,12 @@ Building a robust server for AI agents is more than just writing code. It requir
 
 This template is built on a set of architectural principles to ensure modularity, testability, and operational clarity.
 
-- **Core Server (`src/mcp-server/server.ts`)**: The central point where tools and resources are registered. It uses a `ManagedMcpServer` wrapper to provide enhanced introspection capabilities. It acts the same way as the native McpServer, but with additional features like introspection and enhanced error handling.
+- **Core Server (`src/mcp-server/server.ts`)**: The central point where tools and resources are registered using the standard `McpServer` from the SDK.
 - **Transports (`src/mcp-server/transports/`)**: The transport layer connects the core server to the outside world. It supports both `stdio` for direct process communication and a streamable **Hono**-based `http` server.
 - **"Logic Throws, Handler Catches"**: This is the immutable cornerstone of our error-handling strategy.
   - **Core Logic (`logic.ts`)**: This layer is responsible for pure, self-contained business logic. It **throws** a structured `McpError` on any failure.
-  - **Handlers (`registration.ts`)**: This layer interfaces with the server, invokes the core logic, and **catches** any errors. It is the exclusive location where errors are processed and formatted into a final response.
-- **Structured, Traceable Operations**: Every operation is traced from initiation to completion via a `RequestContext` that is passed through the entire call stack, ensuring comprehensive and structured logging.
+  - **Handlers (`registration.ts`)**: This layer interfaces with the server, invokes the core logic, and **catches** any errors using centralized utilities (`createToolHandler`). It is the exclusive location where errors are processed and formatted into a final response.
+- **Structured, Traceable Operations**: Every operation is traced from initiation to completion via a `RequestContext` that is implicitly available throughout the entire asynchronous call stack using Node.js's `AsyncLocalStorage`.
 
 ## Quick Start
 
@@ -78,11 +79,11 @@ npm run build
 
 - **Via Stdio (Default):**
   ```bash
-  npm run start:server
+  npm run start:stdio
   ```
 - **Via Streamable HTTP:**
   ```bash
-  npm run start:server:http
+  npm run start:http
   ```
 
 ### 4. Running Tests
@@ -106,18 +107,21 @@ This template uses [Vitest](https://vitest.dev/) for testing, with a strong emph
 
 Configure the server using these environment variables (or a `.env` file):
 
-| Variable              | Description                                                                               | Default                                |
-| :-------------------- | :---------------------------------------------------------------------------------------- | :------------------------------------- |
-| `MCP_TRANSPORT_TYPE`  | Server transport: `stdio` or `http`.                                                      | `stdio`                                |
-| `MCP_SESSION_MODE`    | Session mode for HTTP: `stateless`, `stateful`, or `auto`.                                | `auto`                                 |
-| `MCP_HTTP_PORT`       | Port for the HTTP server.                                                                 | `3010`                                 |
-| `MCP_HTTP_HOST`       | Host address for the HTTP server.                                                         | `127.0.0.1`                            |
-| `MCP_ALLOWED_ORIGINS` | Comma-separated allowed origins for CORS.                                                 | (none)                                 |
-| `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.                                                        | (none)                                 |
+| Variable                              | Description                                                                               | Default                                |
+| :------------------------------------ | :---------------------------------------------------------------------------------------- | :------------------------------------- |
+| `MCP_TRANSPORT_TYPE`                  | Server transport: `stdio` or `http`.                                                      | `stdio`                                |
+| `MCP_SESSION_MODE`                    | Session mode for HTTP: `stateless`, `stateful`, or `auto`.                                | `auto`                                 |
+| `MCP_HTTP_PORT`                       | Port for the HTTP server.                                                                 | `3010`                                 |
+| `MCP_HTTP_HOST`                       | Host address for the HTTP server.                                                         | `127.0.0.1`                            |
+| `MCP_ALLOWED_ORIGINS`                 | Comma-separated allowed origins for CORS.                                                 | (none)                                 |
+| `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.                                                        | (none)                                 |
+| `OTEL_ENABLED`                        | Set to `true` to enable OpenTelemetry instrumentation.                                    | `false`                                |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`  | The OTLP endpoint for exporting traces (e.g., `http://localhost:4318/v1/traces`).         | (none; logs to file)                   |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | The OTLP endpoint for exporting metrics (e.g., `http://localhost:4318/v1/metrics`).       | (none)                                 |
 
 ## 🏗️ Project Structure
 
@@ -146,13 +150,13 @@ This is the cornerstone of the architecture:
 
 1.  **`logic.ts`**: This file contains the pure business logic.
     - It defines the Zod schemas for input and output, which serve as the single source of truth for the tool's data contract.
-    - The core logic function is pure: it takes validated parameters and a request context, and either returns a result or **throws** a structured `McpError`.
+    - The core logic function is pure: it takes validated parameters and either returns a result or **throws** a structured `McpError`. It retrieves the request context via `getRequestContext()`.
     - It **never** contains `try...catch` blocks for formatting a final response.
 
 2.  **`registration.ts`**: This file is the "handler" that connects the logic to the MCP server.
     - It imports the schemas and logic function from `logic.ts`.
-    - It calls `server.registerTool()`, providing the tool's metadata and the runtime handler.
-    - The runtime handler **always** wraps the call to the logic function in a `try...catch` block. This is the **only** place where errors are caught, processed by the `ErrorHandler`, and formatted into a standardized error response.
+    - It calls `server.registerTool()`, providing the tool's metadata and the runtime handler created by the `createToolHandler` utility.
+    - The centralized handler **always** wraps the call to the logic function in a `try...catch` block. This is the **only** place where errors are caught, processed by the `ErrorHandler`, and formatted into a standardized error response.
 
 This pattern ensures that core logic remains decoupled, pure, and easily testable, while the registration layer handles all transport-level concerns, side effects, and response formatting.
 

package/dist/config/index.d.ts

@@ -4,87 +4,43 @@
  * environment variables and `package.json`. It uses Zod for schema validation
  * to ensure type safety and correctness of configuration parameters.
  *
- * Key responsibilities:
- * - Load environment variables from a `.env` file.
- * - Read `package.json` for default server name and version.
- * - Define a Zod schema for all expected environment variables.
- * - Validate environment variables against the schema.
- * - Construct and export a comprehensive `config` object.
- * - Export individual configuration values like `logLevel` and `environment` for convenience.
- *
  * @module src/config/index
  */
-/**
- * Main application configuration object.
- * Aggregates settings from validated environment variables and `package.json`.
- */
 export declare const config: {
-    /** Information from package.json. */
     pkg: {
         name: string;
         version: string;
     };
-    /** MCP server name. Env `MCP_SERVER_NAME` > `package.json` name > "mcp-ts-template". */
     mcpServerName: string;
-    /** MCP server version. Env `MCP_SERVER_VERSION` > `package.json` version > "0.0.0". */
     mcpServerVersion: string;
-    /** Logging level. From `MCP_LOG_LEVEL` env var. Default: "debug". */
     logLevel: string;
-    /** Absolute path to the logs directory. From `LOGS_DIR` env var. */
     logsPath: string | null;
-    /** Runtime environment. From `NODE_ENV` env var. Default: "development". */
     environment: string;
-    /** MCP transport type ('stdio' or 'http'). From `MCP_TRANSPORT_TYPE` env var. Default: "stdio". */
     mcpTransportType: "stdio" | "http";
-    /** MCP session mode ('stateless', 'stateful', 'auto'). From `MCP_SESSION_MODE` env var. Default: "auto". */
     mcpSessionMode: "stateless" | "stateful" | "auto";
-    /** HTTP server port (if http transport). From `MCP_HTTP_PORT` env var. Default: 3010. */
     mcpHttpPort: number;
-    /** HTTP server host (if http transport). From `MCP_HTTP_HOST` env var. Default: "127.0.0.1". */
     mcpHttpHost: string;
-    /** MCP endpoint path for HTTP transport. From `MCP_HTTP_ENDPOINT_PATH`. Default: "/mcp". */
     mcpHttpEndpointPath: string;
-    /** Max retries for port binding. From `MCP_HTTP_MAX_PORT_RETRIES`. Default: 15. */
     mcpHttpMaxPortRetries: number;
-    /** Delay between port binding retries. From `MCP_HTTP_PORT_RETRY_DELAY_MS`. Default: 50. */
     mcpHttpPortRetryDelayMs: number;
-    /** Timeout for stale stateful sessions. From `MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS`. Default: 1800000. */
     mcpStatefulSessionStaleTimeoutMs: number;
-    /** Array of allowed CORS origins (http transport). From `MCP_ALLOWED_ORIGINS` (comma-separated). */
     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" | "none";
-    /** 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;
-    /** Development mode client ID. From `DEV_MCP_CLIENT_ID`. */
     devMcpClientId: string | undefined;
-    /** Development mode scopes. From `DEV_MCP_SCOPES`. */
     devMcpScopes: 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`. */
     openrouterAppName: string;
-    /** OpenRouter API Key. From `OPENROUTER_API_KEY`. */
     openrouterApiKey: string | undefined;
-    /** Default LLM model. From `LLM_DEFAULT_MODEL`. */
     llmDefaultModel: string;
-    /** Default LLM temperature. From `LLM_DEFAULT_TEMPERATURE`. */
     llmDefaultTemperature: number | undefined;
-    /** Default LLM top_p. From `LLM_DEFAULT_TOP_P`. */
     llmDefaultTopP: number | undefined;
-    /** Default LLM max tokens. From `LLM_DEFAULT_MAX_TOKENS`. */
     llmDefaultMaxTokens: number | undefined;
-    /** Default LLM top_k. From `LLM_DEFAULT_TOP_K`. */
     llmDefaultTopK: number | undefined;
-    /** Default LLM min_p. From `LLM_DEFAULT_MIN_P`. */
     llmDefaultMinP: number | undefined;
-    /** OAuth Proxy configurations. Undefined if no related env vars are set. */
     oauthProxy: {
         authorizationUrl: string | undefined;
         tokenUrl: string | undefined;
@@ -93,21 +49,21 @@ export declare const config: {
         serviceDocumentationUrl: string | undefined;
         defaultClientRedirectUris: string[] | undefined;
     } | undefined;
-    /** Supabase configuration. Undefined if no related env vars are set. */
     supabase: {
         url: string;
         anonKey: string;
         serviceRoleKey: string | undefined;
     } | undefined;
+    openTelemetry: {
+        enabled: boolean;
+        serviceName: string;
+        serviceVersion: string;
+        tracesEndpoint: string | undefined;
+        metricsEndpoint: string | undefined;
+        samplingRatio: number;
+        logLevel: "NONE" | "ERROR" | "WARN" | "INFO" | "DEBUG" | "VERBOSE" | "ALL";
+    };
 };
-/**
- * Configured logging level for the application.
- * Exported for convenience.
- */
 export declare const logLevel: string;
-/**
- * Configured runtime environment ("development", "production", etc.).
- * Exported for convenience.
- */
 export declare const environment: string;
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA8SH;;;GAGG;AACH,eAAO,MAAM,MAAM;IACjB,qCAAqC;;;;;IAErC,wFAAwF;;IAExF,uFAAuF;;IAEvF,qEAAqE;;IAErE,oEAAoE;;IAEpE,4EAA4E;;IAE5E,mGAAmG;;IAEnG,4GAA4G;;IAE5G,yFAAyF;;IAEzF,gGAAgG;;IAEhG,4FAA4F;;IAE5F,mFAAmF;;IAEnF,4FAA4F;;IAE5F,2GAA2G;;IAE3G,oGAAoG;;IAIpG,oFAAoF;;IAEpF,wEAAwE;;IAExE,qDAAqD;;IAErD,iDAAiD;;IAEjD,iDAAiD;;IAEjD,4DAA4D;;IAE5D,sDAAsD;;IAEtD,uFAAuF;;IAEvF,oFAAoF;;IAEpF,qDAAqD;;IAErD,mDAAmD;;IAEnD,+DAA+D;;IAE/D,mDAAmD;;IAEnD,6DAA6D;;IAE7D,mDAAmD;;IAEnD,mDAAmD;;IAGnD,4EAA4E;;;;;;;;;IAqB5E,wEAAwE;;;;;;CASzE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAwB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoRH,eAAO,MAAM,MAAM;;cAhOiB,MAAM;iBAAW,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuS1D,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAwB,CAAC;AAChD,eAAO,MAAM,WAAW,EAAE,MAA2B,CAAC"}

package/dist/config/index.js

@@ -4,14 +4,6 @@
  * environment variables and `package.json`. It uses Zod for schema validation
  * to ensure type safety and correctness of configuration parameters.
  *
- * Key responsibilities:
- * - Load environment variables from a `.env` file.
- * - Read `package.json` for default server name and version.
- * - Define a Zod schema for all expected environment variables.
- * - Validate environment variables against the schema.
- * - Construct and export a comprehensive `config` object.
- * - Export individual configuration values like `logLevel` and `environment` for convenience.
- *
  * @module src/config/index
  */
 import dotenv from "dotenv";
@@ -21,13 +13,12 @@ import { fileURLToPath } from "url";
 import { z } from "zod";
 dotenv.config();
 // --- Determine Project Root ---
-/**
- * Finds the project root directory by searching upwards for package.json.
- * @param startDir The directory to start searching from.
- * @returns The absolute path to the project root, or throws an error if not found.
- */
 const findProjectRoot = (startDir) => {
     let currentDir = startDir;
+    // If the start directory is in `dist`, start searching from the parent directory.
+    if (path.basename(currentDir) === "dist") {
+        currentDir = path.dirname(currentDir);
+    }
     while (true) {
         const packageJsonPath = join(currentDir, "package.json");
         if (existsSync(packageJsonPath)) {
@@ -35,7 +26,6 @@ const findProjectRoot = (startDir) => {
         }
         const parentDir = dirname(currentDir);
         if (parentDir === currentDir) {
-            // Reached the root of the filesystem without finding package.json
             throw new Error(`Could not find project root (package.json) starting from ${startDir}`);
         }
         currentDir = parentDir;
@@ -43,165 +33,150 @@ const findProjectRoot = (startDir) => {
 };
 let projectRoot;
 try {
-    // For ESM, __dirname is not available directly.
-    // import.meta.url gives the URL of the current module.
     const currentModuleDir = dirname(fileURLToPath(import.meta.url));
     projectRoot = findProjectRoot(currentModuleDir);
 }
 catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     console.error(`FATAL: Error determining project root: ${errorMessage}`);
-    // Fallback to process.cwd() if project root cannot be determined.
-    // This might happen in unusual execution environments.
     projectRoot = process.cwd();
-    console.warn(`Warning: Using process.cwd() (${projectRoot}) as fallback project root.`);
-}
-// --- End Determine Project Root ---
-const pkgPath = join(projectRoot, "package.json"); // Use determined projectRoot
-let pkg = { name: "mcp-ts-template", version: "0.0.0" };
-try {
-    pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-}
-catch (error) {
     if (process.stdout.isTTY) {
-        console.error("Warning: Could not read package.json for default config values. Using hardcoded defaults.", error);
+        console.warn(`Warning: Using process.cwd() (${projectRoot}) as fallback project root.`);
     }
 }
+// --- End Determine Project Root ---
 /**
- * Zod schema for validating environment variables.
- * Provides type safety, validation, defaults, and clear error messages.
+ * Loads and parses the package.json file from the project root.
+ * @returns The parsed package.json object or a fallback default.
  * @private
  */
+const loadPackageJson = () => {
+    const pkgPath = join(projectRoot, "package.json");
+    const fallback = { name: "mcp-ts-template", version: "1.0.0" };
+    if (!existsSync(pkgPath)) {
+        if (process.stdout.isTTY) {
+            console.warn(`Warning: package.json not found at ${pkgPath}. Using fallback values. This is expected in some environments (e.g., Docker) but may indicate an issue with project root detection.`);
+        }
+        return fallback;
+    }
+    try {
+        const fileContents = readFileSync(pkgPath, "utf-8");
+        const parsed = JSON.parse(fileContents);
+        return {
+            name: typeof parsed.name === "string" ? parsed.name : fallback.name,
+            version: typeof parsed.version === "string" ? parsed.version : fallback.version,
+        };
+    }
+    catch (error) {
+        if (process.stdout.isTTY) {
+            console.error("Warning: Could not read or parse package.json. Using hardcoded defaults.", error);
+        }
+        return fallback;
+    }
+};
+const pkg = loadPackageJson();
 const EnvSchema = z.object({
-    /** Optional. The desired name for the MCP server. Defaults to `package.json` name. */
+    // --- Existing MCP and other variables ---
     MCP_SERVER_NAME: z.string().optional(),
-    /** Optional. The version of the MCP server. Defaults to `package.json` version. */
     MCP_SERVER_VERSION: z.string().optional(),
-    /** Minimum logging level. See `McpLogLevel` in logger utility. Default: "debug". */
     MCP_LOG_LEVEL: z.string().default("debug"),
-    /** Directory for log files. Defaults to "logs" in project root. */
     LOGS_DIR: z.string().default(path.join(projectRoot, "logs")),
-    /** Runtime environment (e.g., "development", "production"). Default: "development". */
     NODE_ENV: z.string().default("development"),
-    /** MCP communication transport ("stdio" or "http"). Default: "stdio". */
     MCP_TRANSPORT_TYPE: z.enum(["stdio", "http"]).default("stdio"),
-    /** MCP session mode ('stateless', 'stateful', 'auto'). Default: 'auto'. */
     MCP_SESSION_MODE: z.enum(["stateless", "stateful", "auto"]).default("auto"),
-    /** HTTP server port (if MCP_TRANSPORT_TYPE is "http"). Default: 3010. */
     MCP_HTTP_PORT: z.coerce.number().int().positive().default(3010),
-    /** HTTP server host (if MCP_TRANSPORT_TYPE is "http"). Default: "127.0.0.1". */
     MCP_HTTP_HOST: z.string().default("127.0.0.1"),
-    /** The endpoint path for the MCP server. Default: "/mcp". */
     MCP_HTTP_ENDPOINT_PATH: z.string().default("/mcp"),
-    /** Max retries for binding to a port if the initial one is in use. Default: 15. */
     MCP_HTTP_MAX_PORT_RETRIES: z.coerce.number().int().nonnegative().default(15),
-    /** Delay in ms between port binding retries. Default: 50. */
     MCP_HTTP_PORT_RETRY_DELAY_MS: z.coerce
         .number()
         .int()
         .nonnegative()
         .default(50),
-    /** Timeout in ms for considering a stateful session stale and eligible for cleanup. Default: 1800000 (30 minutes). */
     MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS: z.coerce
         .number()
         .int()
         .positive()
         .default(1_800_000),
-    /** Optional. Comma-separated allowed origins for CORS (HTTP transport). */
     MCP_ALLOWED_ORIGINS: z.string().optional(),
-    /** Optional. Secret key (min 32 chars) for auth tokens (HTTP transport). CRITICAL for production. */
     MCP_AUTH_SECRET_KEY: z
         .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, 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. */
     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. Client ID to use in development mode for JWT strategy. Default: "dev-client-id". */
     DEV_MCP_CLIENT_ID: z.string().optional(),
-    /** Optional. Comma-separated scopes for development mode JWT strategy. Default: "dev-scope". */
     DEV_MCP_SCOPES: z.string().optional(),
-    /** Optional. Application URL for OpenRouter integration. */
     OPENROUTER_APP_URL: z
         .string()
         .url("OPENROUTER_APP_URL must be a valid URL (e.g., http://localhost:3000)")
         .optional(),
-    /** Optional. Application name for OpenRouter. Defaults to MCP_SERVER_NAME or package name. */
     OPENROUTER_APP_NAME: z.string().optional(),
-    /** Optional. API key for OpenRouter services. */
     OPENROUTER_API_KEY: z.string().optional(),
-    /** Default LLM model. Default: "google/gemini-2.5-flash". */
     LLM_DEFAULT_MODEL: z.string().default("google/gemini-2.5-flash"),
-    /** Optional. Default LLM temperature (0.0-2.0). */
     LLM_DEFAULT_TEMPERATURE: z.coerce.number().min(0).max(2).optional(),
-    /** Optional. Default LLM top_p (0.0-1.0). */
     LLM_DEFAULT_TOP_P: z.coerce.number().min(0).max(1).optional(),
-    /** Optional. Default LLM max tokens (positive integer). */
     LLM_DEFAULT_MAX_TOKENS: z.coerce.number().int().positive().optional(),
-    /** Optional. Default LLM top_k (non-negative integer). */
     LLM_DEFAULT_TOP_K: z.coerce.number().int().nonnegative().optional(),
-    /** Optional. Default LLM min_p (0.0-1.0). */
     LLM_DEFAULT_MIN_P: z.coerce.number().min(0).max(1).optional(),
-    /** Optional. OAuth provider authorization endpoint URL. */
     OAUTH_PROXY_AUTHORIZATION_URL: z
         .string()
         .url("OAUTH_PROXY_AUTHORIZATION_URL must be a valid URL.")
         .optional(),
-    /** Optional. OAuth provider token endpoint URL. */
     OAUTH_PROXY_TOKEN_URL: z
         .string()
         .url("OAUTH_PROXY_TOKEN_URL must be a valid URL.")
         .optional(),
-    /** Optional. OAuth provider revocation endpoint URL. */
     OAUTH_PROXY_REVOCATION_URL: z
         .string()
         .url("OAUTH_PROXY_REVOCATION_URL must be a valid URL.")
         .optional(),
-    /** Optional. OAuth provider issuer URL. */
     OAUTH_PROXY_ISSUER_URL: z
         .string()
         .url("OAUTH_PROXY_ISSUER_URL must be a valid URL.")
         .optional(),
-    /** Optional. OAuth service documentation URL. */
     OAUTH_PROXY_SERVICE_DOCUMENTATION_URL: z
         .string()
         .url("OAUTH_PROXY_SERVICE_DOCUMENTATION_URL must be a valid URL.")
         .optional(),
-    /** Optional. Comma-separated default OAuth client redirect URIs. */
     OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS: z.string().optional(),
-    /** Supabase Project URL. From `SUPABASE_URL`. */
     SUPABASE_URL: z.string().url("SUPABASE_URL must be a valid URL.").optional(),
-    /** Supabase Anon Key (public). From `SUPABASE_ANON_KEY`. */
     SUPABASE_ANON_KEY: z.string().optional(),
-    /** Supabase Service Role Key (secret). From `SUPABASE_SERVICE_ROLE_KEY`. */
     SUPABASE_SERVICE_ROLE_KEY: z.string().optional(),
+    // --- START: OpenTelemetry Configuration ---
+    /** If 'true', OpenTelemetry will be initialized and enabled. Default: 'false'. */
+    OTEL_ENABLED: z
+        .string()
+        .transform((v) => v.toLowerCase() === "true")
+        .default("false"),
+    /** The logical name of the service. Defaults to MCP_SERVER_NAME or package name. */
+    OTEL_SERVICE_NAME: z.string().optional(),
+    /** The version of the service. Defaults to MCP_SERVER_VERSION or package version. */
+    OTEL_SERVICE_VERSION: z.string().optional(),
+    /** The OTLP endpoint for traces. If not set, traces are logged to a file in development. */
+    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: z.string().url().optional(),
+    /** The OTLP endpoint for metrics. If not set, metrics are not exported. */
+    OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: z.string().url().optional(),
+    /** Sampling ratio for traces (0.0 to 1.0). 1.0 means sample all. Default: 1.0 */
+    OTEL_TRACES_SAMPLER_ARG: z.coerce.number().min(0).max(1).default(1.0),
+    /** Log level for OpenTelemetry's internal diagnostic logger. Default: "INFO". */
+    OTEL_LOG_LEVEL: z
+        .enum(["NONE", "ERROR", "WARN", "INFO", "DEBUG", "VERBOSE", "ALL"])
+        .default("INFO"),
 });
 const parsedEnv = EnvSchema.safeParse(process.env);
 if (!parsedEnv.success) {
     if (process.stdout.isTTY) {
         console.error("❌ Invalid environment variables found:", parsedEnv.error.flatten().fieldErrors);
     }
-    // Consider throwing an error in production for critical misconfigurations.
 }
 const env = parsedEnv.success ? parsedEnv.data : EnvSchema.parse({});
-// --- Directory Ensurance Function ---
-/**
- * Ensures a directory exists and is within the project root.
- * @param dirPath The desired path for the directory (can be relative or absolute).
- * @param rootDir The root directory of the project to contain the directory.
- * @param dirName The name of the directory type for logging (e.g., "logs").
- * @returns The validated, absolute path to the directory, or null if invalid.
- */
 const ensureDirectory = (dirPath, rootDir, dirName) => {
     const resolvedDirPath = path.isAbsolute(dirPath)
         ? dirPath
         : path.resolve(rootDir, dirPath);
-    // Ensure the resolved path is within the project root boundary
     if (!resolvedDirPath.startsWith(rootDir + path.sep) &&
         resolvedDirPath !== rootDir) {
         if (process.stdout.isTTY) {
@@ -244,95 +219,53 @@ const ensureDirectory = (dirPath, rootDir, dirName) => {
     }
     return resolvedDirPath;
 };
-// --- End Directory Ensurance Function ---
-// --- Logs Directory Handling ---
 let validatedLogsPath = ensureDirectory(env.LOGS_DIR, projectRoot, "logs");
 if (!validatedLogsPath) {
     if (process.stdout.isTTY) {
         console.warn(`Warning: Custom logs directory ('${env.LOGS_DIR}') is invalid or outside the project boundary. Falling back to default.`);
     }
-    // Try again with the absolute default path
     const defaultLogsDir = path.join(projectRoot, "logs");
     validatedLogsPath = ensureDirectory(defaultLogsDir, projectRoot, "logs");
     if (!validatedLogsPath) {
         if (process.stdout.isTTY) {
-            // This is just a warning now, not fatal.
             console.warn("Warning: Default logs directory could not be created. File logging will be disabled.");
         }
-        // Do not exit. validatedLogsPath remains null, and the logger will handle it.
     }
 }
-// --- End Logs Directory Handling ---
-/**
- * Main application configuration object.
- * Aggregates settings from validated environment variables and `package.json`.
- */
 export const config = {
-    /** Information from package.json. */
     pkg,
-    /** MCP server name. Env `MCP_SERVER_NAME` > `package.json` name > "mcp-ts-template". */
     mcpServerName: env.MCP_SERVER_NAME || pkg.name,
-    /** MCP server version. Env `MCP_SERVER_VERSION` > `package.json` version > "0.0.0". */
     mcpServerVersion: env.MCP_SERVER_VERSION || pkg.version,
-    /** Logging level. From `MCP_LOG_LEVEL` env var. Default: "debug". */
     logLevel: env.MCP_LOG_LEVEL,
-    /** Absolute path to the logs directory. From `LOGS_DIR` env var. */
     logsPath: validatedLogsPath,
-    /** Runtime environment. From `NODE_ENV` env var. Default: "development". */
     environment: env.NODE_ENV,
-    /** MCP transport type ('stdio' or 'http'). From `MCP_TRANSPORT_TYPE` env var. Default: "stdio". */
     mcpTransportType: env.MCP_TRANSPORT_TYPE,
-    /** MCP session mode ('stateless', 'stateful', 'auto'). From `MCP_SESSION_MODE` env var. Default: "auto". */
     mcpSessionMode: env.MCP_SESSION_MODE,
-    /** HTTP server port (if http transport). From `MCP_HTTP_PORT` env var. Default: 3010. */
     mcpHttpPort: env.MCP_HTTP_PORT,
-    /** HTTP server host (if http transport). From `MCP_HTTP_HOST` env var. Default: "127.0.0.1". */
     mcpHttpHost: env.MCP_HTTP_HOST,
-    /** MCP endpoint path for HTTP transport. From `MCP_HTTP_ENDPOINT_PATH`. Default: "/mcp". */
     mcpHttpEndpointPath: env.MCP_HTTP_ENDPOINT_PATH,
-    /** Max retries for port binding. From `MCP_HTTP_MAX_PORT_RETRIES`. Default: 15. */
     mcpHttpMaxPortRetries: env.MCP_HTTP_MAX_PORT_RETRIES,
-    /** Delay between port binding retries. From `MCP_HTTP_PORT_RETRY_DELAY_MS`. Default: 50. */
     mcpHttpPortRetryDelayMs: env.MCP_HTTP_PORT_RETRY_DELAY_MS,
-    /** Timeout for stale stateful sessions. From `MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS`. Default: 1800000. */
     mcpStatefulSessionStaleTimeoutMs: env.MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS,
-    /** Array of allowed CORS origins (http transport). From `MCP_ALLOWED_ORIGINS` (comma-separated). */
     mcpAllowedOrigins: env.MCP_ALLOWED_ORIGINS?.split(",")
         .map((origin) => origin.trim())
         .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,
-    /** Development mode client ID. From `DEV_MCP_CLIENT_ID`. */
     devMcpClientId: env.DEV_MCP_CLIENT_ID,
-    /** Development mode scopes. From `DEV_MCP_SCOPES`. */
     devMcpScopes: env.DEV_MCP_SCOPES?.split(",").map((s) => s.trim()),
-    /** 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`. */
-    openrouterAppName: env.OPENROUTER_APP_NAME || pkg.name || "MCP TS App",
-    /** OpenRouter API Key. From `OPENROUTER_API_KEY`. */
+    openrouterAppName: env.OPENROUTER_APP_NAME || pkg.name || "mcp-ts-template",
     openrouterApiKey: env.OPENROUTER_API_KEY,
-    /** Default LLM model. From `LLM_DEFAULT_MODEL`. */
     llmDefaultModel: env.LLM_DEFAULT_MODEL,
-    /** Default LLM temperature. From `LLM_DEFAULT_TEMPERATURE`. */
     llmDefaultTemperature: env.LLM_DEFAULT_TEMPERATURE,
-    /** Default LLM top_p. From `LLM_DEFAULT_TOP_P`. */
     llmDefaultTopP: env.LLM_DEFAULT_TOP_P,
-    /** Default LLM max tokens. From `LLM_DEFAULT_MAX_TOKENS`. */
     llmDefaultMaxTokens: env.LLM_DEFAULT_MAX_TOKENS,
-    /** Default LLM top_k. From `LLM_DEFAULT_TOP_K`. */
     llmDefaultTopK: env.LLM_DEFAULT_TOP_K,
-    /** Default LLM min_p. From `LLM_DEFAULT_MIN_P`. */
     llmDefaultMinP: env.LLM_DEFAULT_MIN_P,
-    /** OAuth Proxy configurations. Undefined if no related env vars are set. */
     oauthProxy: env.OAUTH_PROXY_AUTHORIZATION_URL ||
         env.OAUTH_PROXY_TOKEN_URL ||
         env.OAUTH_PROXY_REVOCATION_URL ||
@@ -350,7 +283,6 @@ export const config = {
                 .filter(Boolean),
         }
         : undefined,
-    /** Supabase configuration. Undefined if no related env vars are set. */
     supabase: env.SUPABASE_URL && env.SUPABASE_ANON_KEY
         ? {
             url: env.SUPABASE_URL,
@@ -358,15 +290,16 @@ export const config = {
             serviceRoleKey: env.SUPABASE_SERVICE_ROLE_KEY,
         }
         : undefined,
+    openTelemetry: {
+        enabled: env.OTEL_ENABLED,
+        serviceName: env.OTEL_SERVICE_NAME || env.MCP_SERVER_NAME || pkg.name,
+        serviceVersion: env.OTEL_SERVICE_VERSION || env.MCP_SERVER_VERSION || pkg.version,
+        tracesEndpoint: env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+        metricsEndpoint: env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
+        samplingRatio: env.OTEL_TRACES_SAMPLER_ARG,
+        logLevel: env.OTEL_LOG_LEVEL,
+    },
 };
-/**
- * Configured logging level for the application.
- * Exported for convenience.
- */
 export const logLevel = config.logLevel;
-/**
- * Configured runtime environment ("development", "production", etc.).
- * Exported for convenience.
- */
 export const environment = config.environment;
 //# sourceMappingURL=index.js.map