@cyanheads/pubchem-mcp-server 1.0.1

package/dist/mcp-server/transports/httpTransport.js

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview Configures and starts the Streamable HTTP MCP transport using Hono.
+ * This module integrates the `@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport`
+ * into a Hono web server. Its responsibilities include:
+ * - Creating a Hono server instance.
+ * - Applying and configuring middleware for CORS, rate limiting, and authentication (JWT/OAuth).
+ * - Defining the routes (`/mcp` endpoint for POST, GET, DELETE) to handle the MCP lifecycle.
+ * - Orchestrating session management by mapping session IDs to SDK transport instances.
+ * - Implementing port-binding logic with automatic retry on conflicts.
+ *
+ * The underlying implementation of the MCP Streamable HTTP specification, including
+ * Server-Sent Events (SSE) for streaming, is handled by the SDK's transport class.
+ *
+ * Specification Reference:
+ * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#streamable-http
+ * @module src/mcp-server/transports/httpTransport
+ */
+import { serve } from "@hono/node-server";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import http from "http";
+import { randomUUID } from "node:crypto";
+import { config } from "../../config/index.js";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, rateLimiter, requestContextService, } from "../../utils/index.js";
+import { jwtAuthMiddleware, oauthMiddleware, } from "./auth/index.js";
+import { httpErrorHandler } from "./httpErrorHandler.js";
+const HTTP_PORT = config.mcpHttpPort;
+const HTTP_HOST = config.mcpHttpHost;
+const MCP_ENDPOINT_PATH = "/mcp";
+const MAX_PORT_RETRIES = 15;
+// The transports map will store active sessions, keyed by session ID.
+// NOTE: This is an in-memory session store, which is a known limitation for scalability.
+// It will not work in a multi-process (clustered) or serverless environment.
+// For a scalable deployment, this would need to be replaced with a distributed
+// store like Redis or Memcached.
+const transports = {};
+async function isPortInUse(port, host, parentContext) {
+    const checkContext = requestContextService.createRequestContext({
+        ...parentContext,
+        operation: "isPortInUse",
+        port,
+        host,
+    });
+    return new Promise((resolve) => {
+        const tempServer = http.createServer();
+        tempServer
+            .once("error", (err) => {
+            resolve(err.code === "EADDRINUSE");
+        })
+            .once("listening", () => {
+            tempServer.close(() => resolve(false));
+        })
+            .listen(port, host);
+    });
+}
+function startHttpServerWithRetry(app, initialPort, host, maxRetries, parentContext) {
+    const startContext = requestContextService.createRequestContext({
+        ...parentContext,
+        operation: "startHttpServerWithRetry",
+    });
+    return new Promise(async (resolve, reject) => {
+        for (let i = 0; i <= maxRetries; i++) {
+            const currentPort = initialPort + i;
+            const attemptContext = {
+                ...startContext,
+                port: currentPort,
+                attempt: i + 1,
+            };
+            if (await isPortInUse(currentPort, host, attemptContext)) {
+                logger.warning(`Port ${currentPort} is in use, retrying...`, attemptContext);
+                continue;
+            }
+            try {
+                const serverInstance = serve({ fetch: app.fetch, port: currentPort, hostname: host }, (info) => {
+                    const serverAddress = `http://${info.address}:${info.port}${MCP_ENDPOINT_PATH}`;
+                    logger.info(`HTTP transport listening at ${serverAddress}`, {
+                        ...attemptContext,
+                        address: serverAddress,
+                    });
+                    if (process.stdout.isTTY) {
+                        console.log(`\n🚀 MCP Server running at: ${serverAddress}\n`);
+                    }
+                });
+                resolve(serverInstance);
+                return;
+            }
+            catch (err) {
+                if (err.code !== "EADDRINUSE") {
+                    reject(err);
+                    return;
+                }
+            }
+        }
+        reject(new Error("Failed to bind to any port after multiple retries."));
+    });
+}
+export async function startHttpTransport(createServerInstanceFn, parentContext) {
+    const app = new Hono();
+    const transportContext = requestContextService.createRequestContext({
+        ...parentContext,
+        component: "HttpTransportSetup",
+    });
+    app.use("*", cors({
+        origin: config.mcpAllowedOrigins || [],
+        allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
+        allowHeaders: [
+            "Content-Type",
+            "Mcp-Session-Id",
+            "Last-Event-ID",
+            "Authorization",
+        ],
+        credentials: true,
+    }));
+    app.use("*", async (c, next) => {
+        c.res.headers.set("X-Content-Type-Options", "nosniff");
+        await next();
+    });
+    app.use(MCP_ENDPOINT_PATH, async (c, next) => {
+        // NOTE (Security): The 'x-forwarded-for' header is used for rate limiting.
+        // This is only secure if the server is run behind a trusted proxy that
+        // correctly sets or validates this header.
+        const clientIp = c.req.header("x-forwarded-for")?.split(",")[0].trim() || "unknown_ip";
+        const context = requestContextService.createRequestContext({
+            operation: "httpRateLimitCheck",
+            ipAddress: clientIp,
+        });
+        // Let the centralized error handler catch rate limit errors
+        rateLimiter.check(clientIp, context);
+        await next();
+    });
+    if (config.mcpAuthMode === "oauth") {
+        app.use(MCP_ENDPOINT_PATH, oauthMiddleware);
+    }
+    else {
+        app.use(MCP_ENDPOINT_PATH, jwtAuthMiddleware);
+    }
+    // Centralized Error Handling
+    app.onError(httpErrorHandler);
+    app.post(MCP_ENDPOINT_PATH, async (c) => {
+        const postContext = requestContextService.createRequestContext({
+            ...transportContext,
+            operation: "handlePost",
+        });
+        const body = await c.req.json();
+        const sessionId = c.req.header("mcp-session-id");
+        let transport = sessionId
+            ? transports[sessionId]
+            : undefined;
+        if (isInitializeRequest(body)) {
+            // If a transport already exists for a session, it's a re-initialization.
+            if (transport) {
+                logger.warning("Re-initializing existing session.", {
+                    ...postContext,
+                    sessionId,
+                });
+                await transport.close(); // This will trigger the onclose handler.
+            }
+            // Create a new transport for a new session.
+            const newTransport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (newId) => {
+                    transports[newId] = newTransport;
+                    logger.info(`HTTP Session created: ${newId}`, {
+                        ...postContext,
+                        newSessionId: newId,
+                    });
+                },
+            });
+            // Set up cleanup logic for when the transport is closed.
+            newTransport.onclose = () => {
+                const closedSessionId = newTransport.sessionId;
+                if (closedSessionId && transports[closedSessionId]) {
+                    delete transports[closedSessionId];
+                    logger.info(`HTTP Session closed: ${closedSessionId}`, {
+                        ...postContext,
+                        closedSessionId,
+                    });
+                }
+            };
+            // Connect the new transport to a new server instance.
+            const server = await createServerInstanceFn();
+            await server.connect(newTransport);
+            transport = newTransport;
+        }
+        else if (!transport) {
+            // If it's not an initialization request and no transport was found, it's an error.
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Invalid or expired session ID.");
+        }
+        // Pass the request to the transport to handle.
+        return await transport.handleRequest(c.env.incoming, c.env.outgoing, body);
+    });
+    // A reusable handler for GET and DELETE requests which operate on existing sessions.
+    const handleSessionRequest = async (c) => {
+        const sessionId = c.req.header("mcp-session-id");
+        const transport = sessionId ? transports[sessionId] : undefined;
+        if (!transport) {
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.");
+        }
+        // Let the transport handle the streaming (GET) or termination (DELETE) request.
+        return await transport.handleRequest(c.env.incoming, c.env.outgoing);
+    };
+    app.get(MCP_ENDPOINT_PATH, handleSessionRequest);
+    app.delete(MCP_ENDPOINT_PATH, handleSessionRequest);
+    return startHttpServerWithRetry(app, HTTP_PORT, HTTP_HOST, MAX_PORT_RETRIES, transportContext);
+}

