mcp-ts-template 1.4.4 → 1.4.6

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.4-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.4.6-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/mcp-server/transports/httpTransport.js

@@ -16,7 +16,8 @@ import express from "express";
 import http from "http";
 import { randomUUID } from "node:crypto";
 import { config } from "../../config/index.js";
-import { logger, requestContextService, } from "../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js"; // For McpError type check
+import { logger, rateLimiter, requestContextService, } from "../../utils/index.js";
 import { mcpAuthMiddleware } from "./authentication/authMiddleware.js";
 /**
  * The port number for the HTTP transport, configured via `MCP_HTTP_PORT` environment variable.
@@ -68,28 +69,52 @@ const httpTransports = {};
  */
 function isOriginAllowed(req, res) {
     const origin = req.headers.origin;
-    const host = req.hostname;
-    const isLocalhostBinding = ["127.0.0.1", "::1", "localhost"].includes(host);
+    // Determine if the server is bound to a localhost interface using the configured HTTP_HOST.
+    const isLocalhostBinding = ["127.0.0.1", "::1", "localhost"].includes(config.mcpHttpHost);
     const allowedOrigins = config.mcpAllowedOrigins || [];
     const context = requestContextService.createRequestContext({
         operation: "isOriginAllowed",
-        origin,
-        host,
+        requestOrigin: origin, // Use a more descriptive key for the request's origin
+        serverBindingHost: config.mcpHttpHost, // Log the server's binding host for context
         isLocalhostBinding,
-        allowedOrigins,
+        configuredAllowedOrigins: allowedOrigins, // Use a more descriptive key
     });
     logger.debug("Checking origin allowance", context);
-    const allowed = (origin && allowedOrigins.includes(origin)) ||
-        (isLocalhostBinding && (!origin || origin === "null"));
+    const allowed = (origin && allowedOrigins.includes(origin)) || // Origin is explicitly in the whitelist
+        (isLocalhostBinding && (!origin || origin === "null")); // Or server is localhost and origin is missing or "null"
     if (allowed && origin) {
-        res.setHeader("Access-Control-Allow-Origin", origin);
+        // If the origin is "null", we must not set Access-Control-Allow-Origin to "null"
+        // when Access-Control-Allow-Credentials is also true (which it is in this block).
+        // This combination is a security risk. By not setting ACAO to "null",
+        // a credentialed request from a "null" origin will likely be blocked by the browser, which is safer.
+        if (origin === "null") {
+            logger.debug(`Origin is "null". Not setting Access-Control-Allow-Origin to "null" due to Access-Control-Allow-Credentials being true.`, context);
+            // Note: Access-Control-Allow-Origin is NOT set to "null".
+        }
+        else {
+            // For any other allowed, non-null origin, reflect it.
+            res.setHeader("Access-Control-Allow-Origin", origin);
+        }
+        // These headers are set for any allowed & originated request.
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Mcp-Session-Id, Last-Event-ID, Authorization");
+        res.setHeader("Access-Control-Allow-Credentials", "true");
+    }
+    else if (allowed && !origin && isLocalhostBinding) {
+        // Case: No origin header, but server is localhost-bound (e.g., same-origin, curl).
+        // 'allowed' is true. We can allow credentials. ACAO is not strictly needed for non-browser or same-origin.
+        // If it's a browser in a weird state sending no origin but expecting CORS for credentials,
+        // it will likely fail without ACAO, which is fine.
+        logger.debug(`No origin header, but request allowed due to localhost binding. Setting Access-Control-Allow-Credentials to true.`, context);
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
         res.setHeader("Access-Control-Allow-Headers", "Content-Type, Mcp-Session-Id, Last-Event-ID, Authorization");
         res.setHeader("Access-Control-Allow-Credentials", "true");
     }
     else if (!allowed && origin) {
+        // Origin was present but not allowed by any rule.
         logger.warning(`Origin denied: ${origin}`, context);
     }
+    // If !allowed and !origin, no specific CORS headers needed, request proceeds to be potentially denied by other logic or auth.
     logger.debug(`Origin check result: ${allowed}`, { ...context, allowed });
     return allowed;
 }
