mcp-server-framework 1.0.0

package/build/errors/core/json-rpc.js

@@ -0,0 +1,79 @@
+/**
+ * JSON-RPC Constants Module
+ *
+ * JSON-RPC 2.0 specification compliant error codes.
+ * Used for MCP protocol communication.
+ *
+ * @see https://www.jsonrpc.org/specification#error_object
+ * @module errors/core/json-rpc
+ */
+// ============================================================================
+// JSON-RPC Error Codes (MCP Spec Compliant)
+// ============================================================================
+/**
+ * Standard JSON-RPC 2.0 error codes.
+ *
+ * Range -32700 to -32600: Spec-defined errors
+ * Range -32000 to -32099: Implementation-defined server errors
+ */
+export const JsonRpcErrorCode = {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Spec-defined errors (-32700 to -32600)
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Invalid JSON was received by the server */
+    PARSE_ERROR: -32700,
+    /** The JSON sent is not a valid Request object */
+    INVALID_REQUEST: -32600,
+    /** The method does not exist / is not available */
+    METHOD_NOT_FOUND: -32601,
+    /** Invalid method parameter(s) */
+    INVALID_PARAMS: -32602,
+    /** Internal JSON-RPC error */
+    INTERNAL_ERROR: -32603,
+    // ─────────────────────────────────────────────────────────────────────────
+    // Implementation-defined server errors (-32000 to -32099)
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Generic server error */
+    SERVER_ERROR: -32000,
+    /** Session not found or expired */
+    SESSION_NOT_FOUND: -32001,
+    /** Request was cancelled */
+    REQUEST_CANCELLED: -32002,
+};
+// ============================================================================
+// JSON-RPC Error Code Utilities
+// ============================================================================
+/**
+ * Check if an error code is a spec-defined JSON-RPC error.
+ */
+export function isSpecDefinedJsonRpcError(code) {
+    return code >= -32700 && code <= -32600;
+}
+/**
+ * Check if an error code is an implementation-defined server error.
+ */
+export function isServerDefinedJsonRpcError(code) {
+    return code >= -32099 && code <= -32000;
+}
+/**
+ * Check if an error code is a valid JSON-RPC error code.
+ */
+export function isValidJsonRpcErrorCode(code) {
+    return isSpecDefinedJsonRpcError(code) || isServerDefinedJsonRpcError(code);
+}
+/**
+ * Creates a JSON-RPC 2.0 error response.
+ *
+ * @param code - JSON-RPC error code (use JsonRpcErrorCode enum)
+ * @param message - Error message
+ * @param id - Request ID (null for notifications)
+ * @returns Structured JSON-RPC 2.0 error response
+ */
+export function createJsonRpcError(code, message, id = null) {
+    return {
+        jsonrpc: "2.0",
+        error: { code, message: message ?? "Unknown error" },
+        id,
+    };
+}
+//# sourceMappingURL=json-rpc.js.map

package/build/errors/core/json-rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-rpc.js","sourceRoot":"","sources":["../../../src/errors/core/json-rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,+EAA+E;AAC/E,4CAA4C;AAC5C,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,4EAA4E;IAC5E,yCAAyC;IACzC,4EAA4E;IAC5E,8CAA8C;IAC9C,WAAW,EAAE,CAAC,KAAK;IACnB,kDAAkD;IAClD,eAAe,EAAE,CAAC,KAAK;IACvB,mDAAmD;IACnD,gBAAgB,EAAE,CAAC,KAAK;IACxB,kCAAkC;IAClC,cAAc,EAAE,CAAC,KAAK;IACtB,8BAA8B;IAC9B,cAAc,EAAE,CAAC,KAAK;IAEtB,4EAA4E;IAC5E,0DAA0D;IAC1D,4EAA4E;IAC5E,2BAA2B;IAC3B,YAAY,EAAE,CAAC,KAAK;IACpB,mCAAmC;IACnC,iBAAiB,EAAE,CAAC,KAAK;IACzB,4BAA4B;IAC5B,iBAAiB,EAAE,CAAC,KAAK;CACjB,CAAC;AAIX,+EAA+E;AAC/E,gCAAgC;AAChC,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,OAAO,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,yBAAyB,CAAC,IAAI,CAAC,IAAI,2BAA2B,CAAC,IAAI,CAAC,CAAC;AAC9E,CAAC;AAmBD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAmC,EACnC,OAAgB,EAChB,KAAuB,IAAI;IAE3B,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE;QACpD,EAAE;KACH,CAAC;AACJ,CAAC"}

