@cyanheads/pubchem-mcp-server 1.0.1

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/scheduling/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from "./scheduler.js";

package/dist/utils/scheduling/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from "./scheduler.js";

package/dist/utils/scheduling/scheduler.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ * This service wraps the 'node-cron' library to offer a unified interface for
+ * defining, starting, stopping, and listing recurring tasks within the application.
+ * @module src/utils/scheduling/scheduler
+ */
+import { ScheduledTask } from "node-cron";
+import { RequestContext } from "../internal/index.js";
+/**
+ * Represents a scheduled job managed by the SchedulerService.
+ */
+export interface Job {
+    /** A unique identifier for the job. */
+    id: string;
+    /** The cron pattern defining the job's schedule. */
+    schedule: string;
+    /** A description of what the job does. */
+    description: string;
+    /** The underlying 'node-cron' task instance. */
+    task: ScheduledTask;
+    /** Indicates whether the job is currently running. */
+    isRunning: boolean;
+}
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export declare class SchedulerService {
+    private static instance;
+    private jobs;
+    /** @private */
+    private constructor();
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance(): SchedulerService;
+    /**
+     * Schedules a new job.
+     *
+     * @param id - A unique identifier for the job.
+     * @param schedule - The cron pattern for the schedule (e.g., '* * * * *').
+     * @param taskFunction - The function to execute on schedule. It receives a RequestContext.
+     * @param description - A description of the job.
+     * @returns The newly created Job object.
+     */
+    schedule(id: string, schedule: string, taskFunction: (context: RequestContext) => void | Promise<void>, description: string): Job;
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id: string): void;
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id: string): void;
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id: string): void;
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs(): Job[];
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export declare const schedulerService: SchedulerService;

