mcp-ts-template 1.1.6

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

@@ -0,0 +1,70 @@
+/**
+ * Handles the setup and connection for the Stdio MCP transport.
+ * Implements the MCP Specification 2025-03-26 for stdio transport.
+ * This transport communicates directly over standard input (stdin) and
+ * standard output (stdout), typically used when the MCP server is launched
+ * as a child process by a host application.
+ *
+ * Specification Reference:
+ * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#stdio
+ *
+ * --- Authentication Note ---
+ * As per the MCP Authorization Specification (2025-03-26, Section 1.2),
+ * STDIO transports SHOULD NOT implement HTTP-based authentication flows.
+ * Authorization is typically handled implicitly by the host application
+ * controlling the server process. This implementation follows that guideline.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// Import core utilities: ErrorHandler for centralized error management and logger for logging.
+import { ErrorHandler, logger } from '../../utils/index.js';
+/**
+ * Connects a given McpServer instance to the Stdio transport. (Asynchronous)
+ * Initializes the SDK's StdioServerTransport, which handles reading newline-delimited
+ * JSON-RPC messages from process.stdin and writing corresponding messages to process.stdout,
+ * adhering to the MCP stdio transport specification.
+ *
+ * MCP Spec Points Covered by SDK's StdioServerTransport:
+ * - Reads JSON-RPC messages (requests, notifications, responses, batches) from stdin.
+ * - Writes JSON-RPC messages to stdout.
+ * - Handles newline delimiters and ensures no embedded newlines in output messages.
+ * - Ensures only valid MCP messages are written to stdout.
+ *
+ * Note: Logging via the `logger` utility MAY result in output to stderr, which is
+ * permitted by the spec for logging purposes.
+ *
+ * @param {McpServer} server - The McpServer instance containing the core logic (tools, resources).
+ * @param {Record<string, any>} context - Logging context for correlation.
+ * @returns {Promise<void>} A promise that resolves when the connection is successfully established.
+ * @throws {Error} Throws an error if the connection fails during setup (e.g., issues connecting server to transport).
+ */
+export async function connectStdioTransport(server, context) {
+    // Add a specific operation name to the context for better log filtering.
+    const operationContext = { ...context, operation: 'connectStdioTransport', transportType: 'Stdio' };
+    logger.debug('Attempting to connect stdio transport...', operationContext);
+    try {
+        logger.debug('Creating StdioServerTransport instance...', operationContext);
+        // Instantiate the transport provided by the SDK for standard I/O communication.
+        // This class encapsulates the logic for reading from stdin and writing to stdout
+        // according to the MCP stdio spec.
+        const transport = new StdioServerTransport();
+        logger.debug('Connecting McpServer instance to StdioServerTransport...', operationContext);
+        // Establish the link between the server's core logic and the transport layer.
+        // This internally starts the necessary listeners on process.stdin.
+        await server.connect(transport);
+        // Log successful connection. The server is now ready to process messages via stdio.
+        logger.info('MCP Server connected and listening via stdio transport.', operationContext);
+        // Use console.log for prominent startup message visibility when run directly, only if TTY.
+        if (process.stdout.isTTY) {
+            console.log(`\n🚀 MCP Server running in STDIO mode.\n   (MCP Spec: 2025-03-26 Stdio Transport)\n`);
+        }
+    }
+    catch (err) {
+        // Catch and handle any critical errors during the transport connection setup.
+        // Mark as critical because the server cannot function without a connected transport.
+        ErrorHandler.handleError(err, { ...operationContext, critical: true });
+        // Rethrow the error to signal the failure to the calling code (e.g., the main server startup).
+        throw err;
+    }
+}

