Hermes.Client (hermes_mcp v0.3.3)

A GenServer implementation of an MCP (Model Context Protocol) client.

This module handles the client-side implementation of the MCP protocol, including initialization, request/response handling, and maintaining protocol state.

Examples

# Start a client process
{:ok, client} = Hermes.Client.start_link(
  name: MyApp.MCPClient,
  transport: Hermes.Transport.STDIO,
  client_info: %{"name" => "MyApp", "version" => "1.0.0"},
  capabilities: %{"resources" => %{}, "tools" => %{}}
)

# List available resources
{:ok, resources} = Hermes.Client.list_resources(client)

Notes

The initial client <> server handshake is performed automatically when the client is started.

Summary

Types

log_callback()

option()

progress_callback()

Functions

call_tool(client, name, arguments \\ nil, opts \\ [])

Calls a tool on the server.

cancel_all_requests(client, reason \\ "client_cancelled")

Cancels all pending requests.

cancel_request(client, request_id, reason \\ "client_cancelled")

Cancels an in-progress request.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

close(client)

Closes the client connection and terminates the process.

get_prompt(client, name, arguments \\ nil, opts \\ [])

Gets a specific prompt from the server.

get_schema(atom)

get_server_capabilities(client)

Gets the server's capabilities as reported during initialization.

get_server_info(client)

Gets the server's information as reported during initialization.

list_prompts(client, opts \\ [])

Lists available prompts from the server.

list_resources(client, opts \\ [])

Lists available resources from the server.

list_tools(client, opts \\ [])

Lists available tools from the server.

merge_capabilities(client, additional_capabilities)

Merges additional capabilities into the client's capabilities.

parse_options(data)

parse_options!(data)

ping(client, opts \\ [])

Sends a ping request to the server to check connection health. Returns :pong if successful.

read_resource(client, uri, opts \\ [])

Reads a specific resource from the server.

register_log_callback(client, callback)

Registers a callback function to be called when log messages are received.

register_progress_callback(client, progress_token, callback)

Registers a callback function to be called when progress notifications are received for the specified progress token.

send_progress(client, progress_token, progress, total \\ nil)

Sends a progress notification to the server for a long-running operation.

set_log_level(client, level)

Sets the minimum log level for the server to send log messages.

start_link(opts)

Starts a new MCP client process.

unregister_log_callback(client)

Unregisters a previously registered log callback.

unregister_progress_callback(client, progress_token)

Unregisters a previously registered progress callback for the specified token.

Types

log_callback()

@type log_callback() :: (String.t(), term(), String.t() | nil -> any())

option()

@type option() ::
  {:name, atom()}
  | {:transport, module()}
  | {:client_info, map()}
  | {:capabilities, map()}
  | {:protocol_version, String.t()}
  | {:request_timeout, integer()}
  | Supervisor.init_option()

progress_callback()

@type progress_callback() :: (String.t() | integer(), number(), number() | nil ->
                          any())

Functions

call_tool(client, name, arguments \\ nil, opts \\ [])

Calls a tool on the server.

Options

:timeout - Request timeout in milliseconds
:progress - Progress tracking options
- :token - A unique token to track progress (string or integer)
- :callback - A function to call when progress updates are received

cancel_all_requests(client, reason \\ "client_cancelled")

@spec cancel_all_requests(GenServer.server(), String.t()) ::
  {:ok, [Hermes.Client.Request.t()]} | {:error, Hermes.MCP.Error.t()}

Cancels all pending requests.

Parameters

client - The client process
reason - Optional reason for cancellation (defaults to "client_cancelled")

Returns

{:ok, requests} - A list of the Request structs that were cancelled
{:error, reason} - If an error occurred

cancel_request(client, request_id, reason \\ "client_cancelled")

@spec cancel_request(GenServer.server(), String.t(), String.t()) ::
  :ok | {:error, Hermes.MCP.Error.t()} | {:not_found, String.t()}

Cancels an in-progress request.

Parameters

client - The client process
request_id - The ID of the request to cancel
reason - Optional reason for cancellation

Returns

:ok if the cancellation was successful
{:error, reason} if an error occurred
{:not_found, request_id} if the request ID was not found

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

close(client)

Closes the client connection and terminates the process.

