# `OzMcp.Client`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/client.ex#L1)

What a callback can ask of the client: input from the user (elicitation),
a model completion (sampling) and the roots of the client.

The functions block the calling process until the client answers. They
run inside a callback (`tool.call/2`, `resource.read/2`, `prompt.get/2`, a
task tool) and take its `ctx`. They are built on `OzMcp.Outbound.request/4`:
the client must have declared the capability (`elicitation`, `sampling`,
`roots`), else nothing is sent and the result is
`{:error, :capability_not_supported}`. Every error of
`OzMcp.Outbound` is possible; the options `:timeout` and
`:wait_for_stream` are passed to it.

## Invalid arguments

`elicit/3`, `sample/3` and `url_elicitation_required/2` build their params
with the structs of `OzMcp.Structs` and raise `ArgumentError` for invalid
arguments (a missing `:message` or `:max_tokens`, a schema that is not
flat, a URL with credentials, tool use messages out of order). This is for
a programmer error. Inside a callback the raise is caught by the framework:
the client gets the generic `-32603` error and the log has the cause.

## Waiting time

The client has a limited time to answer and a call that waits longer ends
with `{:error, :timeout}` (the client is told to cancel the request). The
default depends on who answers (a person, a model, or `list_roots/2`);
the `:timeout` option of a call overrides it. The guide about the requests
to the client gives the options and the default of each method.

## Elicitation

`elicit/3` asks the user for input. With a schema it is a **form**: the
client shows the fields and returns the values. With a URL it is a **URL**
interaction: the client sends the user to a web page and the data never
passes through the client (use it for credentials and authorizations).

    schema =
      %ElicitationSchema{}
      |> ElicitationSchema.property("name", %StringSchema{} |> StringSchema.title("Name"))
      |> ElicitationSchema.required(["name"])

    case OzMcp.Client.elicit(ctx, schema, message: "Who are you?") do
      {:ok, %{action: :accept, content: %{"name" => name}}} -> name
      {:ok, %{action: action}} when action in [:decline, :cancel] -> nil
      {:error, reason} -> reason
    end

A form the client did not declare is not sent (an empty `elicitation: {}`
means form only). The content of an accepted form is validated against the
schema (`validate: false` turns it off). The guide about the requests to
the client gives the rules of the validation and of the defaults.

A callback that needs a URL interaction before it can run at all returns
the error of `url_elicitation_required/2`.

## Sampling

`sample/3` asks the client to run a model on a conversation. `max_tokens`
is required. Tools (`tools:`) and `tool_choice:` need the client capability
`sampling.tools`; `include_context:` other than `:none` needs
`sampling.context`.

    messages = [OzMcp.Structs.SamplingMessage.user("Summarize this text: ...")]

    {:ok, %{content: [%{"type" => "text", "text" => text}]}} =
      OzMcp.Client.sample(ctx, messages, max_tokens: 300)

## Roots

`list_roots/2` returns the roots the client exposes. A server that wants to
know when they change defines `roots_list_changed/1` (see
`OzMcp.Config.Server`).

## Tasks of the client

`sample/3` and `elicit/3` can run the request as a task of the client:
pass `task: true` or `task: %{ttl: milliseconds}`. The client answers at
once with a task, the server polls `tasks/get` and reads the final result
with `tasks/result`. Use it for a long sampling or a long human input: one
request is not held open. The option needs the runtime option
`client_tasks` (default `false`, experimental) and a client without the
task capability gets a plain request unless `task_required: true`. The
guide about the requests to the client describes the flow and its errors.

## In a task

A callback that runs as a task (`ctx.task_id` is set) can use all of these
functions: the request travels on the `tasks/result` stream of the task
with the `io.modelcontextprotocol/related-task` meta and the task is
`input_required` while it waits. If the client does not call
`tasks/result`, the request ends with `{:error, :timeout}`.

A task of the client (`task:`) is a different thing from the task of the
server: the server task stays `working` while its polls can travel on a
`tasks/result` stream.

# `ctx`

```elixir
@type ctx() :: OzMcp.Outbound.ctx()
```

# `elicit_result`

```elixir
@type elicit_result() :: %{
  :action =&gt; :accept | :decline | :cancel,
  :content =&gt; map() | nil,
  optional(:elicitation_id) =&gt; String.t()
}
```

# `sample_result`