@@ -218,6 +243,48 @@ export async function startHttpTransport(createServerInstanceFn, parentContext)
     });
     logger.debug("Setting up Express app for HTTP transport...", transportContext);
     app.use(express.json());
+    // Rate Limiting Middleware
+    // Apply this before more expensive operations like auth or request processing.
+    const httpRateLimitMiddleware = (req, res, next) => {
+        // Determine a reliable key for rate limiting. Prioritize req.ip,
+        // then fall back to req.socket.remoteAddress, and finally to a default string.
+        const rateLimitKey = req.ip || req.socket.remoteAddress || "unknown_ip_for_rate_limit";
+        const context = requestContextService.createRequestContext({
+            operation: "httpRateLimitCheck",
+            ipAddress: rateLimitKey, // Log the actual key being used
+            method: req.method,
+            path: req.path,
+        });
+        try {
+            rateLimiter.check(rateLimitKey, context); // Use the guaranteed string key
+            logger.debug("Rate limit check passed.", context);
+            next();
+        }
+        catch (error) {
+            if (error instanceof McpError && error.code === BaseErrorCode.RATE_LIMITED) {
+                logger.warning(`Rate limit exceeded for IP: ${rateLimitKey}`, {
+                    ...context,
+                    errorMessage: error.message,
+                    details: error.details,
+                });
+                res.status(429).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32000, message: "Too Many Requests" }, // Generic JSON-RPC error for rate limit
+                    id: req.body?.id || null,
+                });
+            }
+            else {
+                // For other errors, pass them to the default error handler
+                logger.error("Unexpected error in rate limit middleware", {
+                    ...context,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                next(error);
+            }
+        }
+    };
+    // Apply rate limiter to the MCP endpoint for all methods
+    app.use(MCP_ENDPOINT_PATH, httpRateLimitMiddleware);
     app.options(MCP_ENDPOINT_PATH, (req, res) => {
         const optionsContext = requestContextService.createRequestContext({
             ...transportContext,

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

@@ -60,10 +60,18 @@ export class IdGenerator {
      * @returns The generated random string.
      */
     generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
-        const bytes = randomBytes(length);
         let result = "";
-        for (let i = 0; i < length; i++) {
-            result += charset[bytes[i] % charset.length];
+        // Determine the largest multiple of charset.length that is less than or equal to 256
+        // This is the threshold for rejection sampling to avoid bias.
+        const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
+        while (result.length < length) {
+            const byteBuffer = randomBytes(1); // Get one random byte
+            const byte = byteBuffer[0];
+            // If the byte is within the valid range (i.e., it won't introduce bias),
+            // use it to select a character from the charset. Otherwise, discard and try again.
+            if (byte < maxValidByteValue) {
+                result += charset[byte % charset.length];
+            }
         }
         return result;
     }
@@ -101,16 +109,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 +166,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 +179,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

@@ -204,8 +204,11 @@ export class Sanitization {
             })) {
                 throw new Error("Invalid URL format or protocol not in allowed list.");
             }
-            if (trimmedInput.toLowerCase().startsWith("javascript:")) {
-                throw new Error("JavaScript pseudo-protocol is not allowed in URLs.");
+            const lowercasedInput = trimmedInput.toLowerCase();
+            if (lowercasedInput.startsWith("javascript:") ||
+                lowercasedInput.startsWith("data:") ||
+                lowercasedInput.startsWith("vbscript:")) {
+                throw new Error("Disallowed pseudo-protocol (javascript:, data:, or vbscript:) in URL.");
             }
             return trimmedInput;
         }
@@ -377,6 +380,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.4",
+  "version": "1.4.6",
   "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": [