package/dist/mcp-server/transports/stdioTransport.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Handles the setup and connection for the Stdio MCP transport.
+ * Implements the MCP Specification 2025-03-26 for stdio transport.
+ * This transport communicates directly over standard input (stdin) and
+ * standard output (stdout), typically used when the MCP server is launched
+ * as a child process by a host application.
+ *
+ * Specification Reference:
+ * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#stdio
+ *
+ * --- Authentication Note ---
+ * As per the MCP Authorization Specification (2025-03-26, Section 1.2),
+ * STDIO transports SHOULD NOT implement HTTP-based authentication flows.
+ * Authorization is typically handled implicitly by the host application
+ * controlling the server process. This implementation follows that guideline.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ * @module src/mcp-server/transports/stdioTransport
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestContext } from "../../utils/index.js";
+/**
+ * Connects a given `McpServer` instance to the Stdio transport.
+ * This function initializes the SDK's `StdioServerTransport`, which manages
+ * communication over `process.stdin` and `process.stdout` according to the
+ * MCP stdio transport specification.
+ *
+ * MCP Spec Points Covered by SDK's `StdioServerTransport`:
+ * - Reads JSON-RPC messages (requests, notifications, responses, batches) from stdin.
+ * - Writes JSON-RPC messages to stdout.
+ * - Handles newline delimiters and ensures no embedded newlines in output messages.
+ * - Ensures only valid MCP messages are written to stdout.
+ *
+ * Logging via the `logger` utility MAY result in output to stderr, which is
+ * permitted by the spec for logging purposes.
+ *
+ * @param server - The `McpServer` instance.
+ * @param parentContext - The logging and tracing context from the calling function.
+ * @returns A promise that resolves when the Stdio transport is successfully connected.
+ * @throws {Error} If the connection fails during setup.
+ */
+export declare function connectStdioTransport(server: McpServer, parentContext: RequestContext): Promise<void>;

