mcp-server-framework 1.0.0

package/build/connection/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connection/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAoB7C,iFAAiF;AAEjF,kCAAkC;AAClC,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAEtH,gCAAgC;AAChC,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,+EAA+E;AAC/E,wCAAwC;AACxC,+EAA+E;AAE/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/build/connection/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Service Client Types
+ *
+ * Core service client interface and health check types.
+ * The ServiceClient interface defines the minimum contract for connection
+ * management with any backend service.
+ *
+ * @module connection/types
+ */
+/**
+ * Health status values for service client connectivity.
+ */
+export type HealthStatus = "healthy" | "unhealthy";
+/**
+ * Health check result from a service client.
+ *
+ * @example
+ * ```typescript
+ * const result: HealthCheckResult = {
+ *   status: 'healthy',
+ *   message: 'Connection established',
+ *   details: { responseTime: 42 }
+ * };
+ * ```
+ */
+export interface HealthCheckResult {
+    /** Health status of the service client */
+    readonly status: HealthStatus;
+    /** Optional human-readable message */
+    readonly message?: string;
+    /** Optional additional details for debugging (extensible) */
+    readonly details?: {
+        readonly [key: string]: unknown;
+    };
+}
+/**
+ * Generic service client interface for connection management.
+ *
+ * This interface defines the minimum contract that any service client
+ * must implement to work with the MCP server framework's connection
+ * state management and tool execution.
+ *
+ * @example
+ * ```typescript
+ * class MyServiceClient implements ServiceClient {
+ *   readonly clientType = 'my-api';
+ *
+ *   async healthCheck(): Promise<HealthCheckResult> {
+ *     try {
+ *       await this.ping();
+ *       return { status: 'healthy' };
+ *     } catch (error) {
+ *       return { status: 'unhealthy', message: error.message };
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface ServiceClient {
+    /**
+     * Unique identifier for the client type.
+     * Used for logging and telemetry attribution.
+     *
+     * @example 'my-api', 'docker', 'kubernetes'
+     */
+    readonly clientType: string;
+    /**
+     * Performs a health check to verify connectivity.
+     *
+     * This method is OPTIONAL. If not provided, the framework assumes
+     * the client is healthy when connected.
+     *
+     * When provided, this method is called:
+     * - During initial connection to validate credentials
+     * - Periodically to monitor connection health
+     * - On reconnection attempts
+     *
+     * Implementations should:
+     * - Make a lightweight API call (e.g., ping, version check)
+     * - Return quickly (timeout recommended: 5-10 seconds)
+     * - NOT throw errors - return unhealthy status instead
+     *
+     * @returns Health check result with status and optional details
+     */
+    healthCheck?(): Promise<HealthCheckResult>;
+    /**
+     * Gracefully release resources held by the client.
+     *
+     * This method is OPTIONAL. If provided, it is called by
+     * {@link ConnectionStateManager} during disconnect to allow
+     * the client to close sockets, drain pools, flush buffers, etc.
+     *
+     * Implementations should:
+     * - Release all held resources (connections, file handles, timers)
+     * - Be idempotent (safe to call multiple times)
+     * - NOT throw errors — log and swallow instead
+     *
+     * @returns Resolves when cleanup is complete
+     */
+    disconnect?(): Promise<void>;
+}
+/**
+ * Type guard to check if an object implements ServiceClient.
+ *
+ * @param obj - Object to check
+ * @returns True if obj implements ServiceClient interface
+ *
+ * @example
+ * ```typescript
+ * if (isServiceClient(maybeClient)) {
+ *   const result = await maybeClient.healthCheck();
+ * }
+ * ```
+ */
+export declare function isServiceClient(obj: unknown): obj is ServiceClient;
+/**
+ * Factory function type for creating service clients.
+ *
+ * @public Exported for consumer dependency injection and testing patterns.
+ *
+ * @typeParam TService - The service client type to create
+ * @typeParam TConfig - Configuration type for client creation
+ */
+export type ServiceClientFactory<TService extends ServiceClient, TConfig = unknown> = (config: TConfig) => Promise<TService>;
+//# sourceMappingURL=types.d.ts.map

