@spec add_root(t(), String.t(), String.t() | nil, opts :: Keyword.t()) :: :ok

Adds a root directory to the client's roots list.

Parameters

• client - The client process
• uri - The URI of the root directory (must start with "file://")
• name - Optional human-readable name for the root
• opts - Additional options
  • :timeout - Request timeout in milliseconds

@spec call_tool(t(), String.t(), map() | nil, keyword()) ::
  {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

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

@spec cancel_all_requests(t(), String.t(), opts :: Keyword.t()) ::
  {:ok, [Anubis.Client.Request.t()]} | {:error, Anubis.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

@spec cancel_request(t(), String.t(), String.t(), opts :: Keyword.t()) ::
  :ok | {:error, Anubis.MCP.Error.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

Returns a child specification for starting the client under a supervisor.

This starts a supervision tree containing both the client GenServer and the configured transport process, linked with a :one_for_all strategy.

@spec clear_roots(t(), opts :: Keyword.t()) :: :ok

Clears all root directories.

Parameters

• client - The client process
• opts - Additional options
  • :timeout - Request timeout in milliseconds

@spec close(t()) :: :ok

Closes the client connection and terminates the process.

@spec complete(t(), map(), map(), keyword()) ::
  {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

Requests autocompletion suggestions for prompt arguments or resource URIs.

Parameters

• client - The client process
• ref - Reference to what is being completed (required)
  • For prompts: %{"type" => "ref/prompt", "name" => prompt_name}
  • For resources: %{"type" => "ref/resource", "uri" => resource_uri}
• argument - The argument being completed (required)
  • %{"name" => arg_name, "value" => current_value}
• opts - Additional 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

Returns

Returns {:ok, response} with completion suggestions if successful, or {:error, reason} if an error occurs.

The response result contains a "completion" object with:

• values - List of completion suggestions (maximum 100)
• total - Optional total number of matching items
• hasMore - Boolean indicating if more results are available

@spec get_prompt(t(), String.t(), map() | nil, keyword()) ::
  {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

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

@spec get_server_capabilities(t(), opts :: Keyword.t()) :: map() | nil

Gets the server's capabilities as reported during initialization.

Returns nil if the client has not been initialized yet.

@spec get_server_info(t(), opts :: Keyword.t()) :: map() | nil

Gets the server's information as reported during initialization.

Returns nil if the client has not been initialized yet.

Guard to check if an atom is a valid client capability.

Guard to check if a capability is supported by checking map keys.

@spec list_prompts(
  t(),
  keyword()
) :: {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

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

@spec list_resource_templates(
  t(),
  keyword()
) :: {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

Lists available resource templates 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

@spec list_resources(
  t(),
  keyword()
) :: {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

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

@spec list_roots(t(), opts :: Keyword.t()) :: [map()]

Gets a list of all root directories.

Parameters

• client - The client process
• opts - Additional options
  • :timeout - Request timeout in milliseconds

@spec list_tools(
  t(),
  keyword()
) :: {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

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

@spec merge_capabilities(t(), map(), opts :: Keyword.t()) :: map()

Merges additional capabilities into the client's capabilities.

@spec parse_capability(capability() | {capability(), capability_opts()}, map()) ::
  map()

Converts a capability atom or tuple into a map entry.

Useful for building capability maps from ergonomic shorthand:

capabilities =
  [:roots, {:sampling, list_changed?: true}]
  |> Enum.reduce(%{}, &Anubis.Client.parse_capability/2)
# => %{"roots" => %{}, "sampling" => %{}}

@spec ping(
  t(),
  keyword()
) :: :pong | {:error, Anubis.MCP.Error.t()}

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

Options

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

@spec read_resource(t(), String.t(), keyword()) ::
  {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

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

@spec register_log_callback(t(), log_callback(), opts :: Keyword.t()) :: :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.

@spec register_progress_callback(
  t(),
  String.t() | integer(),
  progress_callback(),
  opts :: Keyword.t()
) :: :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.

@spec register_sampling_callback(
  t(),
  (map() -> {:ok, map()} | {:error, String.t()})
) :: :ok

Registers a callback function to handle sampling requests from the server.

The callback function will be called when the server sends a sampling/createMessage request. The callback should implement user approval and return the LLM response.

Callback Function

The callback receives the sampling parameters and must return:

• {:ok, response_map} - Where response_map contains:
  • "role" - Usually "assistant"
  • "content" - Message content (text, image, or audio)
  • "model" - The model that was used
  • "stopReason" - Why generation stopped (e.g., "endTurn")
• {:error, reason} - If the user rejects or an error occurs

@spec remove_root(t(), String.t(), opts :: Keyword.t()) :: :ok

Removes a root directory from the client's roots list.

Parameters

• client - The client process
• uri - The URI of the root directory to remove
• opts - Additional options
  • :timeout - Request timeout in milliseconds

@spec send_progress(
  t(),
  String.t() | integer(),
  number(),
  number() | nil,
  opts :: Keyword.t()
) :: :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.

@spec set_log_level(t(), String.t()) ::
  {:ok, Anubis.MCP.Response.t()} | {:error, Anubis.MCP.Error.t()}

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.

@spec start_link(keyword()) :: Supervisor.on_start()

Starts the client supervision tree (client + transport).

This is the primary entry point for starting a client. It creates a supervisor that manages both the client GenServer and the transport process.

@spec unregister_log_callback(t(), opts :: Keyword.t()) :: :ok

Unregisters a previously registered log callback.

Parameters

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

@spec unregister_progress_callback(t(), String.t() | integer(), opts :: Keyword.t()) ::
  :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)

@spec unregister_sampling_callback(t()) :: :ok

Unregisters the sampling callback.