mcp-server-framework 1.0.0

package/build/errors/categories/system.d.ts

@@ -0,0 +1,95 @@
+/**
+ * System Error Classes
+ *
+ * Errors related to internal system failures:
+ * - InternalError: Unexpected internal errors
+ * - RegistryError: Tool/resource registry errors
+ *
+ * @module errors/categories/system
+ */
+import { AppError } from "../core/index.js";
+import type { BaseErrorOptions } from "../core/index.js";
+/**
+ * Error for unexpected internal failures.
+ *
+ * Use this for errors that shouldn't happen in normal operation
+ * and indicate bugs or system failures.
+ *
+ * @example
+ * ```typescript
+ * throw new InternalError('Unexpected state in request handler');
+ *
+ * // Wrap unexpected errors
+ * catch (err) {
+ *   throw InternalError.wrap(err, 'Failed to process request');
+ * }
+ * ```
+ */
+export declare class InternalError extends AppError {
+    constructor(message: string, options?: Omit<BaseErrorOptions, "code">);
+    /**
+     * Wrap an unknown error in an InternalError.
+     */
+    static wrap(error: unknown, context?: string): InternalError;
+    /**
+     * Create an InternalError for an unexpected state.
+     */
+    static unexpectedState(description: string): InternalError;
+    /**
+     * Create an InternalError for missing implementation.
+     */
+    static notImplemented(feature: string): InternalError;
+}
+/**
+ * Error for tool/resource registry operations.
+ *
+ * Used when registering, unregistering, or looking up
+ * tools and resources fails.
+ *
+ * @example
+ * ```typescript
+ * throw RegistryError.toolNotFound('unknown_tool');
+ * throw RegistryError.duplicateTool('existing_tool');
+ * ```
+ */
+export declare class RegistryError extends AppError {
+    /** The type of registry item (tool, resource, prompt) */
+    readonly itemType: "tool" | "resource" | "prompt";
+    /** The name of the item */
+    readonly itemName: string;
+    constructor(message: string, itemType: "tool" | "resource" | "prompt", itemName: string, options?: Omit<BaseErrorOptions, "code">);
+    /**
+     * Create a RegistryError for a tool not found.
+     */
+    static toolNotFound(name: string): RegistryError;
+    /**
+     * Create a RegistryError for duplicate tool registration.
+     */
+    static duplicateTool(name: string): RegistryError;
+    /**
+     * Create a RegistryError for a resource not found.
+     */
+    static resourceNotFound(name: string): RegistryError;
+    /**
+     * Create a RegistryError for duplicate resource registration.
+     */
+    static duplicateResource(name: string): RegistryError;
+    /**
+     * Create a RegistryError for a prompt not found.
+     */
+    static promptNotFound(name: string): RegistryError;
+    /**
+     * Create a RegistryError for duplicate prompt registration.
+     */
+    static duplicatePrompt(name: string): RegistryError;
+    /** @internal Mapping for valid registry item types — eliminates type assertion */
+    private static readonly TYPE_MAP;
+    /**
+     * Create a RegistryError for a generic duplicate registration.
+     *
+     * @param itemType - The type of item (e.g., 'Tool', 'Resource', 'Prompt')
+     * @param itemName - The name of the item
+     */
+    static duplicate(itemType: string, itemName: string): RegistryError;
+}
+//# sourceMappingURL=system.d.ts.map

package/build/errors/categories/system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/system.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAc,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;IAezE;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa;IAY5D;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa;IAM1D;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa;CAKtD;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,SAAQ,QAAQ;IACzC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;IAElD,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGxB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,EACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;IAuB9C;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAMhD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAUjD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAMpD;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAUrD;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAMlD;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAUnD,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAI9B;IAEF;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa;CAMpE"}

package/build/errors/categories/system.js

