@cyanheads/pubchem-mcp-server 1.0.1

package/dist/mcp-server/tools/fetchCompoundProperties/registration.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_compound_properties` tool.
+ * @module src/mcp-server/tools/fetchCompoundProperties/registration
+ */
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { PubchemFetchCompoundPropertiesInputSchema, pubchemFetchCompoundPropertiesLogic, } from "./logic.js";
+/**
+ * Registers the 'pubchem_fetch_compound_properties' tool with the MCP server.
+ * This tool fetches a list of specified physicochemical properties for one or more
+ * PubChem Compound IDs (CIDs).
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export const registerPubchemFetchCompoundPropertiesTool = async (server) => {
+    const toolName = "pubchem_fetch_compound_properties";
+    const toolDescription = "Fetches a list of specified physicochemical properties (e.g., MolecularWeight, XLogP) for one or more PubChem Compound IDs (CIDs). Essential for retrieving detailed chemical data in bulk.";
+    server.tool(toolName, toolDescription, PubchemFetchCompoundPropertiesInputSchema.shape, async (params, mcpContext) => {
+        const handlerContext = requestContextService.createRequestContext({
+            operation: "HandleToolRequest",
+            toolName,
+            mcpToolContext: mcpContext,
+            input: params,
+        });
+        try {
+            logger.info(`Initiating tool request for ${toolName} for ${params.cids.length} CIDs.`, handlerContext);
+            const result = await pubchemFetchCompoundPropertiesLogic(params, handlerContext);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            const handledError = ErrorHandler.handleError(error, {
+                operation: "pubchemFetchCompoundPropertiesToolHandler",
+                context: handlerContext,
+                input: params,
+            });
+            // No need to log here, handleError already does it.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: ErrorHandler.formatError(handledError),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/mcp-server/tools/fetchCompoundXrefs/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the `pubchem_fetch_compound_xrefs` tool.
+ * This file serves as the public interface for the tool module,
+ * primarily exporting the `registerPubchemFetchCompoundXrefsTool` function.
+ * @module src/mcp-server/tools/fetchCompoundXrefs/index
+ */
+export { registerPubchemFetchCompoundXrefsTool } from "./registration.js";

package/dist/mcp-server/tools/fetchCompoundXrefs/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the `pubchem_fetch_compound_xrefs` tool.
+ * This file serves as the public interface for the tool module,
+ * primarily exporting the `registerPubchemFetchCompoundXrefsTool` function.
+ * @module src/mcp-server/tools/fetchCompoundXrefs/index
+ */
+export { registerPubchemFetchCompoundXrefsTool } from "./registration.js";

package/dist/mcp-server/tools/fetchCompoundXrefs/logic.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_compound_xrefs` tool.
+ * This version includes pagination for large responses.
+ * @module src/mcp-server/tools/fetchCompoundXrefs/logic
+ */
+import { z } from "zod";
+import { type RequestContext } from "../../../utils/index.js";
+export declare const PubchemXrefTypesEnum: z.ZodEnum<["RegistryID", "RN", "PubMedID", "PatentID", "GeneID", "ProteinGI", "TaxonomyID"]>;
+export declare const PubchemFetchCompoundXrefsInputSchema: z.ZodObject<{
+    cid: z.ZodNumber;
+    xrefTypes: z.ZodArray<z.ZodEnum<["RegistryID", "RN", "PubMedID", "PatentID", "GeneID", "ProteinGI", "TaxonomyID"]>, "many">;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    cid: number;
+    xrefTypes: ("RegistryID" | "RN" | "PubMedID" | "PatentID" | "GeneID" | "ProteinGI" | "TaxonomyID")[];
+    page: number;
+    pageSize: number;
+}, {
+    cid: number;
+    xrefTypes: ("RegistryID" | "RN" | "PubMedID" | "PatentID" | "GeneID" | "ProteinGI" | "TaxonomyID")[];
+    page?: number | undefined;
+    pageSize?: number | undefined;
+}>;
+export type PubchemFetchCompoundXrefsInput = z.infer<typeof PubchemFetchCompoundXrefsInputSchema>;
+export declare const PubchemFetchCompoundXrefsOutputSchema: z.ZodObject<{
+    cid: z.ZodNumber;
+    xrefs: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        ids: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        ids: (string | number)[];
+    }, {
+        type: string;
+        ids: (string | number)[];
+    }>, "many">;
+    pagination: z.ZodObject<{
+        currentPage: z.ZodNumber;
+        pageSize: z.ZodNumber;
+        totalRecords: z.ZodNumber;
+        totalPages: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        pageSize: number;
+        currentPage: number;
+        totalRecords: number;
+        totalPages: number;
+    }, {
+        pageSize: number;
+        currentPage: number;
+        totalRecords: number;
+        totalPages: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    cid: number;
+    xrefs: {
+        type: string;
+        ids: (string | number)[];
+    }[];
+    pagination: {
+        pageSize: number;
+        currentPage: number;
+        totalRecords: number;
+        totalPages: number;
+    };
+}, {
+    cid: number;
+    xrefs: {
+        type: string;
+        ids: (string | number)[];
+    }[];
+    pagination: {
+        pageSize: number;
+        currentPage: number;
+        totalRecords: number;
+        totalPages: number;
+    };
+}>;
+export type PubchemFetchCompoundXrefsOutput = z.infer<typeof PubchemFetchCompoundXrefsOutputSchema>;
+/**
+ * Core logic for the `pubchem_fetch_compound_xrefs` tool. It retrieves a paginated
+ * list of external cross-references (XRefs) for a given PubChem Compound ID (CID).
+ *
+ * @param {PubchemFetchCompoundXrefsInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchCompoundXrefsOutput>} A promise that resolves with the paginated cross-reference results.
+ * @throws {McpError} Throws a structured error if the API request fails, the CID is not found, or the response is malformed.
+ */
+export declare function pubchemFetchCompoundXrefsLogic(params: PubchemFetchCompoundXrefsInput, context: RequestContext): Promise<PubchemFetchCompoundXrefsOutput>;