package/build/errors/core/messages.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Transport Error Messages
+ *
+ * String constants used by transport layer code (SSE handler, Streamable HTTP, middleware)
+ * to return protocol-level error messages in HTTP responses.
+ *
+ * These are static strings (no interpolation needed) — each maps a short semantic key
+ * to the user-facing error message string.
+ *
+ * @module errors/core/messages
+ */
+/**
+ * Transport-specific error message constants.
+ *
+ * Provides a convenient API for transport layer code to reference
+ * standardized error messages.
+ *
+ * @example
+ * ```typescript
+ * import { TransportErrorMessage } from '../errors/index.js';
+ *
+ * res.status(HttpStatus.BAD_REQUEST)
+ *    .json({ error: TransportErrorMessage.SESSION_ID_REQUIRED });
+ * ```
+ */
+export declare const TransportErrorMessage: {
+    readonly SESSION_ID_REQUIRED: "Mcp-Session-Id header required";
+    readonly SESSION_ID_OR_PARAM_REQUIRED: "Mcp-Session-Id header or sessionId query parameter required";
+    readonly SESSION_NOT_FOUND: "Session not found or expired";
+    readonly SESSION_NOT_FOUND_REINIT: "Session has expired. Please re-initialize.";
+    readonly TOO_MANY_SESSIONS: "Service unavailable: too many active sessions";
+    readonly MISSING_ACCEPT_HEADER: "Missing Accept header";
+    readonly INVALID_ACCEPT_HEADER: "Invalid Accept header";
+    readonly INVALID_CONTENT_TYPE: "Content-Type must be application/json";
+    readonly INVALID_JSON: "Invalid JSON";
+    readonly INVALID_JSONRPC: "Invalid JSON-RPC version";
+    readonly INVALID_JSONRPC_VERSION: "JSON-RPC version must be 2.0";
+    readonly INVALID_JSONRPC_BATCH: "Invalid batch request: array must not be empty";
+    readonly MISSING_JSONRPC_METHOD: "Missing method field";
+    readonly DNS_REBINDING_BLOCKED: "Forbidden: Invalid Host header";
+    readonly ORIGIN_NOT_ALLOWED: "Forbidden: Invalid Origin header";
+    readonly RATE_LIMIT_EXCEEDED: "Too many requests from this IP, please try again later.";
+    readonly PROXY_NOT_CONFIGURED: "Bad Gateway: proxy headers detected but trust proxy is not configured";
+    readonly TRANSPORT_CLOSED: "Transport is closed";
+    readonly UNSUPPORTED_PROTOCOL_VERSION: "Unsupported MCP-Protocol-Version";
+    readonly SSE_DISABLED: "SSE transport is disabled. Enable with MCP_LEGACY_SSE_ENABLED=true or use Streamable HTTP transport.";
+    readonly SESSION_ID_QUERY_REQUIRED: "sessionId query parameter required";
+    readonly INTERNAL_ERROR: "An internal error occurred";
+};
+export type TransportErrorMessageKey = keyof typeof TransportErrorMessage;
+//# sourceMappingURL=messages.d.ts.map

package/build/errors/core/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/errors/core/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;CAkCxB,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,MAAM,OAAO,qBAAqB,CAAC"}

package/build/errors/core/messages.js

