@cyanheads/pubchem-mcp-server 1.0.1

package/dist/utils/internal/requestContext.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Utilities for creating and managing request contexts.
+ * A request context is an object carrying a unique ID, timestamp, and other
+ * relevant data for logging, tracing, and processing. It also defines
+ * configuration and operational context structures.
+ * @module src/utils/internal/requestContext
+ */
+import { generateUUID } from "../index.js";
+import { logger } from "./logger.js";
+/**
+ * Singleton-like service object for managing request context operations.
+ * @private
+ */
+const requestContextServiceInstance = {
+    /**
+     * Internal configuration store for the service.
+     */
+    config: {},
+    /**
+     * Configures the request context service with new settings.
+     * Merges the provided partial configuration with existing settings.
+     *
+     * @param config - A partial `ContextConfig` object containing settings to update or add.
+     * @returns A shallow copy of the newly updated configuration.
+     */
+    configure(config) {
+        this.config = {
+            ...this.config,
+            ...config,
+        };
+        const logContext = this.createRequestContext({
+            operation: "RequestContextService.configure",
+            newConfigState: { ...this.config },
+        });
+        logger.debug("RequestContextService configuration updated", logContext);
+        return { ...this.config };
+    },
+    /**
+     * Retrieves a shallow copy of the current service configuration.
+     * This prevents direct mutation of the internal configuration state.
+     *
+     * @returns A shallow copy of the current `ContextConfig`.
+     */
+    getConfig() {
+        return { ...this.config };
+    },
+    /**
+     * Creates a new {@link RequestContext} instance.
+     * Each context is assigned a unique `requestId` (UUID) and a current `timestamp` (ISO 8601).
+     * Additional custom properties can be merged into the context.
+     *
+     * @param additionalContext - An optional record of key-value pairs to be
+     *   included in the created request context.
+     * @returns A new `RequestContext` object.
+     */
+    createRequestContext(additionalContext = {}) {
+        const requestId = generateUUID();
+        const timestamp = new Date().toISOString();
+        const context = {
+            requestId,
+            timestamp,
+            ...additionalContext,
+        };
+        return context;
+    },
+};
+/**
+ * Primary export for request context functionalities.
+ * This service provides methods to create and manage {@link RequestContext} instances,
+ * which are essential for logging, tracing, and correlating operations.
+ */
+export const requestContextService = requestContextServiceInstance;

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for metrics-related utility modules.
+ * This file re-exports utilities for collecting and processing metrics,
+ * such as token counting.
+ * @module src/utils/metrics
+ */
+export * from "./tokenCounter.js";