package/build/connection/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACjC,CAAC;CACH;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE3C;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,aAAa,CAclE;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,CAAC,QAAQ,SAAS,aAAa,EAAE,OAAO,GAAG,OAAO,IAAI,CACpF,MAAM,EAAE,OAAO,KACZ,OAAO,CAAC,QAAQ,CAAC,CAAC"}

package/build/connection/types.js

@@ -0,0 +1,39 @@
+/**
+ * Service Client Types
+ *
+ * Core service client interface and health check types.
+ * The ServiceClient interface defines the minimum contract for connection
+ * management with any backend service.
+ *
+ * @module connection/types
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if an object implements ServiceClient.
+ *
+ * @param obj - Object to check
+ * @returns True if obj implements ServiceClient interface
+ *
+ * @example
+ * ```typescript
+ * if (isServiceClient(maybeClient)) {
+ *   const result = await maybeClient.healthCheck();
+ * }
+ * ```
+ */
+export function isServiceClient(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        "clientType" in obj &&
+        // @type-guard — After 'in' check, property exists but TS cannot narrow unknown for property access
+        typeof obj.clientType === "string" &&
+        // healthCheck is optional - only validate if present
+        // @type-guard — Same pattern: validate optional property type after 'in' existence check
+        (!("healthCheck" in obj) || typeof obj.healthCheck === "function") &&
+        // disconnect is optional - only validate if present
+        // @type-guard — Same pattern: validate optional property type after 'in' existence check
+        (!("disconnect" in obj) || typeof obj.disconnect === "function"));
+}
+//# sourceMappingURL=types.js.map

package/build/connection/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6GH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,YAAY,IAAI,GAAG;QACnB,mGAAmG;QACnG,OAAQ,GAAqB,CAAC,UAAU,KAAK,QAAQ;QACrD,qDAAqD;QACrD,yFAAyF;QACzF,CAAC,CAAC,CAAC,aAAa,IAAI,GAAG,CAAC,IAAI,OAAQ,GAAqB,CAAC,WAAW,KAAK,UAAU,CAAC;QACrF,oDAAoD;QACpD,yFAAyF;QACzF,CAAC,CAAC,CAAC,YAAY,IAAI,GAAG,CAAC,IAAI,OAAQ,GAAqB,CAAC,UAAU,KAAK,UAAU,CAAC,CACpF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * Auth Error Classes
+ *
+ * Errors related to authentication and authorization:
+ * - AuthenticationError: Token validation failures, missing tokens (HTTP 401)
+ * - AuthorizationError: Insufficient permissions or scopes (HTTP 403)
+ *
+ * @module errors/categories/auth
+ */
+import { AppError } from "../core/index.js";
+import type { BaseErrorOptions } from "../core/index.js";
+/**
+ * Error thrown when authentication fails.
+ *
+ * Maps to HTTP 401 Unauthorized — the request lacks valid credentials.
+ *
+ * @example
+ * ```typescript
+ * throw AuthenticationError.invalidToken('Token signature invalid');
+ * throw AuthenticationError.tokenExpired();
+ * throw AuthenticationError.missingToken();
+ * ```
+ */
+export declare class AuthenticationError extends AppError {
+    constructor(message: string, options?: BaseErrorOptions);
+    /** Token is invalid or malformed */
+    static invalidToken(reason?: string): AuthenticationError;
+    /** Token has expired */
+    static tokenExpired(): AuthenticationError;
+    /** No token provided in request */
+    static missingToken(): AuthenticationError;
+}
+/**
+ * Error thrown when authorization fails (authenticated but not permitted).
+ *
+ * Maps to HTTP 403 Forbidden — the request is authenticated but lacks
+ * the required permissions or scopes.
+ *
+ * @example
+ * ```typescript
+ * throw AuthorizationError.insufficientScope(['mcp:write'], ['mcp:read']);
+ * throw AuthorizationError.forbidden('Admin access required');
+ * ```
+ */
+export declare class AuthorizationError extends AppError {
+    /** Scopes that were required */
+    readonly requiredScopes?: readonly string[] | undefined;
+    /** Scopes that the token actually has */
+    readonly actualScopes?: readonly string[] | undefined;
+    constructor(message: string, options?: BaseErrorOptions & {
+        requiredScopes?: string[] | undefined;
+        actualScopes?: string[] | undefined;
+    });
+    /** Token lacks required scopes */
+    static insufficientScope(required: readonly string[], actual: readonly string[]): AuthorizationError;
+    /** Generic forbidden — authenticated but not authorized */
+    static forbidden(reason?: string): AuthorizationError;
+}
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAc,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAa3D,oCAAoC;IACpC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB;IAOzD,wBAAwB;IACxB,MAAM,CAAC,YAAY,IAAI,mBAAmB;IAM1C,mCAAmC;IACnC,MAAM,CAAC,YAAY,IAAI,mBAAmB;CAK3C;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,gCAAgC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAExD,yCAAyC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;gBAGpD,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAgB,GAAG;QAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QACtC,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;KAChC;IAsBR,kCAAkC;IAClC,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB;IAQpG,2DAA2D;IAC3D,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,kBAAkB;CAItD"}

