mcp-ts-template 1.1.8 → 1.2.1

package/README.md

@@ -1,9 +1,9 @@
 # MCP TypeScript Template 🚀
 
 [![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.11.0-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-1.11.2-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--03--26-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.1.8-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.2.1-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/mcp-ts-template/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/mcp-ts-template?style=social)](https://github.com/cyanheads/mcp-ts-template)
@@ -23,7 +23,7 @@ Whether you're creating a new MCP server to extend an AI's capabilities or integ
 | **🚀 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 stub for HTTP). | Throughout, `src/utils/security/`, `src/mcp-server/transports/authentication/` |
 | **⚙️ Error Handling**       | Consistent error categorization (`BaseErrorCode`), detailed logging, centralized handling (`ErrorHandler`).                      | `src/utils/internal/errorHandler.ts`, `src/types-global/`                      |
-| **📚 Documentation**        | Comprehensive `README.md`, inline JSDoc comments.                                                                                | `README.md`, Codebase                                                          |
+| **📚 Documentation**        | Comprehensive `README.md`, structured JSDoc comments (via `tsdoc.json`), API references.                                         | `README.md`, Codebase, `tsdoc.json`, `docs/api-references/`                    |
 | **🤖 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/`                                                                     |
 
@@ -71,7 +71,13 @@ Get the example server running in minutes:
     # Or use 'npm run rebuild' for a clean install (deletes node_modules, logs, dist)
     ```
 
-4.  **Run the Example Server:**
+4.  **Format the code (Optional but Recommended):**
+
+    ```bash
+    npm run format
+    ```
+
+5.  **Run the Example Server:**
 
     - **Via Stdio (Default):** Many MCP host applications will run this automatically using `stdio`. To run manually for testing:
       ```bash
@@ -90,26 +96,26 @@ Get the example server running in minutes:
 
 Configure the MCP server's behavior using these environment variables:
 
-| Variable                  | Description                                                                                         | Default                                |
-| :------------------------ | :-------------------------------------------------------------------------------------------------- | :------------------------------------- |
-| `MCP_TRANSPORT_TYPE`      | Server transport: `stdio` or `http`.                                                                | `stdio`                                |
-| `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_SERVER_NAME`         | Optional server name (used in MCP initialization).                                                  | (from package.json)                    |
-| `MCP_SERVER_VERSION`      | Optional server version (used in MCP initialization).                                               | (from package.json)                    |
-| `MCP_LOG_LEVEL`           | Server logging level (`debug`, `info`, `warning`, `error`, etc.).                                   | `info`                                 |
-| `NODE_ENV`                | Runtime environment (`development`, `production`).                                                  | `development`                          |
-| `MCP_AUTH_SECRET_KEY`     | **Required for HTTP transport.** Secret key (min 32 chars) for signing/verifying auth tokens (JWT). | (none - **MUST be set in production**) |
-| `APP_URL`                 | URL of the application (used by OpenRouter service for HTTP Referer).                               | `http://localhost:3000`                |
-| `APP_NAME`                | Name of the application (used by OpenRouter service for X-Title header).                            | (from package.json or 'MCP TS App')    |
-| `OPENROUTER_API_KEY`      | API key for OpenRouter.ai service. Optional, but service will be unconfigured without it.           | (none)                                 |
-| `LLM_DEFAULT_MODEL`       | Default model to use for LLM calls via OpenRouter.                                                  | `openrouter/auto`                      |
-| `LLM_DEFAULT_TEMPERATURE` | Default temperature for LLM calls (0-2). Optional.                                                  | (none)                                 |
-| `LLM_DEFAULT_TOP_P`       | Default top_p for LLM calls (0-1). Optional.                                                        | (none)                                 |
-| `LLM_DEFAULT_MAX_TOKENS`  | Default max_tokens for LLM calls. Optional.                                                         | (none)                                 |
-| `LLM_DEFAULT_TOP_K`       | Default top_k for LLM calls (non-negative integer). Optional.                                       | (none)                                 |
-| `LLM_DEFAULT_MIN_P`       | Default min_p for LLM calls (0-1). Optional.                                                        | (none)                                 |
+| Variable                  | Description                                                                                         | Default                                    |
+| :------------------------ | :-------------------------------------------------------------------------------------------------- | :----------------------------------------- |
+| `MCP_TRANSPORT_TYPE`      | Server transport: `stdio` or `http`.                                                                | `stdio`                                    |
+| `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_SERVER_NAME`         | Optional server name (used in MCP initialization).                                                  | (from package.json)                        |
+| `MCP_SERVER_VERSION`      | Optional server version (used in MCP initialization).                                               | (from package.json)                        |
+| `MCP_LOG_LEVEL`           | Server logging level (`debug`, `info`, `warning`, `error`, etc.).                                   | `info`                                     |
+| `NODE_ENV`                | Runtime environment (`development`, `production`).                                                  | `development`                              |
+| `MCP_AUTH_SECRET_KEY`     | **Required for HTTP transport.** Secret key (min 32 chars) for signing/verifying auth tokens (JWT). | (none - **MUST be set in production**)     |
+| `OPENROUTER_APP_URL`      | URL of the application (used by OpenRouter service for HTTP Referer).                               | `https://caseyjhand.com`                   |
+| `OPENROUTER_APP_NAME`     | Name of the application (used by OpenRouter service for X-Title header).                            | 'mcp-ts-template'                          |
+| `OPENROUTER_API_KEY`      | API key for OpenRouter.ai service. Optional, but service will be unconfigured without it.           | (none)                                     |
+| `LLM_DEFAULT_MODEL`       | Default model to use for LLM calls via OpenRouter.                                                  | `google/gemini-2.5-flash-preview:thinking` |
+| `LLM_DEFAULT_TEMPERATURE` | Default temperature for LLM calls (0-2). Optional.                                                  | (none)                                     |
+| `LLM_DEFAULT_TOP_P`       | Default top_p for LLM calls (0-1). Optional.                                                        | (none)                                     |
+| `LLM_DEFAULT_MAX_TOKENS`  | Default max_tokens for LLM calls. Optional.                                                         | (none)                                     |
+| `LLM_DEFAULT_TOP_K`       | Default top_k for LLM calls (non-negative integer). Optional.                                       | (none)                                     |
+| `LLM_DEFAULT_MIN_P`       | Default min_p for LLM calls (0-1). Optional.                                                        | (none)                                     |
 
 **Note on HTTP Port Retries:** If the `MCP_HTTP_PORT` is busy, the server automatically tries the next port (up to 15 times).
 
