Hermes.MCP.Error (hermes_mcp v0.3.12)

Represents errors in the MCP protocol.

This module defines standardized error types based on the JSON-RPC 2.0 error codes, with additional MCP-specific error reasons.

Error Structure

Each error includes:

  • code: Numeric error code (following JSON-RPC 2.0 conventions)
  • reason: Atom representing the error type (e.g., :parse_error, :timeout)
  • data: Additional context or metadata about the error

Error Categories

Errors are categorized into:

  • Standard JSON-RPC errors (parse errors, invalid requests, etc.)
  • Transport errors (connection issues, timeouts)
  • Client errors (request handling issues)
  • Server errors (capability issues, domain errors)

Examples

# Creating standard RPC errors
Hermes.MCP.Error.parse_error()

# Creating transport errors
Hermes.MCP.Error.transport_error(:connection_refused)

# Creating client errors
Hermes.MCP.Error.client_error(:request_timeout, %{elapsed_ms: 30000})

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

Summary

Functions

Creates a client-related error.

Creates a domain-level error from an MCP server response.

Converts from a JSON-RPC error object to a Hermes.MCP.Error struct.

Creates an internal error.

Creates an invalid params error.

Creates an invalid request error.

Creates a method not found error.

Creates a parse error.

Converts an MCP error to a tuple of the form {:error, error}.

Creates a transport-related error.

Types

t()

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

Functions

client_error(reason, data \\ %{})

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

Creates a client-related error.

Used for errors that occur within the client implementation.

Parameters

  • reason - Atom representing the specific client error
  • data - Additional error context or metadata

Examples

iex> Hermes.MCP.Error.client_error(:request_timeout, %{elapsed_ms: 30000})
%Hermes.MCP.Error{code: -32000, reason: :request_timeout, data: %{type: :client, elapsed_ms: 30000}}

domain_error(data)

@spec domain_error(map()) :: t()

Creates a domain-level error from an MCP server response.

Used for application-level errors returned as valid JSON-RPC responses with isError: true.

Examples

iex> Hermes.MCP.Error.domain_error(%{"message" => "Resource not found"})
%Hermes.MCP.Error{code: -32000, reason: :domain_error, data: %{"message" => "Resource not found"}}

from_json_rpc(error)

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

Converts from a JSON-RPC error object to a Hermes.MCP.Error struct.

Parameters

  • error - A map containing the JSON-RPC error fields

Examples

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

internal_error(data \\ %{})

@spec internal_error(map()) :: t()

Creates an internal error.

Used when an internal server error occurs.

Examples

iex> Hermes.MCP.Error.internal_error()
%Hermes.MCP.Error{code: -32603, reason: :internal_error, data: %{}}

invalid_params(data \\ %{})

@spec invalid_params(map()) :: t()

Creates an invalid params error.

Used when the parameters provided are invalid for the requested method.

Examples

iex> Hermes.MCP.Error.invalid_params(%{param: "name"})
%Hermes.MCP.Error{code: -32602, reason: :invalid_params, data: %{param: "name"}}

invalid_request(data \\ %{})

@spec invalid_request(map()) :: t()

Creates an invalid request error.

Used when the JSON sent is not a valid request object.

Examples

iex> Hermes.MCP.Error.invalid_request()
%Hermes.MCP.Error{code: -32600, reason: :invalid_request, data: %{}}

method_not_found(data \\ %{})

@spec method_not_found(map()) :: t()

Creates a method not found error.

Used when the requested method does not exist or is not available.

Examples

iex> Hermes.MCP.Error.method_not_found(%{method: "unknown_method"})
%Hermes.MCP.Error{code: -32601, reason: :method_not_found, data: %{method: "unknown_method"}}

parse_error(data \\ %{})

@spec parse_error(map()) :: t()

Creates a parse error.

Used when the server is unable to parse the JSON received.

Examples

iex> Hermes.MCP.Error.parse_error()
%Hermes.MCP.Error{code: -32700, reason: :parse_error, data: %{}}

to_tuple(error)

@spec to_tuple(t()) :: {:error, t()}

Converts an MCP error to a tuple of the form {:error, error}.

This is useful for returning errors in functions that follow the {:ok, result} | {:error, reason} pattern.

Examples

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

transport_error(reason, data \\ %{})

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

Creates a transport-related error.

Used for communication/network errors between client and server.

Parameters

  • reason - Atom representing the specific transport error
  • data - Additional error context or metadata

Examples

iex> Hermes.MCP.Error.transport_error(:connection_refused)
%Hermes.MCP.Error{code: -32000, reason: :connection_refused, data: %{type: :transport}}