# All files / src/tools/shared errors.ts

100% Statements 13/13
100% Branches 10/10
100% Functions 1/1
100% Lines 13/13

Press n or j to go to the next uncovered block, b, p or k for the previous block.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77

    330x
    330x
    330x
    330x
    330x
    330x
    31x

    330x
    11x

    330x
    16x

    330x
    275x

     /**
     * Structured error class for MCP tool error reporting.
     *
     * ISMS Policy: SC-002 (Input Validation), AC-003 (Least Privilege), AU-002 (Audit Logging)
     */

    /**
     * Machine-readable error codes for MCP tool error categorization.
     * Enables programmatic retry/skip/fallback logic by clients.
     */
    export type ErrorCode =
      | 'UPSTREAM_404'
      | 'UPSTREAM_500'
      | 'UPSTREAM_503'
      | 'UPSTREAM_TIMEOUT'
      | 'RATE_LIMITED'
      | 'INVALID_PARAMS'
      | 'FEED_FALLBACK'
      | 'UNKNOWN_TOOL'
      | 'INTERNAL_ERROR';

    /**
     * High-level error categories for client-side retry/skip decisions.
     */
    export type ErrorCategory =
      | 'DATA_UNAVAILABLE'
      | 'SERVER_ERROR'
      | 'TIMEOUT'
      | 'RATE_LIMIT'
      | 'CLIENT_ERROR'
      | 'DATA_QUALITY'
      | 'INTERNAL';

    /**
     * Structured error class that all MCP tools use for consistent error reporting.
     * Ensures tool name, operation, and safe context are always included without
     * leaking internal implementation details to clients.
     */
    export class ToolError extends Error {
      readonly toolName: string;
      readonly operation: string;
      readonly isRetryable: boolean;
      readonly errorCode?: ErrorCode;
      readonly errorCategory?: ErrorCategory;
      readonly httpStatus?: number;
      override readonly cause?: Error;

      constructor(options: {
        toolName: string;
        operation: string;
        message: string;
        isRetryable?: boolean;
        cause?: unknown;
        errorCode?: ErrorCode;
        errorCategory?: ErrorCategory;
        httpStatus?: number;
      }) {
        super(`[${options.toolName}] ${options.operation}: ${options.message}`);
        this.name = 'ToolError';
        this.toolName = options.toolName;
        this.operation = options.operation;
        this.isRetryable = options.isRetryable ?? false;
        if (options.errorCode !== undefined) {
          this.errorCode = options.errorCode;
        }
        if (options.errorCategory !== undefined) {
          this.errorCategory = options.errorCategory;
        }
        if (options.httpStatus !== undefined) {
          this.httpStatus = options.httpStatus;
        }
        if (options.cause instanceof Error) {
          this.cause = options.cause;
        }
      }
    }