ExMCP.Server.RequestContext (ex_mcp v1.0.0-rc.8)

Validated protocol context for one inbound MCP message.

The context separates transport/protocol metadata from application params. Legacy messages remain valid without modern metadata; a message that uses either required modern field must provide the complete modern _meta object.

Summary

Types

context_error()

t()

Functions

error_response(reason, id, protocol_mode \\ nil)

Builds a JSON-RPC error response for a context-validation failure.

from_message(message)

Extracts context from a JSON-RPC request or notification.

http_status(error)

Returns the HTTP status required for context-validation errors.

require_client_capabilities(context, required)

Verifies that a modern request declared every capability an operation needs.

validate_method(context)

Validates that a method belongs to the selected protocol revision.

validate_protocol_mode(arg1, mode)

Validates an extracted context against an explicitly configured server mode.

Types

context_error()

@type context_error() ::
  ExMCP.Protocol.Meta.validation_error()
  | {:unsupported_protocol_version, String.t()}
  | {:protocol_mode_mismatch, ExMCP.Types.protocol_mode(), :legacy | :modern}
  | {:method_not_available, String.t(), String.t()}

t()

@type t() :: %ExMCP.Server.RequestContext{
  client_capabilities: map() | nil,
  client_info: map() | nil,
  delivery_semantics: :at_least_once | :single_use | nil,
  endpoint: String.t() | nil,
  era: :legacy | :modern | :unknown,
  input_responses: map() | nil,
  log_level: String.t() | nil,
  meta: map(),
  method: String.t(),
  mrtr_jti: String.t() | nil,
  mrtr_round: non_neg_integer() | nil,
  notification_target: pid() | nil,
  principal_id: String.t() | nil,
  progress_token: ExMCP.Types.progress_token() | nil,
  protocol_version: String.t() | nil,
  request?: boolean(),
  request_id: ExMCP.Types.request_id() | nil,
  request_state: term(),
  sealed_request_state: String.t() | nil,
  tenant_id: String.t() | nil,
  trace_context: map()
}

Functions

error_response(reason, id, protocol_mode \\ nil)

@spec error_response(
  context_error(),
  ExMCP.Types.request_id() | nil,
  ExMCP.Types.protocol_mode() | nil
) :: map()

Builds a JSON-RPC error response for a context-validation failure.

from_message(message)

@spec from_message(map()) :: {:ok, t()} | {:error, context_error()}

Extracts context from a JSON-RPC request or notification.

http_status(error)

@spec http_status(context_error()) :: 400

Returns the HTTP status required for context-validation errors.

require_client_capabilities(context, required)

@spec require_client_capabilities(t(), map()) ::
  :ok | {:error, ExMCP.Error.ProtocolError.t()}

Verifies that a modern request declared every capability an operation needs.

Empty capability objects require presence of that capability. Nested maps require the corresponding nested keys. On failure, the returned protocol error can be returned directly as a handler error reason.

validate_method(context)

@spec validate_method(t()) :: :ok | {:error, context_error()}

Validates that a method belongs to the selected protocol revision.

validate_protocol_mode(arg1, mode)

@spec validate_protocol_mode(t(), ExMCP.Types.protocol_mode() | nil) ::
  :ok | {:error, context_error()}

Validates an extracted context against an explicitly configured server mode.