Hermes.Client (hermes_mcp v0.2.1)

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

Functions

Returns a specification to start this module under a supervisor.

Closes the client connection and terminates the process.

Gets a specific prompt from the server.

Gets the server's capabilities as reported during initialization.

Gets the server's information as reported during initialization.

Lists available prompts from the server.

Lists available resources from the server.

Lists available tools from the server.

Merges additional capabilities into the client's capabilities.

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

Reads a specific resource from the server.

Starts a new MCP client process.

Types

option()

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

Functions

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

Calls a tool on the server.

Options

  • :timeout - Request timeout in milliseconds

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

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

list_resources(client, opts \\ [])

Lists available resources from the server.

Options

  • :cursor - Pagination cursor for continuing a previous request
  • :timeout - Request timeout in milliseconds

list_tools(client, opts \\ [])

Lists available tools from the server.

Options

  • :cursor - Pagination cursor for continuing a previous request
  • :timeout - Request timeout in milliseconds

merge_capabilities(client, additional_capabilities)

Merges additional capabilities into the client's capabilities.

parse_options(data)

parse_options!(data)

ping(client, timeout \\ nil)

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

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)