Hermes.MCP.Error (hermes_mcp v0.10.0)

Fluent API for building MCP protocol errors.

This module provides a semantic interface for creating errors that comply with the MCP specification and JSON-RPC 2.0 error standards.

Error Categories

Protocol Errors: Standard JSON-RPC errors (parse, invalid request, etc.)
Transport Errors: Connection and communication issues
Resource Errors: MCP-specific resource handling errors
Execution Errors: Tool and operation execution failures

Examples

# Protocol errors
Hermes.MCP.Error.protocol(:parse_error)
Hermes.MCP.Error.protocol(:method_not_found, %{method: "unknown"})

# Transport errors
Hermes.MCP.Error.transport(:connection_refused)
Hermes.MCP.Error.transport(:timeout, %{elapsed_ms: 30000})

# Resource errors
Hermes.MCP.Error.resource(:not_found, %{uri: "file:///missing.txt"})

# Execution errors with custom messages
Hermes.MCP.Error.execution("Database connection failed", %{retries: 3})

# Converting from JSON-RPC
Hermes.MCP.Error.from_json_rpc(%{"code" => -32700, "message" => "Parse error"})

Summary

Types

t()

Functions

build_json_rpc(error, id \\ ID.generate_error_id())

execution(message, data \\ %{})

Creates an execution error with a custom message.

from_json_rpc(error)

Creates an error from a JSON-RPC error object.

protocol(reason, data \\ %{})

Creates a protocol-level error.

resource(atom, data \\ %{})

Creates a resource-specific error.

to_json_rpc(error, id \\ ID.generate_error_id())

Encodes the error as a JSON-RPC error response.

transport(reason, data \\ %{})

Creates a transport-level error.

Types

t()

@type t() :: %Hermes.MCP.Error{
  code: integer(),
  data: map(),
  message: String.t() | nil,
  reason: atom()
}

Functions

build_json_rpc(error, id \\ ID.generate_error_id())

execution(message, data \\ %{})

@spec execution(String.t(), map()) :: t()

Creates an execution error with a custom message.

Used for tool execution failures and domain-specific errors.

Examples

iex> Hermes.MCP.Error.execution("Database connection failed")
%Hermes.MCP.Error{code: -32000, reason: :execution_error, message: "Database connection failed", data: %{}}

iex> Hermes.MCP.Error.execution("API rate limit exceeded", %{retry_after: 60})
%Hermes.MCP.Error{code: -32000, reason: :execution_error, message: "API rate limit exceeded", data: %{retry_after: 60}}

from_json_rpc(error)

@spec from_json_rpc(map()) :: t()

Creates an error from a JSON-RPC error object.

Examples

iex> Hermes.MCP.Error.from_json_rpc(%{"code" => -32700, "message" => "Parse error"})
%Hermes.MCP.Error{code: -32700, reason: :parse_error, message: "Parse error", data: %{}}

iex> Hermes.MCP.Error.from_json_rpc(%{"code" => -32002, "message" => "Not found", "data" => %{"uri" => "/file"}})
%Hermes.MCP.Error{code: -32002, reason: :resource_not_found, message: "Not found", data: %{"uri" => "/file"}}

protocol(reason, data \\ %{})

@spec protocol(atom(), map()) :: t()

Creates a protocol-level error.

These are standard JSON-RPC errors that occur during message parsing and validation.

Supported Reasons

:parse_error - Invalid JSON was received
:invalid_request - The JSON is not a valid Request object
:method_not_found - The method does not exist
:invalid_params - Invalid method parameters
:internal_error - Internal JSON-RPC error

Examples

iex> Hermes.MCP.Error.protocol(:parse_error)
%Hermes.MCP.Error{code: -32700, reason: :parse_error, message: "Parse error", data: %{}}

iex> Hermes.MCP.Error.protocol(:method_not_found, %{method: "foo"})
%Hermes.MCP.Error{code: -32601, reason: :method_not_found, message: "Method not found", data: %{method: "foo"}}

resource(atom, data \\ %{})

@spec resource(atom(), map()) :: t()

Creates a resource-specific error.

Used for MCP resource operations.

Examples

iex> Hermes.MCP.Error.resource(:not_found, %{uri: "file:///missing.txt"})
%Hermes.MCP.Error{code: -32002, reason: :resource_not_found, message: "Resource not found", data: %{uri: "file:///missing.txt"}}

to_json_rpc(error, id \\ ID.generate_error_id())

@spec to_json_rpc(t(), String.t() | integer()) :: {:ok, String.t()} | {:error, term()}

Encodes the error as a JSON-RPC error response.

Examples

iex> error = Hermes.MCP.Error.protocol(:parse_error)
iex> {:ok, encoded} = Hermes.MCP.Error.to_json_rpc(error, "req-123")
iex> String.contains?(encoded, "Parse error")
true

transport(reason, data \\ %{})

@spec transport(atom(), map()) :: t()

Creates a transport-level error.

Used for network, connection, and communication failures.

Examples

iex> Hermes.MCP.Error.transport(:connection_refused)
%Hermes.MCP.Error{code: -32000, reason: :connection_refused, message: "Connection Refused", data: %{}}

iex> Hermes.MCP.Error.transport(:timeout, %{elapsed_ms: 5000})
%Hermes.MCP.Error{code: -32000, reason: :timeout, message: "Timeout", data: %{elapsed_ms: 5000}}