package/dist/mcp-server/transports/stdioTransport.js

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Handles the setup and connection for the Stdio MCP transport.
+ * Implements the MCP Specification 2025-03-26 for stdio transport.
+ * This transport communicates directly over standard input (stdin) and
+ * standard output (stdout), typically used when the MCP server is launched
+ * as a child process by a host application.
+ *
+ * Specification Reference:
+ * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#stdio
+ *
+ * --- Authentication Note ---
+ * As per the MCP Authorization Specification (2025-03-26, Section 1.2),
+ * STDIO transports SHOULD NOT implement HTTP-based authentication flows.
+ * Authorization is typically handled implicitly by the host application
+ * controlling the server process. This implementation follows that guideline.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ * @module src/mcp-server/transports/stdioTransport
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ErrorHandler, logger } from "../../utils/index.js";
+/**
+ * Connects a given `McpServer` instance to the Stdio transport.
+ * This function initializes the SDK's `StdioServerTransport`, which manages
+ * communication over `process.stdin` and `process.stdout` according to the
+ * MCP stdio transport specification.
+ *
+ * MCP Spec Points Covered by SDK's `StdioServerTransport`:
+ * - Reads JSON-RPC messages (requests, notifications, responses, batches) from stdin.
+ * - Writes JSON-RPC messages to stdout.
+ * - Handles newline delimiters and ensures no embedded newlines in output messages.
+ * - Ensures only valid MCP messages are written to stdout.
+ *
+ * Logging via the `logger` utility MAY result in output to stderr, which is
+ * permitted by the spec for logging purposes.
+ *
+ * @param server - The `McpServer` instance.
+ * @param parentContext - The logging and tracing context from the calling function.
+ * @returns A promise that resolves when the Stdio transport is successfully connected.
+ * @throws {Error} If the connection fails during setup.
+ */
+export async function connectStdioTransport(server, parentContext) {
+    const operationContext = {
+        ...parentContext,
+        operation: "connectStdioTransport",
+        transportType: "Stdio",
+    };
+    logger.debug("Attempting to connect stdio transport...", operationContext);
+    try {
+        logger.debug("Creating StdioServerTransport instance...", operationContext);
+        const transport = new StdioServerTransport();
+        logger.debug("Connecting McpServer instance to StdioServerTransport...", operationContext);
+        await server.connect(transport);
+        logger.info("MCP Server connected and listening via stdio transport.", operationContext);
+        if (process.stdout.isTTY) {
+            console.log(`\n🚀 MCP Server running in STDIO mode.\n   (MCP Spec: 2025-03-26 Stdio Transport)\n`);
+        }
+    }
+    catch (err) {
+        ErrorHandler.handleError(err, { ...operationContext, critical: true });
+        throw err; // Re-throw after handling to allow caller to react if necessary
+    }
+}

