Registers a component (tool, prompt, or resource) with the server.

@spec send_elicitation_request(String.t(), map(), configuration) ::
  :ok | {:error, term()}
when configuration: [{:timeout, non_neg_integer() | nil}]

Sends an elicitation/create request to the client.

Per the MCP 2025-06-18 specification, the server provides a human-readable message and a restricted-subset JSON requested_schema describing the expected user input. The client presents this to the user and returns one of three actions: accept (with content matching the schema), decline, or cancel.

This is an asynchronous operation. The response will be delivered to your handle_elicitation/3 callback.

The requested_schema is validated synchronously before any wire I/O. The client must advertise the elicitation capability or the call returns {:error, :capability_not_supported} after enqueueing.

Schema Subset

• Top level must be %{"type" => "object", "properties" => %{...}}
• Properties may declare "type" of "string", "number", "integer", "boolean", or use "enum" (string-only)
• String properties may set "format" of "email", "uri", "date", or "date-time"

Per the spec, servers MUST NOT request sensitive information through elicitation.

Example

defmodule MyServer.Tools.Greet do
  use Anubis.Server.Component, type: :tool

  @impl true
  def execute(_args, frame) do
    Anubis.Server.send_elicitation_request("What's your name?", %{
      "type" => "object",
      "properties" => %{
        "name" => %{"type" => "string", "minLength" => 1}
      },
      "required" => ["name"]
    })

    {:reply, "asked for name", frame}
  end
end

@spec send_log_message(
  level :: Logger.level(),
  message :: String.t(),
  metadata :: map() | nil
) :: :ok

Sends a log message to the client.

Must be called from within a Session callback — see send_resources_list_changed/0 for details.

@spec send_progress(progress_token(), progress_step(), opts) :: :ok
when opts: [total: progress_total(), message: String.t()]

Sends a progress notification for an ongoing operation.

@spec send_prompts_list_changed() :: :ok

Sends a prompts list changed notification.

Must be called from within a Session callback — see send_resources_list_changed/0 for details.

@spec send_resource_updated(uri :: String.t(), timestamp :: DateTime.t() | nil) :: :ok

Sends a resource updated notification for a specific resource.

Subscription-gated: only emits if the current session has previously received a resources/subscribe request for this URI. Calls for unsubscribed URIs are silently dropped.

Must be called from within a Session callback — see send_resources_list_changed/0 for details.

@spec send_resources_list_changed() :: :ok

Sends a resources list changed notification.

Must be called from within a Session callback — the current process must be the Session GenServer. Calling from outside a callback will silently lose the message.

For external processes, use send(session_pid, {:send_notification, "notifications/resources/list_changed", %{}}).

@spec send_roots_request([{:timeout, non_neg_integer() | nil}]) :: :ok

Sends a roots/list request to the client.

@spec send_sampling_request([map()], configuration) :: :ok
when configuration: [
       model_preferences: map() | nil,
       system_prompt: String.t() | nil,
       max_tokens: non_neg_integer() | nil,
       timeout: non_neg_integer() | nil
     ]

Sends a sampling/createMessage request to the client.

This is an asynchronous operation. The response will be delivered to your handle_sampling/3 callback.

@spec send_task_status(task_id :: String.t()) :: :ok

Sends a notifications/tasks/status notification with the current state of the given task.

Must be called from within a Session callback — see send_resources_list_changed/0 for details.

Per spec (2025-11-25), receivers MAY send these notifications when a task's status changes; they are optional and requestors MUST NOT rely on them. This helper looks up the task in the configured task store and emits the full Task projection.

@spec send_tools_list_changed() :: :ok

Sends a tools list changed notification.

Must be called from within a Session callback — see send_resources_list_changed/0 for details.