package/dist/mcp-server/tools/fetchCompoundXrefs/logic.js

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_compound_xrefs` tool.
+ * This version includes pagination for large responses.
+ * @module src/mcp-server/tools/fetchCompoundXrefs/logic
+ */
+import { z } from "zod";
+import { pubChemApiClient } from "../../../services/pubchem/pubchemApiClient.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { logger } from "../../../utils/index.js";
+// 1. Define and export the Zod enum for available cross-reference types
+export const PubchemXrefTypesEnum = z.enum([
+    "RegistryID",
+    "RN",
+    "PubMedID",
+    "PatentID",
+    "GeneID",
+    "ProteinGI",
+    "TaxonomyID",
+]);
+// 2. Define and export the Zod schema for input validation
+export const PubchemFetchCompoundXrefsInputSchema = z.object({
+    cid: z
+        .number()
+        .int()
+        .positive()
+        .describe("The PubChem Compound ID (CID) to find cross-references for. Must be a positive integer."),
+    xrefTypes: z
+        .array(PubchemXrefTypesEnum)
+        .min(1, "At least one cross-reference type is required.")
+        .describe("A list of cross-reference types to retrieve."),
+    page: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(1)
+        .describe("The page number for pagination, used when the result set is large. Defaults to 1."),
+    pageSize: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(50)
+        .describe("The number of records to return per page. Defaults to 50."),
+});
+// 4. Define and export the Zod schemas for the tool's output
+const XrefGroupSchema = z.object({
+    type: z
+        .string()
+        .describe("The type of the cross-reference (e.g., 'PubMedID')."),
+    ids: z
+        .array(z.union([z.string(), z.number()]))
+        .describe("A list of identifiers for this type."),
+});
+const PaginationSchema = z.object({
+    currentPage: z.number().int().describe("The current page number."),
+    pageSize: z.number().int().describe("The number of records per page."),
+    totalRecords: z
+        .number()
+        .int()
+        .describe("The total number of records available."),
+    totalPages: z.number().int().describe("The total number of pages available."),
+});
+export const PubchemFetchCompoundXrefsOutputSchema = z.object({
+    cid: z.number().int().describe("The CID for which xrefs were fetched."),
+    xrefs: z
+        .array(XrefGroupSchema)
+        .describe("A paginated list of cross-references, grouped by type."),
+    pagination: PaginationSchema.describe("Pagination details for the result set."),
+});
+/**
+ * Core logic for the `pubchem_fetch_compound_xrefs` tool. It retrieves a paginated
+ * list of external cross-references (XRefs) for a given PubChem Compound ID (CID).
+ *
+ * @param {PubchemFetchCompoundXrefsInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchCompoundXrefsOutput>} A promise that resolves with the paginated cross-reference results.
+ * @throws {McpError} Throws a structured error if the API request fails, the CID is not found, or the response is malformed.
+ */
+export async function pubchemFetchCompoundXrefsLogic(params, context) {
+    logger.debug("Processing pubchem_fetch_compound_xrefs logic...", {
+        ...context,
+        params,
+    });
+    const { cid, xrefTypes, page, pageSize } = params;
+    const allXrefs = [];
+    // Fetch each xref type individually to avoid timeouts on large requests
+    for (const xrefType of xrefTypes) {
+        const path = `/compound/cid/${cid}/xrefs/${xrefType}/JSON`;
+        logger.debug(`Fetching xref type: ${xrefType}`, { ...context, cid, path });
+        try {
+            const response = await pubChemApiClient.get(path, context);
+            if (response?.InformationList?.Information) {
+                for (const info of response.InformationList.Information) {
+                    if (info[xrefType] && Array.isArray(info[xrefType])) {
+                        for (const id of info[xrefType]) {
+                            allXrefs.push({ type: xrefType, id });
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Log the error for the specific xref type but continue with others
+            logger.warning(`Failed to fetch xref type '${xrefType}' for CID ${cid}`, {
+                ...context,
+                cid,
+                error,
+            });
+        }
+    }
+    if (allXrefs.length === 0) {
+        throw new McpError(BaseErrorCode.NOT_FOUND, `No cross-references found for CID ${cid} with the specified types.`, { ...context, cid, xrefTypes });
+    }
+    // Group the flattened list by type
+    const groupedXrefs = allXrefs.reduce((acc, { type, id }) => {
+        if (!acc[type]) {
+            acc[type] = [];
+        }
+        acc[type].push(id);
+        return acc;
+    }, {});
+    // Convert the grouped map to an array of objects for pagination
+    const xrefGroups = Object.entries(groupedXrefs).map(([type, ids]) => ({
+        type,
+        ids,
+    }));
+    // Paginate the grouped list
+    const totalRecords = xrefGroups.length;
+    const totalPages = Math.ceil(totalRecords / pageSize);
+    const startIndex = (page - 1) * pageSize;
+    const paginatedXrefGroups = xrefGroups.slice(startIndex, startIndex + pageSize);
+    const result = {
+        cid,
+        xrefs: paginatedXrefGroups,
+        pagination: {
+            currentPage: page,
+            pageSize,
+            totalRecords,
+            totalPages,
+        },
+    };
+    logger.info(`Successfully fetched page ${page}/${totalPages} of xrefs for CID ${cid}.`, context);
+    return result;
+}

package/dist/mcp-server/tools/fetchCompoundXrefs/registration.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_compound_xrefs` tool.
+ * @module src/mcp-server/tools/fetchCompoundXrefs/registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'pubchem_fetch_compound_xrefs' tool with the MCP server.
+ * This tool fetches a paginated list of external cross-references (XRefs) for a given
+ * PubChem Compound ID (CID).
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export declare const registerPubchemFetchCompoundXrefsTool: (server: McpServer) => Promise<void>;

