mcp-mgba 0.1.0

package/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.

package/README.md

@@ -0,0 +1,186 @@
+# mcp-mgba
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the [mGBA](https://mgba.io) Game Boy Advance emulator to any MCP-compatible client (Claude Desktop, Claude Code, etc.).
+
+Lets your model **read and write GBA memory, inject button presses, take screenshots, and step the emulator** — all through a clean tool interface.
+
+![demo](docs/demo.gif)
+
+*Claude driving an in-development homebrew side-scroller through `mgba_press_buttons` — Start to begin, A to confirm New Game, then Right to walk and A to jump. Each frame is captured via `mgba_screenshot`.*
+
+## How it works
+
+```
++------------------+    stdio     +------------------+   TCP :8765   +------------------+
+|   MCP client     |   JSON-RPC   |     mcp-mgba     |  newline JSON |  mGBA emulator   |
+| (Claude / etc.)  | ===========> |     (Node.js)    | ============> |    bridge.lua    |
++------------------+              +------------------+               +------------------+
+```
+
+Two pieces:
+- **`lua/bridge.lua`** — runs *inside* mGBA's scripting engine, opens a loopback TCP server on port 8765
+- **`dist/index.js`** — Node.js MCP server, talks to the Lua bridge over TCP, exposes tools over stdio
+
+## Requirements
+
+- [mGBA](https://mgba.io/downloads.html) **0.10 or newer** (with Lua scripting)
+- **Node.js 18+** (for the MCP server)
+
+## Install
+
+### Option A — clone and install globally (recommended for now)
+
+```bash
+git clone https://github.com/dmang-dev/mcp-mgba
+cd mcp-mgba
+npm install -g .
+```
+
+That puts `mcp-mgba` on your `PATH` (the build runs automatically via `npm install`'s `prepare` hook). Verify with `mcp-mgba --help` (it'll print a startup line and wait for stdio — `Ctrl+C` to exit).
+
+### Option B — clone without global install
+
+```bash
+git clone https://github.com/dmang-dev/mcp-mgba
+cd mcp-mgba
+npm install        # runs the build automatically
+```
+
+Then reference the absolute path to `dist/index.js` when registering.
+
+### Option C — `npx` from GitHub (no clone needed)
+
+```bash
+npx -y github:dmang-dev/mcp-mgba
+```
+
+`npx` will fetch, build (via `prepare`), and run the server in one shot.
+
+## Set up the mGBA bridge
+
+1. Launch mGBA and load any GBA ROM.
+2. Open **Tools > Scripting…**
+3. Click **File > Load script** and select `lua/bridge.lua` from this repo.
+
+You should see in the scripting console:
+```
+[mcp-mgba] bridge listening on 127.0.0.1:8765
+[mcp-mgba] frame callback registered — bridge is active
+```
+
+If you see a `bind failed` error, the previous instance's socket is still held — quit and relaunch mGBA.
+
+## Register with your MCP client
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add mgba --scope user mcp-mgba
+```
+
+(if you used Option B without global install, replace `mcp-mgba` with `node /absolute/path/to/dist/index.js`)
+
+Verify:
+```bash
+claude mcp list
+# mgba: mcp-mgba - ✓ 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` |
+
+Add (assuming Option A — globally installed):
+```json
+{
+  "mcpServers": {
+    "mgba": {
+      "command": "mcp-mgba"
+    }
+  }
+}
+```
+
+Or with explicit Node + path (Option B):
+```json
+{
+  "mcpServers": {
+    "mgba": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-mgba/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+### Other MCP clients
+
+The server speaks standard MCP over stdio. Run `mcp-mgba` (or `node dist/index.js`) and connect any MCP client to its stdio.
+
+## Configuration
+
+| Env var     | Default       | Purpose                |
+|-------------|---------------|------------------------|
+| `MGBA_HOST` | `127.0.0.1`   | Bridge host to dial    |
+| `MGBA_PORT` | `8765`        | Bridge port to dial    |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `mgba_ping` | Verify bridge connectivity (returns `pong`) |
+| `mgba_get_info` | Game title, code, frame count |
+| `mgba_read8` / `mgba_read16` / `mgba_read32` | Read memory at an address |
+| `mgba_write8` / `mgba_write16` / `mgba_write32` | Write to RAM |
+| `mgba_read_range` | Read up to 4096 bytes as a byte array |
+| `mgba_press_buttons` | Hold GBA buttons for N frames |
+| `mgba_advance_frames` | Step the emulator N frames |
+| `mgba_pause` / `mgba_unpause` | Pause / resume emulation |
+| `mgba_reset` | Reset the loaded ROM |
+| `mgba_screenshot` | Save a PNG of the current display |
+
+### GBA button names
+
+`A`, `B`, `Select`, `Start`, `Right`, `Left`, `Up`, `Down`, `R`, `L`
+
+### GBA address space (cheat sheet)
+
+| Range          | Region                        |
+|----------------|-------------------------------|
+| `0x02000000`   | EWRAM (256 KiB, general)      |
+| `0x03000000`   | IWRAM (32 KiB, fast)          |
+| `0x04000000`   | I/O registers                 |
+| `0x05000000`   | Palette RAM                   |
+| `0x06000000`   | VRAM                          |
+| `0x07000000`   | OAM                           |
+| `0x08000000`   | ROM (read-only)               |
+
+## Troubleshooting
+
+| Symptom | Cause / Fix |
+|---|---|
+| `Cannot reach mGBA bridge at 127.0.0.1:8765` | mGBA isn't running, or `bridge.lua` isn't loaded — open Tools > Scripting and load it |
+| `bind failed — port 8765 may already be in use` | A previous mGBA instance still holds the socket; quit and relaunch mGBA |
+| Tool calls hang | The bridge script may have errored out silently after a hot-reload — check the mGBA scripting console |
+| Tools missing in Claude after install | Restart your MCP client; Claude only enumerates servers on startup |
+
+## Development
+
+```bash
+npm install
+npm run dev      # tsc --watch — autobuilds on src/ changes
+```
+
+The Lua side (`lua/bridge.lua` and `lua/json.lua`) needs no build step. Edit and reload via mGBA's `File > Load script`.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { MgbaClient } from "./mgba.js";
+import { registerTools } from "./tools.js";
+const HOST = process.env.MGBA_HOST ?? "127.0.0.1";
+const PORT = parseInt(process.env.MGBA_PORT ?? "8765", 10);
+async function main() {
+    const mgba = new MgbaClient(HOST, PORT);
+    // Connect eagerly — if mGBA isn't running the server still starts, but
+    // each tool call will return a clear "not connected" error rather than
+    // crashing the MCP host.
+    try {
+        await mgba.connect();
+        process.stderr.write(`[mcp-mgba] connected to mGBA bridge at ${HOST}:${PORT}\n`);
+    }
+    catch (err) {
+        process.stderr.write(`[mcp-mgba] WARNING: could not connect to mGBA bridge (${HOST}:${PORT}): ${err}\n` +
+            `           Start mGBA, load a ROM, then open Tools > Scripting and run lua/bridge.lua.\n`);
+    }
+    const server = new Server({ name: "mcp-mgba", version: "0.1.0" }, { capabilities: { tools: {} } });
+    registerTools(server, mgba);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("[mcp-mgba] MCP server ready (stdio)\n");
+}
+main().catch((err) => {
+    process.stderr.write(`[mcp-mgba] fatal: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,WAAW,CAAC;AAClD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;AAE3D,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAExC,uEAAuE;IACvE,uEAAuE;IACvE,yBAAyB;IACzB,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0CAA0C,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC;IACnF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yDAAyD,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI;YAClF,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EACtC,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;AAChE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/mgba.d.ts

@@ -0,0 +1,28 @@
+export interface RpcRequest {
+    id: number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface RpcResponse {
+    id: number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export declare class MgbaClient {
+    private readonly host;
+    private readonly port;
+    private socket;
+    private pending;
+    private nextId;
+    private buf;
+    private connectPromise;
+    constructor(host?: string, port?: number);
+    connect(): Promise<void>;
+    disconnect(): void;
+    get connected(): boolean;
+    call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+}
+//# sourceMappingURL=mgba.d.ts.map

package/dist/mgba.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mgba.d.ts","sourceRoot":"","sources":["../src/mgba.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,qBAAa,UAAU;IAQnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IARvB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,OAAO,CAAiD;IAChE,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,cAAc,CAA8B;gBAGjC,IAAI,GAAE,MAAoB,EAC1B,IAAI,GAAE,MAAa;IAGtC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoDxB,UAAU,IAAI,IAAI;IAMlB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;CAwCd"}

package/dist/mgba.js

@@ -0,0 +1,110 @@
+import net from "net";
+export class MgbaClient {
+    host;
+    port;
+    socket = null;
+    pending = new Map();
+    nextId = 1;
+    buf = "";
+    connectPromise = null;
+    constructor(host = "127.0.0.1", port = 8765) {
+        this.host = host;
+        this.port = port;
+    }
+    connect() {
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = new Promise((resolve, reject) => {
+            const sock = net.createConnection({ host: this.host, port: this.port });
+            sock.setEncoding("utf8");
+            sock.once("connect", () => {
+                this.socket = sock;
+                resolve();
+            });
+            sock.once("error", (err) => {
+                this.connectPromise = null;
+                reject(err);
+            });
+            sock.on("data", (chunk) => {
+                this.buf += chunk;
+                let nl;
+                while ((nl = this.buf.indexOf("\n")) !== -1) {
+                    const line = this.buf.slice(0, nl).trim();
+                    this.buf = this.buf.slice(nl + 1);
+                    if (line.length === 0)
+                        continue;
+                    let resp;
+                    try {
+                        resp = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (resp.id != null) {
+                        const cb = this.pending.get(resp.id);
+                        if (cb) {
+                            this.pending.delete(resp.id);
+                            cb(resp);
+                        }
+                    }
+                }
+            });
+            sock.on("close", () => {
+                this.socket = null;
+                this.connectPromise = null;
+                // Reject all in-flight calls
+                for (const cb of this.pending.values()) {
+                    cb({ id: null, error: { code: -1, message: "connection closed" } });
+                }
+                this.pending.clear();
+            });
+        });
+        return this.connectPromise;
+    }
+    disconnect() {
+        this.socket?.destroy();
+        this.socket = null;
+        this.connectPromise = null;
+    }
+    get connected() {
+        return this.socket !== null && !this.socket.destroyed;
+    }
+    async call(method, params) {
+        // Lazy (re)connect — bridge.lua reloads kill the socket, and the user
+        // shouldn't have to restart the MCP host every time they edit the script.
+        if (!this.socket || this.socket.destroyed) {
+            try {
+                await this.connect();
+            }
+            catch (err) {
+                throw new Error(`Cannot reach mGBA bridge at ${this.host}:${this.port}. ` +
+                    `Make sure mGBA is running with bridge.lua loaded (Tools > Scripting). ` +
+                    `Underlying error: ${err.message}`);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const sock = this.socket;
+            if (!sock) {
+                reject(new Error("socket vanished after connect"));
+                return;
+            }
+            const id = this.nextId++;
+            this.pending.set(id, (resp) => {
+                if (resp.error) {
+                    reject(new Error(`mGBA RPC error [${resp.error.code}]: ${resp.error.message}`));
+                }
+                else {
+                    resolve(resp.result);
+                }
+            });
+            const msg = JSON.stringify({ id, method, params: params ?? {} }) + "\n";
+            sock.write(msg, (err) => {
+                if (err) {
+                    this.pending.delete(id);
+                    reject(err);
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=mgba.js.map

package/dist/mgba.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mgba.js","sourceRoot":"","sources":["../src/mgba.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,4 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { MgbaClient } from "./mgba.js";
+export declare function registerTools(server: Server, mgba: MgbaClient): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AA0LvC,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CA+FpE"}

package/dist/tools.js

@@ -0,0 +1,258 @@
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// GBA memory map landmarks (useful in tool descriptions)
+const GBA_REGIONS = `
+GBA address space:
+  0x02000000  EWRAM  (256 KiB, general-purpose)
+  0x03000000  IWRAM  (32 KiB, fast stack/variables)
+  0x04000000  IO registers
+  0x05000000  Palette RAM (1 KiB)
+  0x06000000  VRAM (96 KiB)
+  0x07000000  OAM (1 KiB)
+  0x08000000  ROM (up to 32 MiB, read-only)`.trim();
+const VALID_KEYS = ["A", "B", "Select", "Start", "Right", "Left", "Up", "Down", "R", "L"];
+// ── Tool definitions ─────────────────────────────────────────────────────────
+const TOOLS = [
+    {
+        name: "mgba_ping",
+        description: "Check connectivity to the mGBA bridge. Returns 'pong' if the emulator is running and the Lua bridge is loaded.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "mgba_get_info",
+        description: "Get the currently-loaded game title, game code (e.g. AGBE), and frame count.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "mgba_read8",
+        description: `Read a single unsigned byte (u8) from a GBA memory address.\n\n${GBA_REGIONS}`,
+        inputSchema: {
+            type: "object",
+            required: ["address"],
+            properties: {
+                address: {
+                    type: "integer",
+                    description: "GBA memory address (decimal or hex — use 0x prefix in JSON strings, or pass as decimal integer)",
+                },
+            },
+        },
+    },
+    {
+        name: "mgba_read16",
+        description: "Read an unsigned 16-bit little-endian value from a GBA memory address. Address should be 2-byte aligned.",
+        inputSchema: {
+            type: "object",
+            required: ["address"],
+            properties: {
+                address: { type: "integer", description: "GBA memory address (must be 2-byte aligned)" },
+            },
+        },
+    },
+    {
+        name: "mgba_read32",
+        description: "Read an unsigned 32-bit little-endian value from a GBA memory address. Address should be 4-byte aligned.",
+        inputSchema: {
+            type: "object",
+            required: ["address"],
+            properties: {
+                address: { type: "integer", description: "GBA memory address (must be 4-byte aligned)" },
+            },
+        },
+    },
+    {
+        name: "mgba_write8",
+        description: "Write a single byte value to a GBA memory address. Only works on RAM regions (EWRAM, IWRAM). Writing to ROM has no effect.",
+        inputSchema: {
+            type: "object",
+            required: ["address", "value"],
+            properties: {
+                address: { type: "integer", description: "GBA RAM address" },
+                value: { type: "integer", minimum: 0, maximum: 255, description: "Byte value (0–255)" },
+            },
+        },
+    },
+    {
+        name: "mgba_write16",
+        description: "Write a 16-bit value to a GBA memory address (little-endian). Address must be 2-byte aligned.",
+        inputSchema: {
+            type: "object",
+            required: ["address", "value"],
+            properties: {
+                address: { type: "integer", description: "GBA RAM address (2-byte aligned)" },
+                value: { type: "integer", minimum: 0, maximum: 65535, description: "16-bit value (0–65535)" },
+            },
+        },
+    },
+    {
+        name: "mgba_write32",
+        description: "Write a 32-bit value to a GBA memory address (little-endian). Address must be 4-byte aligned.",
+        inputSchema: {
+            type: "object",
+            required: ["address", "value"],
+            properties: {
+                address: { type: "integer", description: "GBA RAM address (4-byte aligned)" },
+                value: { type: "integer", minimum: 0, description: "32-bit value" },
+            },
+        },
+    },
+    {
+        name: "mgba_read_range",
+        description: "Read a contiguous range of bytes from GBA memory and return them as an array of integers. Maximum 4096 bytes per call.",
+        inputSchema: {
+            type: "object",
+            required: ["address", "length"],
+            properties: {
+                address: { type: "integer", description: "Start address" },
+                length: { type: "integer", minimum: 1, maximum: 4096, description: "Number of bytes to read" },
+            },
+        },
+    },
+    {
+        name: "mgba_press_buttons",
+        description: `Press one or more GBA buttons for a given number of frames. Valid button names: ${VALID_KEYS.join(", ")}.`,
+        inputSchema: {
+            type: "object",
+            required: ["buttons"],
+            properties: {
+                buttons: {
+                    type: "array",
+                    items: { type: "string", enum: VALID_KEYS },
+                    description: "List of button names to hold simultaneously",
+                },
+                frames: {
+                    type: "integer",
+                    minimum: 1,
+                    default: 1,
+                    description: "Number of frames to hold the buttons (at 60 fps; default 1)",
+                },
+            },
+        },
+    },
+    {
+        name: "mgba_advance_frames",
+        description: "Advance emulation by N frames without returning to the event loop. Useful for precise timing in tests.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                count: { type: "integer", minimum: 1, default: 1, description: "Number of frames to advance (default 1)" },
+            },
+        },
+    },
+    {
+        name: "mgba_pause",
+        description: "Pause emulation.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "mgba_unpause",
+        description: "Resume emulation after a pause.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "mgba_reset",
+        description: "Reset the currently-loaded ROM (equivalent to pressing the GBA reset button).",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "mgba_screenshot",
+        description: "Take a screenshot of the current GBA display and save it to a file. Returns the saved file path.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Absolute file path to save the PNG (optional — defaults to a temp file)",
+                },
+            },
+        },
+    },
+];
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function formatHex(n) {
+    if (typeof n !== "number")
+        return String(n);
+    return `${n} (0x${n.toString(16).toUpperCase()})`;
+}
+// ── Registration ─────────────────────────────────────────────────────────────
+export function registerTools(server, mgba) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args = {} } = req.params;
+        const p = args;
+        switch (name) {
+            case "mgba_ping": {
+                const r = await mgba.call("ping");
+                return ok(r);
+            }
+            case "mgba_get_info": {
+                const r = await mgba.call("get_info");
+                return ok(`Title: ${r.title}\nCode:  ${r.code}\nFrame: ${r.frame}`);
+            }
+            case "mgba_read8": {
+                const v = await mgba.call("read8", { address: p.address });
+                return ok(`0x${p.address.toString(16).toUpperCase()}: ${formatHex(v)}`);
+            }
+            case "mgba_read16": {
+                const v = await mgba.call("read16", { address: p.address });
+                return ok(`0x${p.address.toString(16).toUpperCase()}: ${formatHex(v)}`);
+            }
+            case "mgba_read32": {
+                const v = await mgba.call("read32", { address: p.address });
+                return ok(`0x${p.address.toString(16).toUpperCase()}: ${formatHex(v)}`);
+            }
+            case "mgba_write8": {
+                await mgba.call("write8", { address: p.address, value: p.value });
+                return ok(`Wrote ${formatHex(p.value)} → 0x${p.address.toString(16).toUpperCase()}`);
+            }
+            case "mgba_write16": {
+                await mgba.call("write16", { address: p.address, value: p.value });
+                return ok(`Wrote ${formatHex(p.value)} → 0x${p.address.toString(16).toUpperCase()}`);
+            }
+            case "mgba_write32": {
+                await mgba.call("write32", { address: p.address, value: p.value });
+                return ok(`Wrote ${formatHex(p.value)} → 0x${p.address.toString(16).toUpperCase()}`);
+            }
+            case "mgba_read_range": {
+                const bytes = await mgba.call("read_range", {
+                    address: p.address,
+                    length: p.length,
+                });
+                const hex = bytes
+                    .map((b) => b.toString(16).padStart(2, "0").toUpperCase())
+                    .join(" ");
+                const addr = p.address.toString(16).toUpperCase();
+                return ok(`0x${addr} [${bytes.length} bytes]:\n${hex}`);
+            }
+            case "mgba_press_buttons": {
+                await mgba.call("press_buttons", { buttons: p.buttons, frames: p.frames ?? 1 });
+                const keys = p.buttons.join("+");
+                return ok(`Pressed ${keys} for ${p.frames ?? 1} frame(s)`);
+            }
+            case "mgba_advance_frames": {
+                const frame = await mgba.call("advance_frames", { count: p.count ?? 1 });
+                return ok(`Advanced ${p.count ?? 1} frame(s). Current frame: ${frame}`);
+            }
+            case "mgba_pause": {
+                await mgba.call("pause");
+                return ok("Emulation paused");
+            }
+            case "mgba_unpause": {
+                await mgba.call("unpause");
+                return ok("Emulation resumed");
+            }
+            case "mgba_reset": {
+                await mgba.call("reset");
+                return ok("ROM reset");
+            }
+            case "mgba_screenshot": {
+                const path = await mgba.call("screenshot", p.path ? { path: p.path } : {});
+                return ok(`Screenshot saved: ${path}`);
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/lua/bridge.lua

@@ -0,0 +1,246 @@
+-- bridge.lua: mGBA scripting bridge for mcp-mgba
+--
+-- Exposes a newline-delimited JSON-RPC server on 127.0.0.1:8765.
+-- Load via mGBA: Tools > Scripting... > Open Script (select this file).
+--
+-- json.lua must live in the same folder as this file.
+-- socket is a pre-registered global in mGBA's Lua environment.
+--
+-- mGBA socket API (discovered via metatable probe):
+--   bind, listen, accept, connect, send, receive, hasdata, poll, _hook
+--
+-- Requires mGBA >= 0.10.
+
+local json = require("json")
+
+local HOST = "127.0.0.1"
+local PORT = 8765
+
+-- ── GBA key name → bitmask bit index ────────────────────────────────────────
+local KEY_BIT = {
+    A = 0, B = 1, Select = 2, Start = 3,
+    Right = 4, Left = 5, Up = 6, Down = 7,
+    R = 8, L = 9,
+}
+
+-- ── Per-frame key-hold state ─────────────────────────────────────────────────
+local hold_bits   = 0
+local hold_frames = 0
+
+-- ── Command handlers ─────────────────────────────────────────────────────────
+
+local function cmd_ping()     return "pong" end
+local function cmd_get_info()
+    return { title = emu:getGameTitle(), code = emu:getGameCode(), frame = emu:currentFrame() }
+end
+
+-- emu:read8/16/32 are flaky when called repeatedly via pcall from the frame
+-- callback ("invoking failed" intermittently). emu:readRange is reliable, so
+-- we route the typed reads through it and decode little-endian on the Lua side.
+local function cmd_read8(p)
+    local raw = emu:readRange(assert(p.address, "address required"), 1)
+    return raw:byte(1)
+end
+local function cmd_read16(p)
+    local raw = emu:readRange(assert(p.address, "address required"), 2)
+    return raw:byte(1) | (raw:byte(2) << 8)
+end
+local function cmd_read32(p)
+    local raw = emu:readRange(assert(p.address, "address required"), 4)
+    return raw:byte(1) | (raw:byte(2) << 8) | (raw:byte(3) << 16) | (raw:byte(4) << 24)
+end
+
+-- emu:writeN — like emu:readN — intermittently throws "invoking failed" when
+-- pcall'd from a frame callback. Retry up to a few times before giving up.
+local function retry_call(fn, ...)
+    local attempts = 8
+    local last_err
+    for _ = 1, attempts do
+        local ok, err = pcall(fn, ...)
+        if ok then return true end
+        last_err = err
+    end
+    error(last_err)
+end
+
+local function cmd_write8(p)
+    local addr = assert(p.address, "address required")
+    local val  = assert(p.value,   "value required")
+    retry_call(function() emu:write8(addr, val) end)
+    return true
+end
+local function cmd_write16(p)
+    local addr = assert(p.address, "address required")
+    local val  = assert(p.value,   "value required")
+    retry_call(function() emu:write16(addr, val) end)
+    return true
+end
+local function cmd_write32(p)
+    local addr = assert(p.address, "address required")
+    local val  = assert(p.value,   "value required")
+    retry_call(function() emu:write32(addr, val) end)
+    return true
+end
+
+local function cmd_read_range(p)
+    local addr = assert(p.address, "address required")
+    local len  = assert(p.length,  "length required")
+    if len > 4096 then error("length exceeds 4096 byte limit") end
+    local raw   = emu:readRange(addr, len)
+    local bytes = {}
+    for i = 1, #raw do bytes[i] = raw:byte(i) end
+    return bytes
+end
+
+local function cmd_press_buttons(p)
+    local keys = assert(p.buttons, "buttons required")
+    local bits = 0
+    for _, name in ipairs(keys) do
+        local b = KEY_BIT[name]
+        if not b then error("unknown key: " .. tostring(name)) end
+        bits = bits | (1 << b)
+    end
+    hold_bits   = bits
+    hold_frames = p.frames or 1
+    return true
+end
+
+local function cmd_advance_frames(p)
+    local n = p.count or 1
+    for _ = 1, n do emu:frameAdvance() end
+    return emu:currentFrame()
+end
+
+local function cmd_pause()   emu:pause();   return true end
+local function cmd_unpause() emu:unpause(); return true end
+local function cmd_reset()   emu:reset();   return true end
+
+local function cmd_screenshot(p)
+    local path = p.path or (os.tmpname() .. ".png")
+    -- mGBA's emu:screenshot takes the destination path directly and writes
+    -- the PNG itself; it does not return an image object.
+    emu:screenshot(path)
+    return path
+end
+
+-- ── Dispatch table ───────────────────────────────────────────────────────────
+
+local HANDLERS = {
+    ping           = cmd_ping,
+    get_info       = cmd_get_info,
+    read8          = cmd_read8,
+    read16         = cmd_read16,
+    read32         = cmd_read32,
+    write8         = cmd_write8,
+    write16        = cmd_write16,
+    write32        = cmd_write32,
+    read_range     = cmd_read_range,
+    press_buttons  = cmd_press_buttons,
+    advance_frames = cmd_advance_frames,
+    pause          = cmd_pause,
+    unpause        = cmd_unpause,
+    reset          = cmd_reset,
+    screenshot     = cmd_screenshot,
+}
+
+local function dispatch(cmd)
+    if not cmd.method then
+        return nil, { code = -32600, message = "missing method field" }
+    end
+    local handler = HANDLERS[cmd.method]
+    if not handler then
+        return nil, { code = -32601, message = "unknown method: " .. cmd.method }
+    end
+    local ok, result = pcall(handler, cmd.params or {})
+    if not ok then
+        return nil, { code = -32603, message = tostring(result) }
+    end
+    return result, nil
+end
+
+-- ── Process one client's buffer — call after appending new data ──────────────
+
+local function process_buffer(c)
+    while true do
+        local nl = c.buf:find("\n", 1, true)
+        if not nl then break end
+
+        local line = c.buf:sub(1, nl - 1)
+        c.buf      = c.buf:sub(nl + 1)
+
+        if #line > 0 then
+            local parse_ok, cmd = pcall(json.decode, line)
+            local response
+            if parse_ok and type(cmd) == "table" then
+                local result, rpc_err = dispatch(cmd)
+                if rpc_err then
+                    response = { id = cmd.id, error = rpc_err }
+                else
+                    response = { id = cmd.id, result = result }
+                end
+            else
+                response = { id = nil, error = { code = -32700, message = "parse error" } }
+            end
+            c.sock:send(json.encode(response) .. "\n")
+        end
+    end
+end
+
+-- ── Server socket ────────────────────────────────────────────────────────────
+
+local server = assert(socket.tcp(), "socket.tcp() failed")
+assert(server:bind(HOST, PORT), "bind failed — port " .. PORT .. " may already be in use")
+assert(server:listen(),         "listen failed")
+
+-- Active client table: array of { sock, buf }
+local clients = {}
+
+-- ── Per-frame callback ───────────────────────────────────────────────────────
+
+callbacks:add("frame", function()
+
+    -- Key hold
+    if hold_frames > 0 then
+        emu:setKeys(hold_bits)
+        hold_frames = hold_frames - 1
+        if hold_frames == 0 then emu:setKeys(0) end
+    end
+
+    -- poll() flushes the socket's internal event queue. Without it, accept()
+    -- and hasdata() see stale state and never observe new I/O.
+    server:poll()
+    local client = server:accept()
+    if client then
+        console:log("[mcp-mgba] client connected")
+        table.insert(clients, { sock = client, buf = "" })
+    end
+
+    -- Service existing clients
+    local i = 1
+    while i <= #clients do
+        local c = clients[i]
+        c.sock:poll()
+        if c.sock:hasdata() then
+            -- mGBA's receive(maxBytes) reads up to maxBytes — non-blocking
+            -- when guarded by hasdata(). Wrap in pcall so any internal error
+            -- doesn't spam the console every frame.
+            local ok, data = pcall(function() return c.sock:receive(4096) end)
+            if ok and data and #data > 0 then
+                c.buf = c.buf .. data
+                process_buffer(c)
+                i = i + 1
+            elseif ok and data == nil then
+                console:log("[mcp-mgba] client disconnected")
+                table.remove(clients, i)
+            else
+                console:log("[mcp-mgba] receive error: " .. tostring(data))
+                table.remove(clients, i)
+            end
+        else
+            i = i + 1
+        end
+    end
+end)
+
+console:log(string.format("[mcp-mgba] bridge listening on %s:%d", HOST, PORT))
+console:log("[mcp-mgba] frame callback registered — bridge is active")

package/lua/json.lua

@@ -0,0 +1,200 @@
+-- json.lua: minimal JSON encode/decode for mGBA's Lua environment
+-- Supports objects, arrays, strings, numbers, booleans, null.
+-- No external dependencies.
+
+local json = {}
+
+-- ── Encoder ─────────────────────────────────────────────────────────────────
+
+local escape_map = {
+    ['"']  = '\\"',
+    ['\\'] = '\\\\',
+    ['\n'] = '\\n',
+    ['\r'] = '\\r',
+    ['\t'] = '\\t',
+}
+
+local function encode_string(s)
+    return '"' .. s:gsub('["\\\n\r\t]', escape_map) .. '"'
+end
+
+local encode_value  -- forward declaration
+
+local function encode_array(t, n)
+    local parts = {}
+    for i = 1, n do parts[i] = encode_value(t[i]) end
+    return "[" .. table.concat(parts, ",") .. "]"
+end
+
+local function encode_object(t)
+    local parts = {}
+    for k, v in pairs(t) do
+        parts[#parts + 1] = encode_string(tostring(k)) .. ":" .. encode_value(v)
+    end
+    return "{" .. table.concat(parts, ",") .. "}"
+end
+
+encode_value = function(v)
+    local tv = type(v)
+    if tv == "nil"     then return "null"
+    elseif tv == "boolean" then return tostring(v)
+    elseif tv == "number"  then
+        -- integers stay integers, floats keep decimals
+        if v ~= v then return "null" end          -- NaN guard
+        if v == math.huge or v == -math.huge then return "null" end
+        if math.floor(v) == v then return string.format("%d", v) end
+        return string.format("%.17g", v)
+    elseif tv == "string" then
+        return encode_string(v)
+    elseif tv == "table" then
+        -- detect array: sequential integer keys starting at 1
+        local n = #v
+        local is_arr = (n > 0)
+        if is_arr then
+            for k in pairs(v) do
+                if type(k) ~= "number" or k < 1 or k > n or math.floor(k) ~= k then
+                    is_arr = false; break
+                end
+            end
+        else
+            -- empty table with no keys → emit as object {}
+            local has_keys = false
+            for _ in pairs(v) do has_keys = true; break end
+            if not has_keys then return "{}" end
+        end
+        return is_arr and encode_array(v, n) or encode_object(v)
+    end
+    return "null"
+end
+
+function json.encode(v)
+    return encode_value(v)
+end
+
+-- ── Decoder ──────────────────────────────────────────────────────────────────
+
+local function skip_ws(s, i)
+    while i <= #s do
+        local c = s:sub(i, i)
+        if c == ' ' or c == '\t' or c == '\n' or c == '\r' then
+            i = i + 1
+        else
+            break
+        end
+    end
+    return i
+end
+
+local decode_value  -- forward declaration
+
+local function decode_string(s, i)
+    -- i points to the opening '"'
+    i = i + 1
+    local buf = {}
+    while i <= #s do
+        local c = s:sub(i, i)
+        if c == '"' then
+            return table.concat(buf), i + 1
+        elseif c == '\\' then
+            local e = s:sub(i + 1, i + 1)
+            if     e == '"'  then buf[#buf+1] = '"';  i = i + 2
+            elseif e == '\\' then buf[#buf+1] = '\\'; i = i + 2
+            elseif e == '/'  then buf[#buf+1] = '/';  i = i + 2
+            elseif e == 'n'  then buf[#buf+1] = '\n'; i = i + 2
+            elseif e == 'r'  then buf[#buf+1] = '\r'; i = i + 2
+            elseif e == 't'  then buf[#buf+1] = '\t'; i = i + 2
+            elseif e == 'b'  then buf[#buf+1] = '\b'; i = i + 2
+            elseif e == 'f'  then buf[#buf+1] = '\f'; i = i + 2
+            elseif e == 'u'  then
+                -- \uXXXX — keep raw for now (ASCII subset only needed)
+                local hex = s:sub(i + 2, i + 5)
+                local cp  = tonumber(hex, 16)
+                if cp and cp < 128 then
+                    buf[#buf+1] = string.char(cp)
+                else
+                    buf[#buf+1] = '?' -- non-ASCII placeholder
+                end
+                i = i + 6
+            else
+                buf[#buf+1] = e; i = i + 2
+            end
+        else
+            buf[#buf+1] = c; i = i + 1
+        end
+    end
+    error("json: unterminated string at " .. i)
+end
+
+local function decode_number(s, i)
+    -- grab the full number token
+    local j = i
+    if s:sub(j, j) == '-' then j = j + 1 end
+    while j <= #s and s:sub(j, j):match('%d') do j = j + 1 end
+    if j <= #s and s:sub(j, j) == '.' then
+        j = j + 1
+        while j <= #s and s:sub(j, j):match('%d') do j = j + 1 end
+    end
+    if j <= #s and s:sub(j, j):match('[eE]') then
+        j = j + 1
+        if j <= #s and s:sub(j, j):match('[+-]') then j = j + 1 end
+        while j <= #s and s:sub(j, j):match('%d') do j = j + 1 end
+    end
+    return tonumber(s:sub(i, j - 1)), j
+end
+
+local function decode_object(s, i)
+    local t = {}
+    i = skip_ws(s, i + 1)  -- skip '{'
+    if s:sub(i, i) == '}' then return t, i + 1 end
+    while true do
+        i = skip_ws(s, i)
+        local k; k, i = decode_string(s, i)
+        i = skip_ws(s, i)
+        if s:sub(i, i) ~= ':' then error("json: expected ':' at " .. i) end
+        i = skip_ws(s, i + 1)
+        local v; v, i = decode_value(s, i)
+        t[k] = v
+        i = skip_ws(s, i)
+        local c = s:sub(i, i)
+        if     c == '}' then return t, i + 1
+        elseif c == ',' then i = i + 1
+        else error("json: expected ',' or '}' at " .. i) end
+    end
+end
+
+local function decode_array(s, i)
+    local t = {}
+    i = skip_ws(s, i + 1)  -- skip '['
+    if s:sub(i, i) == ']' then return t, i + 1 end
+    while true do
+        i = skip_ws(s, i)
+        local v; v, i = decode_value(s, i)
+        t[#t + 1] = v
+        i = skip_ws(s, i)
+        local c = s:sub(i, i)
+        if     c == ']' then return t, i + 1
+        elseif c == ',' then i = i + 1
+        else error("json: expected ',' or ']' at " .. i) end
+    end
+end
+
+decode_value = function(s, i)
+    i = skip_ws(s, i)
+    if i > #s then error("json: unexpected end of input") end
+    local c = s:sub(i, i)
+    if     c == '"' then return decode_string(s, i)
+    elseif c == '{' then return decode_object(s, i)
+    elseif c == '[' then return decode_array(s, i)
+    elseif c == 't' then return true,  i + 4
+    elseif c == 'f' then return false, i + 5
+    elseif c == 'n' then return nil,   i + 4
+    elseif c == '-' or c:match('%d') then return decode_number(s, i)
+    else error("json: unexpected character '" .. c .. "' at " .. i) end
+end
+
+function json.decode(s)
+    local v, _ = decode_value(s, 1)
+    return v
+end
+
+return json

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "mcp-mgba",
+  "version": "0.1.0",
+  "description": "MCP server that bridges Claude to the mGBA Game Boy Advance emulator via Lua scripting",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mcp-mgba": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "lua/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"import('node:fs').then(fs => fs.chmodSync('dist/index.js', 0o755))\"",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepare": "npm run build",
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmang-dev/mcp-mgba.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dmang-dev/mcp-mgba/issues"
+  },
+  "homepage": "https://github.com/dmang-dev/mcp-mgba#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mgba",
+    "gba",
+    "game-boy-advance",
+    "emulator",
+    "lua"
+  ]
+}