get_prompt(client, name, arguments \\ nil, opts \\ [])

Gets a specific prompt from the server.

Options

:timeout - Request timeout in milliseconds
:progress - Progress tracking options
- :token - A unique token to track progress (string or integer)
- :callback - A function to call when progress updates are received

get_schema(atom)

get_server_capabilities(client)

Gets the server's capabilities as reported during initialization.

Returns nil if the client has not been initialized yet.

get_server_info(client)

Gets the server's information as reported during initialization.

Returns nil if the client has not been initialized yet.

list_prompts(client, opts \\ [])

Lists available prompts from the server.

Options

:cursor - Pagination cursor for continuing a previous request
:timeout - Request timeout in milliseconds
:progress - Progress tracking options
- :token - A unique token to track progress (string or integer)
- :callback - A function to call when progress updates are received

list_resources(client, opts \\ [])

Lists available resources from the server.

Options

:cursor - Pagination cursor for continuing a previous request
:timeout - Request timeout in milliseconds
:progress - Progress tracking options
- :token - A unique token to track progress (string or integer)
- :callback - A function to call when progress updates are received

list_tools(client, opts \\ [])

Lists available tools from the server.

Options

:cursor - Pagination cursor for continuing a previous request
:timeout - Request timeout in milliseconds
:progress - Progress tracking options
- :token - A unique token to track progress (string or integer)
- :callback - A function to call when progress updates are received

merge_capabilities(client, additional_capabilities)

Merges additional capabilities into the client's capabilities.

parse_options(data)

parse_options!(data)

ping(client, opts \\ [])

Sends a ping request to the server to check connection health. Returns :pong if successful.

read_resource(client, uri, opts \\ [])

Reads a specific resource from the server.

Options

:timeout - Request timeout in milliseconds
:progress - Progress tracking options
- :token - A unique token to track progress (string or integer)
- :callback - A function to call when progress updates are received

register_log_callback(client, callback)

@spec register_log_callback(GenServer.server(), log_callback()) :: :ok

Registers a callback function to be called when log messages are received.

Parameters

client - The client process
callback - A function that takes three arguments: level, data, and logger name

The callback function will be called whenever a log message notification is received.

register_progress_callback(client, progress_token, callback)

@spec register_progress_callback(
  GenServer.server(),
  String.t() | integer(),
  progress_callback()
) :: :ok

Registers a callback function to be called when progress notifications are received for the specified progress token.

Parameters

client - The client process
progress_token - The progress token to watch for (string or integer)
callback - A function that takes three arguments: progress_token, progress, and total

The callback function will be called whenever a progress notification with the matching token is received.

send_progress(client, progress_token, progress, total \\ nil)

@spec send_progress(
  GenServer.server(),
  String.t() | integer(),
  number(),
  number() | nil
) ::
  :ok | {:error, term()}

Sends a progress notification to the server for a long-running operation.

Parameters

client - The client process
progress_token - The progress token provided in the original request (string or integer)
progress - The current progress value (number)
total - The optional total value for the operation (number)

Returns :ok if notification was sent successfully, or {:error, reason} otherwise.

set_log_level(client, level)

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

Sets the minimum log level for the server to send log messages.

Parameters

client - The client process
level - The minimum log level (debug, info, notice, warning, error, critical, alert, emergency)

Returns {:ok, result} if successful, {:error, reason} otherwise.

start_link(opts)

@spec start_link([option()]) :: Supervisor.on_start()

Starts a new MCP client process.

Options

:name - Optional name to register the client process
:transport - The transport process or name to use (required)
:client_info - Information about the client (required)
:capabilities - Client capabilities to advertise
:protocol_version - Protocol version to use (defaults to "2024-11-05")
:request_timeout - Default timeout for requests in milliseconds (default: 30s)

unregister_log_callback(client)

@spec unregister_log_callback(GenServer.server()) :: :ok

Unregisters a previously registered log callback.

Parameters

client - The client process
callback - The callback function to unregister

unregister_progress_callback(client, progress_token)

@spec unregister_progress_callback(GenServer.server(), String.t() | integer()) :: :ok

Unregisters a previously registered progress callback for the specified token.

Parameters

client - The client process
progress_token - The progress token to stop watching (string or integer)