feat: initial mcp-retroarch project — MCP server for RetroArch

RetroArch's Network Control Interface (NCI) is a text-based UDP
protocol on port 55355 that ships with every RetroArch build. This
project is a thin TypeScript MCP server that translates MCP tool
calls into NCI commands, so any MCP client (Claude Desktop, Claude
Code, etc.) can drive any libretro core — read/write memory, save/
load state, pause/frame-advance/reset, take screenshots, and show
on-screen messages.

- src/retroarch.ts: serial UDP client for the NCI text protocol
- src/tools.ts: 17 MCP tools covering memory r/w (system map +
  CHEEVOS), save/load state suite, emulator control, screenshot,
  show-message, get-config
- src/index.ts: stdio MCP entry; configurable target via
  RETROARCH_HOST / RETROARCH_PORT env vars

End-to-end verified against RetroArch 1.22.2 with the mGBA core
loaded on totp-gba-test:
  GET_STATUS returned game_boy_advance + game name + CRC32
  READ_CORE_MEMORY at 0x0000 returned the GBA's interrupt vectors
    (recognizable as ARM "ea" branch instructions)
  READ_CORE_RAM at 0x0000 returned a different address space
    (CHEEVOS), confirming both paths are wired up correctly
  SHOW_MSG rendered a notification on the RetroArch overlay

Honest scope: the NCI doesn't expose game-pad input — only menu
navigation and hotkeys. Controller injection requires the separate
"Remote RetroPad" core on UDP port 55400+, which is out of scope for
v0.1.0. For input + screenshot on Game Boy Advance, see mcp-mgba.