package/dist/mcp-server/tools/fetchCompoundXrefs/registration.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_compound_xrefs` tool.
+ * @module src/mcp-server/tools/fetchCompoundXrefs/registration
+ */
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { PubchemFetchCompoundXrefsInputSchema, pubchemFetchCompoundXrefsLogic, } from "./logic.js";
+/**
+ * Registers the 'pubchem_fetch_compound_xrefs' tool with the MCP server.
+ * This tool fetches a paginated list of external cross-references (XRefs) for a given
+ * PubChem Compound ID (CID).
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export const registerPubchemFetchCompoundXrefsTool = async (server) => {
+    const toolName = "pubchem_fetch_compound_xrefs";
+    const toolDescription = "Fetches external cross-references (XRefs) for a given PubChem Compound ID (CID), such as Registry IDs, Patent IDs, or PubMed IDs. Supports pagination for handling large result sets.";
+    server.tool(toolName, toolDescription, PubchemFetchCompoundXrefsInputSchema.shape, async (params, mcpContext) => {
+        const handlerContext = requestContextService.createRequestContext({
+            operation: "HandleToolRequest",
+            toolName,
+            mcpToolContext: mcpContext,
+            input: params,
+        });
+        try {
+            logger.info(`Initiating tool request for ${toolName} for CID: ${params.cid}`, handlerContext);
+            const result = await pubchemFetchCompoundXrefsLogic(params, handlerContext);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            const handledError = ErrorHandler.handleError(error, {
+                operation: "pubchemFetchCompoundXrefsToolHandler",
+                context: handlerContext,
+                input: params,
+            });
+            // No need to log here, handleError already does it.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: ErrorHandler.formatError(handledError),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/mcp-server/tools/fetchSubstanceDetails/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the `pubchem_fetch_substance_details` tool.
+ * This file serves as the public interface for the tool module,
+ * primarily exporting the `registerPubchemFetchSubstanceDetailsTool` function.
+ * @module src/mcp-server/tools/fetchSubstanceDetails/index
+ */
+export { registerPubchemFetchSubstanceDetailsTool } from "./registration.js";

package/dist/mcp-server/tools/fetchSubstanceDetails/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the `pubchem_fetch_substance_details` tool.
+ * This file serves as the public interface for the tool module,
+ * primarily exporting the `registerPubchemFetchSubstanceDetailsTool` function.
+ * @module src/mcp-server/tools/fetchSubstanceDetails/index
+ */
+export { registerPubchemFetchSubstanceDetailsTool } from "./registration.js";

package/dist/mcp-server/tools/fetchSubstanceDetails/logic.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_substance_details` tool.
+ * @module src/mcp-server/tools/fetchSubstanceDetails/logic
+ */
+import { z } from "zod";
+import { type RequestContext } from "../../../utils/index.js";
+export declare const PubchemFetchSubstanceDetailsInputSchema: z.ZodObject<{
+    sid: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sid: number;
+}, {
+    sid: number;
+}>;
+export type PubchemFetchSubstanceDetailsInput = z.infer<typeof PubchemFetchSubstanceDetailsInputSchema>;
+export declare const PubchemFetchSubstanceDetailsOutputSchema: z.ZodObject<{
+    sid: z.ZodNumber;
+    source: z.ZodObject<{
+        name: z.ZodString;
+        sourceId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        sourceId?: string | undefined;
+    }, {
+        name: string;
+        sourceId?: string | undefined;
+    }>;
+    depositionDate: z.ZodString;
+    modificationDate: z.ZodString;
+    synonyms: z.ZodArray<z.ZodString, "many">;
+    relatedCids: z.ZodArray<z.ZodNumber, "many">;
+    xrefs: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodString>, "many">>;
+    compounds: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+}, "strip", z.ZodTypeAny, {
+    sid: number;
+    source: {
+        name: string;
+        sourceId?: string | undefined;
+    };
+    depositionDate: string;
+    modificationDate: string;
+    synonyms: string[];
+    relatedCids: number[];
+    xrefs?: Record<string, string>[] | undefined;
+    compounds?: any[] | undefined;
+}, {
+    sid: number;
+    source: {
+        name: string;
+        sourceId?: string | undefined;
+    };
+    depositionDate: string;
+    modificationDate: string;
+    synonyms: string[];
+    relatedCids: number[];
+    xrefs?: Record<string, string>[] | undefined;
+    compounds?: any[] | undefined;
+}>;
+export type PubchemFetchSubstanceDetailsOutput = z.infer<typeof PubchemFetchSubstanceDetailsOutputSchema>;
+/**
+ * Core logic for the `pubchem_fetch_substance_details` tool. It retrieves detailed
+ * information for a given PubChem Substance ID (SID), including its source,
+ * synonyms, and any associated Compound IDs (CIDs).
+ *
+ * @param {PubchemFetchSubstanceDetailsInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchSubstanceDetailsOutput>} A promise that resolves with the substance details.
+ * @throws {McpError} Throws a structured error if the API requests fail, the SID is not found, or the response is malformed.
+ */
+export declare function pubchemFetchSubstanceDetailsLogic(params: PubchemFetchSubstanceDetailsInput, context: RequestContext): Promise<PubchemFetchSubstanceDetailsOutput>;