@@ -0,0 +1,190 @@
+/**
+ * System Error Classes
+ *
+ * Errors related to internal system failures:
+ * - InternalError: Unexpected internal errors
+ * - RegistryError: Tool/resource registry errors
+ *
+ * @module errors/categories/system
+ */
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { AppError, ErrorCodes } from "../core/index.js";
+// ============================================================================
+// Internal Error
+// ============================================================================
+/**
+ * Error for unexpected internal failures.
+ *
+ * Use this for errors that shouldn't happen in normal operation
+ * and indicate bugs or system failures.
+ *
+ * @example
+ * ```typescript
+ * throw new InternalError('Unexpected state in request handler');
+ *
+ * // Wrap unexpected errors
+ * catch (err) {
+ *   throw InternalError.wrap(err, 'Failed to process request');
+ * }
+ * ```
+ */
+export class InternalError extends AppError {
+    constructor(message, options = {}) {
+        super(message, {
+            code: ErrorCodes.INTERNAL_ERROR,
+            statusCode: 500,
+            mcpCode: ErrorCode.InternalError,
+            cause: options.cause,
+            recoveryHint: options.recoveryHint || "This is an internal error. Please try again or contact support.",
+            context: options.context,
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Wrap an unknown error in an InternalError.
+     */
+    static wrap(error, context) {
+        const message = context
+            ? `${context}: ${error instanceof Error ? error.message : String(error)}`
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        return new InternalError(message, {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    /**
+     * Create an InternalError for an unexpected state.
+     */
+    static unexpectedState(description) {
+        return new InternalError(`Unexpected state: ${description}`, {
+            recoveryHint: "This indicates a bug. Please report this issue.",
+        });
+    }
+    /**
+     * Create an InternalError for missing implementation.
+     */
+    static notImplemented(feature) {
+        return new InternalError(`Feature '${feature}' is not implemented`, {
+            recoveryHint: `The feature '${feature}' is not yet implemented.`,
+        });
+    }
+}
+// ============================================================================
+// Registry Error
+// ============================================================================
+/**
+ * Error for tool/resource registry operations.
+ *
+ * Used when registering, unregistering, or looking up
+ * tools and resources fails.
+ *
+ * @example
+ * ```typescript
+ * throw RegistryError.toolNotFound('unknown_tool');
+ * throw RegistryError.duplicateTool('existing_tool');
+ * ```
+ */
+export class RegistryError extends AppError {
+    /** The type of registry item (tool, resource, prompt) */
+    itemType;
+    /** The name of the item */
+    itemName;
+    constructor(message, itemType, itemName, options = {}) {
+        super(message, {
+            code: ErrorCodes.REGISTRY_ERROR,
+            statusCode: 404, // Usually not found
+            mcpCode: ErrorCode.MethodNotFound,
+            cause: options.cause,
+            recoveryHint: options.recoveryHint,
+            context: {
+                ...options.context,
+                itemType,
+                itemName,
+            },
+        });
+        this.itemType = itemType;
+        this.itemName = itemName;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Tool Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a RegistryError for a tool not found.
+     */
+    static toolNotFound(name) {
+        return new RegistryError(`Tool '${name}' not found`, "tool", name, {
+            recoveryHint: `Check the tool name '${name}' is correct. Use tools/list to see available tools.`,
+        });
+    }
+    /**
+     * Create a RegistryError for duplicate tool registration.
+     */
+    static duplicateTool(name) {
+        return new RegistryError(`Tool '${name}' is already registered`, "tool", name, {
+            recoveryHint: `Tool '${name}' is already registered. Use a different name.`,
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Resource Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a RegistryError for a resource not found.
+     */
+    static resourceNotFound(name) {
+        return new RegistryError(`Resource '${name}' not found`, "resource", name, {
+            recoveryHint: `Check the resource URI '${name}' is correct. Use resources/list to see available resources.`,
+        });
+    }
+    /**
+     * Create a RegistryError for duplicate resource registration.
+     */
+    static duplicateResource(name) {
+        return new RegistryError(`Resource '${name}' is already registered`, "resource", name, {
+            recoveryHint: `Resource '${name}' is already registered. Use a different URI.`,
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Prompt Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a RegistryError for a prompt not found.
+     */
+    static promptNotFound(name) {
+        return new RegistryError(`Prompt '${name}' not found`, "prompt", name, {
+            recoveryHint: `Check the prompt name '${name}' is correct. Use prompts/list to see available prompts.`,
+        });
+    }
+    /**
+     * Create a RegistryError for duplicate prompt registration.
+     */
+    static duplicatePrompt(name) {
+        return new RegistryError(`Prompt '${name}' is already registered`, "prompt", name, {
+            recoveryHint: `Prompt '${name}' is already registered. Use a different name.`,
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Generic Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /** @internal Mapping for valid registry item types — eliminates type assertion */
+    static TYPE_MAP = {
+        tool: "tool",
+        resource: "resource",
+        prompt: "prompt",
+    };
+    /**
+     * Create a RegistryError for a generic duplicate registration.
+     *
+     * @param itemType - The type of item (e.g., 'Tool', 'Resource', 'Prompt')
+     * @param itemName - The name of the item
+     */
+    static duplicate(itemType, itemName) {
+        const normalizedType = RegistryError.TYPE_MAP[itemType.toLowerCase()] ?? "tool";
+        return new RegistryError(`${itemType} '${itemName}' is already registered`, normalizedType, itemName, {
+            recoveryHint: `${itemType} '${itemName}' is already registered. Use a different name.`,
+        });
+    }
+}
+//# sourceMappingURL=system.js.map

package/build/errors/categories/system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.js","sourceRoot":"","sources":["../../../src/errors/categories/system.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGxD,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAe,EAAE,UAA0C,EAAE;QACvE,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,UAAU,CAAC,cAAc;YAC/B,UAAU,EAAE,GAAG;YACf,OAAO,EAAE,SAAS,CAAC,aAAa;YAChC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,iEAAiE;YACvG,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,kBAAkB;IAClB,4EAA4E;IAE5E;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,KAAc,EAAE,OAAgB;QAC1C,MAAM,OAAO,GAAG,OAAO;YACrB,CAAC,CAAC,GAAG,OAAO,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;YACzE,CAAC,CAAC,KAAK,YAAY,KAAK;gBACtB,CAAC,CAAC,KAAK,CAAC,OAAO;gBACf,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAEpB,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE;YAChC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;SAClD,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,WAAmB;QACxC,OAAO,IAAI,aAAa,CAAC,qBAAqB,WAAW,EAAE,EAAE;YAC3D,YAAY,EAAE,iDAAiD;SAChE,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAe;QACnC,OAAO,IAAI,aAAa,CAAC,YAAY,OAAO,sBAAsB,EAAE;YAClE,YAAY,EAAE,gBAAgB,OAAO,2BAA2B;SACjE,CAAC,CAAC;IACL,CAAC;CACF;AAED,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,yDAAyD;IAChD,QAAQ,CAAiC;IAElD,2BAA2B;IAClB,QAAQ,CAAS;IAE1B,YACE,OAAe,EACf,QAAwC,EACxC,QAAgB,EAChB,UAA0C,EAAE;QAE5C,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,UAAU,CAAC,cAAc;YAC/B,UAAU,EAAE,GAAG,EAAE,oBAAoB;YACrC,OAAO,EAAE,SAAS,CAAC,cAAc;YACjC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,OAAO,EAAE;gBACP,GAAG,OAAO,CAAC,OAAO;gBAClB,QAAQ;gBACR,QAAQ;aACT;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,4EAA4E;IAC5E,uBAAuB;IACvB,4EAA4E;IAE5E;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAY;QAC9B,OAAO,IAAI,aAAa,CAAC,SAAS,IAAI,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE;YACjE,YAAY,EAAE,wBAAwB,IAAI,sDAAsD;SACjG,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,IAAY;QAC/B,OAAO,IAAI,aAAa,CAAC,SAAS,IAAI,yBAAyB,EAAE,MAAM,EAAE,IAAI,EAAE;YAC7E,YAAY,EAAE,SAAS,IAAI,gDAAgD;SAC5E,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,2BAA2B;IAC3B,4EAA4E;IAE5E;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAY;QAClC,OAAO,IAAI,aAAa,CAAC,aAAa,IAAI,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE;YACzE,YAAY,EAAE,2BAA2B,IAAI,8DAA8D;SAC5G,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAY;QACnC,OAAO,IAAI,aAAa,CAAC,aAAa,IAAI,yBAAyB,EAAE,UAAU,EAAE,IAAI,EAAE;YACrF,YAAY,EAAE,aAAa,IAAI,+CAA+C;SAC/E,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,yBAAyB;IACzB,4EAA4E;IAE5E;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,IAAY;QAChC,OAAO,IAAI,aAAa,CAAC,WAAW,IAAI,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE;YACrE,YAAY,EAAE,0BAA0B,IAAI,0DAA0D;SACvG,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,IAAY;QACjC,OAAO,IAAI,aAAa,CAAC,WAAW,IAAI,yBAAyB,EAAE,QAAQ,EAAE,IAAI,EAAE;YACjF,YAAY,EAAE,WAAW,IAAI,gDAAgD;SAC9E,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,0BAA0B;IAC1B,4EAA4E;IAE5E,kFAAkF;IAC1E,MAAM,CAAU,QAAQ,GAA6D;QAC3F,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,UAAU;QACpB,MAAM,EAAE,QAAQ;KACjB,CAAC;IAEF;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,QAAgB,EAAE,QAAgB;QACjD,MAAM,cAAc,GAAG,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,MAAM,CAAC;QAChF,OAAO,IAAI,aAAa,CAAC,GAAG,QAAQ,KAAK,QAAQ,yBAAyB,EAAE,cAAc,EAAE,QAAQ,EAAE;YACpG,YAAY,EAAE,GAAG,QAAQ,KAAK,QAAQ,gDAAgD;SACvF,CAAC,CAAC;IACL,CAAC"}

package/build/errors/categories/transport.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Transport Error
+ *
+ * Error for MCP transport layer issues (connection, binding, rate limiting).
+ *
+ * @module errors/categories/transport
+ */
+import { AppError } from "../core/index.js";
+import type { BaseErrorOptions } from "../core/index.js";
+/**
+ * Error thrown for transport layer issues.
+ *
+ * @example
+ * ```typescript
+ * throw TransportError.closed();
+ * throw TransportError.connectionFailed('timeout');
+ * ```
+ */
+export declare class TransportError extends AppError {
+    /** The transport type */
+    readonly transportType?: "http" | "sse" | "stdio" | undefined;
+    constructor(message: string, options?: Omit<BaseErrorOptions, "code"> & {
+        transportType?: "http" | "sse" | "stdio" | undefined;
+    });
+    /**
+     * Create an error for closed transport.
+     */
+    static closed(): TransportError;
+    /**
+     * Create an error for transport not started.
+     */
+    static notStarted(): TransportError;
+    /**
+     * Create an error for unsupported transport type.
+     */
+    static unsupported(transport: string): TransportError;
+    /**
+     * Create an error for connection failure.
+     */
+    static connectionFailed(reason: string): TransportError;
+    /**
+     * Create an error for connection closed.
+     */
+    static connectionClosed(reason?: string): TransportError;
+    /**
+     * Create an error for invalid header.
+     */
+    static invalidHeader(header: string, reason: string): TransportError;
+    /**
+     * Create an error for protocol mismatch.
+     */
+    static protocolMismatch(expected: string, received: string): TransportError;
+    /**
+     * Create an error for rate limiting.
+     */
+    static rateLimited(retryAfterSeconds?: number): TransportError;
+    /**
+     * Create an error for DNS rebinding attack.
+     */
+    static dnsRebinding(host: string): TransportError;
+    /**
+     * Create an error for port already in use (EADDRINUSE).
+     */
+    static portInUse(bind: string): TransportError;
+    /**
+     * Create an error for insufficient privileges to bind (EACCES).
+     */
+    static privilegesRequired(bind: string): TransportError;
+}
+//# sourceMappingURL=transport.d.ts.map

package/build/errors/categories/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/transport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,QAAQ,EAA0B,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,yBAAyB;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;gBAG5D,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG;QACxC,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;KACjD;IAqBR;;OAEG;IACH,MAAM,CAAC,MAAM,IAAI,cAAc;IAM/B;;OAEG;IACH,MAAM,CAAC,UAAU,IAAI,cAAc;IAMnC;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc;IAMrD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc;IAOvD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc;IAQxD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc;IAQpE;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc;IAQ3E;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,cAAc;IAc9D;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAQjD;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAO9C;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;CAMxD"}

package/build/errors/categories/transport.js

@@ -0,0 +1,148 @@
+/**
+ * Transport Error
+ *
+ * Error for MCP transport layer issues (connection, binding, rate limiting).
+ *
+ * @module errors/categories/transport
+ */
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { AppError, ErrorCodes, HttpStatus } from "../core/index.js";
+// ============================================================================
+// Transport Error
+// ============================================================================
+/**
+ * Error thrown for transport layer issues.
+ *
+ * @example
+ * ```typescript
+ * throw TransportError.closed();
+ * throw TransportError.connectionFailed('timeout');
+ * ```
+ */
+export class TransportError extends AppError {
+    /** The transport type */
+    transportType;
+    constructor(message, options = {}) {
+        super(message, {
+            code: ErrorCodes.SERVICE_UNAVAILABLE,
+            statusCode: options.statusCode ?? HttpStatus.SERVICE_UNAVAILABLE,
+            mcpCode: ErrorCode.InternalError,
+            cause: options.cause,
+            recoveryHint: options.recoveryHint,
+            context: {
+                ...options.context,
+                transportType: options.transportType,
+            },
+        });
+        this.transportType = options.transportType;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create an error for closed transport.
+     */
+    static closed() {
+        return new TransportError("Transport is closed", {
+            recoveryHint: "The transport connection was closed. Reconnect to continue.",
+        });
+    }
+    /**
+     * Create an error for transport not started.
+     */
+    static notStarted() {
+        return new TransportError("Transport not started", {
+            recoveryHint: "Ensure the transport is properly started before sending messages.",
+        });
+    }
+    /**
+     * Create an error for unsupported transport type.
+     */
+    static unsupported(transport) {
+        return new TransportError(`Unsupported transport type: ${transport}`, {
+            recoveryHint: "Use a supported transport type: stdio or http.",
+        });
+    }
+    /**
+     * Create an error for connection failure.
+     */
+    static connectionFailed(reason) {
+        return new TransportError(`Connection failed: ${reason}`, {
+            statusCode: HttpStatus.BAD_GATEWAY,
+            recoveryHint: `Connection failed: ${reason}. Check network connectivity and try again.`,
+        });
+    }
+    /**
+     * Create an error for connection closed.
+     */
+    static connectionClosed(reason) {
+        const message = reason ? `Connection closed: ${reason}` : "Connection closed";
+        return new TransportError(message, {
+            recoveryHint: "The connection was closed. Reconnect to continue.",
+        });
+    }
+    /**
+     * Create an error for invalid header.
+     */
+    static invalidHeader(header, reason) {
+        return new TransportError(`Invalid header '${header}': ${reason}`, {
+            statusCode: HttpStatus.BAD_REQUEST,
+            context: { header, reason },
+            recoveryHint: `Check the '${header}' header value.`,
+        });
+    }
+    /**
+     * Create an error for protocol mismatch.
+     */
+    static protocolMismatch(expected, received) {
+        return new TransportError(`Protocol mismatch: expected '${expected}', received '${received}'`, {
+            statusCode: HttpStatus.BAD_REQUEST,
+            context: { expected, received },
+            recoveryHint: `Use protocol version '${expected}'.`,
+        });
+    }
+    /**
+     * Create an error for rate limiting.
+     */
+    static rateLimited(retryAfterSeconds) {
+        const message = retryAfterSeconds
+            ? `Rate limit exceeded. Retry after ${retryAfterSeconds} seconds`
+            : "Rate limit exceeded";
+        return new TransportError(message, {
+            statusCode: HttpStatus.TOO_MANY_REQUESTS,
+            context: retryAfterSeconds ? { retryAfterSeconds } : undefined,
+            recoveryHint: retryAfterSeconds
+                ? `Wait ${retryAfterSeconds} seconds before retrying.`
+                : "Wait a moment before retrying.",
+        });
+    }
+    /**
+     * Create an error for DNS rebinding attack.
+     */
+    static dnsRebinding(host) {
+        return new TransportError(`DNS rebinding attack detected from host '${host}'`, {
+            statusCode: HttpStatus.FORBIDDEN,
+            context: { host },
+            recoveryHint: "Access denied for security reasons.",
+        });
+    }
+    /**
+     * Create an error for port already in use (EADDRINUSE).
+     */
+    static portInUse(bind) {
+        return new TransportError(`Port ${bind} is already in use — server cannot start`, {
+            context: { bind },
+            recoveryHint: `Free port or choose a different one via MCP_PORT.`,
+        });
+    }
+    /**
+     * Create an error for insufficient privileges to bind (EACCES).
+     */
+    static privilegesRequired(bind) {
+        return new TransportError(`Binding to ${bind} requires elevated privileges`, {
+            context: { bind },
+            recoveryHint: "Use a port above 1024 or run with elevated privileges.",
+        });
+    }
+}
+//# sourceMappingURL=transport.js.map

package/build/errors/categories/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../../src/errors/categories/transport.ts"],"names":[],"mappings":"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"}

package/build/errors/categories/validation.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Validation Error Classes
+ *
+ * Errors related to input validation and configuration:
+ * - ValidationError: Input validation failures
+ * - ConfigurationError: Configuration/environment errors
+ *
+ * @module errors/categories/validation
+ */
+import { ZodError } from "zod";
+import { AppError } from "../core/index.js";
+import type { ValidationErrorOptions, ValidationIssue, BaseErrorOptions } from "../core/index.js";
+/**
+ * Error thrown when input validation fails.
+ *
+ * Integrates with Zod for schema validation errors.
+ *
+ * @example
+ * ```typescript
+ * // From Zod error
+ * throw ValidationError.fromZodError(zodError, 'Invalid server configuration');
+ *
+ * // Manual validation
+ * throw new ValidationError('Server name is required', {
+ *   field: 'server',
+ *   value: undefined
+ * });
+ *
+ * // Using factory methods
+ * throw ValidationError.fieldRequired('server');
+ * ```
+ */
+export declare class ValidationError extends AppError {
+    /** The field that failed validation */
+    readonly field?: string | undefined;
+    /** The invalid value (sanitized) */
+    readonly value?: unknown;
+    /** All validation issues (for multi-field validation) */
+    readonly issues?: ValidationIssue[] | undefined;
+    constructor(message: string, options?: ValidationErrorOptions);
+    /**
+     * Sanitize a value for safe storage/logging.
+     * Removes potential sensitive data.
+     */
+    private sanitizeValue;
+    /**
+     * Create a ValidationError from a Zod error.
+     */
+    static fromZodError(zodError: ZodError, message?: string): ValidationError;
+    /**
+     * Create a ValidationError for a required field.
+     */
+    static fieldRequired(field: string): ValidationError;
+    /**
+     * Create a ValidationError for an invalid field value.
+     */
+    static fieldInvalid(field: string, value?: unknown): ValidationError;
+    /**
+     * Create a ValidationError for a type mismatch.
+     */
+    static fieldTypeMismatch(field: string, expectedType: string): ValidationError;
+    /**
+     * Create a ValidationError for minimum value constraint.
+     */
+    static fieldMin(field: string, min: number): ValidationError;
+    /**
+     * Create a ValidationError for maximum value constraint.
+     */
+    static fieldMax(field: string, max: number): ValidationError;
+    /**
+     * Create a ValidationError for pattern mismatch.
+     */
+    static fieldPattern(field: string): ValidationError;
+    /**
+     * Format issues as a human-readable list.
+     */
+    formatIssues(): string;
+}
+/**
+ * Error thrown when configuration is invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new ConfigurationError('Missing required environment variable: API_URL');
+ *
+ * // Using factory methods
+ * throw ConfigurationError.missingEnvVar('API_URL');
+ * throw ConfigurationError.invalidEnvVar('API_PORT', 'must be a number');
+ * ```
+ */
+export declare class ConfigurationError extends AppError {
+    /** The configuration key that is invalid */
+    readonly configKey?: string | undefined;
+    constructor(message: string, options?: Omit<BaseErrorOptions, "code"> & {
+        configKey?: string | undefined;
+    });
+    /**
+     * Create a ConfigurationError for a missing environment variable.
+     */
+    static missingEnvVar(varName: string): ConfigurationError;
+    /**
+     * Create a ConfigurationError for an invalid environment variable value.
+     */
+    static invalidEnvVar(varName: string, reason: string): ConfigurationError;
+    /**
+     * Create a ConfigurationError with a custom message.
+     */
+    static invalid(message: string): ConfigurationError;
+    /**
+     * Create a ConfigurationError for an explicitly specified config file that doesn't exist.
+     */
+    static fileNotFound(filePath: string): ConfigurationError;
+    /**
+     * Create a ConfigurationError for a file that could not be read.
+     */
+    static fileReadFailed(filePath: string, cause?: Error): ConfigurationError;
+    /**
+     * Create a ConfigurationError for a TOML/YAML parse failure.
+     */
+    static fileParseFailed(filePath: string, cause?: Error): ConfigurationError;
+    /**
+     * Create a ConfigurationError for schema validation failures in a config file.
+     *
+     * Formats Zod issues into a human-readable message with the file path
+     * so users can locate and fix typos or invalid values.
+     */
+    static fileValidationFailed(filePath: string, zodError: ZodError): ConfigurationError;
+    /**
+     * Create a ConfigurationError for an unsupported config file extension.
+     */
+    static unsupportedFormat(extension: string): ConfigurationError;
+    /**
+     * Create a ConfigurationError for cross-field validation failures.
+     *
+     * Used after merging all config sources (env + file + overrides)
+     * to validate constraints that span multiple fields.
+     */
+    static constraintViolation(message: string, fields: string[]): ConfigurationError;
+}
+//# sourceMappingURL=validation.d.ts.map

package/build/errors/categories/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/validation.ts"],"names":[],"mappings":"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"}