Hermes.MCP.Response (hermes_mcp v0.10.0)

Represents successful responses in the MCP protocol.

This module provides a wrapper around JSON-RPC responses, handling domain-specific error semantics for MCP's "isError" field in results.

Response Structure

Each response includes:

  • result: The response data from the server
  • id: The request ID this response is associated with
  • is_error: Boolean flag indicating if this is a domain-level error

Domain vs. Protocol Errors

The MCP protocol distinguishes between two types of errors:

  1. Protocol errors: Standard JSON-RPC errors with error codes (handled by Hermes.MCP.Error)
  2. Domain errors: Valid responses that indicate application-level errors with isError: true

This module specifically handles domain errors, which are successful at the protocol level but indicate failures at the application level.

Examples

# Create from a JSON-RPC response
response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"data" => "value"}, "id" => "req_123"})

# Check if the response is successful or has a domain error
if Hermes.MCP.Response.success?(response) do
  # Handle success
else
  # Handle domain error
end

# Unwrap the response to get the result or error
case Hermes.MCP.Response.unwrap(response) do
  {:ok, result} -> # Handle success
  {:error, error} -> # Handle domain error
end

Summary

Types

t()

Functions

error?(arg1)

Checks if the response has a domain error.

from_json_rpc(map)

Creates a Response struct from a JSON-RPC response.

get_id(response)

Gets the request ID associated with this response.

get_result(response)

Gets the result data from the response.

success?(arg1)

Checks if the response is successful (no domain error).

unwrap(response)

Unwraps the response, returning the raw result.

Types

t()

@type t() :: %Hermes.MCP.Response{
  id: String.t(),
  is_error: boolean(),
  method: String.t() | nil,
  result: map()
}

Functions

error?(arg1)

@spec error?(t()) :: boolean()

Checks if the response has a domain error.

Examples

iex> response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"data" => "value"}, "id" => "req_123"})
iex> Hermes.MCP.Response.error?(response)
false

iex> error_response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"isError" => true}, "id" => "req_123"})
iex> Hermes.MCP.Response.error?(error_response)
true

from_json_rpc(map)

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

Creates a Response struct from a JSON-RPC response.

Automatically detects domain errors by checking for the "isError" field.

Parameters

  • response - A map containing the JSON-RPC response

Examples

iex> Hermes.MCP.Response.from_json_rpc(%{"result" => %{}, "id" => "req_123"})
%Hermes.MCP.Response{result: %{}, id: "req_123", is_error: false}

iex> Hermes.MCP.Response.from_json_rpc(%{"result" => %{"isError" => true}, "id" => "req_123"})
%Hermes.MCP.Response{result: %{"isError" => true}, id: "req_123", is_error: true}

get_id(response)

@spec get_id(t()) :: String.t()

Gets the request ID associated with this response.

Examples

iex> response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{}, "id" => "req_123"})
iex> Hermes.MCP.Response.get_id(response)
"req_123"

get_result(response)

@spec get_result(t()) :: map()

Gets the result data from the response.

This function returns the raw result regardless of whether it represents a success or domain error.

Examples

iex> response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"data" => "value"}, "id" => "req_123"})
iex> Hermes.MCP.Response.get_result(response)
%{"data" => "value"}

success?(arg1)

@spec success?(t()) :: boolean()

Checks if the response is successful (no domain error).

Examples

iex> response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"data" => "value"}, "id" => "req_123"})
iex> Hermes.MCP.Response.success?(response)
true

iex> error_response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"isError" => true}, "id" => "req_123"})
iex> Hermes.MCP.Response.success?(error_response)
false

unwrap(response)

@spec unwrap(t()) :: map()

Unwraps the response, returning the raw result.

Returns the raw result data regardless of whether it represents a success or domain error.

Examples

iex> response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"data" => "value"}, "id" => "req_123"})
iex> Hermes.MCP.Response.unwrap(response)
%{"data" => "value"}

iex> error_response = Hermes.MCP.Response.from_json_rpc(%{"result" => %{"isError" => true, "reason" => "not_found"}, "id" => "req_123"})
iex> Hermes.MCP.Response.unwrap(error_response)
%{"isError" => true, "reason" => "not_found"}