OzMcp.Outbound (OzMcp v0.9.0)

Copy Markdown View Source

Requests the server sends to the client.

A callback (tool.call/2, resource.read/2, prompt.get/2, a task tool) can ask the client something while it runs: ping/2 and the client features built on request/4, which OzMcp.Client wraps (sampling, elicitation, roots). The guide about the requests to the client describes each method with an example.

request/4 sends one JSON-RPC request and blocks the calling process until the client answers, the timeout elapses, or the session ends:

case OzMcp.Outbound.ping(ctx) do
  {:ok, %{}} -> :alive
  {:error, reason} -> {:unreachable, reason}
end

Results

{:ok, result} when the client answered (a map). A failure gives one of these errors: {:error, {:rpc_error, error}} (the client answered with a JSON-RPC error), {:error, :timeout}, {:error, :session_terminated}, {:error, :session_not_found}, {:error, :capability_not_supported}, {:error, :unsupported_method}, {:error, :not_encodable}, {:error, :no_task}, {:error, :no_stream} and {:error, :session_not_initialized}. request_task/4 adds {:error, :client_tasks_disabled} (the runtime option client_tasks is false, the default), {:error, {:client_task_cancelled, task_id}} and {:error, {:invalid_response, result}}. The guide about the requests to the client gives the meaning of each error and the option :wait_for_stream of the :no_stream case.

Capabilities

Only a method whose capability the client declared is sent: ping needs none, sampling/createMessage needs sampling, elicitation/create needs elicitation, roots/list needs roots. Some params need a member of the capability: a task key needs the task capability of the method, the modes of elicitation/create need elicitation.form or elicitation.url and sampling with tools, toolChoice or includeContext needs sampling.tools or sampling.context. The guide about the requests to the client gives the table. The three tasks/* methods are internal to the flow of a client task (see OzMcp.Client): a callback does not send them.

Where the request travels

The callback runs for a POST request, as a task, or outside a request. A callback of a POST request writes the request on the response of that POST, which becomes an event stream (see OzMcp.PostStream). A callback that runs as a task (ctx.task_id is set) writes the request on the tasks/result streams of the task and the task is input_required while it waits. In every other case the request travels on the GET stream of the session and waits in the event log of the session until a stream delivers it. The guide about the requests to the client describes each way and the timeout of each method.

The client answers with a POST that carries a JSON-RPC response. The router hands the answer to the waiting process with deliver/2: an answer for a request of a task goes to the process of the task, by the owner of the task. Any session of the owner can answer; an answer on a session that does not own the task is ignored.

Pending requests

A pending request of a session lives in the process of the session: the session gives each one its id, routes its messages and hands the answer to the process that waits. The end of the session process ends each wait and a callback that is cancelled, stopped at its deadline or killed leaves no pending request: the client receives notifications/cancelled for it. A late answer for an unknown request id is ignored. The request id is generated by the server and is unique in the session; a client can answer only the requests of its own session.

Telemetry

Each call of request/4 gives one client_request span of the events of :telemetry. The guide about the telemetry describes the events.

Summary

Functions

Hands the answer of the client to the process that waits for it.

Sends ping to the client. The client answers with an empty result.

Sends a request to the client and waits for its answer.

Sends a request as a task of the client and waits for the final result. This feature is experimental and the runtime option client_tasks turns it on (default false).

Types

ctx()

@type ctx() :: OzMcp.Context.ctx() | OzMcp.Context.t()

error()

@type error() ::
  {:rpc_error, map()}
  | :timeout
  | :session_terminated
  | :session_not_found
  | :no_stream
  | :session_not_initialized
  | :capability_not_supported
  | :unsupported_method
  | :not_encodable
  | :no_task
  | :client_tasks_disabled
  | {:client_task_cancelled, String.t()}
  | {:invalid_response, map()}

outcome()

@type outcome() :: {:ok, map()} | {:error, error()}

Functions

deliver(instance, session_id, request_id, answer)

@spec deliver(
  OzMcp.Instance.t(),
  String.t(),
  String.t() | integer(),
  {:ok, map()} | {:error, map()}
) :: :ok

Hands the answer of the client to the process that waits for it.

answer is {:ok, result} or {:error, error} (the error object of the response). Always returns :ok: an answer for a request that is not pending (late, repeated, unknown, or of another session) is ignored.

This is the path to one session: the id must name a request that the session holds. The router uses deliver/2, which sends the answer of a request of a task to the task of its owner. An id of a request of a task that reaches this function names no request of the session, so the answer is ignored.

ping(ctx, opts \\ [])

@spec ping(ctx(), keyword()) :: outcome()

Sends ping to the client. The client answers with an empty result.

request(ctx, method, params \\ nil, opts \\ [])

@spec request(ctx(), String.t(), map() | nil, keyword()) :: outcome()

Sends a request to the client and waits for its answer.

Options:

  • :timeout — milliseconds, or :infinity. Defaults to the timeout runtime option of the method (see the moduledoc).
  • :wait_for_stream — true sends a request that only the GET stream can carry even when the client has no stream open (default false, the call fails with :no_stream).

request_task(ctx, method, params, opts \\ [])

@spec request_task(ctx(), String.t(), map(), keyword()) :: outcome()

Sends a request as a task of the client and waits for the final result. This feature is experimental and the runtime option client_tasks turns it on (default false).

Same options as request/4 and:

  • :ttl — milliseconds that the client must keep the task. Defaults to the timeout of the method when it is an integer; with timeout: :infinity the request carries no ttl.
  • :poll_interval — milliseconds between two tasks/get calls. The pollInterval of the client wins. Defaults to the client_task_poll_interval_ms runtime option.

The first request carries params.task. A task value that the params already have is kept: the :ttl option applies only when the params have no task. The client answers with a CreateTaskResult and the call polls tasks/get until the task is terminal. A completed or failed task is read with tasks/result; an input_required task calls tasks/result at once; a cancelled task gives {:error, {:client_task_cancelled, task_id}}.

The client must declare the task capability of the method (tasks.requests.sampling.createMessage, tasks.requests.elicitation.create), else the call gives {:error, :capability_not_supported}.