@cyanheads/pubchem-mcp-server 1.0.1

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

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_search_compounds_by_formula` tool.
+ * @module src/mcp-server/tools/searchCompoundsByFormula/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
+const MOLECULAR_FORMULA_REGEX = /^[A-Z][a-z]?\d*([A-Z][a-z]?\d*)*$/;
+export const PubchemSearchCompoundsByFormulaInputSchema = z.object({
+    formula: z
+        .string()
+        .regex(MOLECULAR_FORMULA_REGEX, "Invalid molecular formula format. It must follow standard chemical notation (e.g., 'C6H12O6').")
+        .describe("A valid molecular formula to search for."),
+    allowOtherElements: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, the search will include compounds that contain the specified formula's elements plus others. Defaults to false."),
+    maxRecords: z
+        .number()
+        .int()
+        .positive()
+        .max(100, "Cannot request more than 100 records.")
+        .optional()
+        .default(50)
+        .describe("The maximum number of matching CIDs to return. Defaults to 50, with a maximum of 100."),
+});
+// 3. Define and export the Zod schema for the tool's output
+export const PubchemSearchCompoundsByFormulaOutputSchema = z.object({
+    cids: z
+        .array(z.number().int())
+        .describe("A list of PubChem Compound IDs (CIDs) that match the specified molecular formula."),
+});
+/**
+ * Core logic for the `pubchem_search_compounds_by_formula` tool. It finds compounds
+ * that match a given molecular formula.
+ *
+ * @param {PubchemSearchCompoundsByFormulaInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {Promise<PubchemSearchCompoundsByFormulaOutput>} A promise that resolves with a list of matching CIDs.
+ * @throws {McpError} Throws a structured error if the API request fails or returns a fault.
+ */
+export async function pubchemSearchCompoundsByFormulaLogic(params, context) {
+    logger.debug("Processing pubchem_search_compounds_by_formula logic...", {
+        ...context,
+        params,
+    });
+    const { formula, allowOtherElements, maxRecords } = params;
+    const path = `/compound/fastformula/${encodeURIComponent(formula)}/cids/JSON?AllowOtherElements=${allowOtherElements}&MaxRecords=${maxRecords}`;
+    const response = await pubChemApiClient.get(path, context);
+    logger.debug("Raw PubChem response for pubchem_search_compounds_by_formula", {
+        ...context,
+        response,
+    });
+    if (response?.Fault) {
+        logger.error("PubChem API returned a fault for formula search.", {
+            ...context,
+            fault: response.Fault,
+        });
+        throw new McpError(BaseErrorCode.EXTERNAL_SERVICE_ERROR, `PubChem API Fault: ${response.Fault.Message}`, { ...context, details: response.Fault.Details });
+    }
+    if (!response ||
+        !response.IdentifierList?.CID ||
+        !Array.isArray(response.IdentifierList.CID)) {
+        logger.warning("No CIDs found for the formula search, or the response format was unexpected. Returning empty list.", { ...context, formula, response });
+        return { cids: [] };
+    }
+    const result = {
+        cids: response.IdentifierList.CID,
+    };
+    logger.info(`Found ${result.cids.length} CIDs for formula '${formula}'.`, context);
+    return result;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_search_compounds_by_formula` tool.
+ * @module src/mcp-server/tools/searchCompoundsByFormula/registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'pubchem_search_compounds_by_formula' tool with the MCP server.
+ * This tool finds compounds that match a given molecular formula.
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export declare const registerPubchemSearchCompoundsByFormulaTool: (server: McpServer) => Promise<void>;

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

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_search_compounds_by_formula` tool.
+ * @module src/mcp-server/tools/searchCompoundsByFormula/registration
+ */
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { PubchemSearchCompoundsByFormulaInputSchema, pubchemSearchCompoundsByFormulaLogic, } from "./logic.js";
+/**
+ * Registers the 'pubchem_search_compounds_by_formula' tool with the MCP server.
+ * This tool finds compounds that match a given molecular formula.
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export const registerPubchemSearchCompoundsByFormulaTool = async (server) => {
+    const toolName = "pubchem_search_compounds_by_formula";
+    const toolDescription = "Finds PubChem Compound IDs (CIDs) that match a given molecular formula (e.g., 'C6H12O6').";
+    server.tool(toolName, toolDescription, PubchemSearchCompoundsByFormulaInputSchema.shape, async (params, mcpContext) => {
+        const handlerContext = requestContextService.createRequestContext({
+            operation: "HandleToolRequest",
+            toolName,
+            mcpToolContext: mcpContext,
+            input: params,
+        });
+        try {
+            logger.info(`Initiating tool request for ${toolName} for formula: '${params.formula}'`, handlerContext);
+            const result = await pubchemSearchCompoundsByFormulaLogic(params, handlerContext);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            const handledError = ErrorHandler.handleError(error, {
+                operation: "pubchemSearchCompoundsByFormulaToolHandler",
+                context: handlerContext,
+                input: params,
+            });
+            const mcpError = handledError instanceof McpError
+                ? handledError
+                : new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while searching for compounds by formula.", { originalErrorName: handledError.name });
+            logger.error(`Error in ${toolName} handler`, {
+                ...handlerContext,
+                error: mcpError,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: {
+                                code: mcpError.code,
+                                message: mcpError.message,
+                                details: mcpError.details,
+                            },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+};

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

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

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_search_compounds_by_similarity` tool.
+ * @module src/mcp-server/tools/searchCompoundsBySimilarity/logic
+ */
+import { z } from "zod";
+import { type RequestContext } from "../../../utils/index.js";
+export declare const PubchemSearchCompoundsBySimilarityInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    queryType: z.ZodEnum<["smiles", "cid"]>;
+    threshold: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxRecords: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    queryType: "smiles" | "cid";
+    maxRecords: number;
+    threshold: number;
+}, {
+    query: string;
+    queryType: "smiles" | "cid";
+    maxRecords?: number | undefined;
+    threshold?: number | undefined;
+}>;
+export type PubchemSearchCompoundsBySimilarityInput = z.infer<typeof PubchemSearchCompoundsBySimilarityInputSchema>;
+export declare const PubchemSearchCompoundsBySimilarityOutputSchema: z.ZodObject<{
+    cids: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    cids: number[];
+}, {
+    cids: number[];
+}>;
+export type PubchemSearchCompoundsBySimilarityOutput = z.infer<typeof PubchemSearchCompoundsBySimilarityOutputSchema>;
+/**
+ * Core logic for the `pubchem_search_compounds_by_similarity` tool. It finds compounds
+ * with a 2D structure similar to a given query compound.
+ *
+ * @param {PubchemSearchCompoundsBySimilarityInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {Promise<PubchemSearchCompoundsBySimilarityOutput>} A promise that resolves with a list of similar CIDs.
+ * @throws {McpError} Throws a structured error if the input is invalid or the API request fails.
+ */
+export declare function pubchemSearchCompoundsBySimilarityLogic(params: PubchemSearchCompoundsBySimilarityInput, context: RequestContext): Promise<PubchemSearchCompoundsBySimilarityOutput>;

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

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_search_compounds_by_similarity` tool.
+ * @module src/mcp-server/tools/searchCompoundsBySimilarity/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 PubchemSearchCompoundsBySimilarityInputSchema = z.object({
+    query: z
+        .string()
+        .min(1, "Query cannot be empty.")
+        .describe("The query structure, provided as a SMILES string or a PubChem CID."),
+    queryType: z
+        .enum(["smiles", "cid"])
+        .describe("The format of the provided query structure ('smiles' or 'cid')."),
+    threshold: z
+        .number()
+        .min(70, "Similarity threshold must be at least 70.")
+        .max(100, "Similarity threshold cannot exceed 100.")
+        .optional()
+        .default(90)
+        .describe("The minimum Tanimoto similarity score required for a match, ranging from 70 to 100. Defaults to 90."),
+    maxRecords: z
+        .number()
+        .int()
+        .positive()
+        .max(100, "Cannot request more than 100 records.")
+        .optional()
+        .default(20)
+        .describe("The maximum number of similar CIDs to return. Defaults to 20, with a maximum of 100."),
+});
+// 3. Define and export the Zod schema for the tool's output
+export const PubchemSearchCompoundsBySimilarityOutputSchema = z.object({
+    cids: z
+        .array(z.number().int())
+        .describe("A list of PubChem Compound IDs (CIDs) with structures similar to the query."),
+});
+/**
+ * Core logic for the `pubchem_search_compounds_by_similarity` tool. It finds compounds
+ * with a 2D structure similar to a given query compound.
+ *
+ * @param {PubchemSearchCompoundsBySimilarityInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {Promise<PubchemSearchCompoundsBySimilarityOutput>} A promise that resolves with a list of similar CIDs.
+ * @throws {McpError} Throws a structured error if the input is invalid or the API request fails.
+ */
+export async function pubchemSearchCompoundsBySimilarityLogic(params, context) {
+    logger.debug("Processing pubchem_search_compounds_by_similarity logic...", {
+        ...context,
+        params,
+    });
+    const { query, queryType, threshold, maxRecords } = params;
+    if (queryType === "cid" && isNaN(parseInt(query, 10))) {
+        throw new McpError(BaseErrorCode.INVALID_INPUT, `Query type is 'cid' but the provided query '${query}' is not a valid number.`, { ...context, query });
+    }
+    const path = `/compound/fastsimilarity_2d/${queryType}/${encodeURIComponent(query)}/cids/JSON?Threshold=${threshold}&MaxRecords=${maxRecords}`;
+    const response = await pubChemApiClient.get(path, context);
+    logger.debug("Raw PubChem response for pubchem_search_compounds_by_similarity", {
+        ...context,
+        response,
+    });
+    if (response?.Fault) {
+        logger.error("PubChem API returned a fault for similarity search.", {
+            ...context,
+            fault: response.Fault,
+        });
+        throw new McpError(BaseErrorCode.EXTERNAL_SERVICE_ERROR, `PubChem API Fault: ${response.Fault.Message}`, { ...context, details: response.Fault.Details });
+    }
+    if (!response ||
+        !response.IdentifierList?.CID ||
+        !Array.isArray(response.IdentifierList.CID)) {
+        logger.warning("No similar CIDs found, or the response format was unexpected. Returning empty list.", { ...context, query, response });
+        return { cids: [] };
+    }
+    const result = {
+        cids: response.IdentifierList.CID,
+    };
+    logger.info(`Found ${result.cids.length} similar CIDs for query '${query}'.`, context);
+    return result;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_search_compounds_by_similarity` tool.
+ * @module src/mcp-server/tools/searchCompoundsBySimilarity/registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'pubchem_search_compounds_by_similarity' tool with the MCP server.
+ * This tool finds compounds with a 2D structure similar to a query compound.
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export declare const registerPubchemSearchCompoundsBySimilarityTool: (server: McpServer) => Promise<void>;

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

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_search_compounds_by_similarity` tool.
+ * @module src/mcp-server/tools/searchCompoundsBySimilarity/registration
+ */
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { PubchemSearchCompoundsBySimilarityInputSchema, pubchemSearchCompoundsBySimilarityLogic, } from "./logic.js";
+/**
+ * Registers the 'pubchem_search_compounds_by_similarity' tool with the MCP server.
+ * This tool finds compounds with a 2D structure similar to a query compound.
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export const registerPubchemSearchCompoundsBySimilarityTool = async (server) => {
+    const toolName = "pubchem_search_compounds_by_similarity";
+    const toolDescription = "Finds compounds with a similar 2D structure to a query compound (provided as SMILES or CID), based on a Tanimoto similarity score.";
+    server.tool(toolName, toolDescription, PubchemSearchCompoundsBySimilarityInputSchema.shape, async (params, mcpContext) => {
+        const handlerContext = requestContextService.createRequestContext({
+            operation: "HandleToolRequest",
+            toolName,
+            mcpToolContext: mcpContext,
+            input: params,
+        });
+        try {
+            logger.info(`Initiating tool request for ${toolName} for query: '${params.query}'`, handlerContext);
+            const result = await pubchemSearchCompoundsBySimilarityLogic(params, handlerContext);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            const handledError = ErrorHandler.handleError(error, {
+                operation: "pubchemSearchCompoundsBySimilarityToolHandler",
+                context: handlerContext,
+                input: params,
+            });
+            const mcpError = handledError instanceof McpError
+                ? handledError
+                : new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while searching for similar compounds.", { originalErrorName: handledError.name });
+            logger.error(`Error in ${toolName} handler`, {
+                ...handlerContext,
+                error: mcpError,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: {
+                                code: mcpError.code,
+                                message: mcpError.message,
+                                details: mcpError.details,
+                            },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+};

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

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

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_search_compounds_by_structure` tool.
+ * @module src/mcp-server/tools/searchCompoundsByStructure/logic
+ */
+import { z } from "zod";
+import { type RequestContext } from "../../../utils/index.js";
+export declare const PubchemSearchCompoundsByStructureInputSchema: z.ZodObject<{
+    searchType: z.ZodEnum<["substructure", "superstructure", "identity"]>;
+    query: z.ZodString;
+    queryType: z.ZodEnum<["smiles", "cid"]>;
+    maxRecords: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    searchType: "substructure" | "superstructure" | "identity";
+    query: string;
+    queryType: "smiles" | "cid";
+    maxRecords: number;
+}, {
+    searchType: "substructure" | "superstructure" | "identity";
+    query: string;
+    queryType: "smiles" | "cid";
+    maxRecords?: number | undefined;
+}>;
+export type PubchemSearchCompoundsByStructureInput = z.infer<typeof PubchemSearchCompoundsByStructureInputSchema>;
+export declare const PubchemSearchCompoundsByStructureOutputSchema: z.ZodObject<{
+    cids: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    cids: number[];
+}, {
+    cids: number[];
+}>;
+export type PubchemSearchCompoundsByStructureOutput = z.infer<typeof PubchemSearchCompoundsByStructureOutputSchema>;
+/**
+ * Core logic for the `pubchem_search_compounds_by_structure` tool. It performs a structural
+ * search (substructure, superstructure, or identity) based on a query structure.
+ *
+ * @param {PubchemSearchCompoundsByStructureInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {Promise<PubchemSearchCompoundsByStructureOutput>} A promise that resolves with a list of matching CIDs.
+ * @throws {McpError} Throws a structured error if the input is invalid or the API request fails.
+ */
+export declare function pubchemSearchCompoundsByStructureLogic(params: PubchemSearchCompoundsByStructureInput, context: RequestContext): Promise<PubchemSearchCompoundsByStructureOutput>;

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

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Defines the core logic, schemas, and types for the `pubchem_search_compounds_by_structure` tool.
+ * @module src/mcp-server/tools/searchCompoundsByStructure/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 PubchemSearchCompoundsByStructureInputSchema = z.object({
+    searchType: z
+        .enum(["substructure", "superstructure", "identity"])
+        .describe("The type of structural search to perform: 'substructure' (finds molecules containing the query), 'superstructure' (finds molecules contained within the query), or 'identity' (finds exact matches)."),
+    query: z
+        .string()
+        .min(1, "Query cannot be empty.")
+        .describe("The query structure, provided as a SMILES string (e.g., 'c1ccccc1') or a PubChem CID (e.g., '2244')."),
+    queryType: z
+        .enum(["smiles", "cid"])
+        .describe("The format of the provided query structure ('smiles' or 'cid')."),
+    maxRecords: z
+        .number()
+        .int()
+        .positive()
+        .max(100, "Cannot request more than 100 records.")
+        .optional()
+        .default(20)
+        .describe("The maximum number of matching CIDs to return. Defaults to 20, with a maximum of 100."),
+});
+// 3. Define and export the Zod schema for the tool's output
+export const PubchemSearchCompoundsByStructureOutputSchema = z.object({
+    cids: z
+        .array(z.number().int())
+        .describe("A list of PubChem Compound IDs (CIDs) that match the structural search criteria."),
+});
+/**
+ * Core logic for the `pubchem_search_compounds_by_structure` tool. It performs a structural
+ * search (substructure, superstructure, or identity) based on a query structure.
+ *
+ * @param {PubchemSearchCompoundsByStructureInput} params - The validated input parameters.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {Promise<PubchemSearchCompoundsByStructureOutput>} A promise that resolves with a list of matching CIDs.
+ * @throws {McpError} Throws a structured error if the input is invalid or the API request fails.
+ */
+export async function pubchemSearchCompoundsByStructureLogic(params, context) {
+    logger.debug("Processing pubchem_search_compounds_by_structure logic...", {
+        ...context,
+        params,
+    });
+    const { searchType, query, queryType, maxRecords } = params;
+    if (queryType === "cid" && isNaN(parseInt(query, 10))) {
+        throw new McpError(BaseErrorCode.INVALID_INPUT, `Query type is 'cid' but the provided query '${query}' is not a valid number.`, { ...context, query });
+    }
+    const path = `/compound/fast${searchType}/${queryType}/${encodeURIComponent(query)}/cids/JSON?MaxRecords=${maxRecords}`;
+    const response = await pubChemApiClient.get(path, context);
+    logger.debug("Raw PubChem response for pubchem_search_compounds_by_structure", {
+        ...context,
+        response,
+    });
+    if (response?.Fault) {
+        logger.error("PubChem API returned a fault for structure search.", {
+            ...context,
+            fault: response.Fault,
+        });
+        throw new McpError(BaseErrorCode.EXTERNAL_SERVICE_ERROR, `PubChem API Fault: ${response.Fault.Message}`, { ...context, details: response.Fault.Details });
+    }
+    if (!response ||
+        !response.IdentifierList?.CID ||
+        !Array.isArray(response.IdentifierList.CID)) {
+        logger.warning("No CIDs found for the structural search, or the response format was unexpected. Returning empty list.", { ...context, query, response });
+        return { cids: [] };
+    }
+    const result = {
+        cids: response.IdentifierList.CID,
+    };
+    logger.info(`Found ${result.cids.length} CIDs for ${searchType} search with query '${query}'.`, context);
+    return result;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_search_compounds_by_structure` tool.
+ * @module src/mcp-server/tools/searchCompoundsByStructure/registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'pubchem_search_compounds_by_structure' tool with the MCP server.
+ * This tool performs a structural search (substructure, superstructure, or identity)
+ * based on a query structure.
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export declare const registerPubchemSearchCompoundsByStructureTool: (server: McpServer) => Promise<void>;

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

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Handles the registration of the `pubchem_search_compounds_by_structure` tool.
+ * @module src/mcp-server/tools/searchCompoundsByStructure/registration
+ */
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { PubchemSearchCompoundsByStructureInputSchema, pubchemSearchCompoundsByStructureLogic, } from "./logic.js";
+/**
+ * Registers the 'pubchem_search_compounds_by_structure' tool with the MCP server.
+ * This tool performs a structural search (substructure, superstructure, or identity)
+ * based on a query structure.
+ *
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ */
+export const registerPubchemSearchCompoundsByStructureTool = async (server) => {
+    const toolName = "pubchem_search_compounds_by_structure";
+    const toolDescription = "Performs a structural search (substructure, superstructure, or identity) using a SMILES string or a PubChem CID as the query. Essential for finding structurally related compounds.";
+    server.tool(toolName, toolDescription, PubchemSearchCompoundsByStructureInputSchema.shape, async (params, mcpContext) => {
+        const handlerContext = requestContextService.createRequestContext({
+            operation: "HandleToolRequest",
+            toolName,
+            mcpToolContext: mcpContext,
+            input: params,
+        });
+        try {
+            logger.info(`Initiating tool request for ${toolName} for query: '${params.query}'`, handlerContext);
+            const result = await pubchemSearchCompoundsByStructureLogic(params, handlerContext);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            const handledError = ErrorHandler.handleError(error, {
+                operation: "pubchemSearchCompoundsByStructureToolHandler",
+                context: handlerContext,
+                input: params,
+            });
+            const mcpError = handledError instanceof McpError
+                ? handledError
+                : new McpError(BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while performing the structure search.", { originalErrorName: handledError.name });
+            logger.error(`Error in ${toolName} handler`, {
+                ...handlerContext,
+                error: mcpError,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: {
+                                code: mcpError.code,
+                                message: mcpError.message,
+                                details: mcpError.details,
+                            },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/mcp-server/transports/auth/core/authContext.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Defines the AsyncLocalStorage context for authentication information.
+ * This module provides a mechanism to store and retrieve authentication details
+ * (like scopes and client ID) across asynchronous operations, making it available
+ * from the middleware layer down to the tool and resource handlers without
+ * drilling props.
+ *
+ * @module src/mcp-server/transports/auth/core/authContext
+ */
+import { AsyncLocalStorage } from "async_hooks";
+import type { AuthInfo } from "./authTypes.js";
+/**
+ * Defines the structure of the store used within the AsyncLocalStorage.
+ * It holds the authentication information for the current request context.
+ */
+interface AuthStore {
+    authInfo: AuthInfo;
+}
+/**
+ * An instance of AsyncLocalStorage to hold the authentication context (`AuthStore`).
+ * This allows `authInfo` to be accessible throughout the async call chain of a request
+ * after being set in the authentication middleware.
+ *
+ * @example
+ * // In middleware:
+ * await authContext.run({ authInfo }, next);
+ *
+ * // In a deeper handler:
+ * const store = authContext.getStore();
+ * const scopes = store?.authInfo.scopes;
+ */
+export declare const authContext: AsyncLocalStorage<AuthStore>;
+export {};

package/dist/mcp-server/transports/auth/core/authContext.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Defines the AsyncLocalStorage context for authentication information.
+ * This module provides a mechanism to store and retrieve authentication details
+ * (like scopes and client ID) across asynchronous operations, making it available
+ * from the middleware layer down to the tool and resource handlers without
+ * drilling props.
+ *
+ * @module src/mcp-server/transports/auth/core/authContext
+ */
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * An instance of AsyncLocalStorage to hold the authentication context (`AuthStore`).
+ * This allows `authInfo` to be accessible throughout the async call chain of a request
+ * after being set in the authentication middleware.
+ *
+ * @example
+ * // In middleware:
+ * await authContext.run({ authInfo }, next);
+ *
+ * // In a deeper handler:
+ * const store = authContext.getStore();
+ * const scopes = store?.authInfo.scopes;
+ */
+export const authContext = new AsyncLocalStorage();