obsidian-mcp-server 1.5.8 → 2.0.2

package/dist/utils/metrics/tokenCounter.js

@@ -0,0 +1,128 @@
+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 is implicitly true for tryCatch
+        // 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 is implicitly true for tryCatch
+        // Removed onErrorReturn
+    });
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Barrel file for Obsidian-specific utilities.
+ */
+export * from "./obsidianStatUtils.js";
+export * from "./obsidianApiUtils.js";

package/dist/utils/obsidian/index.js

@@ -0,0 +1,5 @@
+/**
+ * Barrel file for Obsidian-specific utilities.
+ */
+export * from "./obsidianStatUtils.js";
+export * from "./obsidianApiUtils.js";

package/dist/utils/obsidian/obsidianApiUtils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module ObsidianApiUtils
+ * @description
+ * Internal utilities for the Obsidian REST API service.
+ */
+/**
+ * Encodes a vault-relative file path correctly for API URLs.
+ * Ensures path separators '/' are not encoded, but individual components are.
+ * Handles leading slashes correctly.
+ *
+ * @param filePath - The raw vault-relative file path (e.g., "/Notes/My File.md" or "Notes/My File.md").
+ * @returns The URL-encoded path suitable for appending to `/vault`.
+ */
+export declare function encodeVaultPath(filePath: string): string;

package/dist/utils/obsidian/obsidianApiUtils.js

@@ -0,0 +1,29 @@
+/**
+ * @module ObsidianApiUtils
+ * @description
+ * Internal utilities for the Obsidian REST API service.
+ */
+/**
+ * Encodes a vault-relative file path correctly for API URLs.
+ * Ensures path separators '/' are not encoded, but individual components are.
+ * Handles leading slashes correctly.
+ *
+ * @param filePath - The raw vault-relative file path (e.g., "/Notes/My File.md" or "Notes/My File.md").
+ * @returns The URL-encoded path suitable for appending to `/vault`.
+ */
+export function encodeVaultPath(filePath) {
+    // 1. Trim whitespace and remove any leading/trailing slashes for consistent processing.
+    const trimmedPath = filePath.trim().replace(/^\/+|\/+$/g, "");
+    // 2. If the original path was just '/' or empty, return an empty string (represents root for files).
+    if (trimmedPath === "") {
+        // For file operations, the API expects /vault/filename.md at the root,
+        // so an empty encoded path segment is correct here.
+        // For listFiles, we handle the root case separately.
+        return "";
+    }
+    // 3. Split into components, encode each component, then rejoin with literal '/'.
+    const encodedComponents = trimmedPath.split("/").map(encodeURIComponent);
+    const encodedPath = encodedComponents.join("/");
+    // 4. Prepend the leading slash.
+    return `/${encodedPath}`;
+}

package/dist/utils/obsidian/obsidianStatUtils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Utilities for formatting Obsidian stat objects,
+ * including timestamps and calculating estimated token counts.
+ * @module src/utils/obsidian/obsidianStatUtils
+ */
+import { RequestContext } from "../internal/index.js";
+/**
+ * Formats a Unix timestamp (in milliseconds since the epoch) into a human-readable string.
+ *
+ * @param {number | undefined | null} timestampMs - The Unix timestamp in milliseconds.
+ * @param {RequestContext} context - The request context for logging and error reporting.
+ * @param {string} [formatString=DEFAULT_TIMESTAMP_FORMAT] - Optional format string adhering to `date-fns` tokens.
+ *   Defaults to 'hh:mm:ss a | MM-dd-yyyy'.
+ * @returns {string} The formatted timestamp string.
+ * @throws {McpError} If the provided `timestampMs` is invalid (e.g., undefined, null, not a finite number, or results in an invalid Date object).
+ */
+export declare function formatTimestamp(timestampMs: number | undefined | null, context: RequestContext, formatString?: string): string;
+/**
+ * Represents the structure of an Obsidian API Stat object.
+ */
+export interface ObsidianStat {
+    /** Creation time as a Unix timestamp (milliseconds). */
+    ctime: number;
+    /** Modification time as a Unix timestamp (milliseconds). */
+    mtime: number;
+    /** File size in bytes. */
+    size: number;
+}
+/**
+ * Represents formatted timestamp information derived from an Obsidian Stat object.
+ */
+export interface FormattedTimestamps {
+    /** Human-readable creation time string. */
+    createdTime: string;
+    /** Human-readable modification time string. */
+    modifiedTime: string;
+}
+/**
+ * Formats the `ctime` (creation time) and `mtime` (modification time) from an
+ * Obsidian API Stat object into human-readable strings.
+ *
+ * @param {ObsidianStat | undefined | null} stat - The Stat object from the Obsidian API.
+ *   If undefined or null, placeholder strings ('N/A') are returned.
+ * @param {RequestContext} context - The request context for logging and error reporting.
+ * @returns {FormattedTimestamps} An object containing `createdTime` and `modifiedTime` strings.
+ */
+export declare function formatStatTimestamps(stat: ObsidianStat | undefined | null, context: RequestContext): FormattedTimestamps;
+/**
+ * Represents a fully formatted stat object, including human-readable timestamps
+ * and an estimated token count for the file content.
+ */
+export interface FormattedStatWithTokenCount extends FormattedTimestamps {
+    /** Estimated number of tokens in the file content. -1 if counting failed or content was empty. */
+    tokenCountEstimate: number;
+}
+/**
+ * Creates a formatted stat object that includes human-readable timestamps
+ * (creation and modification times) and an estimated token count for the provided file content.
+ *
+ * @param {ObsidianStat | null | undefined} stat - The original Stat object from the Obsidian API.
+ *   If null or undefined, the function will return the input value (null or undefined).
+ * @param {string} content - The file content string from which to calculate the token count.
+ * @param {RequestContext} context - The request context for logging and error reporting.
+ * @returns {Promise<FormattedStatWithTokenCount | null | undefined>} A promise resolving to an object
+ *   containing `createdTime`, `modifiedTime`, and `tokenCountEstimate`. Returns `null` or `undefined`
+ *   if the input `stat` object was `null` or `undefined`, respectively.
+ */
+export declare function createFormattedStatWithTokenCount(stat: ObsidianStat | null | undefined, content: string, context: RequestContext): Promise<FormattedStatWithTokenCount | null | undefined>;