@@ -211,7 +217,7 @@ This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE
 |                          | Configuration                   | Environment-aware settings with Zod validation.                                                              | `src/config/`, `src/mcp-client/configLoader.ts`  |
 |                          | HTTP Transport                  | Express-based server with SSE, session management, CORS, port retries.                                       | `src/mcp-server/transports/httpTransport.ts`     |
 |                          | Stdio Transport                 | Handles MCP communication over standard input/output.                                                        | `src/mcp-server/transports/stdioTransport.ts`    |
-| **Utilities (Core)**     | Logger                          | Structured, context-aware logging (files & MCP notifications).                                               | `src/utils/internal/logger.ts`                   |
+| **Utilities (Core)**     | Logger                          | Structured, context-aware logging (files with rotation & MCP notifications).                                 | `src/utils/internal/logger.ts`                   |
 |                          | ErrorHandler                    | Centralized error processing, classification, and logging.                                                   | `src/utils/internal/errorHandler.ts`             |
 |                          | RequestContext                  | Request/operation tracking and correlation.                                                                  | `src/utils/internal/requestContext.ts`           |
 | **Utilities (Metrics)**  | TokenCounter                    | Estimates token counts using `tiktoken`.                                                                     | `src/utils/metrics/tokenCounter.ts`              |

package/dist/config/index.d.ts

