c64bridge 0.9.3 → 1.0.0

package/mcp/schemas/c64_graphics.schema.json

@@ -229,7 +229,7 @@
   "required": [
     "op"
   ],
-  "description": "Graphics operations available via the c64_graphics tool.\n\nOperations:\n- capture_frame: Capture one or more complete video frames from the active backend. Required inputs: none. Optional inputs: count, includePixels, encoding.\n- render_petscii_art: Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64. Required inputs: none. Optional inputs: prompt, text, maxWidth, maxHeight, borderColor, backgroundColor, foregroundColor, dryRun, bitmap.\n- render_petscii_text: Display PETSCII text with optional border and background colours. Required inputs: text. Optional inputs: borderColor, backgroundColor.\n- render_sprite: Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. Required inputs: sprite. Optional inputs: index, x, y, color, multicolour.\n- render_bitmap: Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it. Required inputs: imagePath, format. Optional inputs: bitmapAddress, screenAddress, borderColor, backgroundColor, preserveAspect.\n- get_display_state: Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical. Required inputs: none.",
+  "description": "Graphics operations available via the c64_graphics tool.\n\nOperations:\n- capture_frame: Capture one or more complete video frames from the active backend. Required inputs: none. Optional inputs: count, includePixels, encoding.\n- render_petscii_art: Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64. Required inputs: none. Optional inputs: prompt, text, maxWidth, maxHeight, borderColor, backgroundColor, foregroundColor, dryRun, bitmap.\n- render_petscii_text: Display PETSCII text with optional border and background colours. Required inputs: text. Optional inputs: borderColor, backgroundColor.\n- render_sprite: Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. Required inputs: sprite. Optional inputs: index, x, y, color, multicolour.\n- render_bitmap: Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it. Required inputs: imagePath, format. Optional inputs: bitmapAddress, screenAddress, borderColor, backgroundColor, preserveAspect.\n- get_display_state: Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. The same shared-memory path is used on C64U/U64, U2-family hardware, and VICE, so the response shape is identical. Required inputs: none.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -624,12 +624,12 @@
     },
     {
       "op": "get_display_state",
-      "description": "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.",
+      "description": "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. The same shared-memory path is used on C64U/U64, U2-family hardware, and VICE, so the response shape is identical.",
       "required": [],
       "optional": [],
       "inputSchema": {
         "type": "object",
-        "description": "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.",
+        "description": "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. The same shared-memory path is used on C64U/U64, U2-family hardware, and VICE, so the response shape is identical.",
         "properties": {
           "op": {
             "const": "get_display_state"

package/mcp/schemas/c64_input.schema.json

@@ -6,7 +6,10 @@
       "enum": [
         "write_text",
         "key",
-        "joystick"
+        "joystick",
+        "keyboard",
+        "release_all",
+        "state"
       ],
       "description": "Selects the operation."
     },
@@ -69,7 +72,9 @@
           "down",
           "left",
           "right",
-          "fire"
+          "fire",
+          "fire2",
+          "fire3"
         ]
       },
       "minItems": 0
@@ -82,12 +87,98 @@
         "release",
         "tap"
       ]
+    },
+    "inputs": {
+      "type": "array",
+      "description": "One or more keys to transition together (for example left_shift + a).",
+      "items": {
+        "type": "string",
+        "description": "Physical keyboard input.",
+        "enum": [
+          "inst_del",
+          "return",
+          "cursor_left_right",
+          "f7",
+          "f1",
+          "f3",
+          "f5",
+          "cursor_up_down",
+          "0",
+          "1",
+          "2",
+          "3",
+          "4",
+          "5",
+          "6",
+          "7",
+          "8",
+          "9",
+          "a",
+          "b",
+          "c",
+          "d",
+          "e",
+          "f",
+          "g",
+          "h",
+          "i",
+          "j",
+          "k",
+          "l",
+          "m",
+          "n",
+          "o",
+          "p",
+          "q",
+          "r",
+          "s",
+          "t",
+          "u",
+          "v",
+          "w",
+          "x",
+          "y",
+          "z",
+          "left_shift",
+          "right_shift",
+          "plus",
+          "minus",
+          "period",
+          "colon",
+          "at",
+          "comma",
+          "pound",
+          "star",
+          "semicolon",
+          "clr_home",
+          "equals",
+          "arrow_up",
+          "slash",
+          "arrow_left",
+          "ctrl",
+          "space",
+          "commodore",
+          "run_stop",
+          "restore"
+        ]
+      },
+      "minItems": 1,
+      "maxItems": 8
+    },
+    "transition": {
+      "type": "string",
+      "description": "press holds, release frees, tap presses and releases.",
+      "enum": [
+        "press",
+        "release",
+        "tap"
+      ]
     }
   },
   "required": [
     "op"
   ],