Author: dmang-dev

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: build (node ${{ matrix.node }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - name: Install
+        run: npm ci --ignore-scripts
+
+      - name: Type-check & build
+        run: npm run build
+
+      - name: Verify shebang and bin
+        shell: bash
+        run: |
+          head -1 dist/index.js | grep -q '^#!/usr/bin/env node$'
+          test -f dist/index.js
+          test -f dist/retroarch.js
+          test -f dist/tools.js
+          echo "build artifacts OK"

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.js.map
+.rstk/
+.scratch/
+*.png

CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-10
+
+Initial public release.
+
+### Added
+
+- **UDP client (`src/retroarch.ts`)** for RetroArch's text-based Network
+  Control Interface. Serial-by-default (one query in flight at a time)
+  to keep matching simple — the NCI doesn't carry request IDs and
+  matching by command-name echo is fragile.
+- **MCP server (`dist/index.js`)** with eager probe at startup; tools
+  start working as soon as RetroArch is reachable.
+- **17 MCP tools**: `retroarch_ping`, `retroarch_get_status`,
+  `retroarch_get_config`, `retroarch_read_memory` /
+  `retroarch_write_memory` (system memory map), `retroarch_read_ram` /
+  `retroarch_write_ram` (CHEEVOS fallback), `retroarch_pause_toggle`,
+  `retroarch_frame_advance`, `retroarch_reset`, `retroarch_screenshot`,
+  `retroarch_show_message`, save/load state suite (current slot, explicit
+  slot, slot pointer +/-).
+- **Configurable target** via `RETROARCH_HOST` and `RETROARCH_PORT` env
+  vars.
+- **Cross-platform install** via `npm install -g mcp-retroarch`,
+  `npx -y mcp-retroarch`, or clone-and-build.
+- **GitHub Actions CI** matrix on Node 18/20/22 across
+  Linux / macOS / Windows.
+
+### Known limitations
+
+- **Game-pad input not exposed.** The NCI doesn't expose
+  controller-button injection — only RetroArch hotkeys (pause, reset,
+  state slots, etc.). RetroArch has a separate "Remote RetroPad" core
+  on UDP port 55400+ that does, but it requires loading that specific
+  core, which means you can't drive a normal libretro emulation core
+  through it. Out of scope for v0.1.0; may revisit.
+- **Save-state slot targeting is two-step.** NCI's `SAVE_STATE` only
+  saves to the currently-selected slot. To save to slot N, walk the
+  slot pointer to N first via `state_slot_plus` / `state_slot_minus`.
+
+[Unreleased]: https://github.com/dmang-dev/mcp-retroarch/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dmang-dev/mcp-retroarch/releases/tag/v0.1.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dmang-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,169 @@
+# mcp-retroarch
+
+[![npm version](https://img.shields.io/npm/v/mcp-retroarch.svg)](https://www.npmjs.com/package/mcp-retroarch)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-retroarch.svg)](https://www.npmjs.com/package/mcp-retroarch)
+[![CI](https://github.com/dmang-dev/mcp-retroarch/actions/workflows/ci.yml/badge.svg)](https://github.com/dmang-dev/mcp-retroarch/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/mcp-retroarch.svg)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server that bridges Claude (and any other MCP client) to [RetroArch](https://www.retroarch.com/) via its built-in **Network Control Interface** (UDP, port 55355).
+
+Works against any libretro core (NES, SNES, Genesis, GB/GBC/GBA, PSX, N64, etc.) — give the model memory r/w, save-state automation, screenshot, pause / frame-advance / reset, and on-screen messages.
+
+## What it can do
+
+| Capability | Available? | Notes |
+|---|---|---|
+| Memory read / write | ✅ | Two paths: `READ_CORE_MEMORY` (system memory map, preferred) and `READ_CORE_RAM` (CHEEVOS, fallback) |
+| Save / load state | ✅ | Current slot or explicit slot for load; save is current-slot-only (NCI limitation) |
+| Screenshot | ✅ | Saved to RetroArch's configured screenshot directory |
+| Pause / frame advance | ✅ | `PAUSE_TOGGLE` flips state; `FRAMEADVANCE` steps one frame |
+| Reset | ✅ | Hard-reset the running game |
+| On-screen message | ✅ | Useful for "look here" cues during scripted runs |
+| Game info | ✅ | Title, system, CRC32 |
+| **Game-pad input** | ❌ | **NCI doesn't expose this.** RetroArch has a separate "Remote RetroPad" core on UDP port 55400 that does, but it requires loading that specific core (you can't drive an existing emulation core through it). Not in scope for v0.1.0. |
+
+If you need game-pad input on Game Boy Advance specifically, see [mcp-mgba](https://github.com/dmang-dev/mcp-mgba). For PCSX2 (memory + savestate only, no input/screenshot), see [mcp-pine](https://github.com/dmang-dev/mcp-pine).
+
+## How it works
+
+```
++----------------+    stdio     +-----------------+   UDP :55355  +-----------------+
+|   MCP client   |   JSON-RPC   |  mcp-retroarch  |  text proto   |    RetroArch    |
+|  (Claude etc)  | -----------> |    (Node.js)    | ------------> |  (NCI enabled)  |
++----------------+              +-----------------+               +-----------------+
+```
+
+## Requirements
+
+- **RetroArch** (any recent version) with Network Commands enabled
+- **Node.js 18+**
+
+## Install
+
+### Option A — install from npm (recommended)
+
+```bash
+npm install -g mcp-retroarch
+```
+
+### Option B — `npx` (no install)
+
+```bash
+npx -y mcp-retroarch
+```
+
+### Option C — clone and develop
+
+```bash
+git clone https://github.com/dmang-dev/mcp-retroarch
+cd mcp-retroarch
+npm install
+```
+
+## Enable RetroArch's Network Control Interface
+
+Either:
+- **GUI:** Settings → Network → Network Commands → **ON**, then confirm `Network Cmd Port` is `55355` (the default)
+- **Or via `retroarch.cfg`:**
+  ```ini
+  network_cmd_enable = "true"
+  network_cmd_port   = "55355"
+  ```
+
+Then launch any libretro core + game. The NCI is always-on once enabled — no script to load.
+
+## Register with your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add retroarch --scope user mcp-retroarch
+```
+
+Verify:
+```bash
+claude mcp list
+# retroarch: mcp-retroarch - ✓ Connected
+```
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+| Platform | Path |
+|---|---|
+| macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows  | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux    | `~/.config/Claude/claude_desktop_config.json` |
+
+```json
+{
+  "mcpServers": {
+    "retroarch": {
+      "command": "mcp-retroarch"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+## Configuration
+
+| Env var             | Default       | Purpose |
+|---------------------|---------------|---------|
+| `RETROARCH_HOST`    | `127.0.0.1`   | UDP destination host |
+| `RETROARCH_PORT`    | `55355`       | UDP port (must match `network_cmd_port` in `retroarch.cfg`) |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `retroarch_ping` | Verify reachability — returns RetroArch version |
+| `retroarch_get_status` | State (playing/paused), system, game, CRC32 |
+| `retroarch_get_config` | Read named RetroArch config values (e.g. `savestate_directory`) |
+| `retroarch_read_memory` / `retroarch_write_memory` | Memory r/w via system memory map |
+| `retroarch_read_ram` / `retroarch_write_ram` | Memory r/w via CHEEVOS address space (fallback when no memory map) |
+| `retroarch_pause_toggle` | Toggle pause state |
+| `retroarch_frame_advance` | Step one frame (only effective while paused) |
+| `retroarch_reset` | Hardware-reset the running game |
+| `retroarch_screenshot` | Save a screenshot to RetroArch's screenshot directory |
+| `retroarch_show_message` | Display a notification on the RetroArch window |
+| `retroarch_save_state_current` | Save to currently-selected slot |
+| `retroarch_load_state_current` | Load from currently-selected slot |
+| `retroarch_load_state_slot` | Load from explicit slot number |
+| `retroarch_state_slot_plus` / `retroarch_state_slot_minus` | Change current slot pointer (NCI has no "set slot to N") |
+
+See [`docs/RECIPES.md`](docs/RECIPES.md) for end-to-end examples.
+
+## Troubleshooting
+
+| Symptom | Cause / Fix |
+|---|---|
+| `RetroArch query timed out` | Network Commands aren't enabled in RetroArch, or the port doesn't match `RETROARCH_PORT`. Confirm `network_cmd_enable = "true"` in `retroarch.cfg`. |
+| `READ_CORE_MEMORY failed: no memory map defined` | The loaded libretro core doesn't advertise a system memory map. Try `retroarch_read_ram` (CHEEVOS path) — many cores expose CHEEVOS even without a memory map. |
+| `READ_CORE_MEMORY failed: no descriptor for address` | The address isn't covered by the core's memory map. Either a different core would expose it, or the address you want is outside the system bus (e.g. video memory in some cores). |
+| Screenshots don't appear where I expect | RetroArch saves to its configured screenshot directory. The NCI doesn't expose `screenshot_directory` via `GET_CONFIG_PARAM`, so check the value via RetroArch's GUI: Settings → Directory → Screenshot. |
+| Can't save to a specific state slot directly | NCI limitation, not a bug. The protocol only exposes "save to current slot" — you have to walk the slot pointer to your target with `state_slot_plus`/`state_slot_minus`, then save. |
+
+## Development
+
+```bash
+npm install
+npm run dev      # tsc --watch
+```
+
+Smoke test against a running RetroArch:
+```bash
+node .scratch/smoke.cjs
+```
+
+## License
+
+[MIT](LICENSE)
+
+## Related
+
+- [mcp-mgba](https://github.com/dmang-dev/mcp-mgba) — Game Boy Advance via mGBA's Lua bridge (includes button input + screenshot)
+- [mcp-pine](https://github.com/dmang-dev/mcp-pine) — PINE-speaking emulators (PCSX2 et al.) — memory + savestate only
+- [RetroArch NCI documentation](https://docs.libretro.com/development/retroarch/network-control-interface/)