mcp-ts-template 1.4.3 → 1.4.5

package/README.md

@@ -3,7 +3,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-1.12.1-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--03--26-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.4.3-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.4.5-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)

package/dist/mcp-client/transports/stdioClientTransport.js

@@ -40,18 +40,8 @@ export function createStdioClientTransport(transportConfig, parentContext) {
         // Inheriting all of process.env is a security risk.
         // If specific variables from process.env are needed, they should be explicitly
         // listed in the mcp-config.json for that server or handled by an allowlist mechanism.
-        const filteredProcessEnv = {};
-        for (const key in process.env) {
-            if (Object.prototype.hasOwnProperty.call(process.env, key)) {
-                const value = process.env[key];
-                if (value !== undefined) {
-                    filteredProcessEnv[key] = value;
-                }
-            }
-        }
         const serverSpecificEnv = {
-            ...filteredProcessEnv, // Inherit filtered parent process environment
-            ...(transportConfig.env || {}), // Apply server-specific overrides/additions
+            ...(transportConfig.env || {}), // Only use explicitly defined env vars from config
         };
         logger.debug("Creating StdioClientTransport with merged environment", {
             ...context,

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

@@ -5,9 +5,8 @@
  * @module src/mcp-server/tools/catFactFetcher/catFactFetcherLogic
  */
 import { z } from "zod";
-import { logger, fetchWithTimeout, // Added import
- } from "../../../utils/index.js";
-import { McpError, BaseErrorCode } from "../../../types-global/errors.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { fetchWithTimeout, logger, } from "../../../utils/index.js";
 /**
  * Asynchronously fetches a random cat fact from the Cat Fact Ninja API.
  * @param maxLength - Optional maximum length for the cat fact.
@@ -16,11 +15,13 @@ import { McpError, BaseErrorCode } from "../../../types-global/errors.js";
  * @throws {McpError} If the API request fails or returns an error.
  */
 async function fetchRandomCatFactFromApi(maxLength, context) {
+    // Best practice: API URLs should be configurable, e.g., via environment variables or a config file.
     let apiUrl = "https://catfact.ninja/fact";
     if (maxLength !== undefined) {
         apiUrl += `?max_length=${maxLength}`;
     }
     logger.info(`Fetching random cat fact from: ${apiUrl}`, context);
+    // Best practice: Timeouts should be configurable.
     const CAT_FACT_API_TIMEOUT_MS = 5000;
     try {
         // Use the fetchWithTimeout utility
@@ -31,7 +32,7 @@ async function fetchRandomCatFactFromApi(maxLength, context) {
             throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, `Cat Fact API request to ${apiUrl} failed: ${response.status} ${response.statusText}`, {
                 ...context,
                 httpStatusCode: response.status,
-                responseBodyBrief: errorText.substring(0, 200), // Log a snippet of the response
+                responseBodyBrief: errorText,
                 errorSource: "CatFactApiNonOkResponse",
             });
         }

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

@@ -2,9 +2,10 @@
  * @fileoverview Registration for the fetch_image_test MCP tool.
  * @module src/mcp-server/tools/imageTest/registration
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { ErrorHandler, logger, // Added logger import
-requestContextService, } from "../../../utils/index.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService,
+// RequestContext, // No longer needed directly in this function signature
+ } from "../../../utils/index.js";
 import { FetchImageTestInputSchema, fetchImageTestLogic, } from "./logic.js";
 /**
  * Registers the fetch_image_test tool with the MCP server.
@@ -12,27 +13,35 @@ import { FetchImageTestInputSchema, fetchImageTestLogic, } from "./logic.js";
  */
 export function registerFetchImageTestTool(server) {
     const operation = "registerFetchImageTestTool";
-    const context = requestContextService.createRequestContext({ operation });
-    try {
+    const registrationContext = requestContextService.createRequestContext({
+        operation,
+    });
+    ErrorHandler.tryCatch(() => {
         server.tool("fetch_image_test", "Fetches a random cat image from an external API (cataas.com) and returns it as a blob. Useful for testing image handling capabilities.", FetchImageTestInputSchema.shape, // CRITICAL: Pass the .shape
         async (validatedInput, mcpProvidedContext) => {
+            // Create a new context for each tool invocation.
+            // Link to an initial request ID if available from mcpProvidedContext or use registration context's ID as a fallback.
+            const parentRequestId = mcpProvidedContext?.requestId || registrationContext.requestId;
             const handlerRequestContext = requestContextService.createRequestContext({
-                parentRequestId: context.requestId, // Optional: link to registration context
+                parentRequestId,
                 operation: "fetchImageTestToolHandler",
-                mcpToolContext: mcpProvidedContext, // Context from MCP SDK during call
+                toolName: "fetch_image_test",
+                // Include any other relevant details from mcpProvidedContext if needed
+                // For example, if mcpProvidedContext itself is a RequestContext or has useful fields:
+                // ...(typeof mcpProvidedContext === 'object' && mcpProvidedContext !== null ? mcpProvidedContext : {}),
             });
             return fetchImageTestLogic(validatedInput, handlerRequestContext);
         });
-        logger.notice(`Tool 'fetch_image_test' registered.`, context);
-    }
-    catch (error) {
-        ErrorHandler.handleError(new McpError(BaseErrorCode.INITIALIZATION_FAILED, `Failed to register 'fetch_image_test'`, {
-            originalError: error instanceof Error ? error.message : String(error),
-        }), {
-            operation,
-            context,
-            errorCode: BaseErrorCode.INITIALIZATION_FAILED,
-            critical: true,
-        });
-    }
+        logger.notice(`Tool 'fetch_image_test' registered.`, registrationContext);
+    }, {
+        operation, // Operation name for error handling
+        context: registrationContext, // Context for error handling
+        errorCode: BaseErrorCode.INITIALIZATION_FAILED, // Default error code if registration fails
+        critical: true, // Registration failures are typically critical
+        // Note: `rethrow` is not an option for `ErrorHandler.tryCatch`.
+        // `tryCatch` internally calls `ErrorHandler.handleError` with `rethrow: true`.
+        // If non-rethrowing behavior is essential for a specific registration,
+        // a manual try/catch block calling `ErrorHandler.handleError` with `rethrow: false` would be needed.
+        // For consistency with the typical use of `tryCatch`, this assumes rethrowing is acceptable.
+    });
 }

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

@@ -13,8 +13,8 @@
  * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
  * @module src/mcp-server/transports/authentication/authMiddleware
  */
-import { NextFunction, Request, Response } from "express";
 import { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import { NextFunction, Request, Response } from "express";
 declare global {
     namespace Express {
         interface Request {

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

@@ -111,18 +111,29 @@ export function mcpAuthMiddleware(req, res, next) {
                 scopesFromToken = [decoded.scope.trim()];
             }
             else if (scopesFromToken.length === 0 && decoded.scope.trim() === "") {
-                // If scope is an empty string, treat as no scopes rather than erroring, or use a default.
-                // Depending on strictness, could also error here. For now, allow empty array if scope was empty string.
+                // If scope is an empty string, treat as no scopes.
+                // This will now lead to an error if scopes are considered mandatory.
                 logger.debug("JWT 'scope' claim was an empty string, resulting in empty scopes array.", context);
             }
         }
         else {
             // If scopes are strictly mandatory and not found or invalid format
-            logger.warning("Authentication failed: JWT 'scp' or 'scope' claim is missing, not an array of strings, or not a valid space-separated string. Assigning default empty array.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
-            scopesFromToken = []; // Default to empty array if scopes are mandatory but not found/invalid
-            // Or, if truly mandatory and must be non-empty:
-            // res.status(401).json({ error: "Unauthorized: Invalid token, missing or invalid scopes." });
-            // return;
+            logger.warning("Authentication failed: JWT 'scp' or 'scope' claim is missing, not an array of strings, or not a valid space-separated string.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            res.status(401).json({
+                error: "Unauthorized: Invalid token, missing or invalid scopes.",
+            });
+            return;
+        }
+        // If, after parsing, scopesFromToken is empty and scopes are considered mandatory for any operation.
+        // This check assumes that all valid tokens must have at least one scope.
+        // If some tokens are legitimately allowed to have no scopes for certain operations,
+        // this check might need to be adjusted or handled downstream.
+        if (scopesFromToken.length === 0) {
+            logger.warning("Authentication failed: Token resulted in an empty scope array, and scopes are required.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            res.status(401).json({
+                error: "Unauthorized: Token must contain valid, non-empty scopes.",
+            });
+            return;
         }
         // Construct req.auth with only the properties defined in SDK's AuthInfo
         // All other claims from 'decoded' are not part of req.auth for type safety.

package/dist/utils/internal/logger.js

@@ -1,10 +1,3 @@
-/**
- * @fileoverview Provides a singleton Logger class that wraps Winston for file logging
- * and supports sending MCP (Model Context Protocol) `notifications/message`.
- * It handles different log levels compliant with RFC 5424 and MCP specifications.
- * @module src/utils/internal/logger
- */
-import fs from "fs";
 import path from "path";
 import winston from "winston";
 import { config } from "../../config/index.js";
@@ -105,34 +98,13 @@ export class Logger {
             return;
         }
         // Set initialized to true at the beginning of the initialization process.
-        // If initialization fails critically later, the logger might be in an inconsistent state,
-        // but this will prevent "Logger not initialized" messages from within initialize() itself.
         this.initialized = true;
         this.currentMcpLevel = level;
         this.currentWinstonLevel = mcpToWinstonLevel[level];
-        let logsDirCreatedMessage = null; // This message is now informational as creation is handled by config
-        if (isLogsDirSafe) {
-            // Directory creation is handled by config/index.ts ensureDirectory.
-            // We can log if it was newly created by checking if it existed before config ran,
-            // but that's complex. For now, we assume config handled it.
-            // If resolvedLogsDir is set, config ensures it exists.
-            if (!fs.existsSync(resolvedLogsDir)) {
-                // This case should ideally not be hit if config.logsPath is correctly set up and validated.
-                // However, if it somehow occurs (e.g. dir deleted after config init but before logger init),
-                // we attempt to create it.
-                try {
-                    await fs.promises.mkdir(resolvedLogsDir, { recursive: true });
-                    logsDirCreatedMessage = `Re-created logs directory (should have been created by config): ${resolvedLogsDir}`;
-                }
-                catch (err) {
-                    if (process.stdout.isTTY) {
-                        const errorMessage = err instanceof Error ? err.message : String(err);
-                        console.error(`Error creating logs directory at ${resolvedLogsDir}: ${errorMessage}. File logging disabled.`);
-                    }
-                    throw err; // Critical if logs dir cannot be ensured
-                }
-            }
-        }
+        // The logs directory (config.logsPath / resolvedLogsDir) is expected to be created and validated
+        // by the configuration module (src/config/index.ts) before logger initialization.
+        // If isLogsDirSafe is true, we assume resolvedLogsDir exists and is usable.
+        // No redundant directory creation logic here.
         const fileFormat = winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json());
         const transports = [];
         const fileTransportOptions = {
@@ -180,23 +152,17 @@ export class Logger {
             requestId: "logger-init-deferred",
             timestamp: new Date().toISOString(),
         };
-        if (logsDirCreatedMessage) {
-            // Log if we had to re-create it
-            this.info(logsDirCreatedMessage, initialContext);
-        }
+        // Removed logging of logsDirCreatedMessage as it's no longer set
         if (consoleStatus.message) {
             this.info(consoleStatus.message, initialContext);
         }
-        this.initialized = true;
+        this.initialized = true; // Ensure this is set after successful setup
         this.info(`Logger initialized. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${consoleStatus.enabled ? "enabled" : "disabled"}`, {
             loggerSetup: true,
             requestId: "logger-post-init",
             timestamp: new Date().toISOString(),
             logsPathUsed: resolvedLogsDir,
         });
-        // Note: If a critical error occurs during initialization after this point,
-        // this.initialized remains true. Consider adding a try/catch around the core
-        // initialization logic to set this.initialized = false on failure if needed.
     }
     /**
      * Sets the function used to send MCP 'notifications/message'.

package/dist/utils/security/idGenerator.d.ts

@@ -85,6 +85,7 @@ export declare class IdGenerator {
      * @param id - The ID string to validate.
      * @param entityType - The expected entity type of the ID.
      * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
      * @returns `true` if the ID is valid, `false` otherwise.
      */
     isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
@@ -112,7 +113,9 @@ export declare class IdGenerator {
     getEntityType(id: string, separator?: string): string;
     /**
      * Normalizes an entity ID to ensure the prefix matches the registered case
-     * and the random part is uppercase.
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
      * @param id - The ID to normalize (e.g., "proj_a6b3j0").
      * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
      * @returns The normalized ID (e.g., "PROJ_A6B3J0").

package/dist/utils/security/idGenerator.js

@@ -101,16 +101,21 @@ export class IdGenerator {
      * @param id - The ID string to validate.
      * @param entityType - The expected entity type of the ID.
      * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
      * @returns `true` if the ID is valid, `false` otherwise.
      */
     isValid(id, entityType, options = {}) {
         const prefix = this.entityPrefixes[entityType];
-        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, } = options;
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, // Use charset from options or default
+         } = options;
         if (!prefix) {
             return false;
         }
-        // Assumes default charset characters (uppercase letters and digits) for regex.
-        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}[A-Z0-9]{${length}}$`);
+        // Build regex character class from the charset
+        // Escape characters that have special meaning inside a regex character class `[]`
+        const escapedCharsetForClass = charset.replace(/[[\]\\^-]/g, "\\$&");
+        const charsetRegexPart = `[${escapedCharsetForClass}]`;
+        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}${charsetRegexPart}{${length}}$`);
         return pattern.test(id);
     }
     /**
@@ -153,7 +158,9 @@ export class IdGenerator {
     }
     /**
      * Normalizes an entity ID to ensure the prefix matches the registered case
-     * and the random part is uppercase.
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
      * @param id - The ID to normalize (e.g., "proj_a6b3j0").
      * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
      * @returns The normalized ID (e.g., "PROJ_A6B3J0").
@@ -164,6 +171,8 @@ export class IdGenerator {
         const registeredPrefix = this.entityPrefixes[entityType];
         const idParts = id.split(separator);
         const randomPart = idParts.slice(1).join(separator);
+        // Consider if randomPart.toUpperCase() is always correct for custom charsets.
+        // For now, maintaining existing behavior.
         return `${registeredPrefix}${separator}${randomPart.toUpperCase()}`;
     }
 }

package/dist/utils/security/sanitization.d.ts

@@ -148,6 +148,17 @@ export declare class Sanitization {
      * Sanitizes input for logging by redacting sensitive fields.
      * Creates a deep clone and replaces values of fields matching `this.sensitiveFields`
      * (case-insensitive substring match) with "[REDACTED]".
+     *
+     * It uses `structuredClone` if available for a high-fidelity deep clone.
+     * If `structuredClone` is not available (e.g., in older Node.js environments),
+     * it falls back to `JSON.parse(JSON.stringify(input))`. This fallback has limitations:
+     * - `Date` objects are converted to ISO date strings.
+     * - `undefined` values within objects are removed.
+     * - `Map`, `Set`, `RegExp` objects are converted to empty objects (`{}`).
+     * - Functions are removed.
+     * - `BigInt` values will throw an error during `JSON.stringify` unless a `toJSON` method is provided.
+     * - Circular references will cause `JSON.stringify` to throw an error.
+     *
      * @param input - The input data to sanitize for logging.
      * @returns A sanitized (deep cloned) version of the input, safe for logging.
      *   Returns original input if not object/array, or "[Log Sanitization Failed]" on error.

package/dist/utils/security/sanitization.js

@@ -377,6 +377,17 @@ export class Sanitization {
      * Sanitizes input for logging by redacting sensitive fields.
      * Creates a deep clone and replaces values of fields matching `this.sensitiveFields`
      * (case-insensitive substring match) with "[REDACTED]".
+     *
+     * It uses `structuredClone` if available for a high-fidelity deep clone.
+     * If `structuredClone` is not available (e.g., in older Node.js environments),
+     * it falls back to `JSON.parse(JSON.stringify(input))`. This fallback has limitations:
+     * - `Date` objects are converted to ISO date strings.
+     * - `undefined` values within objects are removed.
+     * - `Map`, `Set`, `RegExp` objects are converted to empty objects (`{}`).
+     * - Functions are removed.
+     * - `BigInt` values will throw an error during `JSON.stringify` unless a `toJSON` method is provided.
+     * - Circular references will cause `JSON.stringify` to throw an error.
+     *
      * @param input - The input data to sanitize for logging.
      * @returns A sanitized (deep cloned) version of the input, safe for logging.
      *   Returns original input if not object/array, or "[Log Sanitization Failed]" on error.

package/package.json

@@ -1,6 +1,7 @@
 {
+  "$schema": "http://json.schemastore.org/package",
   "name": "mcp-ts-template",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "TypeScript template for building Model Context Protocol (MCP) Servers & Clients. Features extensive utilities (logger, requestContext, etc.), STDIO & Streamable HTTP (with authMiddleware), examples, and type safety. Ideal starting point for creating production-ready MCP Servers & Clients.",
   "main": "dist/index.js",
   "files": [
@@ -10,6 +11,7 @@
     "mcp-ts-template": "dist/index.js"
   },
   "exports": "./dist/index.js",
+  "types": "dist/index.d.ts",
   "type": "module",
   "repository": {
     "type": "git",
@@ -46,7 +48,7 @@
     "express": "^5.1.0",
     "ignore": "^7.0.5",
     "jsonwebtoken": "^9.0.2",
-    "openai": "^5.0.2",
+    "openai": "^5.1.0",
     "partial-json": "^0.1.7",
     "sanitize-html": "^2.17.0",
     "tiktoken": "^1.0.21",
@@ -56,7 +58,7 @@
     "winston": "^3.17.0",
     "winston-daily-rotate-file": "^5.0.0",
     "yargs": "^18.0.0",
-    "zod": "^3.25.49"
+    "zod": "^3.25.51"
   },
   "keywords": [
     "typescript",
@@ -74,8 +76,18 @@
   ],
   "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/mcp-ts-template#readme)",
   "license": "Apache-2.0",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/cyanheads"
+    },
+    {
+      "type": "buy_me_a_coffee",
+      "url": "https://www.buymeacoffee.com/cyanheads"
+    }
+  ],
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.0.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.2",