@cyanheads/pubchem-mcp-server 1.0.1

package/dist/mcp-server/server.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Main entry point for the MCP (Model Context Protocol) server.
+ * This file orchestrates the server's lifecycle:
+ * 1. Initializes the core `McpServer` instance (from `@modelcontextprotocol/sdk`) with its identity and capabilities.
+ * 2. Registers available resources and tools, making them discoverable and usable by clients.
+ * 3. Selects and starts the appropriate communication transport (stdio or Streamable HTTP)
+ *    based on configuration.
+ * 4. Handles top-level error management during startup.
+ *
+ * MCP Specification References:
+ * - Lifecycle: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/lifecycle.mdx
+ * - Overview (Capabilities): https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/index.mdx
+ * - Transports: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx
+ * @module src/mcp-server/server
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { config, environment } from "../config/index.js";
+import { ErrorHandler, logger, requestContextService } from "../utils/index.js";
+import { BaseErrorCode } from "../types-global/errors.js";
+import { registerPubchemSearchCompoundByIdentifierTool } from "./tools/searchCompoundByIdentifier/index.js";
+import { registerPubchemFetchCompoundPropertiesTool } from "./tools/fetchCompoundProperties/index.js";
+import { registerPubchemGetCompoundImageTool } from "./tools/getCompoundImage/index.js";
+import { registerPubchemSearchCompoundsByStructureTool } from "./tools/searchCompoundsByStructure/index.js";
+import { registerPubchemSearchCompoundsBySimilarityTool } from "./tools/searchCompoundsBySimilarity/index.js";
+import { registerPubchemSearchCompoundsByFormulaTool } from "./tools/searchCompoundsByFormula/index.js";
+import { registerPubchemFetchSubstanceDetailsTool } from "./tools/fetchSubstanceDetails/index.js";
+import { registerPubchemFetchAssaySummaryTool } from "./tools/fetchAssaySummary/index.js";
+import { registerPubchemSearchAssaysByTargetTool } from "./tools/searchAssaysByTarget/index.js";
+import { registerPubchemFetchCompoundXrefsTool } from "./tools/fetchCompoundXrefs/index.js";
+import { startHttpTransport } from "./transports/httpTransport.js";
+import { connectStdioTransport } from "./transports/stdioTransport.js";
+/**
+ * Creates and configures a new instance of the `McpServer`.
+ *
+ * @returns A promise resolving with the configured `McpServer` instance.
+ * @throws {McpError} If any resource or tool registration fails.
+ * @private
+ */
+async function createMcpServerInstance() {
+    const context = requestContextService.createRequestContext({
+        operation: "createMcpServerInstance",
+    });
+    logger.info("Initializing MCP server instance", context);
+    requestContextService.configure({
+        appName: config.mcpServerName,
+        appVersion: config.mcpServerVersion,
+        environment,
+    });
+    const server = new McpServer({ name: config.mcpServerName, version: config.mcpServerVersion }, {
+        capabilities: {
+            logging: {},
+            resources: { listChanged: true },
+            tools: { listChanged: true },
+        },
+    });
+    await ErrorHandler.tryCatch(async () => {
+        logger.debug("Registering resources and tools...", context);
+        await registerPubchemSearchCompoundByIdentifierTool(server);
+        await registerPubchemFetchCompoundPropertiesTool(server);
+        await registerPubchemGetCompoundImageTool(server);
+        await registerPubchemSearchCompoundsByStructureTool(server);
+        await registerPubchemSearchCompoundsBySimilarityTool(server);
+        await registerPubchemSearchCompoundsByFormulaTool(server);
+        await registerPubchemFetchSubstanceDetailsTool(server);
+        await registerPubchemFetchAssaySummaryTool(server);
+        await registerPubchemSearchAssaysByTargetTool(server);
+        await registerPubchemFetchCompoundXrefsTool(server);
+        logger.info("Resources and tools registered successfully", context);
+    }, {
+        operation: "registerAllCapabilities",
+        context,
+        errorCode: BaseErrorCode.INITIALIZATION_FAILED,
+        critical: true,
+    });
+    return server;
+}
+/**
+ * Selects, sets up, and starts the appropriate MCP transport layer based on configuration.
+ *
+ * @returns Resolves with `McpServer` for 'stdio', `http.Server` for 'http', or `void`.
+ * @throws {Error} If transport type is unsupported or setup fails.
+ * @private
+ */
+async function startTransport() {
+    const transportType = config.mcpTransportType;
+    const context = requestContextService.createRequestContext({
+        operation: "startTransport",
+        transport: transportType,
+    });
+    logger.info(`Starting transport: ${transportType}`, context);
+    if (transportType === "http") {
+        return startHttpTransport(createMcpServerInstance, context);
+    }
+    if (transportType === "stdio") {
+        const server = await createMcpServerInstance();
+        await connectStdioTransport(server, context);
+        return server;
+    }
+    throw new Error(`Unsupported transport type: ${transportType}. Must be 'stdio' or 'http'.`);
+}
+/**
+ * Main application entry point. Initializes and starts the MCP server.
+ */
+export async function initializeAndStartServer() {
+    const context = requestContextService.createRequestContext({
+        operation: "initializeAndStartServer",
+    });
+    logger.info("MCP Server initialization sequence started.", context);
+    try {
+        const result = await startTransport();
+        logger.info("MCP Server initialization sequence completed successfully.", context);
+        return result;
+    }
+    catch (err) {
+        ErrorHandler.handleError(err, {
+            operation: "initializeAndStartServer",
+            context: context,
+            critical: true,
+            rethrow: false,
+        });
+        logger.info("Exiting process due to critical initialization error.", context);
+        process.exit(1);
+    }
+}

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

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

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

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

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

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_assay_summary` tool.
+ * @module src/mcp-server/tools/fetchAssaySummary/logic
+ */
+import { z } from "zod";
+import { type RequestContext } from "../../../utils/index.js";
+export declare const PubchemFetchAssaySummaryInputSchema: z.ZodObject<{
+    aids: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    aids: number[];
+}, {
+    aids: number[];
+}>;
+export type PubchemFetchAssaySummaryInput = z.infer<typeof PubchemFetchAssaySummaryInputSchema>;
+export declare const AssaySummarySchema: z.ZodObject<{
+    aid: z.ZodNumber;
+    name: z.ZodString;
+    description: z.ZodString;
+    sourceName: z.ZodString;
+    numSids: z.ZodNumber;
+    numActive: z.ZodNumber;
+    targets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        geneId: z.ZodOptional<z.ZodNumber>;
+        geneSymbol: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        geneId?: number | undefined;
+        geneSymbol?: string | undefined;
+    }, {
+        name: string;
+        geneId?: number | undefined;
+        geneSymbol?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    aid: number;
+    sourceName: string;
+    numSids: number;
+    numActive: number;
+    targets: {
+        name: string;
+        geneId?: number | undefined;
+        geneSymbol?: string | undefined;
+    }[];
+}, {
+    name: string;
+    description: string;
+    aid: number;
+    sourceName: string;
+    numSids: number;
+    numActive: number;
+    targets: {
+        name: string;
+        geneId?: number | undefined;
+        geneSymbol?: string | undefined;
+    }[];
+}>;
+export type AssaySummary = z.infer<typeof AssaySummarySchema>;
+export type PubchemFetchAssaySummaryOutput = AssaySummary[];
+/**
+ * Core logic for the `pubchem_fetch_assay_summary` tool. It retrieves a summary
+ * for a specified list of PubChem BioAssay IDs (AIDs).
+ *
+ * @param {PubchemFetchAssaySummaryInput} params - The validated input parameters, containing the AIDs.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchAssaySummaryOutput>} A promise that resolves with an array of structured assay summaries.
+ * @throws {McpError} Throws a structured error if the API request fails, any AID is not found, or the response is malformed.
+ */
+export declare function pubchemFetchAssaySummaryLogic(params: PubchemFetchAssaySummaryInput, context: RequestContext): Promise<PubchemFetchAssaySummaryOutput>;

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

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_assay_summary` tool.
+ * @module src/mcp-server/tools/fetchAssaySummary/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 PubchemFetchAssaySummaryInputSchema = z.object({
+    aids: z
+        .array(z.number().int().positive())
+        .min(1, "At least one Assay ID (AID) must be provided.")
+        .max(5, "A maximum of 5 Assay IDs (AIDs) can be provided.")
+        .describe("An array of PubChem BioAssay IDs (AIDs). Must contain 1 to 5 positive integers."),
+});
+// 3. Define and export the Zod schema for a single assay summary object
+export const AssaySummarySchema = z.object({
+    aid: z.number().int().describe("The unique PubChem BioAssay ID (AID)."),
+    name: z.string().describe("The official name of the bioassay."),
+    description: z
+        .string()
+        .describe("A detailed description of the assay's purpose and methods."),
+    sourceName: z
+        .string()
+        .describe("The name of the institution or entity that provided the assay."),
+    numSids: z
+        .number()
+        .int()
+        .describe("The total number of substances (SIDs) tested in the assay."),
+    numActive: z
+        .number()
+        .int()
+        .describe("The number of substances found to be active in the assay."),
+    targets: z
+        .array(z.object({
+        name: z.string().describe("Name of the biological target."),
+        geneId: z
+            .number()
+            .int()
+            .optional()
+            .describe("NCBI Gene ID, if available."),
+        geneSymbol: z
+            .string()
+            .optional()
+            .describe("Official gene symbol, if available."),
+    }))
+        .describe("Biological targets of the assay. Note: This is often empty as the summary endpoint may not provide target details."),
+});
+/**
+ * Core logic for the `pubchem_fetch_assay_summary` tool. It retrieves a summary
+ * for a specified list of PubChem BioAssay IDs (AIDs).
+ *
+ * @param {PubchemFetchAssaySummaryInput} params - The validated input parameters, containing the AIDs.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchAssaySummaryOutput>} A promise that resolves with an array of structured assay summaries.
+ * @throws {McpError} Throws a structured error if the API request fails, any AID is not found, or the response is malformed.
+ */
+export async function pubchemFetchAssaySummaryLogic(params, context) {
+    logger.debug("Processing pubchem_fetch_assay_summary logic...", {
+        ...context,
+        params,
+    });
+    const { aids } = params;
+    const path = `/assay/aid/${aids.join(",")}/summary/JSON`;
+    const response = await pubChemApiClient.get(path, context);
+    logger.debug("Raw PubChem response for pubchem_fetch_assay_summary", {
+        ...context,
+        aids,
+        response,
+    });
+    const summaries = response?.AssaySummaries?.AssaySummary;
+    if (!summaries || summaries.length === 0) {
+        throw new McpError(BaseErrorCode.NOT_FOUND, `No assay summaries found for AIDs [${aids.join(", ")}], or the response from PubChem was malformed.`, { ...context, aids, response });
+    }
+    const results = summaries.map((summary) => {
+        // Safely extract description, handling both string and array formats.
+        let description = "No description provided.";
+        if (summary.Description) {
+            description = Array.isArray(summary.Description)
+                ? summary.Description.join("\n")
+                : summary.Description;
+        }
+        return {
+            aid: summary.AID ?? 0,
+            name: summary.Name ?? "N/A",
+            description,
+            sourceName: summary.SourceName ?? "N/A",
+            numSids: summary.SIDCountAll ?? 0,
+            numActive: summary.CIDCountActive ?? 0,
+            targets: [], // The summary endpoint does not provide target details. This is expected.
+        };
+    });
+    logger.info(`Successfully fetched ${results.length} summaries for AIDs [${aids.join(", ")}].`, context);
+    return results;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_assay_summary` tool with the MCP server.
+ * @module src/mcp-server/tools/fetchAssaySummary/registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'pubchem_fetch_assay_summary' tool with the provided MCP server instance.
+ * This tool retrieves a detailed summary for a given PubChem BioAssay ID (AID).
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export declare const registerPubchemFetchAssaySummaryTool: (server: McpServer) => Promise<void>;

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

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_assay_summary` tool with the MCP server.
+ * @module src/mcp-server/tools/fetchAssaySummary/registration
+ */
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { PubchemFetchAssaySummaryInputSchema, pubchemFetchAssaySummaryLogic, } from "./logic.js";
+/**
+ * Registers the 'pubchem_fetch_assay_summary' tool with the provided MCP server instance.
+ * This tool retrieves a detailed summary for a given PubChem BioAssay ID (AID).
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export const registerPubchemFetchAssaySummaryTool = async (server) => {
+    const toolName = "pubchem_fetch_assay_summary";
+    const toolDescription = "Fetches detailed summaries for a list of up to 5 PubChem BioAssay IDs (AIDs), including their names, descriptions, sources, and statistics. This is useful for obtaining metadata about multiple biological assays in a single request.";
+    server.tool(toolName, toolDescription, PubchemFetchAssaySummaryInputSchema.shape, async (params, mcpContext) => {
+        const handlerContext = requestContextService.createRequestContext({
+            operation: "HandleToolRequest",
+            toolName,
+            mcpToolContext: mcpContext,
+            input: params,
+        });
+        try {
+            logger.info(`Initiating tool request for ${toolName} with AIDs: ${params.aids.join(", ")}`, handlerContext);
+            const result = await pubchemFetchAssaySummaryLogic(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) => {
+                if (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: "pubchemFetchAssaySummaryToolHandler",
+                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/fetchCompoundProperties/index.d.ts

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

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

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

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

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_compound_properties` tool.
+ * @module src/mcp-server/tools/fetchCompoundProperties/logic
+ */
+import { z } from "zod";
+import { type RequestContext } from "../../../utils/index.js";
+export declare const PubchemCompoundPropertiesEnum: z.ZodEnum<["MolecularFormula", "MolecularWeight", "InChI", "InChIKey", "IUPACName", "Title", "XLogP", "ExactMass", "MonoisotopicMass", "TPSA", "Complexity", "Charge", "HBondDonorCount", "HBondAcceptorCount", "RotatableBondCount", "HeavyAtomCount", "CovalentUnitCount"]>;
+export declare const PubchemFetchCompoundPropertiesInputSchema: z.ZodObject<{
+    cids: z.ZodArray<z.ZodNumber, "many">;
+    properties: z.ZodArray<z.ZodEnum<["MolecularFormula", "MolecularWeight", "InChI", "InChIKey", "IUPACName", "Title", "XLogP", "ExactMass", "MonoisotopicMass", "TPSA", "Complexity", "Charge", "HBondDonorCount", "HBondAcceptorCount", "RotatableBondCount", "HeavyAtomCount", "CovalentUnitCount"]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    cids: number[];
+    properties: ("MolecularFormula" | "MolecularWeight" | "InChI" | "InChIKey" | "IUPACName" | "Title" | "XLogP" | "ExactMass" | "MonoisotopicMass" | "TPSA" | "Complexity" | "Charge" | "HBondDonorCount" | "HBondAcceptorCount" | "RotatableBondCount" | "HeavyAtomCount" | "CovalentUnitCount")[];
+}, {
+    cids: number[];
+    properties: ("MolecularFormula" | "MolecularWeight" | "InChI" | "InChIKey" | "IUPACName" | "Title" | "XLogP" | "ExactMass" | "MonoisotopicMass" | "TPSA" | "Complexity" | "Charge" | "HBondDonorCount" | "HBondAcceptorCount" | "RotatableBondCount" | "HeavyAtomCount" | "CovalentUnitCount")[];
+}>;
+export type PubchemFetchCompoundPropertiesInput = z.infer<typeof PubchemFetchCompoundPropertiesInputSchema>;
+export declare const PubchemFetchCompoundPropertiesOutputSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        CID: z.ZodNumber;
+        MolecularFormula: z.ZodOptional<z.ZodString>;
+        MolecularWeight: z.ZodOptional<z.ZodNumber>;
+        InChI: z.ZodOptional<z.ZodString>;
+        InChIKey: z.ZodOptional<z.ZodString>;
+        IUPACName: z.ZodOptional<z.ZodString>;
+        Title: z.ZodOptional<z.ZodString>;
+        XLogP: z.ZodOptional<z.ZodNumber>;
+        ExactMass: z.ZodOptional<z.ZodNumber>;
+        MonoisotopicMass: z.ZodOptional<z.ZodNumber>;
+        TPSA: z.ZodOptional<z.ZodNumber>;
+        Complexity: z.ZodOptional<z.ZodNumber>;
+        Charge: z.ZodOptional<z.ZodNumber>;
+        HBondDonorCount: z.ZodOptional<z.ZodNumber>;
+        HBondAcceptorCount: z.ZodOptional<z.ZodNumber>;
+        RotatableBondCount: z.ZodOptional<z.ZodNumber>;
+        HeavyAtomCount: z.ZodOptional<z.ZodNumber>;
+        CovalentUnitCount: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        CID: number;
+        MolecularFormula?: string | undefined;
+        MolecularWeight?: number | undefined;
+        InChI?: string | undefined;
+        InChIKey?: string | undefined;
+        IUPACName?: string | undefined;
+        Title?: string | undefined;
+        XLogP?: number | undefined;
+        ExactMass?: number | undefined;
+        MonoisotopicMass?: number | undefined;
+        TPSA?: number | undefined;
+        Complexity?: number | undefined;
+        Charge?: number | undefined;
+        HBondDonorCount?: number | undefined;
+        HBondAcceptorCount?: number | undefined;
+        RotatableBondCount?: number | undefined;
+        HeavyAtomCount?: number | undefined;
+        CovalentUnitCount?: number | undefined;
+    }, {
+        CID: number;
+        MolecularFormula?: string | undefined;
+        MolecularWeight?: number | undefined;
+        InChI?: string | undefined;
+        InChIKey?: string | undefined;
+        IUPACName?: string | undefined;
+        Title?: string | undefined;
+        XLogP?: number | undefined;
+        ExactMass?: number | undefined;
+        MonoisotopicMass?: number | undefined;
+        TPSA?: number | undefined;
+        Complexity?: number | undefined;
+        Charge?: number | undefined;
+        HBondDonorCount?: number | undefined;
+        HBondAcceptorCount?: number | undefined;
+        RotatableBondCount?: number | undefined;
+        HeavyAtomCount?: number | undefined;
+        CovalentUnitCount?: number | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    results: {
+        CID: number;
+        MolecularFormula?: string | undefined;
+        MolecularWeight?: number | undefined;
+        InChI?: string | undefined;
+        InChIKey?: string | undefined;
+        IUPACName?: string | undefined;
+        Title?: string | undefined;
+        XLogP?: number | undefined;
+        ExactMass?: number | undefined;
+        MonoisotopicMass?: number | undefined;
+        TPSA?: number | undefined;
+        Complexity?: number | undefined;
+        Charge?: number | undefined;
+        HBondDonorCount?: number | undefined;
+        HBondAcceptorCount?: number | undefined;
+        RotatableBondCount?: number | undefined;
+        HeavyAtomCount?: number | undefined;
+        CovalentUnitCount?: number | undefined;
+    }[];
+}, {
+    results: {
+        CID: number;
+        MolecularFormula?: string | undefined;
+        MolecularWeight?: number | undefined;
+        InChI?: string | undefined;
+        InChIKey?: string | undefined;
+        IUPACName?: string | undefined;
+        Title?: string | undefined;
+        XLogP?: number | undefined;
+        ExactMass?: number | undefined;
+        MonoisotopicMass?: number | undefined;
+        TPSA?: number | undefined;
+        Complexity?: number | undefined;
+        Charge?: number | undefined;
+        HBondDonorCount?: number | undefined;
+        HBondAcceptorCount?: number | undefined;
+        RotatableBondCount?: number | undefined;
+        HeavyAtomCount?: number | undefined;
+        CovalentUnitCount?: number | undefined;
+    }[];
+}>;
+export type PubchemFetchCompoundPropertiesOutput = z.infer<typeof PubchemFetchCompoundPropertiesOutputSchema>;
+/**
+ * Core logic for the `pubchem_fetch_compound_properties` tool. It retrieves a list of
+ * specified physicochemical properties for one or more PubChem Compound IDs (CIDs).
+ *
+ * @param {PubchemFetchCompoundPropertiesInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchCompoundPropertiesOutput>} A promise that resolves with the fetched properties.
+ * @throws {McpError} Throws a structured error if the API request fails, CIDs are not found, or the response is malformed.
+ */
+export declare function pubchemFetchCompoundPropertiesLogic(params: PubchemFetchCompoundPropertiesInput, context: RequestContext): Promise<PubchemFetchCompoundPropertiesOutput>;

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

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_fetch_compound_properties` tool.
+ * @module src/mcp-server/tools/fetchCompoundProperties/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 compound properties
+export const PubchemCompoundPropertiesEnum = z.enum([
+    "MolecularFormula",
+    "MolecularWeight",
+    "InChI",
+    "InChIKey",
+    "IUPACName",
+    "Title",
+    "XLogP",
+    "ExactMass",
+    "MonoisotopicMass",
+    "TPSA",
+    "Complexity",
+    "Charge",
+    "HBondDonorCount",
+    "HBondAcceptorCount",
+    "RotatableBondCount",
+    "HeavyAtomCount",
+    "CovalentUnitCount",
+]);
+// 2. Define and export the Zod schema for input validation
+export const PubchemFetchCompoundPropertiesInputSchema = z.object({
+    cids: z
+        .array(z.number().int().positive())
+        .min(1, "At least one CID is required.")
+        .describe("An array of one or more PubChem Compound IDs (CIDs) to fetch properties for. Must be positive integers."),
+    properties: z
+        .array(PubchemCompoundPropertiesEnum)
+        .min(1, "At least one property must be specified.")
+        .describe("A list of physicochemical properties to retrieve for each CID."),
+});
+// 4. Define and export the Zod schema for a single compound's properties in the output
+const CompoundPropertiesSchema = z
+    .object({
+    CID: z.number().int().describe("The PubChem Compound ID."),
+    MolecularFormula: z.string().optional(),
+    MolecularWeight: z.number().optional(),
+    InChI: z.string().optional(),
+    InChIKey: z.string().optional(),
+    IUPACName: z.string().optional(),
+    Title: z.string().optional(),
+    XLogP: z.number().optional(),
+    ExactMass: z.number().optional(),
+    MonoisotopicMass: z.number().optional(),
+    TPSA: z.number().optional(),
+    Complexity: z.number().optional(),
+    Charge: z.number().optional(),
+    HBondDonorCount: z.number().int().optional(),
+    HBondAcceptorCount: z.number().int().optional(),
+    RotatableBondCount: z.number().int().optional(),
+    HeavyAtomCount: z.number().int().optional(),
+    CovalentUnitCount: z.number().int().optional(),
+})
+    .describe("An object containing the requested properties for a single compound.");
+// 5. Define and export the Zod schema for the tool's complete output
+export const PubchemFetchCompoundPropertiesOutputSchema = z.object({
+    results: z
+        .array(CompoundPropertiesSchema)
+        .describe("A list of property results, with one object for each successfully retrieved CID."),
+});
+/**
+ * Core logic for the `pubchem_fetch_compound_properties` tool. It retrieves a list of
+ * specified physicochemical properties for one or more PubChem Compound IDs (CIDs).
+ *
+ * @param {PubchemFetchCompoundPropertiesInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging, tracing, and error handling.
+ * @returns {Promise<PubchemFetchCompoundPropertiesOutput>} A promise that resolves with the fetched properties.
+ * @throws {McpError} Throws a structured error if the API request fails, CIDs are not found, or the response is malformed.
+ */
+export async function pubchemFetchCompoundPropertiesLogic(params, context) {
+    logger.debug("Processing pubchem_fetch_compound_properties logic...", {
+        ...context,
+        params,
+    });
+    const { cids, properties } = params;
+    const cidsString = cids.join(",");
+    const propertiesString = properties.join(",");
+    const path = `/compound/cid/${cidsString}/property/${propertiesString}/JSON`;
+    const response = await pubChemApiClient.get(path, context);
+    logger.debug("Raw PubChem response for pubchem_fetch_compound_properties", {
+        ...context,
+        response,
+    });
+    if (!response || !response.PropertyTable?.Properties) {
+        throw new McpError(BaseErrorCode.NOT_FOUND, "Received an unexpected response format from PubChem API. Ensure CIDs are valid.", { ...context, cids, response });
+    }
+    const result = {
+        results: response.PropertyTable.Properties,
+    };
+    logger.info(`Successfully fetched properties for ${result.results.length} CIDs.`, context);
+    return result;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_fetch_compound_properties` tool.
+ * @module src/mcp-server/tools/fetchCompoundProperties/registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.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 declare const registerPubchemFetchCompoundPropertiesTool: (server: McpServer) => Promise<void>;