OzMcp.Client (OzMcp v0.9.0)

Copy Markdown View Source

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.

Summary

Functions

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).

Asks the client for its roots.

Asks the client to complete a conversation with a model.

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

Types

ctx()

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

elicit_result()

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

sample_result()

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

Functions

elicit(ctx, schema_or_url, opts \\ [])

@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(ctx, opts \\ [])

@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(ctx, messages, opts \\ [])

@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(elicitations, message \\ "This request requires more information.")

@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.