```elixir
@type sample_result() :: %{
  role: String.t(),
  content: [map()],
  model: String.t(),
  stop_reason: String.t() | nil
}
```

# `elicit`

```elixir
@spec elicit(
  ctx(),
  OzMcp.Structs.ElicitationSchema.t() | map() | String.t(),
  keyword()
) ::
  {:ok, elicit_result()} | {:error, term()}
```

Asks the user for input. `schema_or_url` is an
`OzMcp.Structs.ElicitationSchema` struct or a map (form mode), or a URL
string (URL mode).

Options:

  * `:message` (required) — what the user sees, with the reason for the
    request.
  * `:elicitation_id` — URL mode only: the identifier of the interaction
    (generated by default). It is part of the result.
  * `:validate` — form mode only: validate the content against the schema
    (default `true`).
  * `:_meta` — a `_meta` map for the request.
  * `:task` — run the request as a task of the client: `true` or
    `%{ttl: milliseconds}`. Needs the runtime option `client_tasks`
    (experimental) and the client capability
    `tasks.requests.elicitation.create`.
  * `:task_required` and `:poll_interval` — the same as in
    `OzMcp.Outbound.request_task/4`.
  * `:timeout`, `:wait_for_stream` — see `OzMcp.Outbound.request/4`.

Returns `{:ok, %{action: action, content: content}}`. `action` is
`:accept`, `:decline` or `:cancel`; `content` is the map of the values
(string keys) for an accepted form, `nil` otherwise. In URL mode `:accept`
means the user agreed to open the URL, not that the interaction is done.
A client task gives the errors of `OzMcp.Outbound.request_task/4`:
`{:error, {:client_task_cancelled, task_id}}` and
`{:error, {:invalid_response, result}}` in addition to the plain ones.

# `list_roots`

```elixir
@spec list_roots(ctx(), keyword()) :: {:ok, [map()]} | {:error, term()}
```

Asks the client for its roots.

Returns `{:ok, roots}`: a list of maps with the string keys `"uri"` (a
`file://` URI) and, optionally, `"name"`.

# `sample`

```elixir
@spec sample(ctx(), [OzMcp.Structs.SamplingMessage.t() | map()], keyword()) ::
  {:ok, sample_result()} | {:error, term()}
```

Asks the client to complete a conversation with a model.

`messages` is a list of `OzMcp.Structs.SamplingMessage` structs or maps.

Options:

  * `:max_tokens` (required)
  * `:system_prompt`, `:temperature`, `:stop_sequences`, `:metadata`
  * `:model_preferences` — a `OzMcp.Structs.ModelPreferences` struct or map
  * `:include_context` — `:none`, `:this_server` or `:all_servers`
  * `:tools` — a list of `OzMcp.Structs.Tool` structs or maps
  * `:tool_choice` — `:auto`, `:required`, `:none` or a
    `OzMcp.Structs.ToolChoice`
  * `:task` — run the request as a task of the client: `true` or
    `%{ttl: milliseconds}`. Needs the runtime option `client_tasks`
    (experimental) and the client capability
    `tasks.requests.sampling.createMessage`.
  * `:task_required` and `:poll_interval` — the same as in
    `OzMcp.Outbound.request_task/4`.
  * `:_meta`, `:timeout`, `:wait_for_stream`

Returns `{:ok, result}` with `role`, `content` (always a list of blocks
with string keys), `model` and `stop_reason` (`"endTurn"`, `"toolUse"`,
`"maxTokens"`, ... or `nil`). When `stop_reason` is `"toolUse"` the content
has `tool_use` blocks: run the tools and sample again with their results.
A client task gives the errors of `OzMcp.Outbound.request_task/4`:
`{:error, {:client_task_cancelled, task_id}}` and
`{:error, {:invalid_response, result}}` in addition to the plain ones.

# `url_elicitation_required`

```elixir
@spec url_elicitation_required([map()], String.t()) :: OzMcp.Utils.Error.t()
```

Builds the error of a request that cannot run before the user finishes a
URL interaction (JSON-RPC error `-32042`). A callback returns it:

    def call(ctx, params) do
      {:error,
       OzMcp.Client.url_elicitation_required([
         %{url: "https://example.com/connect", message: "Connect your account"}
       ])}
    end

Each elicitation is a map with `:url` and `:message` and optionally
`:elicitation_id` (generated by default). The client opens the URLs and
retries the request when the interactions are done.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
