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

The context of one JSON-RPC message and the `ctx` map that the
callbacks of the entities receive.

The transport builds a `%OzMcp.Context{}` struct for each message:
`OzMcp.Router` for HTTP, `OzMcp.Transport.Stdio` for stdio. The
validation (OzMcp.Validate) fills the struct. The struct is
internal.

The framework passes the short `ctx` map to the callbacks `call/2`,
`read/2`, `read/4`, `get/2`, `complete/4` and `roots_list_changed/1`:

| Key | Value |
|---|---|
| `:instance` | the name of the instance that serves the request. It is always set. |
| `:server` | the server module |
| `:session_id` | the id of the session (`nil` before `initialize`) |
| `:request_id` | the JSON-RPC id of the request (`nil` in a task) |
| `:progress_token` | the `progressToken` of `_meta` of the request, or `nil` |
| `:task_id` | the id of the task in a task runner, else `nil` |
| `:client_capabilities` | the capabilities that the client declared in `initialize` |
| `:principal` | an `OzMcp.Auth.Principal`, or `nil` when the server has no authorization |

Read the capabilities of the client with `client_supports?/2`, or with
the pure form `capability?/2`. `client_task_support?/2` tells whether
the client runs a request as a task. The framework uses the other
public functions. The application does not call them.

The struct also carries the config of the instance (`config`). The
router reads it one time for each request and puts it here, so the
stages and the handler do not read the Registry again. The config is
frozen at boot: a long stream or a stdio loop keeps the config of its
start while the instance restarts with the same options.

# `ctx`

```elixir
@type ctx() :: %{
  instance: OzMcp.Instance.t(),
  server: module(),
  session_id: String.t() | nil,
  request_id: integer() | String.t() | nil,
  progress_token: term() | nil,
  task_id: String.t() | nil,
  client_capabilities: map(),
  principal: OzMcp.Auth.Principal.t() | nil
}
```

# `mode`

```elixir
@type mode() :: :http | :rpc
```

# `rpc_kind`

```elixir
@type rpc_kind() :: OzMcp.Utils.JsonRpc.kind() | nil
```

# `t`

```elixir
@type t() :: %OzMcp.Context{
  bound: OzMcp.Pipeline.Bound.t() | nil,
  client_capabilities: map() | nil,
  client_info: map() | nil,
  completion_argument: map() | nil,
  completion_context: map() | nil,
  completion_ref: String.t() | nil,
  config: OzMcp.Instance.Config.t() | nil,
  conn:
    %Plug.Conn{
      adapter: term(),
      assigns: term(),
      body_params: term(),
      cookies: term(),
      halted: term(),
      host: term(),
      method: term(),
      owner: term(),
      params: term(),
      path_info: term(),
      path_params: term(),
      port: term(),
      private: term(),
      query_params: term(),
      query_string: term(),
      remote_ip: term(),
      req_cookies: term(),
      req_headers: term(),
      request_path: term(),
      resp_body: term(),
      resp_cookies: term(),
      resp_headers: term(),
      scheme: term(),
      script_name: term(),
      secret_key_base: term(),
      state: term(),
      status: term()
    }
    | nil,
  error:
    %OzMcp.Context.Error{code: term(), data: term(), headers: term()} | nil,
  instance: OzMcp.Instance.t(),
  log_level: atom() | nil,
  mode: mode(),
  negotiated_protocol_version: String.t() | nil,
  principal: OzMcp.Auth.Principal.t() | nil,
  progress_token: term() | nil,
  rpc: map() | nil,
  rpc_id: OzMcp.Utils.JsonRpc.id(),
  rpc_kind: rpc_kind(),
  rpc_method: String.t() | nil,
  rpc_params: map() | nil,
  rpc_response: {:ok, map()} | {:error, map()} | {:orphan_error, map()} | nil,
  server: module(),
  session_id: String.t() | nil,
  session_initialized: boolean() | nil,
  task_id: String.t() | nil,
  tasks_cursor: String.t() | nil,
  transport: transport()
}
```

# `transport`

```elixir
@type transport() :: :http_streamable | :stdio
```

# `capability?`

```elixir
@spec capability?(term(), atom() | String.t() | [atom() | String.t()]) :: boolean()
```

Pure form of `client_supports?/2`: looks the capability up in a map of
declared client capabilities (JSON object with string keys).

# `client_supports?`

```elixir
@spec client_supports?(ctx() | t(), atom() | String.t() | [atom() | String.t()]) ::
  boolean()
```

True when the client declared the capability during `initialize`.

`capability` is an atom or a string (`:sampling`, `"roots"`), or a list of
them for a nested member (`[:sampling, :tools]`). A capability the client
declared with an empty object (`"elicitation": {}`) is supported.

Accepts the short context handed to the user callbacks: the capabilities
are part of it (`ctx.client_capabilities`, fixed by `initialize`), so this
is a lookup in a map. A hand-built ctx without them (`:client_capabilities`
key missing) is answered from the session of `:instance` and `:session_id`,
so the result is `false` when the session does not exist any more, or when
the ctx has no `:instance`.

# `client_task_support?`

```elixir
@spec client_task_support?(ctx() | t(), String.t()) :: boolean()
```

`true` when the client runs the request `method` as a task:
`tasks.requests.sampling.createMessage` or
`tasks.requests.elicitation.create`.

A method that the client cannot run as a task gives `false`. Accepts the
same contexts as `client_supports?/2`.

---

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