jsbeeb-mcp 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# jsbeeb-mcp
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that
+exposes a headless [BBC Micro emulator](https://github.com/mattgodbolt/jsbeeb)
+to AI assistants (Claude, Cursor, etc.).
+
+Write a BASIC program, run it, get the text output and a screenshot — all
+without opening a browser.
+
+## Setup
+
+```bash
+npm install
+```
+
+## Running
+
+```bash
+# via npx (no install needed)
+npx jsbeeb-mcp
+
+# or if installed globally
+npm install -g jsbeeb-mcp
+jsbeeb-mcp
+```
+
+## Connecting to Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "jsbeeb": {
+      "command": "npx",
+      "args": ["jsbeeb-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `run_basic` _(convenience — no session management needed)_
+
+One-shot: boot a BBC Micro, load a BASIC program, run it, return text output
+and an optional screenshot, then clean up.
+
+```json
+{
+  "source": "10 PRINT \"HELLO WORLD\"\n20 GOTO 10",
+  "model": "B-DFS1.2",
+  "timeout_secs": 10,
+  "screenshot": true
+}
+```
+
+### Session-based tools
+
+For multi-step interaction (debugging, iterative development):
+
+| Tool               | Description                                                    |
+| ------------------ | -------------------------------------------------------------- |
+| `create_machine`   | Boot a BBC Micro (B or Master), returns a `session_id`         |
+| `destroy_machine`  | Free a session                                                 |
+| `load_basic`       | Tokenise + load BBC BASIC source into PAGE                     |
+| `type_input`       | Type text at the current keyboard prompt (RETURN is automatic) |
+| `run_until_prompt` | Run until BASIC/OS prompt, return captured screen text         |
+| `screenshot`       | Capture the current screen as a PNG image                      |
+| `read_memory`      | Read bytes from the memory map (with hex dump)                 |
+| `write_memory`     | Poke bytes into memory                                         |
+| `read_registers`   | Get 6502 CPU registers (PC, A, X, Y, S, P)                     |
+| `run_for_cycles`   | Run exactly N 2MHz CPU cycles                                  |
+| `load_disc`        | Load an `.ssd`/`.dsd` disc image into drive 0                  |
+
+## What works
+
+- ✅ BBC BASIC programs (tokenised and loaded directly into memory)
+- ✅ Text output capture (position, colour, mode)
+- ✅ Screenshots (real Video chip output → PNG via `sharp`)
+- ✅ Memory read/write
+- ✅ CPU register inspection
+- ✅ BBC B and Master models
+- ✅ Multiple concurrent sessions
+- ✅ Disc image loading (`.ssd`/`.dsd`)
+
+## Known limitations
+
+- **Boot text**: the VDU capture hook is installed after the initial boot
+  completes, so the OS startup banner isn't captured. Everything after the
+  first `>` prompt is captured.
+- **No assembler built in**: to run machine code, poke it via `write_memory`
+  and `CALL` it from BASIC, or use the BBC's own inline assembler in BASIC.
+- **Sound**: the sound chip runs but produces no audio output (headless mode).
+
+## Architecture
+
+```
+server.js   # MCP server — tool definitions, session store
+examples/   # Standalone scripts demonstrating MachineSession directly
+```
+
+`MachineSession` lives in jsbeeb itself (`src/machine-session.js`) and is
+imported here as `jsbeeb/machine-session`. It wraps jsbeeb's `TestMachine`
+with a real `Video` instance (full video chip into a 1024×625 RGBA
+framebuffer), VDU text capture, and screenshot support via `sharp`.
+
+Framebuffer snapshots are taken inside the `paint_ext` vsync callback (before
+the buffer is cleared), ensuring screenshots always show a complete frame.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "jsbeeb-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for jsbeeb — lets AI assistants control a headless BBC Micro emulator",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "jsbeeb-mcp": "./server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "test": "node test-mcp-client.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "jsbeeb": "^1.3.2",
+    "sharp": "^0.34.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mattgodbolt/jsbeeb-mcp.git"
+  },
+  "keywords": ["bbc-micro", "mcp", "emulator", "jsbeeb", "ai"],
+  "author": "Matt Godbolt",
+  "license": "GPL-3.0-or-later"
+}