package/dist/utils/metrics/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for metrics-related utility modules.
+ * This file re-exports utilities for collecting and processing metrics,
+ * such as token counting.
+ * @module src/utils/metrics
+ */
+export * from "./tokenCounter.js";

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

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Provides utility functions for counting tokens in text and chat messages
+ * using the `tiktoken` library, specifically configured for 'gpt-4o' tokenization.
+ * These functions are essential for managing token limits and estimating costs
+ * when interacting with language models.
+ * @module src/utils/metrics/tokenCounter
+ */
+import { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import { RequestContext } from "../index.js";
+/**
+ * Calculates the number of tokens for a given text string using the
+ * tokenizer specified by `TOKENIZATION_MODEL`.
+ * Wraps tokenization in `ErrorHandler.tryCatch` for robust error management.
+ *
+ * @param text - The input text to tokenize.
+ * @param context - Optional request context for logging and error handling.
+ * @returns A promise that resolves with the number of tokens in the text.
+ * @throws {McpError} If tokenization fails.
+ */
+export declare function countTokens(text: string, context?: RequestContext): Promise<number>;
+/**
+ * Calculates the estimated number of tokens for an array of chat messages.
+ * Uses the tokenizer specified by `TOKENIZATION_MODEL` and accounts for
+ * special tokens and message overhead according to OpenAI's guidelines.
+ *
+ * For multi-part content, only text parts are currently tokenized.
+ *
+ * Reference: {@link https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb}
+ *
+ * @param messages - An array of chat messages.
+ * @param context - Optional request context for logging and error handling.
+ * @returns A promise that resolves with the estimated total number of tokens.
+ * @throws {McpError} If tokenization fails.
+ */
+export declare function countChatTokens(messages: ReadonlyArray<ChatCompletionMessageParam>, context?: RequestContext): Promise<number>;

package/dist/utils/metrics/tokenCounter.js

@@ -0,0 +1,110 @@
+import { encoding_for_model } from "tiktoken";
+import { BaseErrorCode } from "../../types-global/errors.js";
+import { ErrorHandler, logger } from "../index.js";
+/**
+ * The specific Tiktoken model used for all tokenization operations in this module.
+ * This ensures consistent token counting.
+ * @private
+ */
+const TOKENIZATION_MODEL = "gpt-4o";
+/**
+ * Calculates the number of tokens for a given text string using the
+ * tokenizer specified by `TOKENIZATION_MODEL`.
+ * Wraps tokenization in `ErrorHandler.tryCatch` for robust error management.
+ *
+ * @param text - The input text to tokenize.
+ * @param context - Optional request context for logging and error handling.
+ * @returns A promise that resolves with the number of tokens in the text.
+ * @throws {McpError} If tokenization fails.
+ */
+export async function countTokens(text, context) {
+    return ErrorHandler.tryCatch(() => {
+        let encoding = null;
+        try {
+            encoding = encoding_for_model(TOKENIZATION_MODEL);
+            const tokens = encoding.encode(text);
+            return tokens.length;
+        }
+        finally {
+            encoding?.free();
+        }
+    }, {
+        operation: "countTokens",
+        context: context,
+        input: { textSample: text.substring(0, 50) + "..." },
+        errorCode: BaseErrorCode.INTERNAL_ERROR,
+    });
+}
+/**
+ * Calculates the estimated number of tokens for an array of chat messages.
+ * Uses the tokenizer specified by `TOKENIZATION_MODEL` and accounts for
+ * special tokens and message overhead according to OpenAI's guidelines.
+ *
+ * For multi-part content, only text parts are currently tokenized.
+ *
+ * Reference: {@link https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb}
+ *
+ * @param messages - An array of chat messages.
+ * @param context - Optional request context for logging and error handling.
+ * @returns A promise that resolves with the estimated total number of tokens.
+ * @throws {McpError} If tokenization fails.
+ */
+export async function countChatTokens(messages, context) {
+    return ErrorHandler.tryCatch(() => {
+        let encoding = null;
+        let num_tokens = 0;
+        try {
+            encoding = encoding_for_model(TOKENIZATION_MODEL);
+            const tokens_per_message = 3; // For gpt-4o, gpt-4, gpt-3.5-turbo
+            const tokens_per_name = 1; // For gpt-4o, gpt-4, gpt-3.5-turbo
+            for (const message of messages) {
+                num_tokens += tokens_per_message;
+                num_tokens += encoding.encode(message.role).length;
+                if (typeof message.content === "string") {
+                    num_tokens += encoding.encode(message.content).length;
+                }
+                else if (Array.isArray(message.content)) {
+                    for (const part of message.content) {
+                        if (part.type === "text") {
+                            num_tokens += encoding.encode(part.text).length;
+                        }
+                        else {
+                            logger.warning(`Non-text content part found (type: ${part.type}), token count contribution ignored.`, context);
+                        }
+                    }
+                }
+                if ("name" in message && message.name) {
+                    num_tokens += tokens_per_name;
+                    num_tokens += encoding.encode(message.name).length;
+                }
+                if (message.role === "assistant" &&
+                    "tool_calls" in message &&
+                    message.tool_calls) {
+                    for (const tool_call of message.tool_calls) {
+                        if (tool_call.function.name) {
+                            num_tokens += encoding.encode(tool_call.function.name).length;
+                        }
+                        if (tool_call.function.arguments) {
+                            num_tokens += encoding.encode(tool_call.function.arguments).length;
+                        }
+                    }
+                }
+                if (message.role === "tool" &&
+                    "tool_call_id" in message &&
+                    message.tool_call_id) {
+                    num_tokens += encoding.encode(message.tool_call_id).length;
+                }
+            }
+            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 },
+        errorCode: BaseErrorCode.INTERNAL_ERROR,
+    });
+}

package/dist/utils/network/fetchWithTimeout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Provides a utility function to make fetch requests with a specified timeout.
+ * @module src/utils/network/fetchWithTimeout
+ */
+import type { RequestContext } from "../internal/requestContext.js";
+/**
+ * Options for the fetchWithTimeout utility.
+ * Extends standard RequestInit but omits 'signal' as it's handled internally.
+ */
+export type FetchWithTimeoutOptions = Omit<RequestInit, "signal">;
+/**
+ * Fetches a resource with a specified timeout.
+ *
+ * @param url - The URL to fetch.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @param context - The request context for logging.
+ * @param options - Optional fetch options (RequestInit), excluding 'signal'.
+ * @returns A promise that resolves to the Response object.
+ * @throws {McpError} If the request times out or another fetch-related error occurs.
+ */
+export declare function fetchWithTimeout(url: string | URL, timeoutMs: number, context: RequestContext, options?: FetchWithTimeoutOptions): Promise<Response>;

package/dist/utils/network/fetchWithTimeout.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Provides a utility function to make fetch requests with a specified timeout.
+ * @module src/utils/network/fetchWithTimeout
+ */
+import { logger } from "../internal/logger.js"; // Adjusted import path
+import { McpError, BaseErrorCode } from "../../types-global/errors.js";
+/**
+ * Fetches a resource with a specified timeout.
+ *
+ * @param url - The URL to fetch.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @param context - The request context for logging.
+ * @param options - Optional fetch options (RequestInit), excluding 'signal'.
+ * @returns A promise that resolves to the Response object.
+ * @throws {McpError} If the request times out or another fetch-related error occurs.
+ */
+export async function fetchWithTimeout(url, timeoutMs, context, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const urlString = url.toString();
+    const operationDescription = `fetch ${options?.method || "GET"} ${urlString}`;
+    logger.debug(`Attempting ${operationDescription} with ${timeoutMs}ms timeout.`, context);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        logger.debug(`Successfully fetched ${urlString}. Status: ${response.status}`, context);
+        return response;
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Error && error.name === "AbortError") {
+            logger.error(`${operationDescription} timed out after ${timeoutMs}ms.`, {
+                ...context,
+                errorSource: "FetchTimeout",
+            });
+            throw new McpError(BaseErrorCode.TIMEOUT, `${operationDescription} timed out.`, { ...context, errorSource: "FetchTimeout" });
+        }
+        // Log and re-throw other errors as McpError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Network error during ${operationDescription}: ${errorMessage}`, {
+            ...context,
+            originalErrorName: error instanceof Error ? error.name : "UnknownError",
+            errorSource: "FetchNetworkError",
+        });
+        if (error instanceof McpError) {
+            // If it's already an McpError, re-throw it
+            throw error;
+        }
+        throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, // Generic error for network/service issues
+        `Network error during ${operationDescription}: ${errorMessage}`, {
+            ...context,
+            originalErrorName: error instanceof Error ? error.name : "UnknownError",
+            errorSource: "FetchNetworkErrorWrapper",
+        });
+    }
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for network utilities.
+ * @module src/utils/network/index
+ */
+export * from "./fetchWithTimeout.js";
+export type { FetchWithTimeoutOptions } from "./fetchWithTimeout.js";