package/dist/types-global/errors.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/**
+ * Defines a set of standardized error codes for common issues within MCP servers or tools.
+ * These codes help clients understand the nature of an error programmatically.
+ */
+export declare enum BaseErrorCode {
+    /** Access denied due to invalid credentials or lack of authentication. */
+    UNAUTHORIZED = "UNAUTHORIZED",
+    /** Access denied despite valid authentication, due to insufficient permissions. */
+    FORBIDDEN = "FORBIDDEN",
+    /** The requested resource or entity could not be found. */
+    NOT_FOUND = "NOT_FOUND",
+    /** The request could not be completed due to a conflict with the current state of the resource. */
+    CONFLICT = "CONFLICT",
+    /** The request failed due to invalid input parameters or data. */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** An error occurred while parsing input data (e.g., date string, JSON). */
+    PARSING_ERROR = "PARSING_ERROR",
+    /** The request was rejected because the client has exceeded rate limits. */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** The request timed out before a response could be generated. */
+    TIMEOUT = "TIMEOUT",
+    /** The service is temporarily unavailable, possibly due to maintenance or overload. */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    /** An unexpected error occurred on the server side. */
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    /** An error occurred, but the specific cause is unknown or cannot be categorized. */
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    /** An error occurred during the loading or validation of configuration data. */
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR"
+}
+/**
+ * Custom error class for MCP-specific errors.
+ * Encapsulates a `BaseErrorCode`, a descriptive message, and optional details.
+ * Provides a method to format the error into a standard MCP tool response.
+ */
+export declare class McpError extends Error {
+    code: BaseErrorCode;
+    details?: Record<string, unknown> | undefined;
+    /**
+     * Creates an instance of McpError.
+     * @param {BaseErrorCode} code - The standardized error code.
+     * @param {string} message - A human-readable description of the error.
+     * @param {Record<string, unknown>} [details] - Optional additional details about the error.
+     */
+    constructor(code: BaseErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Zod schema for validating error objects, potentially used for parsing
+ * error responses or validating error structures internally.
+ */
+export declare const ErrorSchema: z.ZodObject<{
+    /** The error code, corresponding to BaseErrorCode enum values. */
+    code: z.ZodNativeEnum<typeof BaseErrorCode>;
+    /** A human-readable description of the error. */
+    message: z.ZodString;
+    /** Optional additional details or context about the error. */
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    code: BaseErrorCode;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}, {
+    code: BaseErrorCode;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}>;
+/**
+ * TypeScript type inferred from `ErrorSchema`.
+ * Represents a validated error object structure.
+ * @typedef {z.infer<typeof ErrorSchema>} ErrorResponse
+ */
+export type ErrorResponse = z.infer<typeof ErrorSchema>;

package/dist/types-global/errors.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+/**
+ * Defines a set of standardized error codes for common issues within MCP servers or tools.
+ * These codes help clients understand the nature of an error programmatically.
+ */
+export var BaseErrorCode;
+(function (BaseErrorCode) {
+    /** Access denied due to invalid credentials or lack of authentication. */
+    BaseErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    /** Access denied despite valid authentication, due to insufficient permissions. */
+    BaseErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    /** The requested resource or entity could not be found. */
+    BaseErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    /** The request could not be completed due to a conflict with the current state of the resource. */
+    BaseErrorCode["CONFLICT"] = "CONFLICT";
+    /** The request failed due to invalid input parameters or data. */
+    BaseErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** An error occurred while parsing input data (e.g., date string, JSON). */
+    BaseErrorCode["PARSING_ERROR"] = "PARSING_ERROR";
+    /** The request was rejected because the client has exceeded rate limits. */
+    BaseErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    /** The request timed out before a response could be generated. */
+    BaseErrorCode["TIMEOUT"] = "TIMEOUT";
+    /** The service is temporarily unavailable, possibly due to maintenance or overload. */
+    BaseErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    /** An unexpected error occurred on the server side. */
+    BaseErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    /** An error occurred, but the specific cause is unknown or cannot be categorized. */
+    BaseErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+    /** An error occurred during the loading or validation of configuration data. */
+    BaseErrorCode["CONFIGURATION_ERROR"] = "CONFIGURATION_ERROR";
+})(BaseErrorCode || (BaseErrorCode = {}));
+/**
+ * Custom error class for MCP-specific errors.
+ * Encapsulates a `BaseErrorCode`, a descriptive message, and optional details.
+ * Provides a method to format the error into a standard MCP tool response.
+ */
+export class McpError extends Error {
+    /**
+     * Creates an instance of McpError.
+     * @param {BaseErrorCode} code - The standardized error code.
+     * @param {string} message - A human-readable description of the error.
+     * @param {Record<string, unknown>} [details] - Optional additional details about the error.
+     */
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        // Set the error name for identification
+        this.name = 'McpError';
+        // Ensure the prototype chain is correct
+        Object.setPrototypeOf(this, McpError.prototype);
+    }
+}
+/**
+ * Zod schema for validating error objects, potentially used for parsing
+ * error responses or validating error structures internally.
+ */
+export const ErrorSchema = z.object({
+    /** The error code, corresponding to BaseErrorCode enum values. */
+    code: z.nativeEnum(BaseErrorCode).describe("Standardized error code"),
+    /** A human-readable description of the error. */
+    message: z.string().describe("Detailed error message"),
+    /** Optional additional details or context about the error. */
+    details: z.record(z.unknown()).optional().describe("Optional structured error details")
+}).describe("Schema for validating structured error objects.");

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './internal/index.js';
+export * from './parsing/index.js';
+export * from './security/index.js';
+export * from './metrics/index.js';

package/dist/utils/index.js

@@ -0,0 +1,12 @@
+// Re-export all utilities from their categorized subdirectories
+export * from './internal/index.js';
+export * from './parsing/index.js';
+export * from './security/index.js';
+export * from './metrics/index.js';
+// It's good practice to have index.ts files in each subdirectory
+// that export the contents of that directory.
+// Assuming those will be created or already exist.
+// If not, this might need adjustment to export specific files, e.g.:
+// export * from './internal/errorHandler.js';
+// export * from './internal/logger.js';
+// ... etc.

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

@@ -0,0 +1,90 @@
+import { BaseErrorCode } from '../../types-global/errors.js';
+/**
+ * Generic error context interface
+ */
+export interface ErrorContext {
+    /** Unique request or operation identifier */
+    requestId?: string;
+    /** Any additional context information */
+    [key: string]: unknown;
+}
+/**
+ * Error handler options
+ */
+export interface ErrorHandlerOptions {
+    /** The context of the operation that caused the error */
+    context?: ErrorContext;
+    /** The name of the operation being performed */
+    operation: string;
+    /** The input that caused the error */
+    input?: unknown;
+    /** Whether to rethrow the error after handling */
+    rethrow?: boolean;
+    /** Custom error code to use when creating an McpError */
+    errorCode?: BaseErrorCode;
+    /** Custom error mapper function */
+    errorMapper?: (error: unknown) => Error;
+    /** Whether to include stack traces in logs */
+    includeStack?: boolean;
+    /** Whether this is a critical error that should abort operations */
+    critical?: boolean;
+}
+/**
+ * Base error mapping rule
+ */
+export interface BaseErrorMapping {
+    /** Pattern to match in the error message */
+    pattern: string | RegExp;
+    /** Error code for mapped errors */
+    errorCode: BaseErrorCode;
+    /** Custom error message template */
+    messageTemplate?: string;
+}
+/**
+ * Error mapping configuration
+ */
+export interface ErrorMapping<T extends Error = Error> extends BaseErrorMapping {
+    /** Factory function to create the mapped error */
+    factory: (error: unknown, context?: Record<string, unknown>) => T;
+    /** Additional context to merge with error context */
+    additionalContext?: Record<string, unknown>;
+}
+/**
+ * Error handler utility class with various error handling methods
+ */
+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
+     */
+    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
+     */
+    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
+     */
+    static mapError<T extends Error>(error: unknown, mappings: 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
+     */
+    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
+     */
+    static tryCatch<T>(fn: () => Promise<T> | T, options: ErrorHandlerOptions): Promise<T>;
+}

package/dist/utils/internal/errorHandler.js

@@ -0,0 +1,247 @@
+import { BaseErrorCode, McpError } from '../../types-global/errors.js'; // Corrected path
+import { logger } from './logger.js';
+import { sanitizeInputForLogging } from '../index.js'; // Import from main barrel file
+/**
+ * Simple mapper that maps error types to error codes
+ */
+const ERROR_TYPE_MAPPINGS = {
+    'SyntaxError': BaseErrorCode.VALIDATION_ERROR,
+    'TypeError': BaseErrorCode.VALIDATION_ERROR,
+    'ReferenceError': BaseErrorCode.INTERNAL_ERROR,
+    'RangeError': BaseErrorCode.VALIDATION_ERROR,
+    'URIError': BaseErrorCode.VALIDATION_ERROR,
+    'EvalError': BaseErrorCode.INTERNAL_ERROR
+};
+/**
+ * Common error patterns for automatic classification
+ */
+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: /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 }
+];
+/**
+ * Get a readable name for an error
+ * @param error Error to get name for
+ * @returns User-friendly error name
+ */
+function getErrorName(error) {
+    if (error instanceof Error) {
+        return error.name || 'Error';
+    }
+    if (error === null) {
+        return 'NullError';
+    }
+    if (error === undefined) {
+        return 'UndefinedError';
+    }
+    return typeof error === 'object'
+        ? 'ObjectError'
+        : 'UnknownError';
+}
+/**
+ * Get a message from an error
+ * @param error Error to get message from
+ * @returns Error message
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (error === null) {
+        return 'Null error occurred';
+    }
+    if (error === undefined) {
+        return 'Undefined error occurred';
+    }
+    return typeof error === 'string'
+        ? error
+        : String(error);
+}
+/**
+ * Error handler utility class with various error handling methods
+ */
+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
+     */
+    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');
+            if (regex.test(errorMessage) || regex.test(errorName)) {
+                return pattern.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
+     */
+    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
+        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 };
+            }
+            // 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;
+            }
+            // 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),
+            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);
+        }
+        else {
+            transformedError = new McpError(errorCode, `Error ${operation}: ${getErrorMessage(error)}`, // Use helper function
+            {
+                originalError: getErrorName(error),
+                ...context
+            });
+        }
+        // Rethrow if requested
+        if (rethrow) {
+            throw transformedError;
+        }
+        // Ensure the function returns an Error type
+        return transformedError;
+    }
+    /**
+     * 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
+     */
+    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
+        for (const mapping of mappings) {
+            const matches = mapping.pattern instanceof RegExp
+                ? mapping.pattern.test(errorMessage)
+                : errorMessage.includes(mapping.pattern);
+            if (matches) {
+                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));
+    }
+    // Removed createErrorMapper method for simplification
+    /**
+     * Format an error for consistent response structure
+     * @param error The error to format
+     * @returns Formatted error object
+     */
+    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 : {}
+            };
+        }
+        if (error instanceof Error) {
+            return {
+                code: ErrorHandler.determineErrorCode(error),
+                message: error.message,
+                details: { errorType: error.name }
+            };
+        }
+        return {
+            code: BaseErrorCode.UNKNOWN_ERROR,
+            message: String(error),
+            details: { errorType: typeof 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
+     */
+    static async tryCatch(fn, options) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            throw ErrorHandler.handleError(error, { ...options, rethrow: true });
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+export * from './errorHandler.js';
+export * from './logger.js';
+export * from './requestContext.js';

package/dist/utils/internal/index.js

@@ -0,0 +1,3 @@
+export * from './errorHandler.js';
+export * from './logger.js';
+export * from './requestContext.js';

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

@@ -0,0 +1,50 @@
+/**
+ * Supported logging levels based on RFC 5424 Syslog severity levels used by MCP.
+ * emerg: 0, alert: 1, crit: 2, error: 3, warning: 4, notice: 5, info: 6, debug: 7
+ */
+export type McpLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'crit' | 'alert' | 'emerg';
+export type McpNotificationSender = (level: McpLogLevel, data: any, loggerName?: string) => void;
+/**
+ * Singleton Logger wrapping Winston, adapted for MCP.
+ * Logs to files and optionally sends MCP notifications/message.
+ */
+declare class Logger {
+    private static instance;
+    private winstonLogger?;
+    private initialized;
+    private mcpNotificationSender?;
+    private currentMcpLevel;
+    private currentWinstonLevel;
+    private constructor();
+    /**
+     * Initialize Winston logger for file transport. Must be called once at app start.
+     * Console transport is added conditionally.
+     * @param level Initial minimum level to log ('info' default).
+     */
+    initialize(level?: McpLogLevel): Promise<void>;
+    /**
+     * Sets the function used to send MCP 'notifications/message'.
+     */
+    setMcpNotificationSender(sender: McpNotificationSender | undefined): void;
+    /**
+     * Dynamically sets the minimum logging level.
+     */
+    setLevel(newLevel: McpLogLevel): void;
+    /** Get singleton instance. */
+    static getInstance(): Logger;
+    /** Ensures the logger has been initialized. */
+    private ensureInitialized;
+    /** Centralized log processing */
+    private log;
+    debug(msg: string, context?: Record<string, any>): void;
+    info(msg: string, context?: Record<string, any>): void;
+    notice(msg: string, context?: Record<string, any>): void;
+    warning(msg: string, context?: Record<string, any>): void;
+    error(msg: string, err?: Error | Record<string, any>, context?: Record<string, any>): void;
+    crit(msg: string, err?: Error | Record<string, any>, context?: Record<string, any>): void;
+    alert(msg: string, err?: Error | Record<string, any>, context?: Record<string, any>): void;
+    emerg(msg: string, err?: Error | Record<string, any>, context?: Record<string, any>): void;
+    fatal(msg: string, context?: Record<string, any>, error?: Error): void;
+}
+export declare const logger: Logger;
+export {};