ExMCP.Client.Error (ex_mcp v0.10.0)

View Source

Enhanced error formatting and actionable guidance for MCP.

This module transforms low-level MCP protocol errors into developer-friendly error messages with actionable guidance and debugging context.

Features

  • Human-readable error descriptions
  • Actionable troubleshooting steps
  • Context preservation for debugging
  • Error categorization and severity levels
  • Common error pattern recognition

Error Categories

  • Connection: Transport and connectivity issues
  • Protocol: MCP protocol violations or mismatches
  • Authentication: Auth and permission problems
  • Resource: Tool/resource/prompt related errors
  • Timeout: Request timeout and performance issues
  • Validation: Input validation and schema errors

Summary

Types

error_category()
error_severity()
formatted_error()

Functions

format(error_type, reason, context \\ %{})

Formats an error with enhanced context and actionable guidance.

format_suggestions(suggestions)

Formats suggestions as a readable list.

get_suggestions(map)

Gets troubleshooting suggestions for an error.

summarize(map)

Creates a user-friendly error summary for display.

Types

error_category()

@type error_category() ::
  :connection
  | :protocol
  | :authentication
  | :resource
  | :timeout
  | :validation
  | :internal
  | :unknown

error_severity()

@type error_severity() :: :low | :medium | :high | :critical

formatted_error()

@type formatted_error() :: %{
  type: atom(),
  category: error_category(),
  severity: error_severity(),
  message: String.t(),
  details: String.t() | nil,
  suggestions: [String.t()],
  context: map(),
  original_error: any()
}

Functions

format(error_type, reason, context \\ %{})

@spec format(atom(), any(), map()) :: formatted_error()

Formats an error with enhanced context and actionable guidance.

Examples

Error.format(:tool_call_failed, :timeout, %{tool: "slow_tool", args: %{}})
# => %{
#   type: :tool_call_failed,
#   category: :timeout,
#   severity: :medium,
#   message: "Tool call to 'slow_tool' timed out",
#   suggestions: ["Increase timeout value", "Check tool performance"],
#   context: %{tool: "slow_tool", args: %{}}
# }

format_suggestions(suggestions)

@spec format_suggestions([String.t()]) :: String.t()

Formats suggestions as a readable list.

get_suggestions(map)

@spec get_suggestions(formatted_error()) :: [String.t()]

Gets troubleshooting suggestions for an error.

summarize(map)

@spec summarize(formatted_error()) :: String.t()

Creates a user-friendly error summary for display.