package/dist/mcp-server/tools/fetchSubstanceDetails/logic.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_substance_details` tool.
+ * @module src/mcp-server/tools/fetchSubstanceDetails/logic
+ */
+import { z } from "zod";
+import { pubChemApiClient } from "../../../services/pubchem/pubchemApiClient.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { logger } from "../../../utils/index.js";
+// 1. Define and export the Zod schema for input validation
+export const PubchemFetchSubstanceDetailsInputSchema = z.object({
+    sid: z
+        .number()
+        .int()
+        .positive()
+        .describe("The PubChem Substance ID (SID) to retrieve details for. Must be a positive integer."),
+});
+// 3. Define and export the Zod schema for the tool's output
+export const PubchemFetchSubstanceDetailsOutputSchema = z.object({
+    sid: z.number().int().describe("The unique PubChem Substance ID (SID)."),
+    source: z
+        .object({
+        name: z.string().describe("The name of the depositor or data source."),
+        sourceId: z
+            .string()
+            .optional()
+            .describe("The unique identifier for the substance within the source."),
+    })
+        .describe("The original source of the substance information."),
+    depositionDate: z
+        .string()
+        .describe("The date the substance was originally deposited, in YYYY/MM/DD format."),
+    modificationDate: z
+        .string()
+        .describe("The date the substance record was last modified, in YYYY/MM/DD format."),
+    synonyms: z
+        .array(z.string())
+        .describe("A list of alternative names or identifiers for the substance."),
+    relatedCids: z
+        .array(z.number().int())
+        .describe("A list of standardized PubChem Compound IDs (CIDs) that are structurally related to this substance."),
+    xrefs: z
+        .array(z.record(z.string()))
+        .optional()
+        .describe("A list of external cross-references, such as registry IDs or database URLs."),
+    compounds: z
+        .array(z.any())
+        .optional()
+        .describe("A list of associated compound structures, including atoms, bonds, and coordinates."),
+});
+/**
+ * Core logic for the `pubchem_fetch_substance_details` tool. It retrieves detailed
+ * information for a given PubChem Substance ID (SID), including its source,
+ * synonyms, and any associated Compound IDs (CIDs).
+ *
+ * @param {PubchemFetchSubstanceDetailsInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchSubstanceDetailsOutput>} A promise that resolves with the substance details.
+ * @throws {McpError} Throws a structured error if the API requests fail, the SID is not found, or the response is malformed.
+ */
+export async function pubchemFetchSubstanceDetailsLogic(params, context) {
+    logger.debug("Processing pubchem_fetch_substance_details logic...", {
+        ...context,
+        params,
+    });
+    const { sid } = params;
+    // A single API call to get all available substance details.
+    const detailsPath = `/substance/sid/${sid}/JSON`;
+    const detailsResponse = await pubChemApiClient.get(detailsPath, context);
+    logger.debug("Raw PubChem response for pubchem_fetch_substance_details", {
+        ...context,
+        sid,
+        detailsResponse,
+    });
+    if (!detailsResponse || !detailsResponse.PC_Substances?.[0]) {
+        throw new McpError(BaseErrorCode.NOT_FOUND, `No substance details found for SID ${sid}, or the response from PubChem was malformed.`, { ...context, sid, response: detailsResponse });
+    }
+    const substance = detailsResponse.PC_Substances[0];
+    // Extract related CIDs directly from the substance details if available.
+    const relatedCids = substance.compound
+        ?.map((c) => c.id?.id?.cid)
+        .filter((cid) => typeof cid === "number") || [];
+    const result = {
+        sid: substance.sid.id,
+        source: {
+            name: substance.source.db.name,
+            sourceId: substance.source.db.source_id?.str,
+        },
+        depositionDate: substance.dates?.deposition?.date.join("/") || "N/A",
+        modificationDate: substance.dates?.modification?.date.join("/") || "N/A",
+        synonyms: substance.synonyms || [],
+        relatedCids,
+        xrefs: substance.xref,
+        compounds: substance.compound,
+    };
+    logger.info(`Successfully fetched details for SID ${sid}.`, context);
+    return result;
+}

package/dist/mcp-server/tools/fetchSubstanceDetails/registration.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_substance_details` tool.
+ * @module src/mcp-server/tools/fetchSubstanceDetails/registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'pubchem_fetch_substance_details' tool with the MCP server.
+ * This tool retrieves detailed information for a given PubChem Substance ID (SID),
+ * including its source, synonyms, and any associated Compound IDs (CIDs).
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export declare const registerPubchemFetchSubstanceDetailsTool: (server: McpServer) => Promise<void>;

