@spec build_error(map(), String.t() | integer() | nil) :: map()

Builds an error message map without encoding to JSON.

This is useful for batch processing where we need the raw map.

Parameters

• error - The error map with code, message, and optional data
• id - The error response ID

Examples

iex> Message.build_error(%{"code" => -32600, "message" => "Invalid Request"}, "req_123")
%{"jsonrpc" => "2.0", "error" => %{"code" => -32600, "message" => "Invalid Request"}, "id" => "req_123"}

@spec build_notification(String.t(), map()) :: map()

Builds a notification message map without encoding to JSON.

This is useful for batch processing where we need the raw map.

Parameters

• method - The notification method
• params - The notification parameters

Examples

iex> Message.build_notification("notifications/message", %{"level" => "info", "data" => "test"})
%{"jsonrpc" => "2.0", "method" => "notifications/message", "params" => %{"level" => "info", "data" => "test"}}

@spec build_response(map(), String.t() | integer()) :: map()

Builds a response message map without encoding to JSON.

This is useful for batch processing where we need the raw map.

Parameters

• result - The result data
• id - The response ID

Examples

iex> Message.build_response(%{"value" => 42}, "req_123")
%{"jsonrpc" => "2.0", "result" => %{"value" => 42}, "id" => "req_123"}

Decodes raw data (possibly containing multiple messages) into JSON-RPC messages.

Handles both single messages and batch messages (arrays).

Returns either:

• {:ok, messages} where messages is a list of parsed JSON-RPC messages
• {:error, reason} if parsing fails

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

Encodes a batch of JSON-RPC messages.

This function uses Peri schema validation and always returns a JSON array.

Parameters

• messages - A list of complete JSON-RPC message maps
• batch_schema - Optional Peri schema for batch validation (defaults to :batch_schema)

Returns {:ok, encoded_batch} if successful, or {:error, reason} if validation fails.

Encodes an error message to a JSON-RPC 2.0 compliant string.

Returns the encoded string with a newline character appended.

@spec encode_log_message(String.t(), term(), String.t() | nil) ::
  {:ok, String.t()} | {:error, term()}

Encodes a log message notification to be sent to the client.

Parameters

• level - The log level (debug, info, notice, warning, error, critical, alert, emergency)
• data - The data to be logged (any JSON-serializable value)
• logger - Optional name of the logger issuing the message

Returns the encoded notification string with a newline character appended.

Encodes a notification message to a JSON-RPC 2.0 compliant string.

Returns the encoded string with a newline character appended.

Encodes a notification message using a custom schema.

Parameters

• notification - The notification map containing method and params
• schema - The Peri schema to use for validation

Returns the encoded string with a newline character appended.

@spec encode_progress_notification(map(), term() | nil) ::
  {:ok, String.t()} | {:error, term()}

Encodes a progress notification message to a JSON-RPC 2.0 compliant string.

Parameters

• params - Map containing progress parameters:
  • "progressToken" - The token that was provided in the original request (string or integer)
  • "progress" - The current progress value (number)
  • "total" - Optional total value for the operation (number)
  • "message" - Optional descriptive message (string, for 2025-03-26)
• params_schema - Optional Peri schema for params validation (defaults to @progress_notif_params_schema)

Returns the encoded string with a newline character appended.

@spec encode_progress_notification(String.t() | integer(), number(), number() | nil) ::
  {:ok, String.t()} | {:error, term()}

Legacy function for progress notifications with individual parameters.

Deprecated: Prefer using encode_progress_notification/2 with a params map.

This function will be removed in a future release. Update your code to use the newer function:

encode_progress_notification(%{
  "progressToken" => progress_token,
  "progress" => progress,
  "total" => total
})

Encodes a request message to a JSON-RPC 2.0 compliant string.

Returns the encoded string with a newline character appended.

Encodes a request message using a custom schema.

Parameters

• request - The request map containing method and params
• id - The request ID
• schema - The Peri schema to use for validation

Returns the encoded string with a newline character appended.

Encodes a response message to a JSON-RPC 2.0 compliant string.

Returns the encoded string with a newline character appended.

Encodes a response message using a custom schema.

Parameters

• response - The response map containing result
• id - The response ID
• schema - The Peri schema to use for validation

Returns the encoded string with a newline character appended.

Guard to determine if a JSON-RPC message is an error.

A message is considered an error if it contains both "error" and "id" fields.

Examples

iex> message = %{"jsonrpc" => "2.0", "error" => %{"code" => -32600}, "id" => 1}
iex> is_error(message)
true

Guard to check if a request is an initialize request.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "initialize", "id" => 1, "params" => %{}}
iex> is_initialize(message)
true

Guard to check if a message is part of the initialization lifecycle.

This includes both the initialize request and the notifications/initialized notification.

Examples

iex> init_request = %{"jsonrpc" => "2.0", "method" => "initialize", "id" => 1, "params" => %{}}
iex> is_initialize_lifecycle(init_request)
true

iex> init_notification = %{"jsonrpc" => "2.0", "method" => "notifications/initialized"}
iex> is_initialize_lifecycle(init_notification)
true

iex> other_message = %{"jsonrpc" => "2.0", "method" => "tools/list", "id" => 2}
iex> is_initialize_lifecycle(other_message)
false

Guard to determine if a JSON-RPC message is a notification.

A message is considered a notification if it contains a "method" field but no "id" field.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "notification"}
iex> is_notification(message)
true

iex> request = %{"jsonrpc" => "2.0", "method" => "ping", "id" => 1}
iex> is_notification(request)
false

Guard to check if a request is a ping request.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "ping", "id" => 1}
iex> is_ping(message)
true

Guard to determine if a JSON-RPC message is a request.

A message is considered a request if it contains both "method" and "id" fields.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "ping", "id" => 1}
iex> is_request(message)
true

iex> notification = %{"jsonrpc" => "2.0", "method" => "notification"}
iex> is_request(notification)
false

Guard to determine if a JSON-RPC message is a response.

A message is considered a response if it contains both "result" and "id" fields.

Examples

iex> message = %{"jsonrpc" => "2.0", "result" => %{}, "id" => 1}
iex> is_response(message)
true

Returns the standard progress notification parameters schema for 2024-11-05.

Returns the progress notification parameters schema for 2025-03-26 (with message field).

Validates a decoded JSON message to ensure it complies with the MCP schema.