@alcyone-labs/simple-mcp-logger
Version:
Logging solution for MCP servers. Prevents console output from corrupting MCP protocol communication. Drop-in replacement for console, Winston, and Pino with automatic STDOUT suppression in MCP mode.
239 lines • 7.54 kB
TypeScript
/**
* Lightweight centralized logger for ArgParser
* Provides MCP-compliant logging that can be disabled in MCP mode
*/
export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
/**
* Configuration options for SimpleMcpLogger
*/
export interface LoggerConfig {
/** Minimum log level to output */
level: LogLevel;
/** When true, suppresses console output to prevent MCP protocol corruption */
mcpMode: boolean;
/** Optional prefix to prepend to all log messages */
prefix?: string;
/** Optional file path for persistent logging. Creates directory if it doesn't exist. */
logToFile?: string;
}
/**
* Configuration options for MCP Logger
* @since 1.2.0
*/
export interface McpLoggerOptions {
/** Minimum log level to output. Defaults to 'error' for backward compatibility */
level?: LogLevel;
/** When true, suppresses console output to prevent MCP protocol corruption. Defaults to true */
mcpMode?: boolean;
/** Optional prefix to prepend to all log messages */
prefix?: string;
/** Optional file path for persistent logging. Creates directory if it doesn't exist */
logToFile?: string;
}
export declare class Logger {
private config;
private fileStream?;
constructor(config?: Partial<LoggerConfig>);
/**
* Initialize file logging
*/
private initFileLogging;
/**
* Write to file if file logging is enabled
*/
private writeToFile;
/**
* Set MCP mode - when true, all console output is suppressed
*/
setMcpMode(enabled: boolean): void;
/**
* Set log level
*/
setLevel(level: LogLevel): void;
/**
* Set prefix for all log messages
*/
setPrefix(prefix: string): void;
/**
* Set or change the log file path
*
* @param filePath Path to the log file. Directory will be created if it doesn't exist.
*
* @example
* ```typescript
* await logger.setLogFile('./logs/app.log');
* logger.info('This goes to the new file');
* ```
*/
setLogFile(filePath: string): Promise<void>;
/**
* Close file stream
*/
close(): Promise<void>;
/**
* Check if logging is enabled for a given level
*/
private shouldLog;
/**
* Check if console logging should be used (not in MCP mode or file logging disabled)
*/
private shouldLogToConsole;
/**
* Format message with prefix
*/
private formatMessage;
/**
* Debug logging
*/
debug(message: string, ...args: any[]): void;
/**
* Environment-aware debug logging - only outputs if DEBUG environment variable is truthy
* This method respects the DEBUG environment variable and will only log when the DEBUG env var is truthy.
* It works with all configured transports (console, file, etc.) and respects MCP mode settings.
* Treats "false", "0", and empty string as falsy values.
*/
envDebug(message: string, ...args: any[]): void;
/**
* Info logging - uses stderr for MCP compliance
*/
info(message: string, ...args: any[]): void;
/**
* Warning logging
*/
warn(message: string, ...args: any[]): void;
/**
* Error logging - uses stderr which is allowed in MCP mode for debugging
*/
error(message: string, ...args: any[]): void;
/**
* Log method - alias for info to match console.log behavior
*/
log(message: string, ...args: any[]): void;
/**
* Trace logging - uses console.trace for stack traces
*/
trace(message?: string, ...args: any[]): void;
/**
* Table logging - uses console.table for structured data
*/
table(data: any, columns?: string[]): void;
/**
* Group logging - creates a collapsible group
*/
group(label?: string): void;
/**
* Collapsed group logging
*/
groupCollapsed(label?: string): void;
/**
* End group logging
*/
groupEnd(): void;
/**
* Time logging - starts a timer
*/
time(label?: string): void;
/**
* Time end logging - ends a timer and logs the duration
*/
timeEnd(label?: string): void;
/**
* Time log - logs current timer value without ending it
*/
timeLog(label?: string, ...args: any[]): void;
/**
* Count logging - maintains a counter for the label
*/
count(label?: string): void;
/**
* Count reset - resets the counter for the label
*/
countReset(label?: string): void;
/**
* Assert logging - logs an error if assertion fails
*/
assert(condition: boolean, message?: string, ...args: any[]): void;
/**
* Clear console - clears the console if supported
*/
clear(): void;
/**
* Dir logging - displays an interactive list of object properties
*/
dir(obj: any, options?: any): void;
/**
* DirXML logging - displays XML/HTML element representation
*/
dirxml(obj: any): void;
/**
* MCP-safe error logging - always uses STDERR even in MCP mode
*
* STDERR is safe for MCP servers because the MCP protocol only uses STDOUT
* for JSON-RPC messages. STDERR output appears in client logs without
* interfering with protocol communication.
*
* Use this for critical errors, debugging info, and monitoring data that
* needs to be visible even when the logger is in MCP mode.
*/
mcpError(message: string, ...args: any[]): void;
/**
* Create a child logger with additional prefix
*/
child(prefix: string): Logger;
}
/**
* Global logger instance
*/
export declare const logger: Logger;
/**
* Create a logger for MCP mode with options-based configuration
*
* @param options Configuration options for the MCP logger
* @returns Logger instance configured for MCP compliance
*
* @example
* ```typescript
* // Basic MCP logger with default error level
* const logger = createMcpLogger({ prefix: 'MyServer' });
*
* // MCP logger with comprehensive logging
* const logger = createMcpLogger({
* prefix: 'MyServer',
* logToFile: './logs/mcp.log',
* level: 'debug' // Capture all log levels
* });
* ```
* @since 1.2.0
*/
export declare function createMcpLogger(options: McpLoggerOptions): Logger;
/**
* Create a logger for MCP mode (legacy signature)
*
* @deprecated Use createMcpLogger(options) instead. This signature will be removed in v2.0.0
* @param prefix Optional prefix for all log messages
* @param logToFile Optional file path for persistent logging. When provided, logs are written to file even in MCP mode while console output is suppressed.
* @param options Additional options to override defaults
* @returns Logger instance configured for MCP compliance
*
* @example
* ```typescript
* // Basic MCP logger (console suppressed)
* const logger = createMcpLogger('MyServer');
*
* // MCP logger with file output (console suppressed, file enabled)
* const fileLogger = createMcpLogger('MyServer', './logs/mcp.log');
*
* // MCP logger with custom options
* const customLogger = createMcpLogger('MyServer', './logs/mcp.log', { level: 'debug' });
* ```
*/
export declare function createMcpLogger(prefix?: string, logToFile?: string, options?: Partial<McpLoggerOptions>): Logger;
/**
* Create a logger for CLI mode
*/
export declare function createCliLogger(level?: LogLevel, prefix?: string): Logger;
/**
* Default export - the Logger class
*/
export default Logger;
//# sourceMappingURL=SimpleMcpLogger.d.ts.map