package/dist/utils/network/index.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Barrel file for network utilities.
+ * @module src/utils/network/index
+ */
+export * from "./fetchWithTimeout.js";

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

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Provides utility functions 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 "../index.js";
+/**
+ * Parses a natural language date string into a JavaScript Date object.
+ * Uses `chrono.parseDate` for lenient parsing of various date formats.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with a Date object or `null` if parsing fails.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+declare function parseDateString(text: string, context: RequestContext, refDate?: Date): Promise<Date | null>;
+/**
+ * Parses a natural language date string and returns detailed parsing results.
+ * Provides more information than just the Date object, including matched text and components.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with an array of `chrono.ParsedResult` objects. Empty if no dates found.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+declare function parseDateStringDetailed(text: string, context: RequestContext, refDate?: Date): Promise<chrono.ParsedResult[]>;
+/**
+ * An object providing date parsing functionalities.
+ *
+ * @example
+ * ```typescript
+ * import { dateParser, requestContextService } from './utils'; // Assuming utils/index.js exports these
+ * const context = requestContextService.createRequestContext({ operation: 'TestDateParsing' });
+ *
+ * async function testParsing() {
+ *   const dateObj = await dateParser.parseDate("next Friday at 3pm", context);
+ *   if (dateObj) {
+ *     console.log("Parsed Date:", dateObj.toISOString());
+ *   }
+ *
+ *   const detailedResults = await dateParser.parse("Meeting on 2024-12-25 and another one tomorrow", context);
+ *   detailedResults.forEach(result => {
+ *     console.log("Detailed Result:", result.text, result.start.date());
+ *   });
+ * }
+ * testParsing();
+ * ```
+ */
+export declare const dateParser: {
+    /**
+     * Parses a natural language date string and returns detailed parsing results
+     * from `chrono-node`.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with an array of `chrono.ParsedResult` objects.
+     */
+    parse: typeof parseDateStringDetailed;
+    /**
+     * Parses a natural language date string into a single JavaScript Date object.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with a Date object or `null`.
+     */
+    parseDate: typeof parseDateString;
+};
+export {};

