@spec decode_value(String.t()) :: {:ok, String.t()} | :error

Decodes a received header value.

A value that starts with =?base64? and ends with ?= must carry valid, padded standard Base64 of valid UTF-8 and decodes to that string; anything else in that shape returns :error. Every other value is returned unchanged.

@spec encode_value(String.t() | integer() | boolean()) :: String.t()

Encodes a string, integer, or boolean as a header value.

Strings that are not plain header-safe ASCII are wrapped in the =?base64?...?= sentinel; see the module documentation.

@spec header_params(map()) :: [header_param()]

Lists the x-mcp-header annotations reachable from the root of an inputSchema through chains of properties keys only.

Each entry has the declared header Name as written, the property-key path from the root, and the property's declared type. Annotations whose Name or type is not a string are left out; validate_x_mcp_header/1 reports those. Entries are ordered by path.

@spec method_header(String.t()) :: {String.t(), String.t()}

Returns the Mcp-Method header for a request method.

@spec name_header(String.t(), map()) :: {String.t(), String.t()} | nil

Returns the Mcp-Name header for a request, or nil when none applies.

Only tools/call and prompts/get (from params["name"]), resources/read (from params["uri"]) and the tasks extension's tasks/get|update|cancel (from params["taskId"]) carry the header, and only when that param is a string. The value is encoded with encode_value/1.

@spec name_header_required?(String.t()) :: boolean()

Returns whether requests with method must carry an Mcp-Name header.

@spec name_param(String.t()) :: String.t() | nil

The params key Mcp-Name mirrors for method ("name", "uri" or "taskId"), or nil when the method carries no Mcp-Name.

@spec param_headers(map(), map()) :: [{String.t(), String.t()}]

Builds the Mcp-Param-{Name} headers for a tool call.

tool_or_schema is a tool definition (with "inputSchema") or an inputSchema itself; args are the string-keyed call arguments. A header is produced for each annotation from header_params/1 whose argument value at path is a string, integer, boolean, or integral float (42.0 encodes as "42"). Absent and nil values, and values of any other type, produce no header. Header names are "mcp-param-" followed by the lowercased Name.

@spec validate_x_mcp_header(map()) :: :ok | {:error, [String.t()]}

Validates every x-mcp-header annotation in an inputSchema.

The whole schema is searched, including items, composition keywords and $defs. Each annotation must:

• sit on a property reachable from the root through properties keys only;
• be on a property whose "type" is "string", "integer" or "boolean";
• be a non-empty RFC 9110 token (which excludes CR and LF);
• be unique, compared case-insensitively, within the schema.

Errors name the annotation and its JSON Pointer location, never argument values.

@spec value_matches?(String.t(), term()) :: boolean()

Compares a decoded header value to the corresponding body value.

Strings compare exactly and booleans against "true"/"false". Integers and floats compare numerically against a canonical decimal integer header within the JavaScript safe range ("42" matches 42 and 42.0; "042", "-0", "+1" and "42.0" match nothing). Any other body value, including nil, never matches.