package/dist/services/pubchem/pubchemApiClient.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview A singleton service to interact with the PubChem PUG REST API.
+ * This client handles URL construction, rate limiting, request execution,
+ * and error handling for all PubChem API interactions.
+ * @module src/services/pubchem/pubchemApiClient
+ */
+import { type RequestContext } from "../../utils/index.js";
+/**
+ * A singleton class to manage all interactions with the PubChem PUG REST API.
+ */
+declare class PubChemApiClient {
+    private static instance;
+    private readonly limiter;
+    /**
+     * Private constructor to enforce the singleton pattern.
+     * Initializes a rate limiter compliant with PubChem's policy (5 requests/sec).
+     */
+    private constructor();
+    /**
+     * Retrieves the singleton instance of the PubChemApiClient.
+     * @returns The singleton instance.
+     */
+    static getInstance(): PubChemApiClient;
+    /**
+     * Executes a request to the PubChem API for a JSON response, respecting the rate limit.
+     * @param path - The API endpoint path (e.g., '/compound/cid/2244/property/MolecularFormula/JSON').
+     * @param context - The request context for tracing and logging.
+     * @returns A promise that resolves with the JSON response from the API.
+     * @throws {McpError} If the request fails, times out, or the API returns an error.
+     */
+    get<T>(path: string, context: RequestContext): Promise<T | null>;
+    /**
+     * Executes a request to the PubChem API for a binary blob response, respecting the rate limit.
+     * @param path - The API endpoint path (e.g., '/compound/cid/2244/PNG').
+     * @param context - The request context for tracing and logging.
+     * @returns A promise that resolves with an ArrayBuffer of the response body.
+     * @throws {McpError} If the request fails or times out.
+     */
+    getBlob(path: string, context: RequestContext): Promise<ArrayBuffer>;
+    /**
+     * Private helper to execute a generic fetch request, handling rate limiting and basic error checking.
+     * @param path - The API endpoint path.
+     * @param context - The request context.
+     * @returns A promise that resolves with the raw Response object.
+     */
+    private executeRequest;
+}
+/**
+ * Singleton instance of the PubChem API client.
+ */
+export declare const pubChemApiClient: PubChemApiClient;
+export {};

package/dist/services/pubchem/pubchemApiClient.js

