Hermes.Server.Response (hermes_mcp v0.10.0)

Fluent interface for building MCP component responses.

This module provides builders for tool, prompt, and resource responses that integrate seamlessly with the component system.

Examples

# Tool response
Response.tool()
|> Response.text("Result: " <> result)
|> Response.build()

# Resource response (uri and mime_type come from component)
Response.resource()
|> Response.text(file_contents)
|> Response.build()

# Prompt response
Response.prompt()
|> Response.user_message("What is the weather?")
|> Response.assistant_message("Let me check...")
|> Response.build()

Summary

Types

t()

Functions

assistant_message(r, content)

Add an assistant message to a prompt response.

audio(r, data, mime_type, opts \\ [])

Add audio content to a tool response.

blob(r, data)

Set blob (base64) content for a resource response.

description(r, desc)

Set optional description for a resource response.

embedded_resource(r, uri, opts \\ [])

Add an embedded resource reference to a tool response.

error(r, message)

Mark a tool response as an error and add error message.

image(r, data, mime_type)

Add image content to a tool response.

json(r, data)

Add JSON-encoded content to a tool response.

name(r, name)

Set optional name for a resource response.

prompt(description \\ nil)

Start building a prompt response with optional description.

resource()

Start building a resource response.

system_message(r, content)

Add a system message to a prompt response.

text(r, text)

Add text content to a tool or resource response.

to_protocol(r)

Build the final response structure.

to_protocol(r, uri, mime_type)

tool()

Start building a tool response.

user_message(r, content)

Add a user message to a prompt response.

Types

t()

@type t() :: %Hermes.Server.Response{
  content: [map()],
  contents: [map()] | nil,
  isError: boolean(),
  messages: [map()],
  metadata: map(),
  type: :tool | :prompt | :resource
}

Functions

assistant_message(r, content)

Add an assistant message to a prompt response.

Parameters

response - A prompt response struct
content - The message content (string or structured content)

Examples

iex> Response.prompt() |> Response.assistant_message("Let me check the weather for you.")
%Response{
  type: :prompt,
  messages: [%{"role" => "assistant", "content" => "Let me check the weather for you."}]
}

audio(r, data, mime_type, opts \\ [])

Add audio content to a tool response.

Parameters

response - A tool response struct
data - Base64 encoded audio data
mime_type - MIME type of the audio (e.g., "audio/wav")
opts - Optional keyword list with:
- :transcription - Optional text transcription of the audio

Examples

iex> Response.tool() |> Response.audio(audio_data, "audio/wav")
%Response{
  type: :tool,
  content: [%{"type" => "audio", "data" => audio_data, "mimeType" => "audio/wav"}],
  isError: false
}

iex> Response.tool() |> Response.audio(audio_data, "audio/wav", transcription: "Hello")
%Response{
  type: :tool,
  content: [%{
    "type" => "audio",
    "data" => audio_data,
    "mimeType" => "audio/wav",
    "transcription" => "Hello"
  }],
  isError: false
}

blob(r, data)

Set blob (base64) content for a resource response.

Parameters

response - A resource response struct
data - Base64 encoded binary data

Examples

iex> Response.resource() |> Response.blob(base64_data)
%Response{type: :resource, contents: %{"blob" => base64_data}}

description(r, desc)

Set optional description for a resource response.

Parameters

response - A resource response struct
desc - Description of the resource

Examples

iex> Response.resource() |> Response.description("Application configuration settings")
%Response{type: :resource, metadata: %{description: "Application configuration settings"}}

embedded_resource(r, uri, opts \\ [])

Add an embedded resource reference to a tool response.

Parameters

response - A tool response struct
uri - The resource URI
opts - Optional keyword list with:
- :name - Human-readable name
- :description - Resource description
- :mime_type - MIME type
- :text - Text content (for text resources)
- :blob - Base64 data (for binary resources)

Examples

iex> Response.tool() |> Response.embedded_resource("file://example.txt",
...>   name: "Example File",
...>   mime_type: "text/plain",
...>   text: "File contents"
...> )

error(r, message)

