mcp-ts-template 1.1.6 → 1.1.7

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.11.0-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.5-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.1.7-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/config/index.js

@@ -17,7 +17,7 @@ try {
 catch (error) {
     // Silently use default pkg info if reading fails.
     // Consider adding logging here if robust error handling is needed.
-    if (process.stdout.isTTY) {
+    if (process.stdout.isTTY) { // Guarded console.error
         console.error("Warning: Could not read package.json for default config values.", error);
     }
 }

package/dist/mcp-client/client.js

@@ -163,7 +163,6 @@ export async function connectMcpClient(serverName, parentContext) {
         operation: `connecting to MCP server ${serverName}`,
         context: operationContext,
         errorCode: BaseErrorCode.INTERNAL_ERROR, // Use INTERNAL_ERROR as fallback for connection issues
-        rethrow: true, // Rethrow the McpError for the caller to handle
     });
 }
 /**

package/dist/mcp-server/transports/httpTransport.js

@@ -401,8 +401,10 @@ export async function startHttpTransport(createServerInstanceFn, context) {
         // Determine protocol for logging (basic assumption based on HSTS possibility)
         const protocol = config.environment === 'production' ? 'https' : 'http';
         const serverAddress = `${protocol}://${config.mcpHttpHost}:${actualPort}${MCP_ENDPOINT_PATH}`;
-        // Use console.log for prominent startup message.
-        console.log(`\n🚀 MCP Server running in HTTP mode at: ${serverAddress}\n   (MCP Spec: 2025-03-26 Streamable HTTP Transport)\n`);
+        // Use console.log for prominent startup message only if TTY.
+        if (process.stdout.isTTY) {
+            console.log(`\n🚀 MCP Server running in HTTP mode at: ${serverAddress}\n   (MCP Spec: 2025-03-26 Streamable HTTP Transport)\n`);
+        }
     }
     catch (err) {
         logger.fatal('HTTP server failed to start after multiple port retries.', { ...transportContext, error: err instanceof Error ? err.message : String(err) });

package/dist/utils/internal/errorHandler.d.ts

@@ -1,90 +1,172 @@
+/**
+ * @file errorHandler.ts
+ * @description This module provides utilities for creating and managing request contexts.
+ * A request context is a data structure associated with a specific request or operation,
+ * carrying a unique ID, timestamp, and other relevant information for logging, tracing,
+ * and processing.
+ */
 import { BaseErrorCode } from '../../types-global/errors.js';
 /**
- * Generic error context interface
+ * @interface ErrorContext
+ * @description Defines a generic structure for providing context with errors.
+ * This context can include identifiers like `requestId` or any other relevant
+ * key-value pairs that aid in debugging or understanding the error's circumstances.
  */
 export interface ErrorContext {
-    /** Unique request or operation identifier */
+    /**
+     * A unique identifier for the request or operation during which the error occurred.
+     * Useful for tracing errors through logs and distributed systems.
+     * @type {string}
+     * @optional
+     */
     requestId?: string;
-    /** Any additional context information */
+    /**
+     * Allows for arbitrary additional context information.
+     * Keys are strings, and values can be of any type.
+     */
     [key: string]: unknown;
 }
 /**
- * Error handler options
+ * @interface ErrorHandlerOptions
+ * @description Configuration options for the `ErrorHandler.handleError` method.
+ * These options control how an error is processed, logged, and whether it's rethrown.
  */
 export interface ErrorHandlerOptions {
-    /** The context of the operation that caused the error */
+    /**
+     * The context of the operation that caused the error.
+     * This can include `requestId` and other relevant debugging information.
+     * @type {ErrorContext}
+     * @optional
+     */
     context?: ErrorContext;
-    /** The name of the operation being performed */
+    /**
+     * A descriptive name of the operation being performed when the error occurred.
+     * This helps in identifying the source or nature of the error in logs.
+     * Example: "UserLogin", "ProcessPayment", "FetchUserProfile".
+     * @type {string}
+     * @required
+     */
     operation: string;
-    /** The input that caused the error */
+    /**
+     * The input data or parameters that were being processed when the error occurred.
+     * This input will be sanitized before logging to prevent sensitive data exposure.
+     * @type {unknown}
+     * @optional
+     */
     input?: unknown;
-    /** Whether to rethrow the error after handling */
+    /**
+     * If true, the (potentially transformed) error will be rethrown after handling.
+     * Defaults to `false`.
+     * @type {boolean}
+     * @optional
+     */
     rethrow?: boolean;
-    /** Custom error code to use when creating an McpError */
+    /**
+     * A specific `BaseErrorCode` to assign to the error, overriding any
+     * automatically determined error code.
+     * @type {BaseErrorCode}
+     * @optional
+     */
     errorCode?: BaseErrorCode;
-    /** Custom error mapper function */
+    /**
+     * A custom function to map or transform the original error into a new `Error` instance.
+     * If provided, this function is used instead of the default `McpError` creation.
+     * @param {unknown} error - The original error that occurred.
+     * @returns {Error} The transformed error.
+     * @optional
+     */
     errorMapper?: (error: unknown) => Error;
-    /** Whether to include stack traces in logs */
+    /**
+     * If true, stack traces will be included in the logs.
+     * Defaults to `true`.
+     * @type {boolean}
+     * @optional
+     */
     includeStack?: boolean;
-    /** Whether this is a critical error that should abort operations */
+    /**
+     * If true, indicates that the error is critical and might require immediate attention
+     * or could lead to system instability. This is primarily for logging and alerting.
+     * Defaults to `false`.
+     * @type {boolean}
+     * @optional
+     */
     critical?: boolean;
 }
 /**
- * Base error mapping rule
+ * @interface BaseErrorMapping
+ * @description Defines a basic rule for mapping errors based on patterns.
+ * Used internally by `COMMON_ERROR_PATTERNS` and as a base for `ErrorMapping`.
  */
 export interface BaseErrorMapping {
-    /** Pattern to match in the error message */
+    /**
+     * A string or regular expression to match against the error message.
+     * If a string is provided, it's typically used for substring matching (case-insensitive).
+     * @type {string | RegExp}
+     * @required
+     */
     pattern: string | RegExp;
-    /** Error code for mapped errors */
+    /**
+     * The `BaseErrorCode` to assign if the pattern matches.
+     * @type {BaseErrorCode}
+     * @required
+     */
     errorCode: BaseErrorCode;
-    /** Custom error message template */
+    /**
+     * An optional custom message template for the mapped error.
+     * (Note: This property is defined but not directly used by `ErrorHandler.determineErrorCode`
+     * which focuses on `errorCode`. It's more relevant for custom mapping logic.)
+     * @type {string}
+     * @optional
+     */
     messageTemplate?: string;
 }
 /**
- * Error mapping configuration
+ * @interface ErrorMapping
+ * @template T - The type of `Error` this mapping will produce, defaults to `Error`.
+ * @description Extends `BaseErrorMapping` to include a factory function for creating
+ * specific error instances and additional context for the mapping.
+ * Used by `ErrorHandler.mapError`.
  */
 export interface ErrorMapping<T extends Error = Error> extends BaseErrorMapping {
-    /** Factory function to create the mapped error */
+    /**
+     * A factory function that creates and returns an instance of the mapped error type `T`.
+     * @param {unknown} error - The original error that occurred.
+     * @param {Record<string, unknown>} [context] - Optional additional context provided in the mapping rule.
+     * @returns {T} The newly created error instance.
+     * @required
+     */
     factory: (error: unknown, context?: Record<string, unknown>) => T;
-    /** Additional context to merge with error context */
+    /**
+     * Additional static context to be merged or passed to the `factory` function
+     * when this mapping rule is applied.
+     * @type {Record<string, unknown>}
+     * @optional
+     */
     additionalContext?: Record<string, unknown>;
 }
 /**
- * Error handler utility class with various error handling methods
+ * @class ErrorHandler
+ * @description A utility class providing static methods for comprehensive error handling.
  */
 export declare class ErrorHandler {
     /**
-     * Determine the appropriate error code for an error based on patterns and type
-     * @param error The error to classify
-     * @returns The appropriate error code
+     * Determines an appropriate `BaseErrorCode` for a given error.
      */
     static determineErrorCode(error: unknown): BaseErrorCode;
     /**
-     * Handle operation errors with consistent logging and transformation
-     * @param error The error that occurred
-     * @param options Error handling options
-     * @returns The transformed error
+     * Handles an error with consistent logging and optional transformation.
      */
     static handleError(error: unknown, options: ErrorHandlerOptions): Error;
     /**
-     * Map an error to a specific error type based on error message patterns
-     * @param error The error to map
-     * @param mappings Array of pattern and factory mappings
-     * @param defaultFactory Default factory function if no pattern matches
-     * @returns The mapped error
+     * Maps an error to a specific error type `T` based on a list of `ErrorMapping` rules.
      */
-    static mapError<T extends Error>(error: unknown, mappings: ErrorMapping<T>[], defaultFactory?: (error: unknown, context?: Record<string, unknown>) => T): T | Error;
+    static mapError<T extends Error>(error: unknown, mappings: ReadonlyArray<ErrorMapping<T>>, defaultFactory?: (error: unknown, context?: Record<string, unknown>) => T): T | Error;
     /**
-     * Format an error for consistent response structure
-     * @param error The error to format
-     * @returns Formatted error object
+     * Formats an error into a consistent object structure, typically for API responses.
      */
     static formatError(error: unknown): Record<string, unknown>;
     /**
-     * Safely execute a function and handle any errors
-     * @param fn Function to execute
-     * @param options Error handling options
-     * @returns The result of the function or error
+     * Safely executes a function and handles any errors using `ErrorHandler.handleError`.
      */
-    static tryCatch<T>(fn: () => Promise<T> | T, options: ErrorHandlerOptions): Promise<T>;
+    static tryCatch<T>(fn: () => Promise<T> | T, options: Omit<ErrorHandlerOptions, 'rethrow'>): Promise<T>;
 }