package/dist/utils/obsidian/obsidianStatUtils.js

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Utilities for formatting Obsidian stat objects,
+ * including timestamps and calculating estimated token counts.
+ * @module src/utils/obsidian/obsidianStatUtils
+ */
+import { format } from "date-fns";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { logger } from "../internal/index.js";
+import { countTokens } from "../metrics/index.js";
+/**
+ * Default format string for timestamps, providing a human-readable date and time.
+ * Example output: "08:40:00 PM | 05-02-2025"
+ */
+const DEFAULT_TIMESTAMP_FORMAT = "hh:mm:ss a | MM-dd-yyyy";
+/**
+ * Formats a Unix timestamp (in milliseconds since the epoch) into a human-readable string.
+ *
+ * @param {number | undefined | null} timestampMs - The Unix timestamp in milliseconds.
+ * @param {RequestContext} context - The request context for logging and error reporting.
+ * @param {string} [formatString=DEFAULT_TIMESTAMP_FORMAT] - Optional format string adhering to `date-fns` tokens.
+ *   Defaults to 'hh:mm:ss a | MM-dd-yyyy'.
+ * @returns {string} The formatted timestamp string.
+ * @throws {McpError} If the provided `timestampMs` is invalid (e.g., undefined, null, not a finite number, or results in an invalid Date object).
+ */
+export function formatTimestamp(timestampMs, context, formatString = DEFAULT_TIMESTAMP_FORMAT) {
+    const operation = "formatTimestamp";
+    if (timestampMs === undefined ||
+        timestampMs === null ||
+        !Number.isFinite(timestampMs)) {
+        const errorMessage = `Invalid timestamp provided for formatting: ${timestampMs}`;
+        logger.warning(errorMessage, { ...context, operation });
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, errorMessage, {
+            ...context,
+            operation,
+        });
+    }
+    try {
+        const date = new Date(timestampMs);
+        if (isNaN(date.getTime())) {
+            const errorMessage = `Timestamp resulted in an invalid date: ${timestampMs}`;
+            logger.warning(errorMessage, { ...context, operation });
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, errorMessage, {
+                ...context,
+                operation,
+            });
+        }
+        return format(date, formatString);
+    }
+    catch (error) {
+        const errorMessage = `Failed to format timestamp ${timestampMs}: ${error instanceof Error ? error.message : String(error)}`;
+        logger.error(errorMessage, error instanceof Error ? error : undefined, {
+            ...context,
+            operation,
+        });
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, errorMessage, {
+            ...context,
+            operation,
+            originalError: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Formats the `ctime` (creation time) and `mtime` (modification time) from an
+ * Obsidian API Stat object into human-readable strings.
+ *
+ * @param {ObsidianStat | undefined | null} stat - The Stat object from the Obsidian API.
+ *   If undefined or null, placeholder strings ('N/A') are returned.
+ * @param {RequestContext} context - The request context for logging and error reporting.
+ * @returns {FormattedTimestamps} An object containing `createdTime` and `modifiedTime` strings.
+ */
+export function formatStatTimestamps(stat, context) {
+    const operation = "formatStatTimestamps";
+    if (!stat) {
+        logger.debug("Stat object is undefined or null, returning N/A for timestamps.", { ...context, operation });
+        return {
+            createdTime: "N/A",
+            modifiedTime: "N/A",
+        };
+    }
+    try {
+        return {
+            createdTime: formatTimestamp(stat.ctime, context),
+            modifiedTime: formatTimestamp(stat.mtime, context),
+        };
+    }
+    catch (error) {
+        // Log the error from formatTimestamp if it occurs during this higher-level operation
+        logger.error(`Error formatting timestamps within formatStatTimestamps for ctime: ${stat.ctime}, mtime: ${stat.mtime}`, error instanceof Error ? error : undefined, { ...context, operation });
+        // Return N/A as a fallback if formatting fails at this stage
+        return {
+            createdTime: "N/A",
+            modifiedTime: "N/A",
+        };
+    }
+}
+/**
+ * Creates a formatted stat object that includes human-readable timestamps
+ * (creation and modification times) and an estimated token count for the provided file content.
+ *
+ * @param {ObsidianStat | null | undefined} stat - The original Stat object from the Obsidian API.
+ *   If null or undefined, the function will return the input value (null or undefined).
+ * @param {string} content - The file content string from which to calculate the token count.
+ * @param {RequestContext} context - The request context for logging and error reporting.
+ * @returns {Promise<FormattedStatWithTokenCount | null | undefined>} A promise resolving to an object
+ *   containing `createdTime`, `modifiedTime`, and `tokenCountEstimate`. Returns `null` or `undefined`
+ *   if the input `stat` object was `null` or `undefined`, respectively.
+ */
+export async function createFormattedStatWithTokenCount(stat, content, context) {
+    const operation = "createFormattedStatWithTokenCount";
+    if (stat === null || stat === undefined) {
+        logger.debug("Input stat is null or undefined, returning as is.", {
+            ...context,
+            operation,
+        });
+        return stat; // Return original null/undefined
+    }
+    const formattedTimestamps = formatStatTimestamps(stat, context);
+    let tokenCountEstimate = -1; // Default: indicates error or empty content
+    if (content && content.trim().length > 0) {
+        try {
+            tokenCountEstimate = await countTokens(content, context);
+        }
+        catch (tokenError) {
+            logger.warning(`Failed to count tokens for stat object. Error: ${tokenError instanceof Error ? tokenError.message : String(tokenError)}`, {
+                ...context,
+                operation,
+                originalError: tokenError instanceof Error
+                    ? tokenError.message
+                    : String(tokenError),
+            });
+            // tokenCountEstimate remains -1
+        }
+    }
+    else {
+        logger.debug("Content is empty or whitespace-only, setting tokenCountEstimate to 0.", { ...context, operation });
+        tokenCountEstimate = 0;
+    }
+    return {
+        createdTime: formattedTimestamps.createdTime,
+        modifiedTime: formattedTimestamps.modifiedTime,
+        tokenCountEstimate: tokenCountEstimate,
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Provides utilities for parsing natural language date strings
+ * into Date objects or detailed parsing results using the 'chrono-node' library.
+ * @module src/utils/parsing/dateParser
+ */
+import * as chrono from "chrono-node";
+import { RequestContext } from "../internal/index.js";
+/**
+ * Parses a natural language date string (e.g., "tomorrow", "in 5 days", "2024-01-15")
+ * into a JavaScript `Date` object.
+ *
+ * @async
+ * @param {string} text - The natural language date string to parse.
+ * @param {RequestContext} context - The request context for logging and error tracking.
+ * @param {Date} [refDate] - Optional reference date for parsing relative date expressions.
+ *   Defaults to the current date and time if not provided.
+ * @returns {Promise<Date | null>} A promise that resolves to a `Date` object representing
+ *   the parsed date, or `null` if `chrono-node` could not parse the input string into a date.
+ * @throws {McpError} If an unexpected error occurs during the parsing process,
+ *   an `McpError` with `BaseErrorCode.PARSING_ERROR` is thrown.
+ */
+declare function parseDateString(text: string, context: RequestContext, refDate?: Date): Promise<Date | null>;
+/**
+ * Parses a natural language date string and returns detailed parsing results,
+ * including all components and their confidence levels, as provided by `chrono-node`.
+ *
+ * @async
+ * @param {string} text - The natural language date string to parse.
+ * @param {RequestContext} context - The request context for logging and error tracking.
+ * @param {Date} [refDate] - Optional reference date for parsing relative date expressions.
+ *   Defaults to the current date and time if not provided.
+ * @returns {Promise<chrono.ParsedResult[]>} A promise that resolves to an array of
+ *   `chrono.ParsedResult` objects. The array will be empty if no date components
+ *   could be parsed from the input string.
+ * @throws {McpError} If an unexpected error occurs during the parsing process,
+ *   an `McpError` with `BaseErrorCode.PARSING_ERROR` is thrown.
+ */
+declare function parseDateStringDetailed(text: string, context: RequestContext, refDate?: Date): Promise<chrono.ParsedResult[]>;
+/**
+ * Provides methods for parsing natural language date strings.
+ * - `parseToDate`: Parses a string to a single `Date` object or `null`.
+ * - `getDetailedResults`: Provides comprehensive parsing results from `chrono-node`.
+ */
+export declare const dateParser: {
+    /**
+     * Parses a natural language date string into a `Date` object.
+     * @see {@link parseDateString}
+     */
+    parseToDate: typeof parseDateString;
+    /**
+     * Parses a natural language date string and returns detailed `chrono.ParsedResult` objects.
+     * @see {@link parseDateStringDetailed}
+     */
+    getDetailedResults: typeof parseDateStringDetailed;
+};
+export {};

package/dist/utils/parsing/dateParser.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Provides utilities for parsing natural language date strings
+ * into Date objects or detailed parsing results using the 'chrono-node' library.
+ * @module src/utils/parsing/dateParser
+ */
+import * as chrono from "chrono-node";
+import { BaseErrorCode } from "../../types-global/errors.js";
+import { ErrorHandler, logger } from "../internal/index.js";
+/**
+ * Parses a natural language date string (e.g., "tomorrow", "in 5 days", "2024-01-15")
+ * into a JavaScript `Date` object.
+ *
+ * @async
+ * @param {string} text - The natural language date string to parse.
+ * @param {RequestContext} context - The request context for logging and error tracking.
+ * @param {Date} [refDate] - Optional reference date for parsing relative date expressions.
+ *   Defaults to the current date and time if not provided.
+ * @returns {Promise<Date | null>} A promise that resolves to a `Date` object representing
+ *   the parsed date, or `null` if `chrono-node` could not parse the input string into a date.
+ * @throws {McpError} If an unexpected error occurs during the parsing process,
+ *   an `McpError` with `BaseErrorCode.PARSING_ERROR` is thrown.
+ */
+async function parseDateString(text, context, refDate) {
+    const operation = "parseDateString";
+    // Ensure context for logging includes all relevant details
+    const logContext = {
+        ...context,
+        operation,
+        inputText: text,
+        refDate: refDate?.toISOString(),
+    };
+    logger.debug(`Attempting to parse date string: "${text}"`, logContext);
+    return await ErrorHandler.tryCatch(async () => {
+        // chrono.parseDate returns a Date object or null if no date is found.
+        const parsedDate = chrono.parseDate(text, refDate, { forwardDate: true });
+        if (parsedDate) {
+            logger.debug(`Successfully parsed "${text}" to ${parsedDate.toISOString()}`, logContext);
+            return parsedDate;
+        }
+        else {
+            // This is not an error, but chrono-node couldn't find a date.
+            logger.info(`Could not parse a date from string: "${text}"`, logContext);
+            return null;
+        }
+    }, {
+        operation,
+        context: logContext, // Pass the enriched logContext
+        input: { text, refDate: refDate?.toISOString() }, // Log refDate as ISO string for consistency
+        errorCode: BaseErrorCode.PARSING_ERROR, // Default error code for unexpected parsing failures
+    });
+}
+/**
+ * Parses a natural language date string and returns detailed parsing results,
+ * including all components and their confidence levels, as provided by `chrono-node`.
+ *
+ * @async
+ * @param {string} text - The natural language date string to parse.
+ * @param {RequestContext} context - The request context for logging and error tracking.
+ * @param {Date} [refDate] - Optional reference date for parsing relative date expressions.
+ *   Defaults to the current date and time if not provided.
+ * @returns {Promise<chrono.ParsedResult[]>} A promise that resolves to an array of
+ *   `chrono.ParsedResult` objects. The array will be empty if no date components
+ *   could be parsed from the input string.
+ * @throws {McpError} If an unexpected error occurs during the parsing process,
+ *   an `McpError` with `BaseErrorCode.PARSING_ERROR` is thrown.
+ */
+async function parseDateStringDetailed(text, context, refDate) {
+    const operation = "parseDateStringDetailed";
+    const logContext = {
+        ...context,
+        operation,
+        inputText: text,
+        refDate: refDate?.toISOString(),
+    };
+    logger.debug(`Attempting detailed parse of date string: "${text}"`, logContext);
+    return await ErrorHandler.tryCatch(async () => {
+        // chrono.parse returns an array of results.
+        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: refDate?.toISOString() },
+        errorCode: BaseErrorCode.PARSING_ERROR,
+    });
+}
+/**
+ * Provides methods for parsing natural language date strings.
+ * - `parseToDate`: Parses a string to a single `Date` object or `null`.
+ * - `getDetailedResults`: Provides comprehensive parsing results from `chrono-node`.
+ */
+export const dateParser = {
+    /**
+     * Parses a natural language date string into a `Date` object.
+     * @see {@link parseDateString}
+     */
+    parseToDate: parseDateString,
+    /**
+     * Parses a natural language date string and returns detailed `chrono.ParsedResult` objects.
+     * @see {@link parseDateStringDetailed}
+     */
+    getDetailedResults: parseDateStringDetailed,
+};

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,3 @@
+export * from "./jsonParser.js";
+export * from "./dateParser.js";
+// Removed export for dateUtils.js as it was moved

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

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Provides a utility class for parsing potentially partial JSON strings,
+ * with support for handling and logging optional LLM <think> blocks.
+ * It wraps the 'partial-json' library.
+ * @module src/utils/parsing/jsonParser
+ */
+import { RequestContext } from "../internal/index.js";
+/**
+ * Enum mirroring `partial-json`'s `Allow` constants. These constants specify
+ * what types of partial JSON structures are permissible during parsing.
+ * They can be combined using bitwise OR (e.g., `Allow.STR | Allow.OBJ`).
+ *
+ * - `Allow.OBJ`: Allows partial objects (e.g., `{"key": "value",`)
+ * - `Allow.ARR`: Allows partial arrays (e.g., `[1, 2,`)
+ * - `Allow.STR`: Allows partial strings (e.g., `"abc`)
+ * - `Allow.NUM`: Allows partial numbers (e.g., `1.2e+`)
+ * - `Allow.BOOL`: Allows partial booleans (e.g., `tru`)
+ * - `Allow.NULL`: Allows partial nulls (e.g., `nul`)
+ * - `Allow.ALL`: Allows all types of partial JSON structures (default).
+ */
+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 JSON strings that may be partial or incomplete.
+ * It wraps the 'partial-json' library to provide a consistent parsing interface
+ * and includes logic to handle and log optional `<think>...</think>` blocks
+ * that might precede the JSON content (often found in LLM outputs).
+ */
+declare class JsonParser {
+    /**
+     * Parses a JSON string, which may be partial or prefixed with an LLM `<think>` block.
+     *
+     * @template T The expected type of the parsed JavaScript value. Defaults to `any`.
+     * @param {string} jsonString - The JSON string to parse.
+     * @param {number} [allowPartial=Allow.ALL] - A bitwise OR combination of `Allow` constants
+     *   specifying which types of partial JSON structures are permissible (e.g., `Allow.OBJ | Allow.ARR`).
+     *   Defaults to `Allow.ALL`, permitting any form of partial JSON.
+     * @param {RequestContext} [providedContext] - Optional `RequestContext` for logging,
+     *   especially for capturing `<think>` block content or parsing errors.
+     * @returns {T} The parsed JavaScript value.
+     * @throws {McpError} Throws an `McpError` with `BaseErrorCode.VALIDATION_ERROR` if:
+     *   - The string is empty after removing a `<think>` block.
+     *   - The remaining content does not appear to be a valid JSON structure (object, array, or permitted primitive).
+     *   - The `partial-json` library encounters a parsing error.
+     */
+    parse<T = any>(jsonString: string, allowPartial?: number, providedContext?: RequestContext): T;
+}
+/**
+ * Singleton instance of the `JsonParser`.
+ * Use this instance for all partial JSON parsing needs.
+ *
+ * Example:
+ * ```typescript
+ * import { jsonParser, Allow, RequestContext } from './jsonParser';
+ * import { requestContextService } from '../internal'; // Assuming requestContextService is exported from internal utils
+ * const context: RequestContext = requestContextService.createRequestContext({ operation: 'MyOperation' });
+ * try {
+ *   const data = jsonParser.parse('<think>Thinking...</think>{"key": "value", "arr": [1,', Allow.ALL, context);
+ *   console.log(data); // Output: { key: "value", arr: [ 1 ] }
+ * } catch (e) {
+ *   console.error("Parsing failed:", e);
+ * }
+ * ```
+ */
+export declare const jsonParser: JsonParser;
+export {};