pureikyubu — the MCP server

What it is

MCP (the Model Context Protocol) is how an agent application — Claude Desktop, Claude Code, an IDE, a script of your own — uses a program as a set of tools. The server of this emulator speaks the protocol over its own stdin/stdout (the "local server" transport: the client starts the emulator, one JSON-RPC message per line), and the tools it publishes are the commands of the debug interface, described by the specifications the emulator already carries.

MCP client  -- stdio -->  pureikyubu --mcp  -->  the Json Debug Interface  -->  the emulator
     |                          |
     |  tools/call "memdump"    +--> the window stays open and usable (windowed builds)
     +--------------------------+--> no window at all (the headless build)

Command	Meaning
`pureikyubu --mcp`	Start the local MCP server. A file on the command line is loaded and run first, so the client attaches to a running game.
`mcp 1` / `mcp 0`	Start or stop it at run time from the debugger console; `mcp` alone reports whether it is running.
`McpRequest <json>`	The whole protocol as one debug command: a message in, a message out. The transport is only a carrier of those answers.

Connect a client

A client that starts its servers as child processes is configured with the executable and --mcp. The headless build is the one to use for an unattended run; a windowed build works the same way when you want to watch (and use) the emulator yourself.

{
  "mcpServers": {
    "pureikyubu": {
      "command": "C:\\pureikyubu\\pureikyubu_headless.exe",
      "args": ["--mcp"]
    }
  }
}

There is no port, no listener and no authentication: the server is a child process of its client, so whoever started it is the only thing that can talk to it. One client at a time.

The tools

Around 150 commands are published before a machine is loaded and around 170 after: the nodes that belong to the emulated hardware (the Flipper, the GFX pipeline, the disc drive) appear once a file is running. Every tool carries the help text and the usage of the command, the arguments taken from the command's own specification, and a description of what it answers.

Control

load, unload, reset, run, stop, IsLoaded, GetLoaded, MountIso, OpenLid, DvdRead, DumpFst.

The Gekko debugger

r (registers), regs (a Markdown dump), b/bc (breakpoints), u, GekkoDisasm, syms, NameByAddress, dtlb, nop.

The DSP

dregs, dreg, dmem, imem, du (disassembly), dbrk, dspjit, dspmbox.

The hardware

memdump (main memory as Markdown), ramload, gx (the whole GFX pipeline state), gxregs, gxtex, gxpixel, gxshot (a PNG), hwprofile (the interface profiler).

tools/call  load       { "args": ["D:\\Isos\\zelda.iso"] }
tools/call  run        {}
tools/call  r          { "args": ["pc"] }
tools/call  qd         {}                       <- the debug message queue (the output of `r`)
tools/call  memdump    { "address": "0x80000000", "lines": "16" }
tools/call  gxshot     { "filename": "frame.png" }
tools/call  hwprofile  { "value": "text" }

The arguments may be named (from the hints of the command: <address> <lines>) or handed over as the whole command line in args. A command that only reports — and most of the debugger's commands do — answers nothing; its report is in the debug message queue, which the qd tool reads.

Why it is built this way

Nothing new to learn

The server does not implement a second interface: it publishes the one the debugger, the console and the front ends already use. A command that works in the console works as a tool, and a command added to the emulator tomorrow appears in the tool list by itself.

The protocol is a command

McpRequest takes one MCP message and answers with the message the server produced, so the protocol can be driven (and tested) without any transport at all — and the stdio server is a hundred-line reader on top of it.

An agent is a client, not a user

A failed command is reported as a failed tool, with the usage of the command, so the model can correct itself and the session survives. Only an unknown tool name is a protocol error.

Limits

No HTTP or SSE transport, no resources, no prompts, no sampling: this is the local transport of the specification and the tools are what the emulator has. The commands that end the process (exit and its aliases) are deliberately not tools — a tool call would kill the server in the middle of its own answer; the client closes the stream instead, and the emulator shuts down by itself. An answer of a tool call is capped at 4 MB of text, because a command like FileLoad would otherwise turn a whole binary file into Json and push it into the context of the model.

Documentation

Wiki: the MCP server

The whole page: the protocol in one page, how a specification becomes a tool, what a tool call answers, and what the server is not.

The tests

testing/mcp_test.cpp: the handshake, the errors of the protocol, the tool table over a node of its own and over every specification the emulator ships.

The debug interface

wiki/main.md describes the emulator's control surface and the command line; the commands themselves are declared in src/jdispecs.cpp and listed by help in the debugger console.

The MCP server