Task helpers for tool authors.
Helper module over the standard tool ctx map (OzMcp.Context.ctx()).
There is no struct: the tool's single ctx argument IS the channel —
a tool has exactly one mandatory callback, call(ctx, params). A
task-backed execution carries a non-nil ctx.task_id; a plain
synchronous call carries task_id: nil and every helper here returns
{:error, :not_a_task} without sending anything.
A task can also send a log message to its client with
OzMcp.Notify.log(ctx, level, data): the message carries the
io.modelcontextprotocol/related-task _meta and goes to the owner
of the task — each open tasks/result stream of the task, else every
session of the owner. Each receiving session applies its own level.
The dual-mode pattern
One tool handles BOTH execution modes through the same callback:
task-backed — progress/status helpers route through the task record; the progress token is owned by the task (captured at creation from the request
_meta.progressToken), tools never pass it.plain synchronous —
ctx.task_idis nil; progress with a client-requested token goes throughctx.progress_tokenandOzMcp.Notify.progress/5.def call(ctx, params) do total = 10 for i <- 1..total do run_step(i) report(ctx, i, total) end {:ok, %CallToolResult{} |> CallToolResult.build()} end defp report(ctx, i, total) do cond do ctx.task_id != nil -> OzMcp.Tasks.Context.progress(ctx, i, total, "step #{i}") ctx.progress_token != nil -> OzMcp.Notify.progress(ctx.instance, ctx.session_id, ctx.progress_token, i, total: total, message: "step #{i}" ) true -> :ok end end
Summary
Functions
Emits notifications/progress for the task. The progress token is owned
by the task record (captured at creation); tools never pass it here.
This call and OzMcp.Notify.progress/3 with the ctx of a task are the
same: both call OzMcp.Tasks.progress/5.
Sets/updates the statusMessage without changing the status.
Types
@type ctx() :: OzMcp.Context.ctx()
Functions
@spec progress(ctx(), number(), number() | nil, term()) :: :ok | {:error, :not_a_task | :not_encodable | :unavailable}
Emits notifications/progress for the task. The progress token is owned
by the task record (captured at creation); tools never pass it here.
This call and OzMcp.Notify.progress/3 with the ctx of a task are the
same: both call OzMcp.Tasks.progress/5.
The progress value must increase with each call for the same token;
a value that does not is dropped (:ok, the client gets nothing, a
debug line is written). The first value can be any number; a value
that is not a number is not checked.
Returns {:error, :not_a_task} when ctx.task_id is nil,
{:error, :not_encodable} when a value holds a term that JSON cannot
encode and {:error, :unavailable} when the instance does not run.
@spec status_message(ctx(), String.t()) :: :ok | {:error, :not_a_task | :not_encodable | :unavailable}
Sets/updates the statusMessage without changing the status.
Returns {:error, :not_a_task} when ctx.task_id is nil and
{:error, :not_encodable} when the message is a text that JSON cannot
encode (a string that is not valid UTF-8, or a term that is not a
string): the task keeps its old message. {:error, :unavailable} means
that the instance does not run.