package/server.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+/**
+ * jsbeeb MCP Server
+ *
+ * Exposes a headless BBC Micro emulator to AI assistants via the Model
+ * Context Protocol.  Start it with:
+ *
+ *   node server.js
+ *
+ * and connect it from Claude Desktop, Cursor, or any MCP-compatible client
+ * by adding it to mcp_servers in the client config.
+ *
+ * Capabilities:
+ *   - Boot a BBC B or BBC Master
+ *   - Load and run BBC BASIC programs
+ *   - Type at the keyboard
+ *   - Capture text output
+ *   - Take screenshots (PNG, base64-encoded)
+ *   - Read/write memory
+ *   - Inspect CPU registers
+ *   - Persistent sessions (multiple machines at once)
+ *   - One-shot `run_basic` convenience tool (no session management needed)
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { MachineSession } from "jsbeeb/machine-session";
+
+// ---------------------------------------------------------------------------
+// Session store
+// ---------------------------------------------------------------------------
+
+const sessions = new Map(); // sessionId → MachineSession
+
+function requireSession(sessionId) {
+    const s = sessions.get(sessionId);
+    if (!s) throw new Error(`No session with id "${sessionId}". Call create_machine first.`);
+    return s;
+}
+
+function newSessionId() {
+    return crypto.randomUUID();
+}
+
+// ---------------------------------------------------------------------------
+// MCP server
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+    name: "jsbeeb",
+    version: "0.1.0",
+});
+
+// ---------------------------------------------------------------------------
+// Tool: create_machine
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "create_machine",
+    "Boot a BBC Micro emulator and return a session ID for use with all other tools. " +
+        "The machine runs until the BASIC prompt before this call returns.",
+    {
+        model: z
+            .enum(["B-DFS1.2", "B-DFS2.26", "Master", "Master-MOS3.20"])
+            .default("B-DFS1.2")
+            .describe("BBC Micro model to emulate"),
+        boot_timeout_secs: z.number().default(30).describe("Max seconds of emulated time to wait for the boot prompt"),
+    },
+    async ({ model, boot_timeout_secs }) => {
+        const session = new MachineSession(model);
+        await session.initialise();
+        const bootOutput = await session.boot(boot_timeout_secs);
+        const id = newSessionId();
+        sessions.set(id, session);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        session_id: id,
+                        model,
+                        boot_output: bootOutput,
+                    }),
+                },
+            ],
+        };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: destroy_machine
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "destroy_machine",
+    "Destroy a BBC Micro session and free its resources.",
+    { session_id: z.string().describe("Session ID from create_machine") },
+    async ({ session_id }) => {
+        const s = sessions.get(session_id);
+        if (s) {
+            s.destroy();
+            sessions.delete(session_id);
+        }
+        return { content: [{ type: "text", text: "Session destroyed." }] };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: load_disc
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "load_disc",
+    "Insert a disc image (.ssd or .dsd file) into drive 0 of the emulator. " +
+        "After loading, use type_input to issue DFS commands (e.g. '*RUN hello', '*DIR', 'CHAIN\"\"').",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        image_path: z.string().describe("Absolute path to an .ssd or .dsd disc image file"),
+    },
+    async ({ session_id, image_path }) => {
+        const session = requireSession(session_id);
+        await session.loadDisc(image_path);
+        return { content: [{ type: "text", text: `Disc image loaded: ${image_path}` }] };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: load_basic
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "load_basic",
+    "Tokenise BBC BASIC source code and load it into the emulator's PAGE memory, " +
+        "exactly as if you had typed it in and saved it. Does NOT run the program.",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        source: z.string().describe("BBC BASIC source code (plain text, BBC dialect)"),
+    },
+    async ({ session_id, source }) => {
+        const session = requireSession(session_id);
+        await session.loadBasic(source);
+        return { content: [{ type: "text", text: "BASIC program loaded into PAGE." }] };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: type_input
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "type_input",
+    "Type text at the current keyboard prompt (simulates key presses). " +
+        "A newline/RETURN is automatically sent after the text. " +
+        "Use run_until_prompt after this to collect output.",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        text: z.string().describe("Text to type (e.g. 'RUN' or '10 PRINT\"HELLO\"')"),
+    },
+    async ({ session_id, text }) => {
+        const session = requireSession(session_id);
+        await session.type(text);
+        return { content: [{ type: "text", text: `Typed: ${text}` }] };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: run_until_prompt
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "run_until_prompt",
+    "Run the emulator until it returns to a keyboard input prompt (e.g. the BASIC prompt after RUN completes). " +
+        "Returns all text output that was written to the screen since the last call.",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        timeout_secs: z.number().default(60).describe("Max emulated seconds to run before giving up"),
+        clear: z
+            .boolean()
+            .default(true)
+            .describe(
+                "If true (default), clear the output buffer after returning it. " +
+                    "Pass false to peek at accumulated output without consuming it.",
+            ),
+    },
+    async ({ session_id, timeout_secs, clear }) => {
+        const session = requireSession(session_id);
+        const output = await session.runUntilPrompt(timeout_secs, { clear });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(output),
+                },
+            ],
+        };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: screenshot
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "screenshot",
+    "Capture the current BBC Micro screen as a PNG image. " +
+        "Returns a base64-encoded PNG of the full 1024×625 emulated display. " +
+        "Tip: call run_until_prompt first to let the screen settle.",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        active_only: z
+            .boolean()
+            .default(true)
+            .describe("If true, crop to the active display area and apply 2× pixel scaling for clarity"),
+    },
+    async ({ session_id, active_only }) => {
+        const session = requireSession(session_id);
+        const png = active_only ? await session.screenshotActive() : await session.screenshot();
+        return {
+            content: [
+                {
+                    type: "image",
+                    data: png.toString("base64"),
+                    mimeType: "image/png",
+                },
+            ],
+        };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: read_memory
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "read_memory",
+    "Read bytes from the BBC Micro's memory map. " + "Returns an array of decimal byte values plus a hex dump.",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        address: z.number().int().min(0).max(0xffff).describe("Start address (0–65535)"),
+        length: z.number().int().min(1).max(256).default(16).describe("Number of bytes to read (max 256)"),
+    },
+    async ({ session_id, address, length }) => {
+        const session = requireSession(session_id);
+        const bytes = session.readMemory(address, length);
+        const hexDump = formatHexDump(address, bytes);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        address,
+                        addressHex: `0x${address.toString(16).toUpperCase()}`,
+                        bytes,
+                        hexDump,
+                    }),
+                },
+            ],
+        };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: write_memory
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "write_memory",
+    "Write bytes into the BBC Micro's memory. " +
+        "Useful for poking machine code, modifying variables, or patching running programs.",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        address: z.number().int().min(0).max(0xffff).describe("Start address (0–65535)"),
+        bytes: z.array(z.number().int().min(0).max(255)).describe("Array of byte values to write"),
+    },
+    async ({ session_id, address, bytes }) => {
+        const session = requireSession(session_id);
+        session.writeMemory(address, bytes);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Wrote ${bytes.length} byte(s) at 0x${address.toString(16).toUpperCase()}.`,
+                },
+            ],
+        };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: read_registers
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "read_registers",
+    "Read the current 6502 CPU register state (PC, A, X, Y, stack pointer, processor status).",
+    { session_id: z.string().describe("Session ID from create_machine") },
+    async ({ session_id }) => {
+        const session = requireSession(session_id);
+        const regs = session.registers();
+        return { content: [{ type: "text", text: JSON.stringify(regs) }] };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: run_for_cycles
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "run_for_cycles",
+    "Run the emulator for an exact number of 2MHz CPU cycles. " +
+        "Useful for precise timing, or just to advance the clock a bit between interactions.",
+    {
+        session_id: z.string().describe("Session ID from create_machine"),
+        cycles: z.number().int().min(1).describe("Number of 2MHz CPU cycles to execute"),
+        clear: z
+            .boolean()
+            .default(true)
+            .describe("If true (default), clear the output buffer after returning it. Pass false to peek."),
+    },
+    async ({ session_id, cycles, clear }) => {
+        const session = requireSession(session_id);
+        await session.runFor(cycles);
+        const output = session.drainOutput({ clear });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ cycles_run: cycles, output }),
+                },
+            ],
+        };
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Tool: run_basic  (convenience: one-shot, no session management needed)
+// ---------------------------------------------------------------------------
+
+server.tool(
+    "run_basic",
+    "One-shot convenience tool: boot a BBC Micro, load a BASIC program, run it, " +
+        "return all text output and a screenshot, then destroy the session. " +
+        "Perfect for quickly trying out ideas without managing sessions.",
+    {
+        source: z.string().describe("BBC BASIC source code to run"),
+        model: z.enum(["B-DFS1.2", "Master"]).default("B-DFS1.2").describe("BBC Micro model"),
+        timeout_secs: z.number().default(30).describe("Max emulated seconds to allow the program to run"),
+        screenshot: z.boolean().default(true).describe("Include a screenshot of the final screen state"),
+    },
+    async ({ source, model, timeout_secs, screenshot: wantScreenshot }) => {
+        const session = new MachineSession(model);
+        try {
+            await session.initialise();
+            await session.boot(30);
+            await session.loadBasic(source);
+            await session.type("RUN");
+            const output = await session.runUntilPrompt(timeout_secs);
+
+            const result = { output };
+
+            if (wantScreenshot) {
+                const png = await session.screenshotActive();
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result) },
+                        { type: "image", data: png.toString("base64"), mimeType: "image/png" },
+                    ],
+                };
+            }
+
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        } finally {
+            session.destroy();
+        }
+    },
+);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatHexDump(startAddr, bytes) {
+    const lines = [];
+    for (let i = 0; i < bytes.length; i += 16) {
+        const chunk = bytes.slice(i, i + 16);
+        const addr = (startAddr + i).toString(16).toUpperCase().padStart(4, "0");
+        const hex = chunk.map((b) => b.toString(16).toUpperCase().padStart(2, "0")).join(" ");
+        const ascii = chunk.map((b) => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : ".")).join("");
+        lines.push(`${addr}  ${hex.padEnd(47)}  |${ascii}|`);
+    }
+    return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Start server
+// ---------------------------------------------------------------------------
+
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+
+main().catch((err) => {
+    console.error("Failed to start jsbeeb MCP server:", err);
+    process.exit(1);
+});