ConduitMcp.Protocol (ConduitMCP v0.9.4)

Copy Markdown View Source

JSON-RPC 2.0 message construction and MCP protocol version negotiation.

ConduitMCP targets MCP spec 2025-11-25 as the primary version and also accepts clients on 2025-06-18 for backward compatibility. protocol_version/0 returns the preferred version; negotiate_version/1 resolves a client's requested version to one the server supports.

Building responses

Helpers success_response/2, error_response/3,4, and notification/2 produce the right wire shape — string-keyed maps with "jsonrpc", "id", and either "result" or "error". validate_request/1 performs lightweight shape checking on incoming messages.

Error codes

Standard JSON-RPC 2.0 codes and MCP-specific codes are exposed as delegating functions to ConduitMcp.Errors:

Use these instead of hardcoded integers so error code constants stay in one place.

Examples

iex> ConduitMcp.Protocol.success_response(1, %{"value" => 42})
%{"jsonrpc" => "2.0", "id" => 1, "result" => %{"value" => 42}}

iex> ConduitMcp.Protocol.error_response(1, -32601, "no such method")
%{"jsonrpc" => "2.0", "id" => 1, "error" => %{"code" => -32601, "message" => "no such method"}}

Summary

Types

error_object()
error_response()
json_rpc_id()
method()
notification()
request()
response()
success_response()

Functions

error_response(id, code, message, data \\ nil)

Creates an error response.

internal_error()

See ConduitMcp.Errors.internal_error/0.

invalid_params()

See ConduitMcp.Errors.invalid_params/0.

invalid_request()

See ConduitMcp.Errors.invalid_request/0.

method_not_found()

See ConduitMcp.Errors.method_not_found/0.

methods()

Core MCP methods as defined in the specification.

negotiate_version(client_version)

Returns the best matching protocol version for the given client version. Returns nil if no compatible version is found.

notification(method, params \\ nil)

Creates a notification message.

parse_error()

See ConduitMcp.Errors.parse_error/0.

protocol_version()
resource_not_found()

See ConduitMcp.Errors.resource_not_found/0.

success_response(id, result)

Creates a success response.

supported_versions()
valid_notification?(message)

Validates if a message is a valid JSON-RPC 2.0 notification.

valid_request?(message)

Validates if a message is a valid JSON-RPC 2.0 request.

Types

error_object()

@type error_object() :: %{code: integer(), message: String.t(), data: any() | nil}

error_response()

@type error_response() :: %{
  jsonrpc: String.t(),
  id: json_rpc_id(),
  error: error_object()
}

json_rpc_id()

@type json_rpc_id() :: String.t() | integer()

method()

@type method() :: String.t()

notification()

@type notification() :: %{jsonrpc: String.t(), method: method(), params: map() | nil}

request()

@type request() :: %{
  jsonrpc: String.t(),
  id: json_rpc_id(),
  method: method(),
  params: map() | nil
}

response()

@type response() :: success_response() | error_response()

success_response()

@type success_response() :: %{jsonrpc: String.t(), id: json_rpc_id(), result: any()}

Functions

error_response(id, code, message, data \\ nil)

Creates an error response.

internal_error()

See ConduitMcp.Errors.internal_error/0.

invalid_params()

See ConduitMcp.Errors.invalid_params/0.

invalid_request()

See ConduitMcp.Errors.invalid_request/0.

method_not_found()

See ConduitMcp.Errors.method_not_found/0.

methods()

Core MCP methods as defined in the specification.

negotiate_version(client_version)

Returns the best matching protocol version for the given client version. Returns nil if no compatible version is found.

notification(method, params \\ nil)

Creates a notification message.

parse_error()

See ConduitMcp.Errors.parse_error/0.

protocol_version()

resource_not_found()

See ConduitMcp.Errors.resource_not_found/0.

success_response(id, result)

Creates a success response.

supported_versions()

valid_notification?(message)

Validates if a message is a valid JSON-RPC 2.0 notification.

valid_request?(message)

Validates if a message is a valid JSON-RPC 2.0 request.