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
Functions
Creates a client-related error.
Used for errors that occur within the client implementation.
Parameters
reason
- Atom representing the specific client errordata
- 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}}
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"}}
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"}}
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: %{}}
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"}}
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: %{}}
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"}}
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: %{}}
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: %{}}}
Creates a transport-related error.
Used for communication/network errors between client and server.
Parameters
reason
- Atom representing the specific transport errordata
- 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}}