-  "description": "Input operations: write_text, key, joystick.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input by writing directly to CIA1 Port A/B registers. Required inputs: port, controls, action. Optional inputs: durationMs.",
+  "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -183,7 +274,7 @@
     },
     {
       "op": "joystick",
-      "description": "Simulate joystick input by writing directly to CIA1 Port A/B registers.",
+      "description": "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
       "required": [
         "port",
         "controls",
@@ -194,7 +285,7 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Simulate joystick input by writing directly to CIA1 Port A/B registers.",
+        "description": "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
         "properties": {
           "op": {
             "const": "joystick"
@@ -216,7 +307,9 @@
                 "down",
                 "left",
                 "right",
-                "fire"
+                "fire",
+                "fire2",
+                "fire3"
               ]
             },
             "minItems": 0
@@ -249,6 +342,154 @@
         ],
         "additionalProperties": false
       }
+    },
+    {
+      "op": "keyboard",
+      "description": "Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+      "required": [
+        "inputs",
+        "transition"
+      ],
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+        "properties": {
+          "op": {
+            "const": "keyboard"
+          },
+          "inputs": {
+            "type": "array",
+            "description": "One or more keys to transition together (for example left_shift + a).",
+            "items": {
+              "type": "string",
+              "description": "Physical keyboard input.",
+              "enum": [
+                "inst_del",
+                "return",
+                "cursor_left_right",
+                "f7",
+                "f1",
+                "f3",
+                "f5",
+                "cursor_up_down",
+                "0",
+                "1",
+                "2",
+                "3",
+                "4",
+                "5",
+                "6",
+                "7",
+                "8",
+                "9",
+                "a",
+                "b",
+                "c",
+                "d",
+                "e",
+                "f",
+                "g",
+                "h",
+                "i",
+                "j",
+                "k",
+                "l",
+                "m",
+                "n",
+                "o",
+                "p",
+                "q",
+                "r",
+                "s",
+                "t",
+                "u",
+                "v",
+                "w",
+                "x",
+                "y",
+                "z",
+                "left_shift",
+                "right_shift",
+                "plus",
+                "minus",
+                "period",
+                "colon",
+                "at",
+                "comma",
+                "pound",
+                "star",
+                "semicolon",
+                "clr_home",
+                "equals",
+                "arrow_up",
+                "slash",
+                "arrow_left",
+                "ctrl",
+                "space",
+                "commodore",
+                "run_stop",
+                "restore"
+              ]
+            },
+            "minItems": 1,
+            "maxItems": 8
+          },
+          "transition": {
+            "type": "string",
+            "description": "press holds, release frees, tap presses and releases.",
+            "enum": [
+              "press",
+              "release",
+              "tap"
+            ]
+          }
+        },
+        "required": [
+          "op",
+          "inputs",
+          "transition"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "release_all",
+      "description": "Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+      "required": [],
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+        "properties": {
+          "op": {
+            "const": "release_all"
+          }
+        },
+        "required": [
+          "op"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "state",
+      "description": "Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+      "required": [],
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+        "properties": {
+          "op": {
+            "const": "state"
+          }
+        },
+        "required": [
+          "op"
+        ],
+        "additionalProperties": false
+      }
     }
   ]
 }

package/mcp/schemas/c64_memory.schema.json

@@ -178,7 +178,7 @@
   "required": [
     "op"
   ],