package/dist/mcp-server/tools/fetchSubstanceDetails/registration.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_substance_details` tool.
+ * @module src/mcp-server/tools/fetchSubstanceDetails/registration
+ */
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { PubchemFetchSubstanceDetailsInputSchema, pubchemFetchSubstanceDetailsLogic, } from "./logic.js";
+/**
+ * Registers the 'pubchem_fetch_substance_details' tool with the MCP server.
+ * This tool retrieves detailed information for a given PubChem Substance ID (SID),
+ * including its source, synonyms, and any associated Compound IDs (CIDs).
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export const registerPubchemFetchSubstanceDetailsTool = async (server) => {
+    const toolName = "pubchem_fetch_substance_details";
+    const toolDescription = "Retrieves details for a given PubChem Substance ID (SID), including its synonyms, source, deposition/modification dates, and any associated standardized Compound IDs (CIDs).";
+    server.tool(toolName, toolDescription, PubchemFetchSubstanceDetailsInputSchema.shape, async (params, mcpContext) => {
+        const handlerContext = requestContextService.createRequestContext({
+            operation: "HandleToolRequest",
+            toolName,
+            mcpToolContext: mcpContext,
+            input: params,
+        });
+        try {
+            logger.info(`Initiating tool request for ${toolName} for SID: ${params.sid}`, handlerContext);
+            const result = await pubchemFetchSubstanceDetailsLogic(params, handlerContext);
+            // Custom stringify to make large arrays of numbers more compact
+            const placeholderPrefix = "##JSON_STRINGIFY_PLACEHOLDER##";
+            let placeholderIndex = 0;
+            const placeholders = [];
+            const replacer = (key, value) => {
+                const compactArrayKeys = new Set([
+                    "aid",
+                    "element",
+                    "aid1",
+                    "aid2",
+                    "order",
+                    "x",
+                    "y",
+                ]);
+                if (compactArrayKeys.has(key) &&
+                    Array.isArray(value) &&
+                    value.every((item) => typeof item === "number")) {
+                    const placeholder = `${placeholderPrefix}${placeholderIndex++}`;
+                    placeholders.push(JSON.stringify(value));
+                    return placeholder;
+                }
+                return value;
+            };
+            let text = JSON.stringify(result, replacer, 2);
+            for (let i = 0; i < placeholders.length; i++) {
+                text = text.replace(`"${placeholderPrefix}${i}"`, placeholders[i]);
+            }
+            return {
+                content: [{ type: "text", text }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            const handledError = ErrorHandler.handleError(error, {
+                operation: "pubchemFetchSubstanceDetailsToolHandler",
+                context: handlerContext,
+                input: params,
+            });
+            // No need to log here, handleError already does it.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: ErrorHandler.formatError(handledError),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/mcp-server/tools/getCompoundImage/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the `pubchem_get_compound_image` tool.
+ * This file serves as the public interface for the tool module,
+ * primarily exporting the `registerPubchemGetCompoundImageTool` function.
+ * @module src/mcp-server/tools/getCompoundImage/index
+ */
+export { registerPubchemGetCompoundImageTool } from "./registration.js";

package/dist/mcp-server/tools/getCompoundImage/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the `pubchem_get_compound_image` tool.
+ * This file serves as the public interface for the tool module,
+ * primarily exporting the `registerPubchemGetCompoundImageTool` function.
+ * @module src/mcp-server/tools/getCompoundImage/index
+ */
+export { registerPubchemGetCompoundImageTool } from "./registration.js";