@@ -0,0 +1,120 @@
+/**
+ * @fileoverview A singleton service to interact with the PubChem PUG REST API.
+ * This client handles URL construction, rate limiting, request execution,
+ * and error handling for all PubChem API interactions.
+ * @module src/services/pubchem/pubchemApiClient
+ */
+import { RateLimiter } from "limiter";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { fetchWithTimeout, logger, } from "../../utils/index.js";
+const PUBCHEM_API_BASE_URL = "https://pubchem.ncbi.nlm.nih.gov/rest/pug";
+const PUBCHEM_API_TIMEOUT_MS = 30000; // 30 seconds
+/**
+ * A singleton class to manage all interactions with the PubChem PUG REST API.
+ */
+class PubChemApiClient {
+    /**
+     * Private constructor to enforce the singleton pattern.
+     * Initializes a rate limiter compliant with PubChem's policy (5 requests/sec).
+     */
+    constructor() {
+        this.limiter = new RateLimiter({
+            tokensPerInterval: 5,
+            interval: "second",
+        });
+        logger.info("PubChemApiClient initialized with a rate limit of 5 requests/second.");
+    }
+    /**
+     * Retrieves the singleton instance of the PubChemApiClient.
+     * @returns The singleton instance.
+     */
+    static getInstance() {
+        if (!PubChemApiClient.instance) {
+            PubChemApiClient.instance = new PubChemApiClient();
+        }
+        return PubChemApiClient.instance;
+    }
+    /**
+     * Executes a request to the PubChem API for a JSON response, respecting the rate limit.
+     * @param path - The API endpoint path (e.g., '/compound/cid/2244/property/MolecularFormula/JSON').
+     * @param context - The request context for tracing and logging.
+     * @returns A promise that resolves with the JSON response from the API.
+     * @throws {McpError} If the request fails, times out, or the API returns an error.
+     */
+    async get(path, context) {
+        const response = await this.executeRequest(path, context);
+        // Handle cases where the response is OK but there's no content
+        if (response.status === 204) {
+            return null;
+        }
+        return response.json();
+    }
+    /**
+     * Executes a request to the PubChem API for a binary blob response, respecting the rate limit.
+     * @param path - The API endpoint path (e.g., '/compound/cid/2244/PNG').
+     * @param context - The request context for tracing and logging.
+     * @returns A promise that resolves with an ArrayBuffer of the response body.
+     * @throws {McpError} If the request fails or times out.
+     */
+    async getBlob(path, context) {
+        const response = await this.executeRequest(path, context);
+        return response.arrayBuffer();
+    }
+    /**
+     * Private helper to execute a generic fetch request, handling rate limiting and basic error checking.
+     * @param path - The API endpoint path.
+     * @param context - The request context.
+     * @returns A promise that resolves with the raw Response object.
+     */
+    async executeRequest(path, context) {
+        await this.limiter.removeTokens(1);
+        const url = path.startsWith("http")
+            ? path
+            : `${PUBCHEM_API_BASE_URL}${path}`;
+        logger.debug(`Executing PubChem API GET request`, { ...context, url });
+        const response = await fetchWithTimeout(url, PUBCHEM_API_TIMEOUT_MS, context);
+        if (!response.ok) {
+            const errorText = await response.text();
+            const pubChemStatus = response.headers.get("pubchem-pug-status-message") ||
+                "No status message";
+            logger.error("PubChem API request failed", {
+                ...context,
+                url,
+                status: response.status,
+                statusText: response.statusText,
+                pubChemStatus,
+                responseBody: errorText,
+            });
+            // Map HTTP status codes to McpError codes
+            let errorCode;
+            switch (response.status) {
+                case 400:
+                    errorCode = BaseErrorCode.INVALID_INPUT;
+                    break;
+                case 404:
+                    errorCode = BaseErrorCode.NOT_FOUND;
+                    break;
+                case 405:
+                    errorCode = BaseErrorCode.METHOD_NOT_ALLOWED;
+                    break;
+                case 503:
+                    errorCode = BaseErrorCode.SERVICE_UNAVAILABLE;
+                    break;
+                case 504:
+                    errorCode = BaseErrorCode.GATEWAY_TIMEOUT;
+                    break;
+                default:
+                    errorCode = BaseErrorCode.EXTERNAL_SERVICE_ERROR;
+            }
+            throw new McpError(errorCode, `PubChem API Error: ${pubChemStatus}`, {
+                httpStatusCode: response.status,
+                details: errorText,
+            });
+        }
+        return response;
+    }
+}
+/**
+ * Singleton instance of the PubChem API client.
+ */
+export const pubChemApiClient = PubChemApiClient.getInstance();

