mcp-ts-template 1.1.6

package/dist/utils/internal/logger.js

@@ -0,0 +1,267 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import winston from 'winston';
+import { config } from '../../config/index.js';
+// Define the numeric severity for comparison (lower is more severe)
+const mcpLevelSeverity = {
+    emerg: 0, alert: 1, crit: 2, error: 3, warning: 4, notice: 5, info: 6, debug: 7
+};
+// Map MCP levels to Winston's core levels for file logging
+const mcpToWinstonLevel = {
+    debug: 'debug',
+    info: 'info',
+    notice: 'info', // Map notice to info for file logging
+    warning: 'warn',
+    error: 'error',
+    crit: 'error', // Map critical levels to error for file logging
+    alert: 'error',
+    emerg: 'error',
+};
+// Resolve __dirname for ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Calculate project root robustly (works from src/ or dist/)
+const isRunningFromDist = __dirname.includes(path.sep + 'dist' + path.sep);
+const levelsToGoUp = isRunningFromDist ? 3 : 2;
+const pathSegments = Array(levelsToGoUp).fill('..');
+const projectRoot = path.resolve(__dirname, ...pathSegments);
+const logsDir = path.join(projectRoot, 'logs');
+// Security: ensure logsDir is within projectRoot
+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.`);
+}
+/**
+ * Singleton Logger wrapping Winston, adapted for MCP.
+ * Logs to files and optionally sends MCP notifications/message.
+ */
+class Logger {
+    constructor() {
+        this.initialized = false;
+        this.currentMcpLevel = 'info'; // Default MCP level
+        this.currentWinstonLevel = 'info'; // Default Winston level
+    }
+    /**
+     * 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).
+     */
+    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) {
+                console.warn('Logger already initialized.');
+            }
+            return;
+        }
+        this.currentMcpLevel = level;
+        this.currentWinstonLevel = mcpToWinstonLevel[level];
+        // Ensure logs directory exists
+        if (isLogsDirSafe) {
+            try {
+                if (!fs.existsSync(resolvedLogsDir)) {
+                    fs.mkdirSync(resolvedLogsDir, { recursive: true });
+                    // Avoid console.log in stdio mode. This info will be part of the initialization log message.
+                    // if (process.stdout.isTTY) {
+                    //   console.log(`Created logs directory: ${resolvedLogsDir}`);
+                    // }
+                }
+            }
+            catch (err) {
+                console.error(`Error creating logs directory at ${resolvedLogsDir}: ${err.message}. File logging disabled.`);
+            }
+        }
+        // Common format for files
+        const fileFormat = winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json());
+        const transports = [];
+        // Add file transports only if the directory is safe
+        if (isLogsDirSafe) {
+            transports.push(new winston.transports.File({ filename: path.join(resolvedLogsDir, 'error.log'), level: 'error', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'warn.log'), level: 'warn', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'info.log'), level: 'info', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'debug.log'), level: 'debug', format: fileFormat }), new winston.transports.File({ filename: path.join(resolvedLogsDir, 'combined.log'), format: fileFormat }));
+        }
+        else {
+            // Avoid console.warn in stdio mode. This info will be part of the initialization log message.
+            // if (process.stdout.isTTY) {
+            //    console.warn("File logging disabled due to unsafe logs directory path.");
+            // }
+        }
+        // Conditionally add Console transport only if:
+        // 1. MCP level is 'debug'
+        // 2. stdout is a TTY (interactive terminal, not piped)
+        if (this.currentMcpLevel === 'debug' && process.stdout.isTTY) {
+            const consoleFormat = winston.format.combine(winston.format.colorize(), winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.printf(({ timestamp, level, message, ...meta }) => {
+                let metaString = '';
+                const metaCopy = { ...meta };
+                if (metaCopy.error && typeof metaCopy.error === 'object') {
+                    const errorObj = metaCopy.error;
+                    if (errorObj.message)
+                        metaString += `\n  Error: ${errorObj.message}`;
+                    if (errorObj.stack)
+                        metaString += `\n  Stack: ${String(errorObj.stack).split('\n').map((l) => `    ${l}`).join('\n')}`;
+                    delete metaCopy.error;
+                }
+                if (Object.keys(metaCopy).length > 0) {
+                    try {
+                        const remainingMetaJson = JSON.stringify(metaCopy, null, 2);
+                        if (remainingMetaJson !== '{}')
+                            metaString += `\n  Meta: ${remainingMetaJson}`;
+                    }
+                    catch (stringifyError) {
+                        metaString += `\n  Meta: [Error stringifying metadata: ${stringifyError.message}]`;
+                    }
+                }
+                return `${timestamp} ${level}: ${message}${metaString}`;
+            }));
+            transports.push(new winston.transports.Console({
+                level: 'debug',
+                format: consoleFormat,
+            }));
+            // This log will go through winston itself if console transport is added.
+            // If not, it shouldn't go to console.
+            // console.log(`Console logging enabled at level: debug (stdout is TTY)`);
+        }
+        else if (this.currentMcpLevel === 'debug' && !process.stdout.isTTY) {
+            // Avoid console.log in stdio mode. This info will be part of the initialization log message.
+            // console.log(`Console logging skipped: Level is debug, but stdout is not a TTY (likely stdio transport).`);
+        }
+        // Create logger with the initial Winston level and configured transports
+        this.winstonLogger = winston.createLogger({
+            level: this.currentWinstonLevel,
+            transports,
+            exitOnError: false
+        });
+        this.initialized = true;
+        await Promise.resolve(); // Yield to event loop
+        this.info(`Logger initialized. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${process.stdout.isTTY && this.currentMcpLevel === 'debug' ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Sets the function used to send MCP 'notifications/message'.
+     */
+    setMcpNotificationSender(sender) {
+        this.mcpNotificationSender = sender;
+        const status = sender ? 'enabled' : 'disabled';
+        this.info(`MCP notification sending ${status}.`);
+    }
+    /**
+     * Dynamically sets the minimum logging level.
+     */
+    setLevel(newLevel) {
+        if (!this.ensureInitialized()) {
+            console.error("Cannot set level: Logger not initialized.");
+            return;
+        }
+        if (!(newLevel in mcpLevelSeverity)) {
+            this.warning(`Invalid MCP log level provided: ${newLevel}. Level not changed.`);
+            return;
+        }
+        const oldLevel = this.currentMcpLevel;
+        this.currentMcpLevel = newLevel;
+        this.currentWinstonLevel = mcpToWinstonLevel[newLevel];
+        this.winstonLogger.level = this.currentWinstonLevel;
+        // Add or remove console transport based on the new level and TTY status
+        const consoleTransport = this.winstonLogger.transports.find(t => t instanceof winston.transports.Console);
+        const shouldHaveConsole = newLevel === 'debug' && process.stdout.isTTY;
+        if (shouldHaveConsole && !consoleTransport) {
+            // Add console transport
+            const consoleFormat = winston.format.combine( /* ... same format as in initialize ... */); // TODO: Extract format to avoid duplication
+            this.winstonLogger.add(new winston.transports.Console({ level: 'debug', format: consoleFormat }));
+            this.info('Console logging dynamically enabled.');
+        }
+        else if (!shouldHaveConsole && consoleTransport) {
+            // Remove console transport
+            this.winstonLogger.remove(consoleTransport);
+            this.info('Console logging dynamically disabled.');
+        }
+        if (oldLevel !== newLevel) {
+            this.info(`Log level changed. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${shouldHaveConsole ? 'enabled' : 'disabled'}`);
+        }
+    }
+    /** Get singleton instance. */
+    static getInstance() {
+        if (!Logger.instance) {
+            Logger.instance = new Logger();
+        }
+        return Logger.instance;
+    }
+    /** Ensures the logger has been initialized. */
+    ensureInitialized() {
+        if (!this.initialized || !this.winstonLogger) {
+            // Avoid console.warn in stdio mode.
+            // if (process.stdout.isTTY) {
+            //   console.warn('Logger not initialized; message dropped.');
+            // }
+            return false;
+        }
+        return true;
+    }
+    /** Centralized log processing */
+    log(level, msg, context, error) {
+        if (!this.ensureInitialized())
+            return;
+        if (mcpLevelSeverity[level] > mcpLevelSeverity[this.currentMcpLevel]) {
+            return;
+        }
+        const logData = { ...context };
+        const winstonLevel = mcpToWinstonLevel[level];
+        if (error) {
+            this.winstonLogger.log(winstonLevel, msg, { ...logData, error: error });
+        }
+        else {
+            this.winstonLogger.log(winstonLevel, msg, logData);
+        }
+        if (this.mcpNotificationSender) {
+            const mcpDataPayload = { message: msg };
+            if (context)
+                mcpDataPayload.context = context;
+            if (error) {
+                mcpDataPayload.error = { message: error.message };
+                if (this.currentMcpLevel === 'debug' && error.stack) {
+                    mcpDataPayload.error.stack = error.stack.substring(0, 500);
+                }
+            }
+            try {
+                this.mcpNotificationSender(level, mcpDataPayload, config.mcpServerName);
+            }
+            catch (sendError) {
+                this.winstonLogger.error("Failed to send MCP log notification", {
+                    originalLevel: level,
+                    originalMessage: msg,
+                    sendError: sendError instanceof Error ? sendError.message : String(sendError),
+                    mcpPayload: mcpDataPayload
+                });
+            }
+        }
+    }
+    // --- Public Logging Methods ---
+    debug(msg, context) { this.log('debug', msg, context); }
+    info(msg, context) { this.log('info', msg, context); }
+    notice(msg, context) { this.log('notice', msg, context); }
+    warning(msg, context) { this.log('warning', msg, context); }
+    error(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const combinedContext = err instanceof Error ? context : { ...(err || {}), ...(context || {}) };
+        this.log('error', msg, combinedContext, errorObj);
+    }
+    crit(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const combinedContext = err instanceof Error ? context : { ...(err || {}), ...(context || {}) };
+        this.log('crit', msg, combinedContext, errorObj);
+    }
+    alert(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const combinedContext = err instanceof Error ? context : { ...(err || {}), ...(context || {}) };
+        this.log('alert', msg, combinedContext, errorObj);
+    }
+    emerg(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const combinedContext = err instanceof Error ? context : { ...(err || {}), ...(context || {}) };
+        this.log('emerg', msg, combinedContext, errorObj);
+    }
+    fatal(msg, context, error) {
+        this.log('emerg', msg, context, error);
+    }
+}
+// Export singleton instance
+export const logger = Logger.getInstance();

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