package/build/errors/categories/auth.js

@@ -0,0 +1,111 @@
+/**
+ * Auth Error Classes
+ *
+ * Errors related to authentication and authorization:
+ * - AuthenticationError: Token validation failures, missing tokens (HTTP 401)
+ * - AuthorizationError: Insufficient permissions or scopes (HTTP 403)
+ *
+ * @module errors/categories/auth
+ */
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { AppError, ErrorCodes } from "../core/index.js";
+// ============================================================================
+// Authentication Error (401)
+// ============================================================================
+/**
+ * Error thrown when authentication fails.
+ *
+ * Maps to HTTP 401 Unauthorized — the request lacks valid credentials.
+ *
+ * @example
+ * ```typescript
+ * throw AuthenticationError.invalidToken('Token signature invalid');
+ * throw AuthenticationError.tokenExpired();
+ * throw AuthenticationError.missingToken();
+ * ```
+ */
+export class AuthenticationError extends AppError {
+    constructor(message, options = {}) {
+        super(message, {
+            code: ErrorCodes.UNAUTHORIZED,
+            statusCode: 401,
+            mcpCode: ErrorCode.InvalidRequest,
+            ...options,
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Token is invalid or malformed */
+    static invalidToken(reason) {
+        const message = reason ? `Invalid access token: ${reason}` : "Invalid access token";
+        return new AuthenticationError(message, {
+            recoveryHint: "Provide a valid Bearer token in the Authorization header",
+        });
+    }
+    /** Token has expired */
+    static tokenExpired() {
+        return new AuthenticationError("Access token has expired", {
+            recoveryHint: "Refresh the token or obtain a new one",
+        });
+    }
+    /** No token provided in request */
+    static missingToken() {
+        return new AuthenticationError("Missing Bearer token", {
+            recoveryHint: "Include an Authorization: Bearer <token> header",
+        });
+    }
+}
+// ============================================================================
+// Authorization Error (403)
+// ============================================================================
+/**
+ * Error thrown when authorization fails (authenticated but not permitted).
+ *
+ * Maps to HTTP 403 Forbidden — the request is authenticated but lacks
+ * the required permissions or scopes.
+ *
+ * @example
+ * ```typescript
+ * throw AuthorizationError.insufficientScope(['mcp:write'], ['mcp:read']);
+ * throw AuthorizationError.forbidden('Admin access required');
+ * ```
+ */
+export class AuthorizationError extends AppError {
+    /** Scopes that were required */
+    requiredScopes;
+    /** Scopes that the token actually has */
+    actualScopes;
+    constructor(message, options = {}) {
+        super(message, {
+            code: ErrorCodes.FORBIDDEN,
+            statusCode: 403,
+            mcpCode: ErrorCode.InvalidRequest,
+            ...options,
+            context: {
+                ...options.context,
+                requiredScopes: options.requiredScopes,
+                actualScopes: options.actualScopes,
+            },
+        });
+        this.requiredScopes = options.requiredScopes ? Object.freeze([...options.requiredScopes]) : undefined;
+        this.actualScopes = options.actualScopes ? Object.freeze([...options.actualScopes]) : undefined;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Token lacks required scopes */
+    static insufficientScope(required, actual) {
+        return new AuthorizationError(`Insufficient scope: required [${required.join(", ")}], got [${actual.join(", ")}]`, {
+            requiredScopes: [...required],
+            actualScopes: [...actual],
+            recoveryHint: `Token must include scopes: ${required.join(", ")}`,
+        });
+    }
+    /** Generic forbidden — authenticated but not authorized */
+    static forbidden(reason) {
+        const message = reason ? `Access denied: ${reason}` : "Access denied";
+        return new AuthorizationError(message);
+    }
+}
+//# sourceMappingURL=auth.js.map

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

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

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

@@ -0,0 +1,70 @@
+/**
+ * Connection Error Classes
+ *
+ * Generic connection errors for the MCP framework.
+ * Application-specific connection errors should extend these classes.
+ *
+ * @module errors/categories/connection
+ */
+import { AppError } from "../core/index.js";
+import type { BaseErrorOptions } from "../core/index.js";
+/**
+ * Generic error thrown when connection to an API server fails.
+ *
+ * This is a framework-level error. For application-specific connection errors
+ * with custom messages, extend this class in your app/errors/ module.
+ *
+ * @example
+ * ```typescript
+ * // Framework usage
+ * throw ConnectionError.failed('http://api.example.com');
+ * throw ConnectionError.timeout('http://api.example.com', 5000);
+ *
+ * // App-specific extension
+ * class MyApiConnectionError extends ConnectionError {
+ *   static apiServerDown(url: string): MyApiConnectionError {
+ *     return new MyApiConnectionError(
+ *       `API server at ${url} is not responding`,
+ *       url,
+ *       { recoveryHint: 'Ensure the API server is running.' }
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class ConnectionError extends AppError {
+    /** The target URL/address that connection was attempted to */
+    readonly target: string;
+    constructor(message: string, target: string, options?: Omit<BaseErrorOptions, "code">);
+    /**
+     * Create a ConnectionError for a generic failed connection.
+     */
+    static failed(target: string, reason?: string): ConnectionError;
+    /**
+     * Create a ConnectionError for a refused connection.
+     */
+    static refused(target: string): ConnectionError;
+    /**
+     * Create a ConnectionError for a connection timeout.
+     *
+     * @param target - The target URL/address
+     * @param timeoutMs - Optional timeout duration in milliseconds
+     */
+    static timeout(target: string, timeoutMs?: number): ConnectionError;
+    /**
+     * Create a ConnectionError for connection lost.
+     */
+    static lost(target: string): ConnectionError;
+    /**
+     * Create a ConnectionError for connection reset.
+     */
+    static reset(target: string): ConnectionError;
+    /**
+     * Create a ConnectionError for a failed health check.
+     *
+     * @param reason - The reason the health check failed
+     * @param target - Optional target URL (defaults to 'unknown')
+     */
+    static healthCheckFailed(reason: string, target?: string): ConnectionError;
+}
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,QAAQ,EAA0B,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;IAoBzF;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe;IAS/D;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;IAM/C;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,eAAe;IAWnE;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;IAM5C;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;IAM7C;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAY,GAAG,eAAe;CAM9E"}

package/build/errors/categories/connection.js

@@ -0,0 +1,120 @@
+/**
+ * Connection Error Classes
+ *
+ * Generic connection errors for the MCP framework.
+ * Application-specific connection errors should extend these classes.
+ *
+ * @module errors/categories/connection
+ */
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { AppError, ErrorCodes, HttpStatus } from "../core/index.js";
+// ============================================================================
+// Connection Error
+// ============================================================================
+/**
+ * Generic error thrown when connection to an API server fails.
+ *
+ * This is a framework-level error. For application-specific connection errors
+ * with custom messages, extend this class in your app/errors/ module.
+ *
+ * @example
+ * ```typescript
+ * // Framework usage
+ * throw ConnectionError.failed('http://api.example.com');
+ * throw ConnectionError.timeout('http://api.example.com', 5000);
+ *
+ * // App-specific extension
+ * class MyApiConnectionError extends ConnectionError {
+ *   static apiServerDown(url: string): MyApiConnectionError {
+ *     return new MyApiConnectionError(
+ *       `API server at ${url} is not responding`,
+ *       url,
+ *       { recoveryHint: 'Ensure the API server is running.' }
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export class ConnectionError extends AppError {
+    /** The target URL/address that connection was attempted to */
+    target;
+    constructor(message, target, options = {}) {
+        super(message, {
+            code: ErrorCodes.CONNECTION_ERROR,
+            statusCode: options.statusCode ?? HttpStatus.BAD_GATEWAY,
+            mcpCode: ErrorCode.InternalError,
+            cause: options.cause,
+            recoveryHint: options.recoveryHint,
+            context: {
+                ...options.context,
+                target,
+            },
+        });
+        this.target = target;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a ConnectionError for a generic failed connection.
+     */
+    static failed(target, reason) {
+        const baseMessage = "Failed to connect to server";
+        const message = reason ? `${baseMessage}: ${reason}` : `${baseMessage} to '${target}'`;
+        return new ConnectionError(message, target, {
+            recoveryHint: `Check that the server at '${target}' is running and accessible.`,
+        });
+    }
+    /**
+     * Create a ConnectionError for a refused connection.
+     */
+    static refused(target) {
+        return new ConnectionError("Connection refused", target, {
+            recoveryHint: `Ensure the server is running at '${target}' and accepting connections.`,
+        });
+    }
+    /**
+     * Create a ConnectionError for a connection timeout.
+     *
+     * @param target - The target URL/address
+     * @param timeoutMs - Optional timeout duration in milliseconds
+     */
+    static timeout(target, timeoutMs) {
+        const baseMessage = "Connection timed out";
+        const message = timeoutMs ? `${baseMessage} (after ${timeoutMs}ms)` : baseMessage;
+        return new ConnectionError(message, target, {
+            statusCode: HttpStatus.GATEWAY_TIMEOUT,
+            recoveryHint: `Connection to '${target}' timed out. Check network connectivity.`,
+            context: timeoutMs ? { timeoutMs } : undefined,
+        });
+    }
+    /**
+     * Create a ConnectionError for connection lost.
+     */
+    static lost(target) {
+        return new ConnectionError("Connection lost", target, {
+            recoveryHint: `The connection to '${target}' was lost. Reconnecting may help.`,
+        });
+    }
+    /**
+     * Create a ConnectionError for connection reset.
+     */
+    static reset(target) {
+        return new ConnectionError("Connection was reset", target, {
+            recoveryHint: `The connection to '${target}' was reset by the server. Try again.`,
+        });
+    }
+    /**
+     * Create a ConnectionError for a failed health check.
+     *
+     * @param reason - The reason the health check failed
+     * @param target - Optional target URL (defaults to 'unknown')
+     */
+    static healthCheckFailed(reason, target = "unknown") {
+        return new ConnectionError(`Health check failed: ${reason}`, target, {
+            recoveryHint: "The server is reachable but not healthy. Check server logs for details.",
+            context: { reason },
+        });
+    }
+}
+//# sourceMappingURL=connection.js.map

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * Error Categories Barrel Export
+ *
+ * @module errors/categories
+ */
+export { McpProtocolError } from "./protocol.js";
+export { SessionError } from "./session.js";
+export { TransportError } from "./transport.js";
+export { ValidationError, ConfigurationError } from "./validation.js";
+export { InternalError, RegistryError } from "./system.js";
+export { OperationError, OperationCancelledError } from "./operation.js";
+export { ConnectionError } from "./connection.js";
+export { AuthenticationError, AuthorizationError } from "./auth.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGtE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC"}

package/build/errors/categories/index.js

@@ -0,0 +1,20 @@
+/**
+ * Error Categories Barrel Export
+ *
+ * @module errors/categories
+ */
+// MCP Protocol Errors (split from former mcp.ts)
+export { McpProtocolError } from "./protocol.js";
+export { SessionError } from "./session.js";
+export { TransportError } from "./transport.js";
+// Validation Errors
+export { ValidationError, ConfigurationError } from "./validation.js";
+// System Errors
+export { InternalError, RegistryError } from "./system.js";
+// Operation Errors
+export { OperationError, OperationCancelledError } from "./operation.js";
+// Connection Errors
+export { ConnectionError } from "./connection.js";
+// Auth Errors
+export { AuthenticationError, AuthorizationError } from "./auth.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/errors/categories/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iDAAiD;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEtE,gBAAgB;AAChB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3D,mBAAmB;AACnB,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,cAAc;AACd,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC"}