package/dist/utils/internal/errorHandler.js

@@ -1,8 +1,18 @@
-import { BaseErrorCode, McpError } from '../../types-global/errors.js'; // Corrected path
+/**
+ * @file errorHandler.ts
+ * @description This module provides utilities for creating and managing request contexts.
+ * A request context is a data structure associated with a specific request or operation,
+ * carrying a unique ID, timestamp, and other relevant information for logging, tracing,
+ * and processing.
+ */
+import { BaseErrorCode, McpError } from '../../types-global/errors.js';
+import { sanitizeInputForLogging } from '../index.js';
 import { logger } from './logger.js';
-import { sanitizeInputForLogging } from '../index.js'; // Import from main barrel file
 /**
- * Simple mapper that maps error types to error codes
+ * @constant ERROR_TYPE_MAPPINGS
+ * @description Maps standard JavaScript error constructor names to `BaseErrorCode` values.
+ * This allows for quick classification of common built-in error types.
+ * @readonly
  */
 const ERROR_TYPE_MAPPINGS = {
     'SyntaxError': BaseErrorCode.VALIDATION_ERROR,
@@ -10,235 +20,245 @@ const ERROR_TYPE_MAPPINGS = {
     'ReferenceError': BaseErrorCode.INTERNAL_ERROR,
     'RangeError': BaseErrorCode.VALIDATION_ERROR,
     'URIError': BaseErrorCode.VALIDATION_ERROR,
-    'EvalError': BaseErrorCode.INTERNAL_ERROR
+    'EvalError': BaseErrorCode.INTERNAL_ERROR,
 };
 /**
- * Common error patterns for automatic classification
+ * @constant COMMON_ERROR_PATTERNS
+ * @description An array of `BaseErrorMapping` rules used to automatically classify
+ * errors based on keywords or patterns found in their messages or names.
+ * These patterns are typically case-insensitive.
+ * **IMPORTANT**: The order of patterns matters. More specific patterns should generally come
+ * before more generic ones if there's a possibility of overlap, as the first match is used.
+ * @readonly
  */
 const COMMON_ERROR_PATTERNS = [
-    // Authentication related errors
     { pattern: /auth|unauthorized|unauthenticated|not.*logged.*in|invalid.*token|expired.*token/i, errorCode: BaseErrorCode.UNAUTHORIZED },
-    // Permission related errors
     { pattern: /permission|forbidden|access.*denied|not.*allowed/i, errorCode: BaseErrorCode.FORBIDDEN },
-    // Not found errors
     { pattern: /not.*found|missing|no.*such|doesn't.*exist|couldn't.*find/i, errorCode: BaseErrorCode.NOT_FOUND },
-    // Validation errors
-    { pattern: /invalid|validation|malformed|bad request|wrong format/i, errorCode: BaseErrorCode.VALIDATION_ERROR },
-    // Conflict errors
+    { pattern: /invalid|validation|malformed|bad request|wrong format|missing.*required/i, errorCode: BaseErrorCode.VALIDATION_ERROR },
     { pattern: /conflict|already.*exists|duplicate|unique.*constraint/i, errorCode: BaseErrorCode.CONFLICT },
-    // Rate limiting
     { pattern: /rate.*limit|too.*many.*requests|throttled/i, errorCode: BaseErrorCode.RATE_LIMITED },
-    // Timeout errors
     { pattern: /timeout|timed.*out|deadline.*exceeded/i, errorCode: BaseErrorCode.TIMEOUT },
-    // External service errors
-    { pattern: /service.*unavailable|bad.*gateway|gateway.*timeout/i, errorCode: BaseErrorCode.SERVICE_UNAVAILABLE }
+    { pattern: /service.*unavailable|bad.*gateway|gateway.*timeout|upstream.*error/i, errorCode: BaseErrorCode.SERVICE_UNAVAILABLE },
 ];
 /**
- * Get a readable name for an error
- * @param error Error to get name for
- * @returns User-friendly error name
+ * Creates a "safe" RegExp for testing error messages.
+ * Ensures case-insensitivity if not already specified and removes the global flag.
+ * @param pattern - The string or RegExp pattern.
+ * @returns A new RegExp instance.
+ */
+function createSafeRegex(pattern) {
+    if (pattern instanceof RegExp) {
+        let flags = pattern.flags.replace('g', ''); // Remove global flag
+        if (!flags.includes('i')) {
+            flags += 'i'; // Add case-insensitive if not present
+        }
+        return new RegExp(pattern.source, flags);
+    }
+    return new RegExp(pattern, 'i'); // Default to case-insensitive for string patterns
+}
+/**
+ * Retrieves a descriptive name for an error object or value.
+ * Handles various types including `Error` instances, `null`, `undefined`, and other primitives/objects.
+ *
+ * @param error - The error object or value.
+ * @returns A string representing the error's name or type.
  */
 function getErrorName(error) {
     if (error instanceof Error) {
         return error.name || 'Error';
     }
     if (error === null) {
-        return 'NullError';
+        return 'NullValueEncountered';
     }
     if (error === undefined) {
-        return 'UndefinedError';
+        return 'UndefinedValueEncountered';
     }
-    return typeof error === 'object'
-        ? 'ObjectError'
-        : 'UnknownError';
+    if (typeof error === 'object' && error !== null && error.constructor && typeof error.constructor.name === 'string' && error.constructor.name !== 'Object') {
+        return `${error.constructor.name}Encountered`;
+    }
+    return `${typeof error}Encountered`;
 }
 /**
- * Get a message from an error
- * @param error Error to get message from
- * @returns Error message
+ * Extracts a message string from an error object or value.
+ * Handles `Error` instances, primitives, and converts other types to a string representation.
+ *
+ * @param error - The error object or value.
+ * @returns The error message string.
  */
 function getErrorMessage(error) {
     if (error instanceof Error) {
         return error.message;
     }
     if (error === null) {
-        return 'Null error occurred';
+        return 'Null value encountered as error';
     }
     if (error === undefined) {
-        return 'Undefined error occurred';
+        return 'Undefined value encountered as error';
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        const str = String(error);
+        if (str === '[object Object]' && error !== null) {
+            try {
+                return `Non-Error object encountered: ${JSON.stringify(error)}`;
+            }
+            catch (stringifyError) {
+                return `Unstringifyable non-Error object encountered (constructor: ${error.constructor?.name || 'Unknown'})`;
+            }
+        }
+        return str;
+    }
+    catch (e) {
+        return `Error converting error to string: ${e instanceof Error ? e.message : 'Unknown conversion error'}`;
     }
-    return typeof error === 'string'
-        ? error
-        : String(error);
 }
 /**
- * Error handler utility class with various error handling methods
+ * @class ErrorHandler
+ * @description A utility class providing static methods for comprehensive error handling.
  */
 export class ErrorHandler {
     /**
-     * Determine the appropriate error code for an error based on patterns and type
-     * @param error The error to classify
-     * @returns The appropriate error code
+     * Determines an appropriate `BaseErrorCode` for a given error.
      */
     static determineErrorCode(error) {
-        // If it's already an McpError, use its code
         if (error instanceof McpError) {
             return error.code;
         }
         const errorName = getErrorName(error);
         const errorMessage = getErrorMessage(error);
-        // Check if the error type has a direct mapping
         if (errorName in ERROR_TYPE_MAPPINGS) {
             return ERROR_TYPE_MAPPINGS[errorName];
         }
-        // Check for common error patterns
-        for (const pattern of COMMON_ERROR_PATTERNS) {
-            const regex = pattern.pattern instanceof RegExp
-                ? pattern.pattern
-                : new RegExp(pattern.pattern, 'i');
+        for (const mapping of COMMON_ERROR_PATTERNS) {
+            const regex = createSafeRegex(mapping.pattern);
             if (regex.test(errorMessage) || regex.test(errorName)) {
-                return pattern.errorCode;
+                return mapping.errorCode;
             }
         }
-        // Default to internal error if no pattern matches
         return BaseErrorCode.INTERNAL_ERROR;
     }
     /**
-     * Handle operation errors with consistent logging and transformation
-     * @param error The error that occurred
-     * @param options Error handling options
-     * @returns The transformed error
+     * Handles an error with consistent logging and optional transformation.
      */
     static handleError(error, options) {
-        const { context, operation, input, rethrow = false, errorCode: explicitErrorCode, includeStack = true, critical = false } = options;
-        // If it's already an McpError, use it directly but apply additional context
+        const { context = {}, operation, input, rethrow = false, errorCode: explicitErrorCode, includeStack = true, critical = false, errorMapper, } = options;
+        const sanitizedInput = input !== undefined ? sanitizeInputForLogging(input) : undefined;
+        const originalErrorName = getErrorName(error);
+        const originalErrorMessage = getErrorMessage(error);
+        const originalStack = error instanceof Error ? error.stack : undefined;
+        let finalError;
+        let loggedErrorCode;
+        // Consolidate details for McpError and logging
+        const errorDetailsSeed = error instanceof McpError && typeof error.details === 'object' && error.details !== null
+            ? { ...error.details } // Clone to avoid mutating original
+            : {};
+        const consolidatedDetails = {
+            ...errorDetailsSeed,
+            ...context, // Operation context takes precedence over seed details if keys overlap
+            originalErrorName,
+            originalMessage: originalErrorMessage,
+        };
+        if (originalStack && !(error instanceof McpError && error.details?.originalStack)) { // Avoid duplicating if already there
+            consolidatedDetails.originalStack = originalStack;
+        }
         if (error instanceof McpError) {
-            // Add any additional context
-            if (context && Object.keys(context).length > 0) {
-                // Ensure details is an object before spreading
-                const existingDetails = typeof error.details === 'object' && error.details !== null ? error.details : {};
-                error.details = { ...existingDetails, ...context };
+            loggedErrorCode = error.code;
+            finalError = errorMapper ? errorMapper(error) : new McpError(error.code, error.message, consolidatedDetails);
+            if (finalError instanceof McpError && !finalError.details) {
+                finalError.details = consolidatedDetails;
             }
-            // Log the error with sanitized input
-            logger.error(`Error ${operation}: ${error.message}`, {
-                errorCode: error.code,
-                requestId: context?.requestId,
-                input: input ? sanitizeInputForLogging(input) : undefined,
-                stack: includeStack ? error.stack : undefined,
-                critical,
-                ...context
-            });
-            if (rethrow) {
-                throw error;
+        }
+        else {
+            loggedErrorCode = explicitErrorCode || ErrorHandler.determineErrorCode(error);
+            const message = `Error in ${operation}: ${originalErrorMessage}`;
+            finalError = errorMapper ? errorMapper(error) : new McpError(loggedErrorCode, message, consolidatedDetails);
+            if (finalError instanceof McpError && !finalError.details) {
+                finalError.details = consolidatedDetails;
             }
-            // Ensure the function returns an Error type
-            return error;
-        }
-        // Sanitize input for logging
-        const sanitizedInput = input ? sanitizeInputForLogging(input) : undefined;
-        // Log the error with consistent format
-        logger.error(`Error ${operation}`, {
-            error: getErrorMessage(error), // Use helper function
-            errorType: getErrorName(error),
+        }
+        // Preserve original stack if the finalError is a new Error instance and original was an Error
+        if (finalError !== error && error instanceof Error && finalError instanceof Error && !finalError.stack && error.stack) {
+            finalError.stack = error.stack;
+        }
+        // Prepare log payload
+        const logPayload = {
+            operation,
+            requestId: context.requestId,
             input: sanitizedInput,
-            requestId: context?.requestId,
-            stack: includeStack && error instanceof Error ? error.stack : undefined,
             critical,
-            ...context
-        });
-        // Choose the error code (explicit > determined > default)
-        const errorCode = explicitErrorCode ||
-            ErrorHandler.determineErrorCode(error) ||
-            BaseErrorCode.INTERNAL_ERROR;
-        // Transform to appropriate error type
-        let transformedError;
-        if (options.errorMapper) {
-            transformedError = options.errorMapper(error);
+            errorCode: loggedErrorCode,
+            originalErrorType: originalErrorName, // Retain for clarity
+            finalErrorType: getErrorName(finalError),
+        };
+        if (finalError instanceof McpError && finalError.details) {
+            logPayload.errorDetails = finalError.details;
         }
         else {
-            transformedError = new McpError(errorCode, `Error ${operation}: ${getErrorMessage(error)}`, // Use helper function
-            {
-                originalError: getErrorName(error),
-                ...context
-            });
+            // For non-McpError or McpError without details, use the consolidatedDetails we built
+            logPayload.errorDetails = consolidatedDetails;
         }
-        // Rethrow if requested
+        if (includeStack && finalError instanceof Error && finalError.stack) {
+            logPayload.stack = finalError.stack;
+        }
+        else if (includeStack && originalStack && !logPayload.stack) { // Fallback to original stack if finalError lost it
+            logPayload.stack = originalStack;
+        }
+        logger.error(`Error in ${operation}: ${finalError.message || originalErrorMessage}`, logPayload);
         if (rethrow) {
-            throw transformedError;
+            throw finalError;
         }
-        // Ensure the function returns an Error type
-        return transformedError;
+        return finalError;
     }
     /**
-     * Map an error to a specific error type based on error message patterns
-     * @param error The error to map
-     * @param mappings Array of pattern and factory mappings
-     * @param defaultFactory Default factory function if no pattern matches
-     * @returns The mapped error
+     * Maps an error to a specific error type `T` based on a list of `ErrorMapping` rules.
      */
     static mapError(error, mappings, defaultFactory) {
-        // If it's already the target type and we have a default factory to check against, return it
-        if (defaultFactory && error instanceof Error) {
-            const defaultInstance = defaultFactory(error);
-            if (error.constructor === defaultInstance.constructor) {
-                return error;
-            }
-        }
         const errorMessage = getErrorMessage(error);
-        // Check each pattern and return the first match
+        const errorName = getErrorName(error);
         for (const mapping of mappings) {
-            const matches = mapping.pattern instanceof RegExp
-                ? mapping.pattern.test(errorMessage)
-                : errorMessage.includes(mapping.pattern);
-            if (matches) {
+            const regex = createSafeRegex(mapping.pattern);
+            if (regex.test(errorMessage) || regex.test(errorName)) {
                 return mapping.factory(error, mapping.additionalContext);
             }
         }
-        // Return default or original error
         if (defaultFactory) {
             return defaultFactory(error);
         }
-        return error instanceof Error
-            ? error
-            : new Error(String(error));
+        return error instanceof Error ? error : new Error(String(error));
     }
-    // Removed createErrorMapper method for simplification
     /**
-     * Format an error for consistent response structure
-     * @param error The error to format
-     * @returns Formatted error object
+     * Formats an error into a consistent object structure, typically for API responses.
      */
     static formatError(error) {
         if (error instanceof McpError) {
             return {
                 code: error.code,
                 message: error.message,
-                // Ensure details is an object
-                details: typeof error.details === 'object' && error.details !== null ? error.details : {}
+                details: typeof error.details === 'object' && error.details !== null ? error.details : {},
             };
         }
         if (error instanceof Error) {
             return {
                 code: ErrorHandler.determineErrorCode(error),
                 message: error.message,
-                details: { errorType: error.name }
+                details: { errorType: error.name || 'Error' },
             };
         }
         return {
             code: BaseErrorCode.UNKNOWN_ERROR,
-            message: String(error),
-            details: { errorType: typeof error }
+            message: getErrorMessage(error),
+            details: { errorType: getErrorName(error) },
         };
     }
     /**
-     * Safely execute a function and handle any errors
-     * @param fn Function to execute
-     * @param options Error handling options
-     * @returns The result of the function or error
+     * Safely executes a function and handles any errors using `ErrorHandler.handleError`.
      */
     static async tryCatch(fn, options) {
         try {
-            return await fn();
+            return await Promise.resolve(fn());
         }
         catch (error) {
             throw ErrorHandler.handleError(error, { ...options, rethrow: true });

package/dist/utils/internal/logger.js

@@ -31,8 +31,12 @@ const logsDir = path.join(projectRoot, 'logs');
 const resolvedLogsDir = path.resolve(logsDir);
 const isLogsDirSafe = resolvedLogsDir === projectRoot || resolvedLogsDir.startsWith(projectRoot + path.sep);
 if (!isLogsDirSafe) {
-    // Use console.error here as logger might not be initialized or safe
-    console.error(`FATAL: logs directory "${resolvedLogsDir}" is outside project root "${projectRoot}". File logging disabled.`);
+    if (process.stdout.isTTY) {
+        // Use console.error here as logger might not be initialized or safe, but only if TTY
+        console.error(`FATAL: logs directory "${resolvedLogsDir}" is outside project root "${projectRoot}". File logging disabled.`);
+    }
+    // If not TTY, this critical error will be logged to a file if possible by the initialized logger later,
+    // or an MCP notification if configured. Suppressing direct console output here for stdio clients.
 }
 /**
  * Singleton Logger wrapping Winston, adapted for MCP.
@@ -51,10 +55,11 @@ class Logger {
      */
     async initialize(level = 'info') {
         if (this.initialized) {
-            // Avoid console.warn in stdio mode, this will be logged via this.info later if needed.
             if (process.stdout.isTTY) {
+                // This warning is only relevant for interactive sessions.
                 console.warn('Logger already initialized.');
             }
+            // If already initialized, subsequent info log will indicate this.
             return;
         }
         this.currentMcpLevel = level;
@@ -71,7 +76,10 @@ class Logger {
                 }
             }
             catch (err) {
-                console.error(`Error creating logs directory at ${resolvedLogsDir}: ${err.message}. File logging disabled.`);
+                if (process.stdout.isTTY) {
+                    console.error(`Error creating logs directory at ${resolvedLogsDir}: ${err.message}. File logging disabled.`);
+                }
+                // This error will be logged to file/MCP by the logger instance if it initializes successfully.
             }
         }
         // Common format for files
@@ -149,7 +157,9 @@ class Logger {
      */
     setLevel(newLevel) {
         if (!this.ensureInitialized()) {
-            console.error("Cannot set level: Logger not initialized.");
+            if (process.stdout.isTTY) {
+                console.error("Cannot set level: Logger not initialized.");
+            }
             return;
         }
         if (!(newLevel in mcpLevelSeverity)) {

package/dist/utils/internal/requestContext.d.ts

@@ -1,47 +1,79 @@
+/**
+ * @file requestContext.ts
+ * @description Utilities for creating and managing request contexts.
+ * A request context is an object carrying a unique ID, timestamp, and other
+ * relevant data for logging, tracing, and processing.
+ */
 /**
  * Defines the structure for context information associated with a request or operation.
  */
 export interface RequestContext {
-    /** Unique identifier generated for the request context instance. */
+    /**
+     * Unique ID for the context instance.
+     * Used for log correlation and request tracing.
+     */
     requestId: string;
-    /** ISO 8601 timestamp indicating when the context was created. */
+    /**
+     * ISO 8601 timestamp indicating when the context was created.
+     */
     timestamp: string;
-    /** Allows for additional, arbitrary key-value pairs for specific context needs. */
-    [key: string]: any;
+    /**
+     * Allows arbitrary key-value pairs for specific context needs.
+     * Using `unknown` promotes type-safe access.
+     * Consumers must type-check/assert when accessing extended properties.
+     */
+    [key: string]: unknown;
 }
 /**
- * Configuration interface for request context utilities
+ * Configuration interface for the request context service.
+ * Extensible for future configuration.
+ * Placeholder for potential service-wide settings.
  */
 export interface ContextConfig {
-    /** Custom configuration properties */
+    /** Custom configuration properties. Allows for arbitrary key-value pairs. */
     [key: string]: unknown;
 }
 /**
- * Operation context with request data
+ * Represents a broader operation context, optionally including
+ * a `RequestContext` and custom properties.
+ * Often used to pass contextual information for an operation or task.
  */
 export interface OperationContext {
-    /** Request context data */
+    /** Optional request context data, adhering to the `RequestContext` structure. */
     requestContext?: RequestContext;
-    /** Custom context properties */
+    /** Allows for additional, custom properties specific to the operation. */
     [key: string]: unknown;
 }
+/**
+ * Primary export for request context functionalities.
+ * Provides methods to create and manage request contexts.
+ */
 export declare const requestContextService: {
+    /**
+     * Internal configuration store.
+     * Initialized empty, updatable via `configure`.
+     */
     config: ContextConfig;
     /**
-     * Configure service settings
-     * @param config New configuration
-     * @returns Updated configuration
+     * Configures the service with new settings, merging with existing config.
+     *
+     * @param config - A partial `ContextConfig` object containing settings to update.
+     * @returns A shallow copy of the updated configuration.
      */
     configure(config: Partial<ContextConfig>): ContextConfig;
     /**
-     * Get current configuration
-     * @returns Current configuration
+     * Retrieves a shallow copy of the current service configuration.
+     *
+     * @returns A shallow copy of the current `ContextConfig`.
      */
     getConfig(): ContextConfig;
     /**
-     * Create a request context with unique ID and timestamp
-     * @param additionalContext Additional context properties
-     * @returns Request context object
+     * Creates a new request context with a unique `requestId` and `timestamp`.
+     * Custom properties can be added via `additionalContext`.
+     *
+     * @param additionalContext - An optional record of key-value pairs to be
+     *                            included in the request context. Defaults to an empty object.
+     * @returns A `RequestContext` object.
      */
     createRequestContext(additionalContext?: Record<string, unknown>): RequestContext;
 };

package/dist/utils/internal/requestContext.js

@@ -1,48 +1,68 @@
+/**
+ * @file requestContext.ts
+ * @description Utilities for creating and managing request contexts.
+ * A request context is an object carrying a unique ID, timestamp, and other
+ * relevant data for logging, tracing, and processing.
+ */
 import { logger } from './logger.js';
 // Import utils from the main barrel file (generateUUID from ../security/idGenerator.js)
 import { generateUUID } from '../index.js';
-// Direct instance for request context utilities
+/**
+ * Service instance for managing request context operations.
+ * Singleton-like object to configure the service and create contexts.
+ */
 const requestContextServiceInstance = {
+    /**
+     * Internal configuration store.
+     * Initialized empty, updatable via `configure`.
+     */
     config: {},
     /**
-     * Configure service settings
-     * @param config New configuration
-     * @returns Updated configuration
+     * Configures the service with new settings, merging with existing config.
+     *
+     * @param config - A partial `ContextConfig` object containing settings to update.
+     * @returns A shallow copy of the updated configuration.
      */
     configure(config) {
         this.config = {
             ...this.config,
-            ...config
+            ...config,
         };
-        logger.debug('RequestContext configuration updated', { config: this.config });
-        return { ...this.config };
+        logger.debug('RequestContextService configuration updated', { newConfig: this.config });
+        return { ...this.config }; // Return a copy to prevent direct mutation
     },
     /**
-     * Get current configuration
-     * @returns Current configuration
+     * Retrieves a shallow copy of the current service configuration.
+     *
+     * @returns A shallow copy of the current `ContextConfig`.
      */
     getConfig() {
-        return { ...this.config };
+        return { ...this.config }; // Return a copy
     },
     /**
-     * Create a request context with unique ID and timestamp
-     * @param additionalContext Additional context properties
-     * @returns Request context object
+     * Creates a new request context with a unique `requestId` and `timestamp`.
+     * Custom properties can be added via `additionalContext`.
+     *
+     * @param additionalContext - An optional record of key-value pairs to be
+     *                            included in the request context. Defaults to an empty object.
+     * @returns A `RequestContext` object.
      */
     createRequestContext(additionalContext = {}) {
-        const requestId = generateUUID(); // Use imported generateUUID
+        const requestId = generateUUID();
         const timestamp = new Date().toISOString();
-        return {
+        const context = {
             requestId,
             timestamp,
-            ...additionalContext
+            ...additionalContext,
         };
+        // logger.debug('Request context created', { requestId }); // Optional: log context creation
+        return context;
     },
-    // generateSecureRandomString function removed as it was unused and redundant
+    // generateSecureRandomString function was previously here but removed as it was unused and redundant.
+    // Its functionality, if needed for secure random strings, should be sourced from a dedicated crypto/security module.
 };
-// Export the instance directly
+/**
+ * Primary export for request context functionalities.
+ * Provides methods to create and manage request contexts.
+ */
 export const requestContextService = requestContextServiceInstance;
-// Removed delegate functions and default export for simplicity.
-// Users should import and use `requestContextService` directly.
-// e.g., import { requestContextService } from './requestContext.js';
-// requestContextService.createRequestContext();

package/dist/utils/metrics/tokenCounter.js

@@ -31,7 +31,6 @@ export async function countTokens(text, context) {
         context: context,
         input: { textSample: text.substring(0, 50) + '...' }, // Log sanitized input
         errorCode: BaseErrorCode.INTERNAL_ERROR, // Use INTERNAL_ERROR for external lib issues
-        rethrow: true // Rethrow as McpError
         // Removed onErrorReturn as we now rethrow
     });
 }
@@ -118,7 +117,6 @@ context) {
         context: context,
         input: { messageCount: messages.length }, // Log sanitized input
         errorCode: BaseErrorCode.INTERNAL_ERROR, // Use INTERNAL_ERROR
-        rethrow: true // Rethrow as McpError
         // Removed onErrorReturn
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "TypeScript template for building Model Context Protocol (MCP) servers & clients. Features production-ready utilities, stdio/HTTP transports (with JWT auth), examples, and type safety. Ideal starting point for creating MCP-based applications.",
   "main": "dist/index.js",
   "files": [