Caravela.MCP.Protocol (Caravela v0.11.0)

Copy Markdown View Source

JSON-RPC 2.0 message encoding, decoding, and builders for the Caravela MCP server.

Stdio MCP transport is one JSON message per line: every frame is serialized with a trailing newline; every incoming line parses as a complete message. No Content-Length framing (that's the LSP convention, not MCP's).

The standard error codes follow JSON-RPC 2.0:

  • -32700 Parse error — invalid JSON was received
  • -32600 Invalid Request — not a valid request object
  • -32601 Method not found
  • -32602 Invalid params
  • -32603 Internal error

Summary

Functions

decode(line)

Decode a single JSON-RPC message from a line of input. Returns {:ok, map} on success or {:error, reason} on malformed JSON.

encode(message)

Encode a message as a newline-terminated JSON string.

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

Build a JSON-RPC 2.0 error response. code is a JSON-RPC error code (see moduledoc); data is an optional arbitrary term attached to help the client diagnose.

internal_error(id, detail)

Shorthand: -32603 internal error.

invalid_params(id, detail)

Shorthand: -32602 invalid params.

invalid_request(id \\ nil)

Shorthand: -32600 invalid request.

method_not_found(id, method)

Shorthand: -32601 method not found.

parse_error(id \\ nil)

Shorthand: -32700 parse error response.

request?(arg1)

True if the request carries an id field (i.e. expects a response).

response(id, result)

Build a JSON-RPC 2.0 success response.

Functions

decode(line)

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

Decode a single JSON-RPC message from a line of input. Returns {:ok, map} on success or {:error, reason} on malformed JSON.

encode(message)

@spec encode(map()) :: iodata()

Encode a message as a newline-terminated JSON string.

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

@spec error(term(), integer(), String.t(), term()) :: map()

Build a JSON-RPC 2.0 error response. code is a JSON-RPC error code (see moduledoc); data is an optional arbitrary term attached to help the client diagnose.

internal_error(id, detail)

@spec internal_error(term(), String.t()) :: map()

Shorthand: -32603 internal error.

invalid_params(id, detail)

@spec invalid_params(term(), String.t()) :: map()

Shorthand: -32602 invalid params.

invalid_request(id \\ nil)

@spec invalid_request(term()) :: map()

Shorthand: -32600 invalid request.

method_not_found(id, method)

@spec method_not_found(term(), String.t()) :: map()

Shorthand: -32601 method not found.

parse_error(id \\ nil)

@spec parse_error(term()) :: map()

Shorthand: -32700 parse error response.

request?(arg1)

@spec request?(map()) :: boolean()

True if the request carries an id field (i.e. expects a response).

response(id, result)

@spec response(term(), map() | list() | String.t() | number() | boolean() | nil) ::
  map()

Build a JSON-RPC 2.0 success response.