package/dist/utils/scheduling/scheduler.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ * This service wraps the 'node-cron' library to offer a unified interface for
+ * defining, starting, stopping, and listing recurring tasks within the application.
+ * @module src/utils/scheduling/scheduler
+ */
+import cron from "node-cron";
+import { logger } from "../internal/index.js";
+import { requestContextService } from "../internal/requestContext.js";
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export class SchedulerService {
+    /** @private */
+    constructor() {
+        this.jobs = new Map();
+        logger.info("SchedulerService initialized.", {
+            requestId: "scheduler-init",
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance() {
+        if (!SchedulerService.instance) {
+            SchedulerService.instance = new SchedulerService();
+        }
+        return SchedulerService.instance;
+    }
+    /**
+     * Schedules a new job.
+     *
+     * @param id - A unique identifier for the job.
+     * @param schedule - The cron pattern for the schedule (e.g., '* * * * *').
+     * @param taskFunction - The function to execute on schedule. It receives a RequestContext.
+     * @param description - A description of the job.
+     * @returns The newly created Job object.
+     */
+    schedule(id, schedule, taskFunction, description) {
+        if (this.jobs.has(id)) {
+            throw new Error(`Job with ID '${id}' already exists.`);
+        }
+        if (!cron.validate(schedule)) {
+            throw new Error(`Invalid cron schedule: ${schedule}`);
+        }
+        const task = cron.schedule(schedule, async () => {
+            const job = this.jobs.get(id);
+            if (job && job.isRunning) {
+                logger.warning(`Job '${id}' is already running. Skipping this execution.`, {
+                    requestId: `job-skip-${id}`,
+                    timestamp: new Date().toISOString(),
+                });
+                return;
+            }
+            if (job) {
+                job.isRunning = true;
+            }
+            const context = requestContextService.createRequestContext({
+                jobId: id,
+                schedule,
+            });
+            logger.info(`Starting job '${id}'...`, context);
+            try {
+                await Promise.resolve(taskFunction(context));
+                logger.info(`Job '${id}' completed successfully.`, context);
+            }
+            catch (error) {
+                logger.error(`Job '${id}' failed.`, error, context);
+            }
+            finally {
+                if (job) {
+                    job.isRunning = false;
+                }
+            }
+        }, {
+            scheduled: false, // Do not start immediately
+        });
+        const newJob = {
+            id,
+            schedule,
+            description,
+            task,
+            isRunning: false,
+        };
+        this.jobs.set(id, newJob);
+        logger.info(`Job '${id}' scheduled: ${description}`, {
+            requestId: `job-schedule-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+        return newJob;
+    }
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.start();
+        logger.info(`Job '${id}' started.`, {
+            requestId: `job-start-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        logger.info(`Job '${id}' stopped.`, {
+            requestId: `job-stop-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        this.jobs.delete(id);
+        logger.info(`Job '${id}' removed.`, {
+            requestId: `job-remove-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs() {
+        return Array.from(this.jobs.values());
+    }
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export const schedulerService = SchedulerService.getInstance();

package/dist/utils/security/idGenerator.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Defines the structure for configuring entity prefixes.
+ * Keys are entity type names (e.g., "project", "task"), and values are their corresponding ID prefixes (e.g., "PROJ", "TASK").
+ */
+export interface EntityPrefixConfig {
+    [key: string]: string;
+}
+/**
+ * Defines options for customizing ID generation.
+ */
+export interface IdGenerationOptions {
+    length?: number;
+    separator?: string;
+    charset?: string;
+}
+/**
+ * A generic ID Generator class for creating and managing unique, prefixed identifiers.
+ * Allows defining custom prefixes, generating random strings, and validating/normalizing IDs.
+ */
+export declare class IdGenerator {
+    /**
+     * Default character set for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_CHARSET;
+    /**
+     * Default separator character between prefix and random part.
+     * @private
+     */
+    private static DEFAULT_SEPARATOR;
+    /**
+     * Default length for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_LENGTH;
+    /**
+     * Stores the mapping of entity types to their prefixes.
+     * @private
+     */
+    private entityPrefixes;
+    /**
+     * Stores a reverse mapping from prefixes (case-insensitive) to entity types.
+     * @private
+     */
+    private prefixToEntityType;
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param entityPrefixes - An initial map of entity types to their prefixes.
+     */
+    constructor(entityPrefixes?: EntityPrefixConfig);
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal reverse lookup map.
+     * @param entityPrefixes - A map where keys are entity type names and values are their desired ID prefixes.
+     */
+    setEntityPrefixes(entityPrefixes: EntityPrefixConfig): void;
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns The current entity prefix configuration.
+     */
+    getEntityPrefixes(): EntityPrefixConfig;
+    /**
+     * Generates a cryptographically secure random string.
+     * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
+     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @returns The generated random string.
+     */
+    generateRandomString(length?: number, charset?: string): string;
+    /**
+     * Generates a unique ID, optionally prepended with a prefix.
+     * @param prefix - An optional prefix for the ID.
+     * @param options - Optional parameters for ID generation (length, separator, charset).
+     * @returns A unique identifier string.
+     */
+    generate(prefix?: string, options?: IdGenerationOptions): string;
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * @param entityType - The type of entity (must be registered).
+     * @param options - Optional parameters for ID generation.
+     * @returns A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered.
+     */
+    generateForEntity(entityType: string, options?: IdGenerationOptions): string;
+    /**
+     * Validates if an ID conforms to the expected format for a specific entity type.
+     * @param id - The ID string to validate.
+     * @param entityType - The expected entity type of the ID.
+     * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
+     * @returns `true` if the ID is valid, `false` otherwise.
+     */
+    isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
+    /**
+     * Escapes special characters in a string for use in a regular expression.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     * @private
+     */
+    private escapeRegex;
+    /**
+     * Strips the prefix and separator from an ID string.
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The ID part without the prefix, or the original ID if separator not found.
+     */
+    stripPrefix(id: string, separator?: string): string;
+    /**
+     * Determines the entity type from an ID string by its prefix (case-insensitive).
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The determined entity type.
+     * @throws {McpError} If ID format is invalid or prefix is unknown.
+     */
+    getEntityType(id: string, separator?: string): string;
+    /**
+     * Normalizes an entity ID to ensure the prefix matches the registered case
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
+     * @param id - The ID to normalize (e.g., "proj_a6b3j0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The normalized ID (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the entity type cannot be determined from the ID.
+     */
+    normalize(id: string, separator?: string): string;
+}
+/**
+ * Default singleton instance of the `IdGenerator`.
+ * Initialize with `idGenerator.setEntityPrefixes({})` to configure.
+ */
+export declare const idGenerator: IdGenerator;
+/**
+ * Generates a standard Version 4 UUID (Universally Unique Identifier).
+ * Uses the Node.js `crypto` module. This function is independent of the IdGenerator instance
+ * to prevent circular dependencies when used by other utilities like requestContextService.
+ * @returns A new UUID string.
+ */
+export declare const generateUUID: () => string;