ryubing-mcp

ryubing-mcp is a local Model Context Protocol server for automating the Ryubing Nintendo Switch emulator.

This repository contains the MCP server, its versioned bridge protocol, tests, and live smoke-test scripts. A companion opt-in Ryubing control-bridge patch is implemented on the local feature/mcp-control-bridge upstream branch and must be present in the Ryubing binary used by this server.

Tool surface

Every emulator-control tool accepts an optional sessionId. Omit it to target the externally started default bridge, or pass an ID returned by ryubing_create_session to control one of several concurrent processes.

Only use game and update files you are legally entitled to use. This project does not provide games, firmware, title keys, or decryption keys.

Related MCP server: algorithmaide-mcp

Development

Prerequisites: Node.js 20 or newer.

npm install
npm run typecheck
npm test
npm run build

Run the server over stdio:

npm run dev

Example MCP client configuration after building:

{
  "mcpServers": {
    "ryubing": {
      "command": "node",
      "args": ["D:/workspace/____personal____/ryubing-mcp/dist/index.js"],
      "env": {
        "RYUBING_CONTROL_TOKEN": "replace-with-the-same-random-token-used-by-ryubing",
        "RYUBING_ALLOWED_GAME_DIRS": "D:/Games/Switch"
      }
    }
  }
}

Configuration

All three managed-session paths are required before ryubing_create_session is enabled. On Windows, the server uses a one-time token file inside the new profile because GUI processes started by the interactive shell do not inherit the MCP host environment; patched Ryubing deletes that file immediately after reading it. Profiles are retained by default when a session stops.

Live verification

With a patched build already running on the configured default port:

npm run smoke:live

For two fully managed processes, set the managed-session variables plus RYUBING_LIVE_BASE_A, RYUBING_LIVE_UPDATE_A, and RYUBING_LIVE_BASE_B, then:

npm run smoke:parallel

The parallel smoke test starts two isolated profiles, boots both titles, captures both rendered frames, and stops/removes the temporary sessions.

For design status and upstream integration points, see PDCA iteration 01, the live PDCA iteration 02, and the bridge protocol.