Mark a tool response as an error and add error message.

Parameters

response - A tool response struct
message - The error message

Examples

iex> Response.tool() |> Response.error("Division by zero")
%Response{
  type: :tool,
  content: [%{"type" => "text", "text" => "Error: Division by zero"}],
  isError: true
}

image(r, data, mime_type)

Add image content to a tool response.

Parameters

response - A tool response struct
data - Base64 encoded image data
mime_type - MIME type of the image (e.g., "image/png")

Examples

iex> Response.tool() |> Response.image(base64_data, "image/png")
%Response{
  type: :tool,
  content: [%{"type" => "image", "data" => base64_data, "mimeType" => "image/png"}],
  isError: false
}

json(r, data)

Add JSON-encoded content to a tool response.

This is a convenience function that automatically encodes data as JSON and adds it as text content. Useful for returning structured data from tools.

Parameters

response - A tool response struct
data - Any JSON-encodable data structure

Examples

iex> Response.tool() |> Response.json(%{status: "ok", count: 42})
%Response{
  type: :tool,
  content: [%{"type" => "text", "text" => "{\"status\":\"ok\",\"count\":42}"}],
  isError: false
}

iex> Response.tool() |> Response.json([1, 2, 3])
%Response{
  type: :tool,
  content: [%{"type" => "text", "text" => "[1,2,3]"}],
  isError: false
}

name(r, name)

Set optional name for a resource response.

Parameters

response - A resource response struct
name - Human-readable name for the resource

Examples

iex> Response.resource() |> Response.name("Configuration File")
%Response{type: :resource, metadata: %{name: "Configuration File"}}

prompt(description \\ nil)

Start building a prompt response with optional description.

Parameters

description - Optional description of the prompt

Examples

iex> Response.prompt()
%Response{type: :prompt, messages: []}

iex> Response.prompt("Weather assistant prompt")
%Response{type: :prompt, messages: [], description: "Weather assistant prompt"}

resource()

Start building a resource response.

The uri and mimeType are automatically injected from the component's uri/0 and mime_type/0 callbacks when the response is built by the server.

Examples

iex> Response.resource()
%Response{type: :resource, contents: nil}

system_message(r, content)

Add a system message to a prompt response.

Parameters

response - A prompt response struct
content - The message content (string or structured content)

Examples

iex> Response.prompt() |> Response.system_message("You are a helpful weather assistant.")
%Response{
  type: :prompt,
  messages: [%{"role" => "system", "content" => "You are a helpful weather assistant."}]
}

text(r, text)

Add text content to a tool or resource response.

For tool responses, adds text to the content array. For resource responses, sets the text content.

Parameters

response - A tool or resource response struct
text - The text content

Examples

iex> Response.tool() |> Response.text("Hello world")
%Response{
  type: :tool,
  content: [%{"type" => "text", "text" => "Hello world"}],
  isError: false
}

iex> Response.resource() |> Response.text("File contents")
%Response{type: :resource, contents: %{"text" => "File contents"}}

to_protocol(r)

Build the final response structure.

Transforms the response struct into the appropriate format for the MCP protocol.

Parameters

response - A response struct of any type

Examples

iex> Response.tool() |> Response.text("Hello") |> Response.to_protocol()
%{"content" => [%{"type" => "text", "text" => "Hello"}], "isError" => false}

iex> Response.prompt() |> Response.user_message("Hi") |> Response.to_protocol()
%{"messages" => [%{"role" => "user", "content" => "Hi"}]}

iex> Response.resource() |> Response.text("data") |> Response.to_protocol()
%{"text" => "data"}

to_protocol(r, uri, mime_type)

tool()

Start building a tool response.

Examples

iex> Response.tool()
%Response{type: :tool, content: [], isError: false}

user_message(r, content)

Add a user message to a prompt response.

Parameters

response - A prompt response struct
content - The message content (string or structured content)

Examples

iex> Response.prompt() |> Response.user_message("What's the weather?")
%Response{
  type: :prompt,
  messages: [%{"role" => "user", "content" => "What's the weather?"}]
}