@@ -0,0 +1,47 @@
+/**
+ * Defines the structure for context information associated with a request or operation.
+ */
+export interface RequestContext {
+    /** Unique identifier generated for the request context instance. */
+    requestId: string;
+    /** 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;
+}
+/**
+ * Configuration interface for request context utilities
+ */
+export interface ContextConfig {
+    /** Custom configuration properties */
+    [key: string]: unknown;
+}
+/**
+ * Operation context with request data
+ */
+export interface OperationContext {
+    /** Request context data */
+    requestContext?: RequestContext;
+    /** Custom context properties */
+    [key: string]: unknown;
+}
+export declare const requestContextService: {
+    config: ContextConfig;
+    /**
+     * Configure service settings
+     * @param config New configuration
+     * @returns Updated configuration
+     */
+    configure(config: Partial<ContextConfig>): ContextConfig;
+    /**
+     * Get current configuration
+     * @returns Current configuration
+     */
+    getConfig(): ContextConfig;
+    /**
+     * Create a request context with unique ID and timestamp
+     * @param additionalContext Additional context properties
+     * @returns Request context object
+     */
+    createRequestContext(additionalContext?: Record<string, unknown>): RequestContext;
+};

package/dist/utils/internal/requestContext.js

@@ -0,0 +1,48 @@
+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
+const requestContextServiceInstance = {
+    config: {},
+    /**
+     * Configure service settings
+     * @param config New configuration
+     * @returns Updated configuration
+     */
+    configure(config) {
+        this.config = {
+            ...this.config,
+            ...config
+        };
+        logger.debug('RequestContext configuration updated', { config: this.config });
+        return { ...this.config };
+    },
+    /**
+     * Get current configuration
+     * @returns Current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    },
+    /**
+     * Create a request context with unique ID and timestamp
+     * @param additionalContext Additional context properties
+     * @returns Request context object
+     */
+    createRequestContext(additionalContext = {}) {
+        const requestId = generateUUID(); // Use imported generateUUID
+        const timestamp = new Date().toISOString();
+        return {
+            requestId,
+            timestamp,
+            ...additionalContext
+        };
+    },
+    // generateSecureRandomString function removed as it was unused and redundant
+};
+// Export the instance directly
+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/index.d.ts

@@ -0,0 +1 @@
+export * from './tokenCounter.js';

package/dist/utils/metrics/index.js

@@ -0,0 +1 @@
+export * from './tokenCounter.js';

package/dist/utils/metrics/tokenCounter.d.ts

@@ -0,0 +1,27 @@
+import { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+import { RequestContext } from '../index.js';
+/**
+ * Calculates the number of tokens for a given text using the 'gpt-4o' tokenizer.
+ * Uses ErrorHandler for consistent error management.
+ *
+ * @param text - The input text to tokenize.
+ * @param context - Optional request context for logging and error handling.
+ * @returns The number of tokens.
+ * @throws {McpError} Throws an McpError if tokenization fails.
+ */
+export declare function countTokens(text: string, context?: RequestContext): Promise<number>;
+/**
+ * Calculates the number of tokens for chat messages using the ChatCompletionMessageParam structure
+ * and the 'gpt-4o' tokenizer, considering special tokens and message overhead.
+ * This implementation is based on OpenAI's guidelines for gpt-4/gpt-3.5-turbo models.
+ * Uses ErrorHandler for consistent error management.
+ *
+ * See: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb
+ *
+ * @param messages - An array of chat messages in the `ChatCompletionMessageParam` format.
+ * @param context - Optional request context for logging and error handling.
+ * @returns The estimated number of tokens.
+ * @throws {McpError} Throws an McpError if tokenization fails.
+ */
+export declare function countChatTokens(messages: ReadonlyArray<ChatCompletionMessageParam>, // Use the complex type
+context?: RequestContext): Promise<number>;

package/dist/utils/metrics/tokenCounter.js

@@ -0,0 +1,124 @@
+import { encoding_for_model } from 'tiktoken';
+import { BaseErrorCode } from '../../types-global/errors.js';
+// Import utils from the main barrel file (ErrorHandler, logger, RequestContext from ../internal/*)
+import { ErrorHandler, logger } from '../index.js';
+// Define the model used specifically for token counting
+const TOKENIZATION_MODEL = 'gpt-4o'; // Note this is strictly for token counting, not the model used for inference
+/**
+ * Calculates the number of tokens for a given text using the 'gpt-4o' tokenizer.
+ * Uses ErrorHandler for consistent error management.
+ *
+ * @param text - The input text to tokenize.
+ * @param context - Optional request context for logging and error handling.
+ * @returns The number of tokens.
+ * @throws {McpError} Throws an McpError if tokenization fails.
+ */
+export async function countTokens(text, context) {
+    // Wrap the synchronous operation in tryCatch which handles both sync/async
+    return ErrorHandler.tryCatch(() => {
+        let encoding = null;
+        try {
+            // Always use the defined TOKENIZATION_MODEL
+            encoding = encoding_for_model(TOKENIZATION_MODEL);
+            const tokens = encoding.encode(text);
+            return tokens.length;
+        }
+        finally {
+            encoding?.free(); // Ensure the encoder is freed if it was successfully created
+        }
+    }, {
+        operation: 'countTokens',
+        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
+    });
+}
+/**
+ * Calculates the number of tokens for chat messages using the ChatCompletionMessageParam structure
+ * and the 'gpt-4o' tokenizer, considering special tokens and message overhead.
+ * This implementation is based on OpenAI's guidelines for gpt-4/gpt-3.5-turbo models.
+ * Uses ErrorHandler for consistent error management.
+ *
+ * See: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb
+ *
+ * @param messages - An array of chat messages in the `ChatCompletionMessageParam` format.
+ * @param context - Optional request context for logging and error handling.
+ * @returns The estimated number of tokens.
+ * @throws {McpError} Throws an McpError if tokenization fails.
+ */
+export async function countChatTokens(messages, // Use the complex type
+context) {
+    // Wrap the synchronous operation in tryCatch
+    return ErrorHandler.tryCatch(() => {
+        let encoding = null;
+        let num_tokens = 0;
+        try {
+            // Always use the defined TOKENIZATION_MODEL
+            encoding = encoding_for_model(TOKENIZATION_MODEL);
+            // Define tokens per message/name based on gpt-4o (same as gpt-4/gpt-3.5-turbo)
+            const tokens_per_message = 3;
+            const tokens_per_name = 1;
+            for (const message of messages) {
+                num_tokens += tokens_per_message;
+                // Encode role
+                num_tokens += encoding.encode(message.role).length;
+                // Encode content - handle potential null or array content (vision)
+                if (typeof message.content === 'string') {
+                    num_tokens += encoding.encode(message.content).length;
+                }
+                else if (Array.isArray(message.content)) {
+                    // Handle multi-part content (e.g., text + image) - simplified: encode text parts only
+                    for (const part of message.content) {
+                        if (part.type === 'text') {
+                            num_tokens += encoding.encode(part.text).length;
+                        }
+                        else {
+                            // Add placeholder token count for non-text parts (e.g., images) if needed
+                            // This requires specific model knowledge (e.g., OpenAI vision model token costs)
+                            logger.warning(`Non-text content part found (type: ${part.type}), token count contribution ignored.`, context);
+                            // num_tokens += IMAGE_TOKEN_COST; // Placeholder
+                        }
+                    }
+                } // else: content is null, add 0 tokens
+                // Encode name if present (often associated with 'tool' or 'function' roles in newer models)
+                if ('name' in message && message.name) {
+                    num_tokens += tokens_per_name;
+                    num_tokens += encoding.encode(message.name).length;
+                }
+                // --- Handle tool calls (specific to newer models) ---
+                // Assistant message requesting tool calls
+                if (message.role === 'assistant' && 'tool_calls' in message && message.tool_calls) {
+                    for (const tool_call of message.tool_calls) {
+                        // Add tokens for the function name and arguments
+                        if (tool_call.function.name) {
+                            num_tokens += encoding.encode(tool_call.function.name).length;
+                        }
+                        if (tool_call.function.arguments) {
+                            // Arguments are often JSON strings
+                            num_tokens += encoding.encode(tool_call.function.arguments).length;
+                        }
+                    }
+                }
+                // Tool message providing results
+                if (message.role === 'tool' && 'tool_call_id' in message && message.tool_call_id) {
+                    num_tokens += encoding.encode(message.tool_call_id).length;
+                    // Content of the tool message (the result) is already handled by the string content check above
+                }
+            }
+            num_tokens += 3; // every reply is primed with <|start|>assistant<|message|>
+            return num_tokens;
+        }
+        finally {
+            encoding?.free();
+        }
+    }, {
+        operation: 'countChatTokens',
+        context: context,
+        input: { messageCount: messages.length }, // Log sanitized input
+        errorCode: BaseErrorCode.INTERNAL_ERROR, // Use INTERNAL_ERROR
+        rethrow: true // Rethrow as McpError
+        // Removed onErrorReturn
+    });
+}

package/dist/utils/parsing/dateParser.d.ts

@@ -0,0 +1,27 @@
+import * as chrono from 'chrono-node';
+import { RequestContext } from '../index.js';
+/**
+ * Parses a natural language date string into a Date object.
+ *
+ * @param text The natural language date string (e.g., "tomorrow", "in 5 days", "2024-01-15").
+ * @param context The request context for logging and error tracking.
+ * @param refDate Optional reference date for parsing relative dates. Defaults to now.
+ * @returns A Date object representing the parsed date, or null if parsing fails.
+ * @throws McpError if parsing fails unexpectedly.
+ */
+declare function parseDateString(text: string, context: RequestContext, refDate?: Date): Promise<Date | null>;
+/**
+ * Parses a natural language date string and returns detailed parsing results.
+ *
+ * @param text The natural language date string.
+ * @param context The request context for logging and error tracking.
+ * @param refDate Optional reference date for parsing relative dates. Defaults to now.
+ * @returns An array of chrono.ParsedResult objects, or an empty array if parsing fails.
+ * @throws McpError if parsing fails unexpectedly.
+ */
+declare function parseDateStringDetailed(text: string, context: RequestContext, refDate?: Date): Promise<chrono.ParsedResult[]>;
+export declare const dateParser: {
+    parse: typeof parseDateStringDetailed;
+    parseDate: typeof parseDateString;
+};
+export {};

package/dist/utils/parsing/dateParser.js

@@ -0,0 +1,62 @@
+import * as chrono from 'chrono-node';
+// Import utils from the main barrel file (logger, ErrorHandler, RequestContext from ../internal/*)
+import { logger, ErrorHandler } from '../index.js';
+import { BaseErrorCode } from '../../types-global/errors.js'; // Corrected path
+/**
+ * Parses a natural language date string into a Date object.
+ *
+ * @param text The natural language date string (e.g., "tomorrow", "in 5 days", "2024-01-15").
+ * @param context The request context for logging and error tracking.
+ * @param refDate Optional reference date for parsing relative dates. Defaults to now.
+ * @returns A Date object representing the parsed date, or null if parsing fails.
+ * @throws McpError if parsing fails unexpectedly.
+ */
+async function parseDateString(text, context, refDate) {
+    const operation = 'parseDateString';
+    const logContext = { ...context, operation, inputText: text, refDate };
+    logger.debug(`Attempting to parse date string: "${text}"`, logContext);
+    return await ErrorHandler.tryCatch(async () => {
+        const parsedDate = chrono.parseDate(text, refDate, { forwardDate: true });
+        if (parsedDate) {
+            logger.debug(`Successfully parsed "${text}" to ${parsedDate.toISOString()}`, logContext);
+            return parsedDate;
+        }
+        else {
+            logger.warning(`Failed to parse date string: "${text}"`, logContext);
+            return null;
+        }
+    }, {
+        operation,
+        context: logContext,
+        input: { text, refDate },
+        errorCode: BaseErrorCode.PARSING_ERROR,
+    });
+}
+/**
+ * Parses a natural language date string and returns detailed parsing results.
+ *
+ * @param text The natural language date string.
+ * @param context The request context for logging and error tracking.
+ * @param refDate Optional reference date for parsing relative dates. Defaults to now.
+ * @returns An array of chrono.ParsedResult objects, or an empty array if parsing fails.
+ * @throws McpError if parsing fails unexpectedly.
+ */
+async function parseDateStringDetailed(text, context, refDate) {
+    const operation = 'parseDateStringDetailed';
+    const logContext = { ...context, operation, inputText: text, refDate };
+    logger.debug(`Attempting detailed parse of date string: "${text}"`, logContext);
+    return await ErrorHandler.tryCatch(async () => {
+        const results = chrono.parse(text, refDate, { forwardDate: true });
+        logger.debug(`Detailed parse of "${text}" resulted in ${results.length} result(s)`, logContext);
+        return results;
+    }, {
+        operation,
+        context: logContext,
+        input: { text, refDate },
+        errorCode: BaseErrorCode.PARSING_ERROR,
+    });
+}
+export const dateParser = {
+    parse: parseDateStringDetailed,
+    parseDate: parseDateString,
+};

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

@@ -0,0 +1,2 @@
+export * from './jsonParser.js';
+export * from './dateParser.js';

package/dist/utils/parsing/index.js

@@ -0,0 +1,2 @@
+export * from './jsonParser.js';
+export * from './dateParser.js';

package/dist/utils/parsing/jsonParser.d.ts

@@ -0,0 +1,46 @@
+import { RequestContext } from '../index.js';
+/**
+ * Enum mirroring partial-json's Allow constants for specifying
+ * what types of partial JSON structures are permissible during parsing.
+ * Use bitwise OR to combine options (e.g., Allow.STR | Allow.OBJ).
+ */
+export declare const Allow: {
+    STR: number;
+    NUM: number;
+    ARR: number;
+    OBJ: number;
+    NULL: number;
+    BOOL: number;
+    NAN: number;
+    INFINITY: number;
+    _INFINITY: number;
+    INF: number;
+    SPECIAL: number;
+    ATOM: number;
+    COLLECTION: number;
+    ALL: number;
+};
+/**
+ * Utility class for parsing potentially partial JSON strings.
+ * Wraps the 'partial-json' library to provide a consistent interface
+ * within the atlas-mcp-agent project.
+ * Handles optional <think>...</think> blocks at the beginning of the input.
+ */
+declare class JsonParser {
+    /**
+     * Parses a JSON string, potentially allowing for incomplete structures
+     * and handling optional <think> blocks at the start.
+     *
+     * @param jsonString The JSON string to parse.
+     * @param allowPartial A bitwise OR combination of 'Allow' constants specifying permissible partial types (defaults to Allow.ALL).
+     * @param context Optional RequestContext for error correlation and logging think blocks.
+     * @returns The parsed JavaScript value.
+     * @throws {McpError} Throws an McpError with BaseErrorCode.VALIDATION_ERROR if parsing fails due to malformed JSON.
+     */
+    parse<T = any>(jsonString: string, allowPartial?: number, context?: RequestContext): T;
+}
+/**
+ * Singleton instance of the JsonParser utility.
+ */
+export declare const jsonParser: JsonParser;
+export {};