ExMCP.Protocol.Meta (ex_mcp v1.0.0-rc.8)

Builds and validates MCP _meta objects.

MCP 2026-07-28 moves protocol version and client capabilities into every request. This module owns those reserved fields and the common metadata key grammar so outbound and inbound paths cannot drift.

Summary

Types

kind()

validation_error()

Functions

build_request_meta(meta, protocol_version, client_capabilities, opts \\ [])

Builds the metadata required on a modern request.

client_capabilities_key()

Returns the reserved per-request client-capabilities key.

parse(meta, atom)

Parses a _meta object according to its message kind.

parse_notification_meta(meta)

Parses optional notification metadata.

parse_request_meta(meta)

Parses and validates metadata on a modern request.

parse_result_meta(meta)

Parses optional result metadata.

protocol_version_key()

Returns the reserved request protocol-version key.

reserved_key?(key)

Returns whether a key's prefix is reserved for MCP protocol use.

valid_key?(key)

Returns whether a metadata key follows the MCP key grammar.

validate(meta)

Validates the keys of a metadata object.

Types

kind()

@type kind() :: :request | :notification | :result

validation_error()

@type validation_error() ::
  {:invalid_meta, :not_an_object}
  | {:invalid_meta_key, term()}
  | {:missing_meta_field, String.t()}
  | {:invalid_meta_field, String.t()}

Functions

build_request_meta(meta, protocol_version, client_capabilities, opts \\ [])

@spec build_request_meta(map(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, validation_error()}

Builds the metadata required on a modern request.

Caller metadata is preserved after key validation. ExMCP always overwrites protocolVersion, clientCapabilities, and clientInfo with the connection values supplied here. Optional W3C trace-context fields may be supplied via :trace_context.

client_capabilities_key()

@spec client_capabilities_key() :: String.t()

Returns the reserved per-request client-capabilities key.

parse(meta, atom)

@spec parse(map() | nil, kind()) :: {:ok, map()} | {:error, validation_error()}

Parses a _meta object according to its message kind.

parse_notification_meta(meta)

@spec parse_notification_meta(map() | nil) ::
  {:ok, map()} | {:error, validation_error()}

Parses optional notification metadata.

parse_request_meta(meta)

@spec parse_request_meta(map()) :: {:ok, map()} | {:error, validation_error()}

Parses and validates metadata on a modern request.

parse_result_meta(meta)

@spec parse_result_meta(map() | nil) :: {:ok, map()} | {:error, validation_error()}

Parses optional result metadata.

protocol_version_key()

@spec protocol_version_key() :: String.t()

Returns the reserved request protocol-version key.

reserved_key?(key)

@spec reserved_key?(term()) :: boolean()

Returns whether a key's prefix is reserved for MCP protocol use.

valid_key?(key)

@spec valid_key?(term()) :: boolean()

Returns whether a metadata key follows the MCP key grammar.

validate(meta)

@spec validate(map()) :: :ok | {:error, validation_error()}

Validates the keys of a metadata object.