@cyanheads/pubmed-mcp-server 1.0.12

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/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;

package/dist/utils/parsing/jsonParser.js

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Provides a utility class for parsing potentially partial JSON strings.
+ * It wraps the 'partial-json' npm library and includes functionality to handle
+ * optional <think>...</think> blocks often found at the beginning of LLM outputs.
+ * @module src/utils/parsing/jsonParser
+ */
+import { parse as parsePartialJson, Allow as PartialJsonAllow, } from "partial-json";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, requestContextService } 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 const Allow = PartialJsonAllow;
+/**
+ * Regular expression to find a <think> block at the start of a string.
+ * Captures content within <think>...</think> (Group 1) and the rest of the string (Group 2).
+ * @private
+ */
+const thinkBlockRegex = /^<think>([\s\S]*?)<\/think>\s*([\s\S]*)$/;
+/**
+ * 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 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(jsonString, allowPartial = Allow.ALL, context) {
+        let stringToParse = jsonString;
+        const match = jsonString.match(thinkBlockRegex);
+        if (match) {
+            const thinkContent = match[1].trim();
+            const restOfString = match[2];
+            const logContext = context ||
+                requestContextService.createRequestContext({
+                    operation: "JsonParser.thinkBlock",
+                });
+            if (thinkContent) {
+                logger.debug("LLM <think> block detected and logged.", {
+                    ...logContext,
+                    thinkContent,
+                });
+            }
+            else {
+                logger.debug("Empty LLM <think> block detected.", logContext);
+            }
+            stringToParse = restOfString;
+        }
+        stringToParse = stringToParse.trim();
+        if (!stringToParse) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, "JSON string is empty after removing <think> block and trimming.", context);
+        }
+        try {
+            return parsePartialJson(stringToParse, allowPartial);
+        }
+        catch (error) {
+            const errorLogContext = context ||
+                requestContextService.createRequestContext({
+                    operation: "JsonParser.parseError",
+                });
+            logger.error("Failed to parse JSON content.", {
+                ...errorLogContext,
+                errorDetails: error.message,
+                contentAttempted: stringToParse.substring(0, 200),
+            });
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Failed to parse JSON: ${error.message}`, {
+                ...context,
+                originalContentSample: stringToParse.substring(0, 200) +
+                    (stringToParse.length > 200 ? "..." : ""),
+                rawError: error instanceof Error ? error.stack : String(error),
+            });
+        }
+    }
+}
+/**
+ * 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 const jsonParser = new JsonParser();

package/dist/utils/parsing/ncbi-parsing/eSummaryResultParser.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Helper functions for parsing ESummary results from NCBI.
+ * Handles different ESummary XML structures and formats the data into
+ * consistent ParsedBriefSummary objects.
+ * @module src/utils/parsing/ncbi-parsing/eSummaryResultParser
+ */
+import { ESummaryResult, ParsedBriefSummary, ESummaryAuthor as XmlESummaryAuthor } from "../../../types-global/pubmedXml.js";
+import { RequestContext } from "../../../utils/index.js";
+/**
+ * Formats an array of ESummary authors into a string.
+ * Limits to the first 3 authors and adds "et al." if more exist.
+ * @param authors - Array of ESummary author objects (normalized).
+ * @returns A string like "Doe J, Smith A, Brown B, et al." or empty if no authors.
+ */
+export declare function formatESummaryAuthors(authors?: XmlESummaryAuthor[]): string;
+/**
+ * Standardizes date strings from ESummary to "YYYY-MM-DD" format.
+ * Uses the dateParser utility.
+ * @param dateStr - Date string from ESummary (e.g., "2023/01/15", "2023 Jan 15", "2023").
+ * @param parentContext - Optional parent request context for logging.
+ * @returns A promise resolving to a standardized date string ("YYYY-MM-DD") or undefined if parsing fails.
+ */
+export declare function standardizeESummaryDate(dateStr?: string, parentContext?: RequestContext): Promise<string | undefined>;
+/**
+ * Extracts and formats brief summaries from ESummary XML result.
+ * Handles both DocumentSummarySet (newer) and older DocSum structures.
+ * Asynchronously standardizes dates.
+ * @param eSummaryResult - The parsed XML object from ESummary (eSummaryResult part).
+ * @param context - Request context for logging and passing to date standardization.
+ * @returns A promise resolving to an array of parsed brief summary objects.
+ */
+export declare function extractBriefSummaries(eSummaryResult?: ESummaryResult, context?: RequestContext): Promise<ParsedBriefSummary[]>;