@@ -0,0 +1,59 @@
+/**
+ * Transport Error Messages
+ *
+ * String constants used by transport layer code (SSE handler, Streamable HTTP, middleware)
+ * to return protocol-level error messages in HTTP responses.
+ *
+ * These are static strings (no interpolation needed) — each maps a short semantic key
+ * to the user-facing error message string.
+ *
+ * @module errors/core/messages
+ */
+// ============================================================================
+// Transport Error Message Mapping
+// ============================================================================
+/**
+ * Transport-specific error message constants.
+ *
+ * Provides a convenient API for transport layer code to reference
+ * standardized error messages.
+ *
+ * @example
+ * ```typescript
+ * import { TransportErrorMessage } from '../errors/index.js';
+ *
+ * res.status(HttpStatus.BAD_REQUEST)
+ *    .json({ error: TransportErrorMessage.SESSION_ID_REQUIRED });
+ * ```
+ */
+export const TransportErrorMessage = {
+    // Session errors
+    SESSION_ID_REQUIRED: "Mcp-Session-Id header required",
+    SESSION_ID_OR_PARAM_REQUIRED: "Mcp-Session-Id header or sessionId query parameter required",
+    SESSION_NOT_FOUND: "Session not found or expired",
+    SESSION_NOT_FOUND_REINIT: "Session has expired. Please re-initialize.",
+    TOO_MANY_SESSIONS: "Service unavailable: too many active sessions",
+    // Content errors
+    MISSING_ACCEPT_HEADER: "Missing Accept header",
+    INVALID_ACCEPT_HEADER: "Invalid Accept header",
+    INVALID_CONTENT_TYPE: "Content-Type must be application/json",
+    INVALID_JSON: "Invalid JSON",
+    INVALID_JSONRPC: "Invalid JSON-RPC version",
+    INVALID_JSONRPC_VERSION: "JSON-RPC version must be 2.0",
+    INVALID_JSONRPC_BATCH: "Invalid batch request: array must not be empty",
+    MISSING_JSONRPC_METHOD: "Missing method field",
+    // Security errors
+    DNS_REBINDING_BLOCKED: "Forbidden: Invalid Host header",
+    ORIGIN_NOT_ALLOWED: "Forbidden: Invalid Origin header",
+    RATE_LIMIT_EXCEEDED: "Too many requests from this IP, please try again later.",
+    PROXY_NOT_CONFIGURED: "Bad Gateway: proxy headers detected but trust proxy is not configured",
+    // Transport state
+    TRANSPORT_CLOSED: "Transport is closed",
+    // Protocol
+    UNSUPPORTED_PROTOCOL_VERSION: "Unsupported MCP-Protocol-Version",
+    SSE_DISABLED: "SSE transport is disabled. Enable with MCP_LEGACY_SSE_ENABLED=true or use Streamable HTTP transport.",
+    SESSION_ID_QUERY_REQUIRED: "sessionId query parameter required",
+    // Generic
+    INTERNAL_ERROR: "An internal error occurred",
+};
+//# sourceMappingURL=messages.js.map

package/build/errors/core/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/errors/core/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,iBAAiB;IACjB,mBAAmB,EAAE,gCAAgC;IACrD,4BAA4B,EAAE,6DAA6D;IAC3F,iBAAiB,EAAE,8BAA8B;IACjD,wBAAwB,EAAE,4CAA4C;IACtE,iBAAiB,EAAE,+CAA+C;IAElE,iBAAiB;IACjB,qBAAqB,EAAE,uBAAuB;IAC9C,qBAAqB,EAAE,uBAAuB;IAC9C,oBAAoB,EAAE,uCAAuC;IAC7D,YAAY,EAAE,cAAc;IAC5B,eAAe,EAAE,0BAA0B;IAC3C,uBAAuB,EAAE,8BAA8B;IACvD,qBAAqB,EAAE,gDAAgD;IACvE,sBAAsB,EAAE,sBAAsB;IAE9C,kBAAkB;IAClB,qBAAqB,EAAE,gCAAgC;IACvD,kBAAkB,EAAE,kCAAkC;IACtD,mBAAmB,EAAE,yDAAyD;IAC9E,oBAAoB,EAAE,uEAAuE;IAE7F,kBAAkB;IAClB,gBAAgB,EAAE,qBAAqB;IAEvC,WAAW;IACX,4BAA4B,EAAE,kCAAkC;IAChE,YAAY,EAAE,sGAAsG;IACpH,yBAAyB,EAAE,oCAAoC;IAE/D,UAAU;IACV,cAAc,EAAE,4BAA4B;CACpC,CAAC"}

