Module mcp 

shuyi mcp: the tool contract as an MCP server over stdio (ADR-0005 §2, ADR-0031), and shuyi mcp install, which registers it with the agents it finds (install).

Each operation of the contract is a tool, its input the operation’s input (crate::contract::op_schemas), its answer the operation’s Answer. The tools that run the game take project, the game’s folder, from the session’s folder (the client’s first root, or the server’s working folder); the session folder’s own project if it is left out. A project in another cargo workspace than the server’s is answered by that workspace’s own server (forward).

A session keeps one game running headless between calls, so an agent can play it, look at it and play on:

Tool	Does	Answers as
start	builds the game’s tool program and starts its game as its options say	StartOutput
step	plays a script, then runs idle frames	run’s answer
scene	the scene on screen now; with path one value of its data, with shape its shape	scene’s answer
frame_png	a picture of the frame now, as an image	FramePngOutput and the PNG
events	what happened since the start	EventsOutput
perf	the frames’ records since a number, and their summary; a heap snapshot and a diff between two	PerfOutput
reset	the game started again as start started it	StartOutput
stop	the game stopped	StopOutput

start with session starts from a session record instead, played to its end, and reset plays it again.

start with link attaches the session to a debug build already running in its window instead, over the live link (attached).

The one-off scene operation is the session’s scene here: run answers with the scene of a one-off run.

The server runs no game itself. A tool that runs the game runs it in the game’s tool program (shuyi.ron’s game), started with cargo run as shuyi mcp-host (host); the session keeps that program running until stop, so start builds the game’s latest code. A failed answer is an MCP error result with the answer as it is, its code and its help.

Modules

aside

A running server’s program moved aside, so the next build can write a fresh one (ticket 2545).

attached

The session over the live link (ADR-0047): start with link attaches the session to a debug build already running in its window, and the session tools play a player’s input on it and read it as attach does, through attach’s own connection. Nothing else in the build changes: reset is refused, and stop detaches and leaves it running.

child

The game’s tool program as the server’s host: cargo run of the program shuyi.ron names, as shuyi mcp-host, with pipes to its stdin and stdout. What it writes to stderr (the compiler’s errors, a panic) goes on to the server’s stderr, and its last lines go into the error when it stops before it answers.

forward

The projects’ own servers (ticket 2546): a call whose project is in another cargo workspace than the server’s goes to a shuyi mcp built from that workspace’s engine, a forwarded server, so an agent in a worktree plays and checks the worktree’s code, whichever checkout the client started the server in.

host

The game’s side of shuyi mcp: shuyi mcp-host, run in the game’s tool program, answers the server’s Requests, one JSON line each on stdin, with a Reply line each on stdout, after the mark REPLY. It answers the operations that run the game with the game’s tools, and keeps the session’s game (Host).

install

shuyi mcp install: registers the server with the agents it finds, in each one’s project file of MCP servers, in the project’s folder (or the working folder outside one). It shows what changes and asks before writing, and keeps each file it changes as <file>.bak, then runs the entry it wrote with --ready, so the server is built before an agent first connects and waits for it. --dry-run writes nothing and prints each file as it would write it.

server

The MCP server: JSON-RPC 2.0 messages, one per line (Server::handle), the methods initialize, ping, tools/list and tools/call, and the session.

Structs

EventsOutput

What events saw.

FramePngInput

How frame_png paints the frame.

FramePngOutput

What frame_png painted (the picture itself is the tool’s image).

NoInput

A session tool’s input that takes nothing.

PerfInput

Which of the session’s frames’ records perf reads.

PerfOutput

What perf read of the session’s frames.

SceneInput

What the session’s scene answers beyond the scene: one value of its data, or its data’s shape, either in place of the scene.

StartInput

What start starts.

StartLink

The running build start attaches to: its log line shuyi link: listening on <address>, token <token> gives both.

StartOption

A start option the game offers.

StartOutput

What start and reset started.

StepInput

What step plays.

StopOutput

What stop stopped.

Constants

KEPT_SNAPSHOTS

How many heap snapshots a session keeps for perf’s diff_from: the last, by frame.

PERF_MAX

How many records perf answers when its input doesn’t say.

Functions

base64

bytes in standard base64, with padding: how MCP carries an image.

main

shuyi mcp with args, in the working folder cwd: the server on this process’s stdin and stdout, or install. Returns the exit code.

serve

Serves MCP messages from input, one per line, writing each message the server has for one on a line of its own, and the notification that its tools changed when they do (server::Server::poll), until input ends.

takes_project

Whether the tool of op takes project: the operations that run the game, and lint, modules and add.

tool

The tool named name: its operation, and whether it is a session tool (Op::SESSION).

tools

Every tool, as tools/list lists them: the operations (Op::ALL, the one-off scene left out), then the session’s (Op::SESSION).

usage

The usage of shuyi mcp, with command as the tool’s name.