package/dist/utils/parsing/dateParser.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Provides utility functions 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 "../index.js";
+/**
+ * Parses a natural language date string into a JavaScript Date object.
+ * Uses `chrono.parseDate` for lenient parsing of various date formats.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with a Date object or `null` if parsing fails.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+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.
+ * Provides more information than just the Date object, including matched text and components.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with an array of `chrono.ParsedResult` objects. Empty if no dates found.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+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,
+    });
+}
+/**
+ * An object providing date parsing functionalities.
+ *
+ * @example
+ * ```typescript
+ * import { dateParser, requestContextService } from './utils'; // Assuming utils/index.js exports these
+ * const context = requestContextService.createRequestContext({ operation: 'TestDateParsing' });
+ *
+ * async function testParsing() {
+ *   const dateObj = await dateParser.parseDate("next Friday at 3pm", context);
+ *   if (dateObj) {
+ *     console.log("Parsed Date:", dateObj.toISOString());
+ *   }
+ *
+ *   const detailedResults = await dateParser.parse("Meeting on 2024-12-25 and another one tomorrow", context);
+ *   detailedResults.forEach(result => {
+ *     console.log("Detailed Result:", result.text, result.start.date());
+ *   });
+ * }
+ * testParsing();
+ * ```
+ */
+export const dateParser = {
+    /**
+     * Parses a natural language date string and returns detailed parsing results
+     * from `chrono-node`.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with an array of `chrono.ParsedResult` objects.
+     */
+    parse: parseDateStringDetailed,
+    /**
+     * Parses a natural language date string into a single JavaScript Date object.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with a Date object or `null`.
+     */
+    parseDate: parseDateString,
+};

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

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel file for parsing utility modules.
+ * This file re-exports utilities related to parsing various data formats,
+ * such as JSON and dates.
+ * @module src/utils/parsing
+ */
+export * from "./dateParser.js";
+export * from "./jsonParser.js";

package/dist/utils/parsing/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel file for parsing utility modules.
+ * This file re-exports utilities related to parsing various data formats,
+ * such as JSON and dates.
+ * @module src/utils/parsing
+ */
+export * from "./dateParser.js";
+export * from "./jsonParser.js";

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

@@ -0,0 +1,82 @@
+import { RequestContext } from "../index.js";
+/**
+ * Enum mirroring `partial-json`'s `Allow` constants. These specify
+ * what types of partial JSON structures are permissible during parsing.
+ * They can be combined using bitwise OR (e.g., `Allow.STR | Allow.OBJ`).
+ *
+ * The available properties are:
+ * - `STR`: Allow partial string.
+ * - `NUM`: Allow partial number.
+ * - `ARR`: Allow partial array.
+ * - `OBJ`: Allow partial object.
+ * - `NULL`: Allow partial null.
+ * - `BOOL`: Allow partial boolean.
+ * - `NAN`: Allow partial NaN. (Note: Standard JSON does not support NaN)
+ * - `INFINITY`: Allow partial Infinity. (Note: Standard JSON does not support Infinity)
+ * - `_INFINITY`: Allow partial -Infinity. (Note: Standard JSON does not support -Infinity)
+ * - `INF`: Allow both partial Infinity and -Infinity.
+ * - `SPECIAL`: Allow all special values (NaN, Infinity, -Infinity).
+ * - `ATOM`: Allow all atomic values (strings, numbers, booleans, null, special values).
+ * - `COLLECTION`: Allow all collection values (objects, arrays).
+ * - `ALL`: Allow all value types to be partial (default for `partial-json`'s parse).
+ * @see {@link https://github.com/promplate/partial-json-parser-js} for more details.
+ */
+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 for robust JSON parsing, handling
+ * incomplete structures and optional <think> blocks from LLMs.
+ */
+export declare class JsonParser {
+    /**
+     * Parses a JSON string, which may be partial or prefixed with a <think> block.
+     * If a <think> block is present, its content is logged, and parsing proceeds on the
+     * remainder. Uses 'partial-json' to handle incomplete JSON.
+     *
+     * @template T The expected type of the parsed JSON object. Defaults to `any`.
+     * @param jsonString - The JSON string to parse.
+     * @param allowPartial - Bitwise OR combination of `Allow` constants specifying permissible
+     *   partial JSON types. Defaults to `Allow.ALL`.
+     * @param context - Optional `RequestContext` for logging and error correlation.
+     * @returns The parsed JavaScript value.
+     * @throws {McpError} If the string is empty after processing or if `partial-json` fails.
+     */
+    parse<T = any>(jsonString: string, allowPartial?: number, context?: RequestContext): T;
+}
+/**
+ * Singleton instance of the `JsonParser`.
+ * Use this instance to parse JSON strings, with support for partial JSON and <think> blocks.
+ * @example
+ * ```typescript
+ * import { jsonParser, Allow, requestContextService } from './utils';
+ * const context = requestContextService.createRequestContext({ operation: 'TestJsonParsing' });
+ *
+ * const fullJson = '{"key": "value"}';
+ * const parsedFull = jsonParser.parse(fullJson, Allow.ALL, context);
+ * console.log(parsedFull); // Output: { key: 'value' }
+ *
+ * const partialObject = '<think>This is a thought.</think>{"key": "value", "arr": [1,';
+ * try {
+ *   const parsedPartial = jsonParser.parse(partialObject, undefined, context);
+ *   console.log(parsedPartial);
+ * } catch (e) {
+ *   console.error("Parsing partial object failed:", e);
+ * }
+ * ```
+ */
+export declare const jsonParser: JsonParser;