@spec call_tool(client(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Calls a tool with the given arguments.

Parameters

• client - The MCP client
• name - Tool name
• arguments - Tool arguments map
• opts - Options:
  • :timeout - Request timeout override

Returns

• {:ok, %{content: [...], isError: false}} - Success (atom keys)
• {:ok, %{content: [...], isError: true}} - Tool error
• {:error, reason} - Protocol error

Examples

{:ok, result} = Hermolaos.call_tool(client, "read_file", %{"path" => "/tmp/test.txt"})

case result do
  %{isError: false, content: content} ->
    for item <- content do
      case item do
        %{type: "text", text: text} -> IO.puts(text)
        %{type: "image", data: data} -> File.write!("image.png", Base.decode64!(data))
      end
    end

  %{isError: true, content: content} ->
    IO.puts("Tool error: #{inspect(content)}")
end

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

Sends a cancellation notification for a pending request.

Examples

:ok = Hermolaos.cancel(client, request_id)

@spec complete(client(), map(), map(), keyword()) :: {:ok, map()} | {:error, term()}

Requests argument completion suggestions.

Parameters

• client - The MCP client
• ref - Reference object (prompt or resource)
• argument - Argument to complete

Examples

ref = %{"type" => "ref/prompt", "name" => "code_review"}
argument = %{"name" => "language", "value" => "eli"}
{:ok, completions} = Hermolaos.complete(client, ref, argument)

@spec connect(
  transport(),
  keyword()
) :: {:ok, client()} | {:error, term()}

Connects to an MCP server.

Parameters

• transport - Either :stdio or :http
• opts - Transport-specific options

Stdio Options

• :command - Command to execute (required)
• :args - Command arguments (default: [])
• :env - Environment variables as [{name, value}] (default: [])
• :cd - Working directory (optional)

HTTP Options

• :url - Server endpoint URL (required)
• :headers - Additional HTTP headers (default: [])
• :req_options - Options passed to Req (default: [])

Common Options

• :client_info - Client identification map (default: Hermolaos info)
• :capabilities - Client capabilities (default: standard)
• :notification_handler - Module or {module, state} for notifications
• :timeout - Default request timeout in ms (default: 30000)
• :name - GenServer name (optional)

Examples

# Stdio with npx
{:ok, client} = Hermolaos.connect(:stdio,
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
)

# HTTP with authentication
{:ok, client} = Hermolaos.connect(:http,
  url: "https://api.example.com/mcp",
  headers: [{"authorization", "Bearer token123"}]
)

# Named connection
{:ok, _} = Hermolaos.connect(:stdio,
  command: "my-server",
  name: MyApp.MCPClient
)
# Later: Hermolaos.list_tools(MyApp.MCPClient)

@spec disconnect(client()) :: :ok

Disconnects from the MCP server.

This gracefully closes the connection, cleaning up resources.

Examples

:ok = Hermolaos.disconnect(client)

@spec get_image(map()) :: {:ok, binary()} | :error

Extracts image data from a tool call result.

Returns the base64-decoded binary image data.

Examples

{:ok, result} = Hermolaos.call_tool(client, "browser_take_screenshot", %{})
case Hermolaos.get_image(result) do
  {:ok, image_data} -> File.write!("screenshot.png", image_data)
  :error -> IO.puts("No image in response")
end

@spec get_images(map()) :: [binary()]

Extracts all images from a tool call result.

Returns a list of base64-decoded binary image data.

Examples

{:ok, result} = Hermolaos.call_tool(client, "get_images", %{})
images = Hermolaos.get_images(result)
Enum.with_index(images, fn data, i ->
  File.write!("image_#{i}.png", data)
end)

@spec get_prompt(client(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Gets a prompt by name, optionally with argument values.

Parameters

• client - The MCP client
• name - Prompt name
• arguments - Argument values map (default: %{})
• opts - Options

Examples

{:ok, prompt} = Hermolaos.get_prompt(client, "code_review")
{:ok, prompt} = Hermolaos.get_prompt(client, "summarize", %{"language" => "elixir"})

@spec get_text(map()) :: String.t() | nil

Extracts text content from a tool call result.

Tool results contain a list of content items. This helper extracts all text items and concatenates them.

Examples

{:ok, result} = Hermolaos.call_tool(client, "browser_snapshot", %{})
text = Hermolaos.get_text(result)

@spec list_prompts(
  client(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Lists available prompts on the server.

Options

• :cursor - Pagination cursor
• :timeout - Request timeout override

Examples

{:ok, %{prompts: prompts}} = Hermolaos.list_prompts(client)

@spec list_resource_templates(
  client(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Lists resource templates on the server.

Options

• :cursor - Pagination cursor
• :timeout - Request timeout override

Examples

{:ok, %{resourceTemplates: templates}} = Hermolaos.list_resource_templates(client)

@spec list_resources(
  client(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Lists available resources on the server.

Options

• :cursor - Pagination cursor
• :timeout - Request timeout override

Examples

{:ok, %{resources: resources}} = Hermolaos.list_resources(client)

@spec list_tools(
  client(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Lists available tools on the server.

Options

• :cursor - Pagination cursor for subsequent requests
• :timeout - Request timeout override

Returns

• {:ok, %{tools: [...], nextCursor: ...}} - Success (atom keys)
• {:error, reason} - Error

Examples

{:ok, %{tools: tools}} = Hermolaos.list_tools(client)
for tool <- tools do
  IO.puts("Tool: #{tool.name} - #{tool.description}")
end

@spec ping(
  client(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Sends a ping to check server liveness.

Examples

{:ok, %{}} = Hermolaos.ping(client)

@spec read_resource(client(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Reads a resource by URI.

Parameters

• client - The MCP client
• uri - Resource URI
• opts - Options

Returns

• {:ok, %{contents: [...]}} - Success (atom keys)

Examples

{:ok, %{contents: contents}} = Hermolaos.read_resource(client, "file:///project/README.md")
for content <- contents do
  IO.puts(content.text)
end

@spec server_capabilities(client()) :: {:ok, map()} | {:error, :not_initialized}

Gets server capabilities from the initialization response.

Examples

{:ok, caps} = Hermolaos.server_capabilities(client)
if Hermolaos.Protocol.Capabilities.supports?(caps, :tools) do
  # Server supports tools
end

@spec server_info(client()) :: {:ok, map()} | {:error, :not_initialized}

Gets server information from the initialization response.

Examples

{:ok, %{"name" => "MyServer", "version" => "1.0.0"}} = Hermolaos.server_info(client)

@spec set_log_level(client(), String.t()) :: {:ok, map()} | {:error, term()}

Sets the server's logging level.

Parameters

• client - The MCP client
• level - Log level (debug, info, notice, warning, error, critical, alert, emergency)

Examples

{:ok, _} = Hermolaos.set_log_level(client, "debug")

@spec status(client()) :: Hermolaos.Client.Connection.status()

Gets the current connection status.

Returns

• :disconnected - Not connected
• :connecting - Transport starting
• :initializing - MCP handshake in progress
• :ready - Ready for requests

Examples

:ready = Hermolaos.status(client)

@spec subscribe_resource(client(), String.t()) :: {:ok, map()} | {:error, term()}

Subscribes to resource updates.

Requires server to support resource subscriptions.

Examples

:ok = Hermolaos.subscribe_resource(client, "file:///project/src/main.rs")

@spec unsubscribe_resource(client(), String.t()) :: {:ok, map()} | {:error, term()}

Unsubscribes from resource updates.

Examples

:ok = Hermolaos.unsubscribe_resource(client, "file:///project/src/main.rs")