@@ -1,82 +1,161 @@
+/**
+ * @fileoverview Loads, validates, and exports application configuration.
+ * This module centralizes configuration management, sourcing values from
+ * 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 config/index
+ */
 /**
  * Main application configuration object.
- * Aggregates settings from environment variables and package.json.
+ * This object aggregates settings from validated environment variables (`env`)
+ * and `package.json` (`pkg`), providing a single source of truth for configuration
+ * throughout the application.
+ *
+ * @constant {object} config
  */
 export declare const config: {
     /**
      * The name of the MCP server.
-     * Prioritizes MCP_SERVER_NAME env var, falls back to package.json name.
-     * Default: 'mcp-ts-template' (from package.json)
+     * Prioritizes the `MCP_SERVER_NAME` environment variable.
+     * If `MCP_SERVER_NAME` is not set, it falls back to the `name` property from `package.json`.
+     * If `package.json` is also unavailable, it uses the hardcoded default 'mcp-ts-template'.
+     * @type {string}
      */
     mcpServerName: string;
     /**
      * The version of the MCP server.
-     * Prioritizes MCP_SERVER_VERSION env var, falls back to package.json version.
-     * Default: (from package.json)
+     * Prioritizes the `MCP_SERVER_VERSION` environment variable.
+     * If `MCP_SERVER_VERSION` is not set, it falls back to the `version` property from `package.json`.
+     * If `package.json` is also unavailable, it uses the hardcoded default '0.0.0'.
+     * @type {string}
      */
     mcpServerVersion: string;
     /**
      * Logging level for the application (e.g., "debug", "info", "warning", "error").
-     * Controlled by MCP_LOG_LEVEL env var.
-     * Default: "info"
+     * Sourced from the `MCP_LOG_LEVEL` environment variable.
+     * Defaults to "info" if `MCP_LOG_LEVEL` is not set (as defined in `EnvSchema`).
+     * @type {string}
      */
     logLevel: string;
     /**
-     * The runtime environment (e.g., "development", "production").
-     * Controlled by NODE_ENV env var.
-     * Default: "development"
+     * The runtime environment of the application (e.g., "development", "production").
+     * Sourced from the `NODE_ENV` environment variable.
+     * Defaults to "development" if `NODE_ENV` is not set (as defined in `EnvSchema`).
+     * @type {string}
      */
     environment: string;
     /**
-     * Specifies the transport mechanism for the server.
-     * Controlled by MCP_TRANSPORT_TYPE env var. Options: 'stdio', 'http'.
-     * Default: "stdio"
+     * Specifies the transport mechanism for MCP server communication ('stdio' or 'http').
+     * Sourced from the `MCP_TRANSPORT_TYPE` environment variable.
+     * Defaults to "stdio" if `MCP_TRANSPORT_TYPE` is not set (as defined in `EnvSchema`).
+     * @type {"stdio" | "http"}
      */
     mcpTransportType: "stdio" | "http";
     /**
-     * The port number for the HTTP server to listen on (if MCP_TRANSPORT_TYPE is 'http').
-     * Controlled by MCP_HTTP_PORT env var.
-     * Default: 3010
+     * The port number for the HTTP server to listen on.
+     * Only applicable if `mcpTransportType` is 'http'.
+     * Sourced from the `MCP_HTTP_PORT` environment variable.
+     * Defaults to 3010 if `MCP_HTTP_PORT` is not set (as defined in `EnvSchema`).
+     * @type {number}
      */
     mcpHttpPort: number;
     /**
-     * The host address for the HTTP server to bind to (if MCP_TRANSPORT_TYPE is 'http').
-     * Controlled by MCP_HTTP_HOST env var.
-     * Default: "127.0.0.1"
+     * The host address for the HTTP server to bind to (e.g., "127.0.0.1", "0.0.0.0").
+     * Only applicable if `mcpTransportType` is 'http'.
+     * Sourced from the `MCP_HTTP_HOST` environment variable.
+     * Defaults to "127.0.0.1" if `MCP_HTTP_HOST` is not set (as defined in `EnvSchema`).
+     * @type {string}
      */
     mcpHttpHost: string;
     /**
-     * Comma-separated list of allowed origins for CORS requests when using the 'http' transport.
-     * Controlled by MCP_ALLOWED_ORIGINS env var.
-     * Default: undefined (meaning CORS might be restrictive by default in the transport layer)
+     * An array of allowed origins for CORS requests when using the 'http' transport.
+     * Derived from the `MCP_ALLOWED_ORIGINS` environment variable (comma-separated string).
+     * Each origin string is trimmed. Empty strings resulting from multiple commas are filtered out.
+     * If `MCP_ALLOWED_ORIGINS` is not set, this will be `undefined`.
+     * The HTTP transport layer should handle the `undefined` case appropriately (e.g., by applying default CORS policies).
+     * @type {string[] | undefined}
      */
     mcpAllowedOrigins: string[] | undefined;
     /**
-     * A secret key used for signing and verifying authentication tokens (e.g., JWT).
-     * MUST be set in production for HTTP transport security.
-     * Controlled by MCP_AUTH_SECRET_KEY env var.
-     * Default: undefined (Auth middleware should throw error if not set in production)
+     * The secret key used for signing and verifying authentication tokens (e.g., JWTs).
+     * This is critical for securing the HTTP transport if authentication is enabled.
+     * Sourced from the `MCP_AUTH_SECRET_KEY` environment variable.
+     * It's crucial that this key is kept confidential and is sufficiently complex.
+     * The `EnvSchema` enforces a minimum length of 32 characters.
+     * If not set, this will be `undefined`. The authentication middleware should handle this,
+     * potentially throwing an error if it's required but missing, especially in production.
+     * @type {string | undefined}
      */
     mcpAuthSecretKey: string | undefined;
-    appUrl: string;
-    appName: string;
+    /**
+     * The application URL for OpenRouter integration.
+     * Defaults to "http://localhost:3000" if `OPENROUTER_APP_URL` is not set.
+     * @type {string}
+     */
+    openrouterAppUrl: string;
+    /**
+     * The application name for OpenRouter integration.
+     * Defaults to `mcpServerName` (which itself defaults to `pkg.name` or "MCP TS App") if `OPENROUTER_APP_NAME` is not set.
+     * @type {string}
+     */
+    openrouterAppName: string;
+    /**
+     * The API key for OpenRouter services.
+     * Sourced from `OPENROUTER_API_KEY` environment variable. No default is provided here;
+     * the service using this key should handle its absence (e.g., by disabling features or erroring).
+     * @type {string | undefined}
+     */
     openrouterApiKey: string | undefined;
+    /**
+     * Default model for LLM operations.
+     * @type {string}
+     */
     llmDefaultModel: string;
+    /**
+     * Default temperature for LLM sampling.
+     * @type {number | undefined}
+     */
     llmDefaultTemperature: number | undefined;
+    /**
+     * Default top_p for LLM sampling.
+     * @type {number | undefined}
+     */
     llmDefaultTopP: number | undefined;
+    /**
+     * Default maximum tokens for LLM responses.
+     * @type {number | undefined}
+     */
     llmDefaultMaxTokens: number | undefined;
+    /**
+     * Default top_k for LLM sampling.
+     * @type {number | undefined}
+     */
     llmDefaultTopK: number | undefined;
+    /**
+     * Default min_p for LLM sampling.
+     * @type {number | undefined}
+     */
     llmDefaultMinP: number | undefined;
 };
 /**
- * The configured logging level for the application.
- * Exported separately for convenience (e.g., logger initialization).
+ * The configured logging level for the application (e.g., "debug", "info").
+ * This is exported separately from the main `config` object for convenience,
+ * allowing direct import where only the log level is needed (e.g., during logger initialization).
  * @type {string}
  */
 export declare const logLevel: string;
 /**
- * The configured runtime environment for the application.
- * Exported separately for convenience.
+ * The configured runtime environment for the application (e.g., "development", "production").
+ * Exported separately for convenience, useful for conditional logic based on the environment.
  * @type {string}
  */
 export declare const environment: string;