package/build/errors/core/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Error Type Definitions
+ *
+ * Pure TypeScript type definitions for the error system.
+ * Contains only interfaces and type aliases - no runtime values.
+ *
+ * @module errors/core/types
+ */
+import type { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import type { ErrorCodeType } from "./index.js";
+/**
+ * Serializable error information for logging and API responses.
+ */
+export interface SerializedError {
+    /** Error class name */
+    name: string;
+    /** Human-readable error message */
+    message: string;
+    /** Unique error ID for tracking/support */
+    errorId: string;
+    /** Application-specific error code */
+    code: ErrorCodeType | string;
+    /** HTTP status code (if applicable) */
+    statusCode?: number;
+    /** MCP error code (if applicable) */
+    mcpCode?: ErrorCode;
+    /** Stack trace (development only) */
+    stack?: string;
+    /** Original error that caused this error */
+    cause?: SerializedError | string;
+    /** Additional context for debugging */
+    context?: Record<string, unknown>;
+    /** Timestamp of error occurrence */
+    timestamp?: string;
+    /** Recovery hint for users */
+    recoveryHint?: string;
+}
+/**
+ * Base options for creating errors.
+ */
+export interface BaseErrorOptions {
+    /** Application error code */
+    code?: ErrorCodeType | string;
+    /** HTTP status code override */
+    statusCode?: number;
+    /** MCP error code override */
+    mcpCode?: ErrorCode;
+    /** Original error that caused this */
+    cause?: Error | undefined;
+    /** Additional context for debugging */
+    context?: Record<string, unknown> | undefined;
+    /** Recovery hint for users */
+    recoveryHint?: string | undefined;
+}
+/**
+ * Options for validation errors.
+ */
+export interface ValidationErrorOptions extends Omit<BaseErrorOptions, "code"> {
+    /** The field that failed validation */
+    field?: string | undefined;
+    /** The value that failed validation (will be sanitized) */
+    value?: unknown;
+    /** Expected type or format */
+    expected?: string | undefined;
+    /** Multiple validation issues */
+    issues?: ValidationIssue[] | undefined;
+}
+/**
+ * Validation issue for multi-field validation.
+ */
+export interface ValidationIssue {
+    /** Path to the invalid field */
+    path: string;
+    /** Error message for this issue */
+    message: string;
+    /** Zod error code */
+    code?: string;
+}
+export type { ErrorCodeType, ErrorCategoryType } from "./error-codes.js";
+//# sourceMappingURL=types.d.ts.map

package/build/errors/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/errors/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IAC7B,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,KAAK,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC;IACjC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,IAAI,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IAC9B,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,sCAAsC;IACtC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC9C,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAC5E,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,iCAAiC;IACjC,MAAM,CAAC,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/build/errors/core/types.js

@@ -0,0 +1,10 @@
+/**
+ * Error Type Definitions
+ *
+ * Pure TypeScript type definitions for the error system.
+ * Contains only interfaces and type aliases - no runtime values.
+ *
+ * @module errors/core/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/build/errors/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/errors/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/build/errors/factory.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Framework Error Factory
+ *
+ * Centralized error creation for the MCP framework layer.
+ * Application-specific errors should extend these in app/errors/.
+ *
+ * @module errors/factory
+ */
+import { ZodError } from "zod";
+import { AppError } from "./core/index.js";
+import { McpProtocolError, SessionError, TransportError, ValidationError, ConfigurationError, InternalError, RegistryError, OperationError, OperationCancelledError, ConnectionError, AuthenticationError, AuthorizationError } from "./categories/index.js";
+/**
+ * Framework Error Factory
+ *
+ * Provides static methods for creating framework-level errors.
+ * This factory is generic and can be extended by application code.
+ *
+ * @example
+ * ```typescript
+ * // MCP errors
+ * throw FrameworkErrorFactory.mcp.invalidRequest('Missing params');
+ * throw FrameworkErrorFactory.session.expired('sess-123');
+ *
+ * // Validation errors
+ * throw FrameworkErrorFactory.validation.fromZodError(zodError);
+ * throw FrameworkErrorFactory.validation.fieldRequired('name');
+ *
+ * // Operation errors
+ * throw FrameworkErrorFactory.operation.failed('deploy', 'timeout');
+ * ```
+ */
+export declare const FrameworkErrorFactory: {
+    readonly mcp: {
+        /** Create an invalid request error */
+        readonly invalidRequest: (reason: string) => McpProtocolError;
+        /** Create a method not found error */
+        readonly methodNotFound: (method: string) => McpProtocolError;
+        /** Create an invalid params error */
+        readonly invalidParams: (reason: string) => McpProtocolError;
+        /** Create a parse error */
+        readonly parseError: (reason: string) => McpProtocolError;
+        /** Create a custom MCP error */
+        readonly custom: (message: string, code?: number) => McpProtocolError;
+    };
+    readonly session: {
+        /** Create a session not found error */
+        readonly notFound: (sessionId: string) => SessionError;
+        /** Create a session expired error */
+        readonly expired: (sessionId: string) => SessionError;
+        /** Create a session limit reached error */
+        readonly limitReached: (maxSessions: number) => SessionError;
+        /** Create an invalid session state error */
+        readonly invalidState: (sessionId: string, currentState: string, expectedState: string) => SessionError;
+        /** Create a custom session error */
+        readonly custom: (message: string, sessionId?: string) => SessionError;
+    };
+    readonly transport: {
+        /** Create a connection failed error */
+        readonly connectionFailed: (reason: string) => TransportError;
+        /** Create a connection closed error */
+        readonly connectionClosed: (reason?: string) => TransportError;
+        /** Create an invalid header error */
+        readonly invalidHeader: (header: string, reason: string) => TransportError;
+        /** Create a protocol mismatch error */
+        readonly protocolMismatch: (expected: string, received: string) => TransportError;
+        /** Create a rate limited error */
+        readonly rateLimited: (retryAfterSeconds?: number) => TransportError;
+        /** Create a DNS rebinding error */
+        readonly dnsRebinding: (host: string) => TransportError;
+        /** Create a port-in-use error */
+        readonly portInUse: (bind: string) => TransportError;
+        /** Create a privileges-required error */
+        readonly privilegesRequired: (bind: string) => TransportError;
+        /** Create a custom transport error */
+        readonly custom: (message: string, transportType?: "http" | "sse" | "stdio") => TransportError;
+    };
+    readonly validation: {
+        /** Create from a Zod error */
+        readonly fromZodError: (error: ZodError, message?: string) => ValidationError;
+        /** Create a field required error */
+        readonly fieldRequired: (field: string) => ValidationError;
+        /** Create a field invalid error */
+        readonly fieldInvalid: (field: string, value?: unknown) => ValidationError;
+        /** Create a type mismatch error */
+        readonly fieldTypeMismatch: (field: string, expectedType: string) => ValidationError;
+        /** Create a min constraint error */
+        readonly fieldMin: (field: string, min: number) => ValidationError;
+        /** Create a max constraint error */
+        readonly fieldMax: (field: string, max: number) => ValidationError;
+        /** Create a pattern mismatch error */
+        readonly fieldPattern: (field: string) => ValidationError;
+        /** Create a custom validation error */
+        readonly custom: (message: string, field?: string) => ValidationError;
+    };
+    readonly configuration: {
+        /** Create a missing env var error */
+        readonly missingEnvVar: (varName: string) => ConfigurationError;
+        /** Create an invalid env var error */
+        readonly invalidEnvVar: (varName: string, reason: string) => ConfigurationError;
+        /** Create an invalid configuration error */
+        readonly invalid: (message: string) => ConfigurationError;
+        /** Config file not found (explicit MCP_CONFIG_FILE path) */
+        readonly fileNotFound: (filePath: string) => ConfigurationError;
+        /** Config file could not be read */
+        readonly fileReadFailed: (filePath: string, cause?: Error) => ConfigurationError;
+        /** Config file TOML/YAML parse failure */
+        readonly fileParseFailed: (filePath: string, cause?: Error) => ConfigurationError;
+        /** Config file schema validation failed (typos, wrong types) */
+        readonly fileValidationFailed: (filePath: string, zodError: ZodError) => ConfigurationError;
+        /** Unsupported config file extension */
+        readonly unsupportedFormat: (extension: string) => ConfigurationError;
+        /** Cross-field constraint violation */
+        readonly constraintViolation: (message: string, fields: string[]) => ConfigurationError;
+        /** Create a custom configuration error */
+        readonly custom: (message: string, configKey?: string) => ConfigurationError;
+    };
+    readonly operation: {
+        /** Create a failed operation error */
+        readonly failed: (operation: string, reason?: string) => OperationError;
+        /** Create a timeout error */
+        readonly timeout: (operation: string, timeoutMs: number) => OperationError;
+        /** Create an unavailable error */
+        readonly unavailable: (operation: string) => OperationError;
+        /** Create a custom operation error */
+        readonly custom: (message: string, operation?: string) => OperationError;
+    };
+    readonly cancellation: {
+        /** Create from a cancelled request */
+        readonly fromRequest: (requestId: string | number, reason?: string) => OperationCancelledError;
+        /** Create from an AbortSignal */
+        readonly fromAbortSignal: (signal: AbortSignal, requestId?: string | number) => OperationCancelledError;
+        /** Create a custom cancellation error */
+        readonly custom: (message: string, requestId?: string | number) => OperationCancelledError;
+    };
+    readonly internal: {
+        /** Wrap an unknown error */
+        readonly wrap: (error: unknown, context?: string) => InternalError;
+        /** Create an unexpected state error */
+        readonly unexpectedState: (description: string) => InternalError;
+        /** Create a not implemented error */
+        readonly notImplemented: (feature: string) => InternalError;
+        /** Create a custom internal error */
+        readonly custom: (message: string) => InternalError;
+    };
+    readonly registry: {
+        /** Tool not found */
+        readonly toolNotFound: (name: string) => RegistryError;
+        /** Duplicate tool */
+        readonly duplicateTool: (name: string) => RegistryError;
+        /** Resource not found */
+        readonly resourceNotFound: (name: string) => RegistryError;
+        /** Duplicate resource */
+        readonly duplicateResource: (name: string) => RegistryError;
+        /** Prompt not found */
+        readonly promptNotFound: (name: string) => RegistryError;
+        /** Duplicate prompt */
+        readonly duplicatePrompt: (name: string) => RegistryError;
+    };
+    readonly connection: {
+        /** Create a generic connection failed error */
+        readonly failed: (target: string, reason?: string) => ConnectionError;
+        /** Create a connection refused error */
+        readonly refused: (target: string) => ConnectionError;
+        /** Create a connection timeout error */
+        readonly timeout: (target: string, timeoutMs?: number) => ConnectionError;
+        /** Create a connection lost error */
+        readonly lost: (target: string) => ConnectionError;
+        /** Create a connection reset error */
+        readonly reset: (target: string) => ConnectionError;
+        /** Create a health check failed error */
+        readonly healthCheckFailed: (reason: string, target?: string) => ConnectionError;
+        /** Create a custom connection error */
+        readonly custom: (message: string, target: string) => ConnectionError;
+    };
+    readonly auth: {
+        /** Token is invalid or malformed */
+        readonly invalidToken: (reason?: string) => AuthenticationError;
+        /** Token has expired */
+        readonly tokenExpired: () => AuthenticationError;
+        /** No token provided */
+        readonly missingToken: () => AuthenticationError;
+        /** Token lacks required scopes */
+        readonly insufficientScope: (required: string[], actual: string[]) => AuthorizationError;
+        /** Generic forbidden */
+        readonly forbidden: (reason?: string) => AuthorizationError;
+        /** Custom authentication error */
+        readonly unauthorized: (message: string) => AuthenticationError;
+    };
+    /**
+     * Check if an error is an AppError (framework or app error)
+     */
+    readonly isAppError: (error: unknown) => error is AppError;
+    /**
+     * Normalize any error to an AppError
+     */
+    readonly normalize: (error: unknown, fallbackMessage?: string) => AppError;
+};
+export type FrameworkErrorFactoryType = typeof FrameworkErrorFactory;
+//# sourceMappingURL=factory.d.ts.map

package/build/errors/factory.d.ts.map

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