OzMcp.Transport.Stdio (OzMcp v0.9.0)

Copy Markdown View Source

The MCP stdio transport: newline-delimited JSON-RPC on stdin and stdout.

The transport serves one client that starts the process as a subprocess. Each line of stdin carries one JSON-RPC message; each message the server sends is written as one line of UTF-8 text on stdout. Nothing else may write to stdout: logs and stray prints belong on stderr (OzMcp.Transport.Stdio.Console prepares the devices and the Mix task mix oz_mcp.stdio calls it). The transport holds one session with no id on the wire: the first initialize creates it, the end of stdin ends it. A request that is not cheap (tools/call, resources/read, ...) runs in a process of its own, so a callback that waits for the client does not block the reading of the next lines; the cheap methods (initialize, ping, notifications, the answers of the client) run in the transport process, in the order of the lines.

Authorization is not used on stdio: the client owns the process of the server. A server that declares an authorization block runs open — no principal, no scope check, no filter on the lists (see OzMcp.Auth).

From any code, run/2 runs a server on stdio and blocks until the connection ends; start_link/1 starts the transport process alone, for a test or an entry of its own. The lifecycle, the refusals, the ordering of the lines and the limits are in the guide stdio transport.

The end of the connection

  • The end of stdin starts a drain: the transport waits for the requests in flight, up to :drain_timeout_ms (default 1000), then it ends the session and stops normally.
  • A failed write to stdout, or a failure of the reader of stdin (a read function that raises, or one that returns {:error, reason}), stops the transport with an error: no answer can reach, or no line will ever arrive.
  • The transport monitors the session process. When it stops (a crash, for example), the transport writes an error on stderr and stops with {:shutdown, :session_lost}. The Mix task then exits with code 1 and a message that names the case.
  • A request that gets -32001 for the session of the connection (the instance lost the session) writes its error line first and the transport then stops with {:shutdown, :session_lost}: each later request would get the same error.

Summary

Functions

Returns a specification to start this module under a supervisor.

Runs a server on stdio and blocks until the connection ends. The options and the result values are in the guide stdio transport; the caller prepares the :read and :write functions, so run/2 itself changes no global state. When an instance with the name :instance runs, the transport joins it; when it does not run, run/2 starts one in the stdio mode, with the server module and :server_opts.

Functions

child_spec(init_arg)

@spec child_spec(keyword()) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See Supervisor.

run(server, opts)

@spec run(module(), keyword()) :: :ok | {:error, term()}

Runs a server on stdio and blocks until the connection ends. The options and the result values are in the guide stdio transport; the caller prepares the :read and :write functions, so run/2 itself changes no global state. When an instance with the name :instance runs, the transport joins it; when it does not run, run/2 starts one in the stdio mode, with the server module and :server_opts.

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()