SuperPi.MCP.Transport behaviour (super_pi v0.1.0)

Copy Markdown View Source

How SuperPi.MCP.Client talks to one MCP server. The client owns the protocol (handshake, request ids, timeouts); a transport only moves JSON-RPC messages.

A transport runs inside the client process and keeps its state in a term the client holds. Whatever the transport spawns (a port, an HTTP request task) sends its results to the client process as ordinary messages. The client hands every message it does not know to handle_info/2, which turns it into JSON-RPC messages or reports that the server is gone.

Built in: SuperPi.MCP.Transport.Stdio (a child process) and SuperPi.MCP.Transport.StreamableHTTP (a URL).

Summary

Types

message()
state()

Callbacks

close(state)

Releases the transport's resources.

handle_info(state, term)

Handles a message sent to the owner. Returns the JSON-RPC messages it carried, :ignore for a message that carries none, or :closed when the server is gone.

protocol_version()

The protocolVersion the client offers in initialize over this transport.

send_message(state, message)

Sends one JSON-RPC message. Never waits for the answer: it arrives through handle_info/2.

start(opts)

Opens the transport. The calling process is the owner and receives its messages.

Types

message()

@type message() :: map()

state()

@type state() :: term()

Callbacks

close(state)

@callback close(state()) :: :ok

Releases the transport's resources.

handle_info(state, term)

@callback handle_info(state(), term()) ::
  {:messages, [message()], state()}
  | {:ignore, state()}
  | {:closed, term(), state()}

Handles a message sent to the owner. Returns the JSON-RPC messages it carried, :ignore for a message that carries none, or :closed when the server is gone.

protocol_version()

@callback protocol_version() :: String.t()

The protocolVersion the client offers in initialize over this transport.

send_message(state, message)

@callback send_message(state(), message()) :: state()

Sends one JSON-RPC message. Never waits for the answer: it arrives through handle_info/2.

start(opts)

@callback start(opts :: keyword()) :: {:ok, state()} | {:error, term()}

Opens the transport. The calling process is the owner and receives its messages.