package/dist/types-global/errors.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Defines standardized error codes, a custom error class, and related schemas
+ * for handling errors within the Model Context Protocol (MCP) server and its components.
+ * This module provides a structured way to represent and communicate errors, ensuring
+ * consistency and clarity for both server-side operations and client-side error handling.
+ * @module src/types-global/errors
+ */
+import { z } from "zod";
+/**
+ * Defines a comprehensive set of standardized error codes for common issues encountered
+ * within MCP servers, tools, or related operations. These codes are designed to help
+ * clients and developers programmatically understand the nature of an error, facilitating
+ * more precise error handling and debugging.
+ */
+export declare enum BaseErrorCode {
+    /** Access denied due to invalid credentials or lack of authentication. */
+    UNAUTHORIZED = "UNAUTHORIZED",
+    /** Access denied despite valid authentication, due to insufficient permissions. */
+    FORBIDDEN = "FORBIDDEN",
+    /** The requested resource or entity could not be found. */
+    NOT_FOUND = "NOT_FOUND",
+    /** The request could not be completed due to a conflict with the current state of the resource. */
+    CONFLICT = "CONFLICT",
+    /** The request failed due to invalid input parameters or data. */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** The request was made with an invalid input. */
+    INVALID_INPUT = "INVALID_INPUT",
+    /** The request was made with a method that is not allowed for the resource. */
+    METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED",
+    /** An error occurred while parsing input data (e.g., date string, JSON). */
+    PARSING_ERROR = "PARSING_ERROR",
+    /** The request was rejected because the client has exceeded rate limits. */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** The request timed out before a response could be generated. */
+    TIMEOUT = "TIMEOUT",
+    /** The service is temporarily unavailable, possibly due to maintenance or overload. */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    /** The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server. */
+    GATEWAY_TIMEOUT = "GATEWAY_TIMEOUT",
+    /** A generic error occurred when interacting with an external service. */
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR",
+    /** An unexpected error occurred on the server side. */
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    /** An error occurred, but the specific cause is unknown or cannot be categorized. */
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    /** An error occurred during the loading or validation of configuration data. */
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR",
+    /** An error occurred during the initialization phase of a service or module. */
+    INITIALIZATION_FAILED = "INITIALIZATION_FAILED",
+    /** A service was used before it was properly initialized. */
+    SERVICE_NOT_INITIALIZED = "SERVICE_NOT_INITIALIZED",
+    /** A generic error occurred during a database operation. */
+    DATABASE_ERROR = "DATABASE_ERROR",
+    /** An error occurred while loading or interacting with an extension. */
+    EXTENSION_ERROR = "EXTENSION_ERROR",
+    /** An error occurred during the shutdown phase of a service or module. */
+    SHUTDOWN_ERROR = "SHUTDOWN_ERROR",
+    /** A generic error occurred during the execution of an agent's task. */
+    AGENT_EXECUTION_ERROR = "AGENT_EXECUTION_ERROR"
+}
+/**
+ * Custom error class for MCP-specific errors, extending the built-in `Error` class.
+ * It standardizes error reporting by encapsulating a `BaseErrorCode`, a descriptive
+ * human-readable message, and optional structured details for more context.
+ *
+ * This class is central to error handling within the MCP framework, allowing for
+ * consistent error creation and propagation.
+ */
+export declare class McpError extends Error {
+    /**
+     * The standardized error code from {@link BaseErrorCode}.
+     */
+    readonly code: BaseErrorCode;
+    /**
+     * Optional additional details or context about the error.
+     * This can be any structured data that helps in understanding or debugging the error.
+     */
+    readonly details?: Record<string, unknown>;
+    /**
+     * Creates an instance of McpError.
+     *
+     * @param code - The standardized error code that categorizes the error.
+     * @param message - A human-readable description of the error.
+     * @param details - Optional. A record containing additional structured details about the error.
+     */
+    constructor(code: BaseErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Zod schema for validating error objects. This schema can be used for:
+ * - Validating error structures when parsing error responses from external services.
+ * - Ensuring consistency when creating or handling error objects internally.
+ * - Generating TypeScript types for error objects.
+ *
+ * The schema enforces the presence of a `code` (from {@link BaseErrorCode}) and a `message`,
+ * and allows for optional `details`.
+ */
+export declare const ErrorSchema: z.ZodObject<{
+    /**
+     * The error code, corresponding to one of the {@link BaseErrorCode} enum values.
+     * This field is required and helps in programmatically identifying the error type.
+     */
+    code: z.ZodNativeEnum<typeof BaseErrorCode>;
+    /**
+     * A human-readable, descriptive message explaining the error.
+     * This field is required and provides context to developers or users.
+     */
+    message: z.ZodString;
+    /**
+     * Optional. A record containing additional structured details or context about the error.
+     * This can include things like invalid field names, specific values that caused issues, or other relevant data.
+     */
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    code: BaseErrorCode;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}, {
+    code: BaseErrorCode;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}>;
+/**
+ * TypeScript type inferred from the {@link ErrorSchema}.
+ * This type represents the structure of a validated error object, commonly used
+ * for error responses or when passing error information within the application.
+ */
+export type ErrorResponse = z.infer<typeof ErrorSchema>;