-  "description": "Memory operations available via the c64_memory tool.\n\nOperations:\n- read: Read a range of bytes and return a hex dump with address metadata. Required inputs: address. Optional inputs: length.\n- write: Write a hexadecimal byte sequence into RAM. Required inputs: address, bytes. Optional inputs: verify, expected, mask, abortOnMismatch.\n- read_screen: Return the current 40x25 text screen converted to ASCII. Required inputs: none.\n- wait_for_text: Poll the screen until a substring or regex appears, or timeout elapses. Required inputs: pattern. Optional inputs: isRegex, caseInsensitive, timeoutMs, intervalMs.\n- disassemble: Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on both C64U and VICE. Required inputs: address. Optional inputs: length, instructionCount.\n- copy_memory: Copy a RAM region to another address. Required inputs: source, dest, length.\n- fill_memory: Fill a memory range with a repeating byte pattern. Required inputs: address, length, pattern.\n- search_memory: Search for a byte pattern within a memory range and return matching addresses. Required inputs: startAddress, endAddress, pattern. Optional inputs: maxResults.\n- compare_memory: Compare two memory regions byte-by-byte and report differences. Required inputs: address1, address2, length. Optional inputs: maxDiffs.\n- save_memory: Dump a memory range to a local file, with an optional PRG load-address header. Required inputs: startAddress, endAddress, filePath. Optional inputs: asPrg.",
+  "description": "Memory operations available via the c64_memory tool.\n\nOperations:\n- read: Read a range of bytes and return a hex dump with address metadata. Required inputs: address. Optional inputs: length.\n- write: Write a hexadecimal byte sequence into RAM. Required inputs: address, bytes. Optional inputs: verify, expected, mask, abortOnMismatch.\n- read_screen: Return the current 40x25 text screen converted to ASCII. Required inputs: none.\n- wait_for_text: Poll the screen until a substring or regex appears, or timeout elapses. Required inputs: pattern. Optional inputs: isRegex, caseInsensitive, timeoutMs, intervalMs.\n- disassemble: Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on C64U/U64, U2-family hardware, and VICE. Required inputs: address. Optional inputs: length, instructionCount.\n- copy_memory: Copy a RAM region to another address. Required inputs: source, dest, length.\n- fill_memory: Fill a memory range with a repeating byte pattern. Required inputs: address, length, pattern.\n- search_memory: Search for a byte pattern within a memory range and return matching addresses. Required inputs: startAddress, endAddress, pattern. Optional inputs: maxResults.\n- compare_memory: Compare two memory regions byte-by-byte and report differences. Required inputs: address1, address2, length. Optional inputs: maxDiffs.\n- save_memory: Dump a memory range to a local file, with an optional PRG load-address header. Required inputs: startAddress, endAddress, filePath. Optional inputs: asPrg.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -372,7 +372,7 @@
     },
     {
       "op": "disassemble",
-      "description": "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on both C64U and VICE.",
+      "description": "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on C64U/U64, U2-family hardware, and VICE.",
       "required": [
         "address"
       ],
@@ -382,7 +382,7 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on both C64U and VICE.",
+        "description": "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on C64U/U64, U2-family hardware, and VICE.",
         "properties": {
           "address": {
             "type": "string",

package/mcp/schemas/c64_program.schema.json

@@ -256,7 +256,7 @@
   "required": [
     "op"
   ],
-  "description": "Program operations available via the c64_program tool.\n\nOperations:\n- load_prg: Load a PRG from Ultimate storage without executing it. Required inputs: path. Optional inputs: symbolsFile.\n- run_prg: Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE. Required inputs: path. Optional inputs: symbolsFile.\n- run_crt: Mount and run a CRT cartridge image. Required inputs: path.\n- upload_run_basic: Upload Commodore BASIC v2 source and execute it immediately. Required inputs: program. Optional inputs: verify.\n- upload_run_asm: Assemble 6502/6510 source, upload the PRG, and execute it. Required inputs: program. Optional inputs: verify.\n- batch_run: Run multiple PRG/CRT programs with post-run assertions. Required inputs: programs. Optional inputs: continueOnError, durationMs, outputPath, resetDelayMs.\n- bundle_run: Capture screen, memory, and debug registers into an artifact bundle. Required inputs: runId, outputPath. Optional inputs: captureScreen, memoryRanges, captureDebugReg.\n- cross_platform_greeting: Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results. Required inputs: none. Optional inputs: platforms, messageTemplate, verify, captureScreenshot, outputPath, restoreActiveBackend, timeoutMs, pollIntervalMs.",
+  "description": "Program operations available via the c64_program tool.\n\nOperations:\n- load_prg: Load a PRG from Ultimate storage without executing it. Required inputs: path. Optional inputs: symbolsFile.\n- run_prg: Load and execute a PRG from Ultimate-visible storage on C64U/U64 or U2-family hardware, or from a host-local path on VICE. Required inputs: path. Optional inputs: symbolsFile.\n- run_crt: Mount and run a CRT cartridge image. Required inputs: path.\n- upload_run_basic: Upload Commodore BASIC v2 source and execute it immediately. Required inputs: program. Optional inputs: verify.\n- upload_run_asm: Assemble 6502/6510 source, upload the PRG, and execute it. Required inputs: program. Optional inputs: verify.\n- batch_run: Run multiple PRG/CRT programs with post-run assertions. Required inputs: programs. Optional inputs: continueOnError, durationMs, outputPath, resetDelayMs.\n- bundle_run: Capture screen, memory, and debug registers into an artifact bundle. Required inputs: runId, outputPath. Optional inputs: captureScreen, memoryRanges, captureDebugReg.\n- cross_platform_greeting: Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results. Required inputs: none. Optional inputs: platforms, messageTemplate, verify, captureScreenshot, outputPath, restoreActiveBackend, timeoutMs, pollIntervalMs.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -298,7 +298,7 @@
     },
     {
       "op": "run_prg",
-      "description": "Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE.",
+      "description": "Load and execute a PRG from Ultimate-visible storage on C64U/U64 or U2-family hardware, or from a host-local path on VICE.",
       "required": [
         "path"
       ],
@@ -307,7 +307,7 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE.",
+        "description": "Load and execute a PRG from Ultimate-visible storage on C64U/U64 or U2-family hardware, or from a host-local path on VICE.",
         "properties": {
           "path": {
             "type": "string",

package/mcp/schemas/c64_select_backend.schema.json

@@ -12,6 +12,7 @@
       "type": "string",
       "enum": [
         "c64u",
+        "u2",
         "vice"
       ],
       "description": "Backend to activate for subsequent tool calls."
@@ -42,6 +43,7 @@
             "type": "string",
             "enum": [
               "c64u",
+              "u2",
               "vice"
             ],
             "description": "Backend to activate for subsequent tool calls."

package/mcp/schemas/c64_system.schema.json

@@ -9,7 +9,9 @@
         "reset",
         "reboot",
         "poweroff",
+        "power_cycle",
         "menu",
+        "read_menu_screen",
         "start_task",
         "stop_task",
         "stop_all_tasks",
@@ -89,7 +91,7 @@
   "required": [
     "op"
   ],
-  "description": "System operations available via the c64_system tool.\n\nOperations:\n- pause: Pause the machine until resumed. Required inputs: none.\n- resume: Resume CPU execution after a pause. Required inputs: none.\n- reset: Issue a soft reset without cutting power. Required inputs: none.\n- reboot: Trigger a firmware reboot to recover from faults. Required inputs: none.\n- poweroff: Request a controlled shutdown via the Ultimate firmware. Required inputs: none.\n- menu: Toggle the Ultimate menu button for navigation. Required inputs: none.\n- start_task: Start a named background task that runs on an interval. Required inputs: name, operation. Optional inputs: arguments, intervalMs, maxIterations.\n- stop_task: Stop a specific background task and clear its timer. Required inputs: name.\n- stop_all_tasks: Stop every running background task and persist state. Required inputs: none.\n- list_tasks: List known background tasks with status metadata. Required inputs: none.\n- performance_report: Summarize diagnostics spans and tool latencies from the current or latest MCP session. Required inputs: none. Optional inputs: scope, includeTimeline, maxEntries.",
+  "description": "System operations available via the c64_system tool.\n\nOperations:\n- pause: Pause the machine until resumed. Required inputs: none.\n- resume: Resume CPU execution after a pause. Required inputs: none.\n- reset: Issue a soft reset without cutting power. Required inputs: none.\n- reboot: Trigger a firmware reboot to recover from faults. Required inputs: none.\n- poweroff: Request a controlled shutdown via the Ultimate firmware. Required inputs: none.\n- power_cycle: Return the active backend to a fresh state. C64U/U64 Tool Menu verification requires machine:menu_screen (a C64U firmware version that provides it, or U64 3.15+); U2-family reboots through REST. Required inputs: none.\n- menu: Toggle the Ultimate menu button for navigation. Required inputs: none.\n- read_menu_screen: Read the active Ultimate menu's raw character and colour matrix through machine:menu_screen (a C64U firmware version that provides it, or U64/U2 3.15+). Required inputs: none.\n- start_task: Start a named background task that runs on an interval. Required inputs: name, operation. Optional inputs: arguments, intervalMs, maxIterations.\n- stop_task: Stop a specific background task and clear its timer. Required inputs: name.\n- stop_all_tasks: Stop every running background task and persist state. Required inputs: none.\n- list_tasks: List known background tasks with status metadata. Required inputs: none.\n- performance_report: Summarize diagnostics spans and tool latencies from the current or latest MCP session. Required inputs: none. Optional inputs: scope, includeTimeline, maxEntries.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -187,6 +189,25 @@
         ]
       }
     },
+    {
+      "op": "power_cycle",
+      "description": "Return the active backend to a fresh state. C64U/U64 Tool Menu verification requires machine:menu_screen (a C64U firmware version that provides it, or U64 3.15+); U2-family reboots through REST.",
+      "required": [],
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Return the active backend to a fresh state. C64U/U64 Tool Menu verification requires machine:menu_screen (a C64U firmware version that provides it, or U64 3.15+); U2-family reboots through REST.",
+        "properties": {
+          "op": {
+            "const": "power_cycle"
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
+    },
     {
       "op": "menu",
       "description": "Toggle the Ultimate menu button for navigation.",
@@ -206,6 +227,25 @@
         ]
       }
     },
+    {
+      "op": "read_menu_screen",
+      "description": "Read the active Ultimate menu's raw character and colour matrix through machine:menu_screen (a C64U firmware version that provides it, or U64/U2 3.15+).",
+      "required": [],
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Read the active Ultimate menu's raw character and colour matrix through machine:menu_screen (a C64U firmware version that provides it, or U64/U2 3.15+).",
+        "properties": {
+          "op": {
+            "const": "read_menu_screen"
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
+    },
     {
       "op": "start_task",
       "description": "Start a named background task that runs on an interval.",

package/mcp/server.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "0.9.3",
+  "version": "1.0.0",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "transports": [
     "stdio"