OzMcp.Context (OzMcp v0.9.0)

Copy Markdown View Source

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:

KeyValue
:instancethe name of the instance that serves the request. It is always set.
:serverthe server module
:session_idthe id of the session (nil before initialize)
:request_idthe JSON-RPC id of the request (nil in a task)
:progress_tokenthe progressToken of _meta of the request, or nil
:task_idthe id of the task in a task runner, else nil
:client_capabilitiesthe capabilities that the client declared in initialize
:principalan 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.

Summary

Functions

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

True when the client declared the capability during initialize.

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

Types

ctx()

@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()

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

rpc_kind()

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

t()

@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()

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

Functions

capability?(capabilities, path)

@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?(ctx, capability)

@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?(ctx, method)

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