jsonrpc

Documentation

Overview

Package jsonrpc is an internal framing helper for JSON-RPC 2.0 requests and responses. It is the private abstraction underneath the `mcp+http(s)://` EXEC scheme and the `txco mcp doctor` CLI; it deliberately exposes no transport, no client, no policy.

Per internal docs/todo-mcp.md §8 there is no public `json-rpc+https://` scheme. Callers that need one in the future promote this package into a scheme rather than re-extracting the framing.

Index

• func Call(id int, method string, params []byte) ([]byte, error)
• func ExtractSSE(body []byte) []byte
• func Notify(method string, params []byte) ([]byte, error)
• type Error
  • func (e *Error) Error() string
• type Notification
• type Request
• type Response
  • func Parse(body []byte) (Response, error)

Functions

func Call

func Call(id int, method string, params []byte) ([]byte, error)

Call marshals a single JSON-RPC 2.0 request with a numeric id. params may be nil (no params) or a pre-encoded JSON value (object or array).

func ExtractSSE

func ExtractSSE(body []byte) []byte

ExtractSSE pulls the first complete `event: message` frame's data from a Server-Sent Events body and returns the JSON-RPC payload it carries. MCP streamable-HTTP servers may respond to a single POST with either `application/json` (callers use Parse directly) or `text/event-stream` (callers extract via this helper first, then Parse).

SSE framing per https://html.spec.whatwg.org/multipage/server-sent-events.html: lines beginning `event:` set the event name (default "message"); `data:` lines are joined with newlines; a blank line dispatches a frame. This helper handles only the request/response case (one frame, one event); long-lived streams are out of scope.

Returns an empty byte slice with no error if no `message` frame is found — the caller then surfaces it as a JSON decode error from Parse, which is consistent with other malformed-body behavior.

func Notify

func Notify(method string, params []byte) ([]byte, error)

Notify marshals a JSON-RPC 2.0 notification (no `id`, no response expected on the wire).

Types

type Error

type Error struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

Error is the wire-shape JSON-RPC error object plus implements the Go error interface so callers handle a Result.Error returned by Parse with the same `if err != nil` idiom as a transport error.

func (*Error) Error

func (e *Error) Error() string

type Notification

type Notification struct {
	JSONRPC string          `json:"jsonrpc"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Notification models a JSON-RPC 2.0 notification (no `id`, no response). Used for `notifications/initialized` and the other `notifications/*` methods.

type Request

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int             `json:"id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request models a JSON-RPC 2.0 request or notification. A notification omits ID by serializing with ID == 0 — callers that need true notification semantics (no response) should use Notification instead, which omits the field entirely.

type Response

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int             `json:"id"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *Error          `json:"error,omitempty"`
}

Response is the decoded JSON-RPC 2.0 reply.

func Parse

func Parse(body []byte) (Response, error)

Parse decodes a JSON-RPC response body. Returns the decoded Response and a non-nil error when the body is not valid JSON or when the server returned a JSON-RPC error object (so callers handle both shapes uniformly).