c64bridge 1.0.2 → 1.0.4

package/mcp/schemas/c64_sound.schema.json

@@ -223,7 +223,7 @@
         "string",
         "null"
       ],
-      "description": "Playback target format.",
+      "description": "Playback target format. PRG works on all backends; SID playback requires C64U/U64 or U2 (SID export with dryRun works everywhere).",
       "enum": [
         "prg",
         "sid"
@@ -249,7 +249,8 @@
         "minLength": 1,
         "enum": [
           "vice",
-          "c64u"
+          "c64u",
+          "u2"
         ]
       }
     },
@@ -363,7 +364,7 @@
   "required": [
     "op"
   ],
-  "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. Required inputs: none. Optional inputs: count, encoding.\n- set_volume: Set the SID master volume register at $D418 (0-15). Required inputs: volume.\n- reset: Soft or hard reset of SID registers to clear glitches. Required inputs: none. Optional inputs: hard.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch. Required inputs: none. Optional inputs: voice, note, frequencyHz, system, waveform, pulseWidth, attack, decay, sustain, release.\n- note_off: Release a SID voice by clearing its gate bit. Required inputs: voice.\n- silence_all: Silence all SID voices with optional audio verification. Required inputs: none. Optional inputs: verify.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem. Required inputs: path. Optional inputs: songnr.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player. Required inputs: path.\n- generate: Generate a lightweight SID arpeggio playback sequence. Required inputs: none. Optional inputs: root, pattern, steps, tempoMs, waveform, preset.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately. Required inputs: none. Optional inputs: sidwave, cpg, format, output, dryRun.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven. Required inputs: none. Optional inputs: preset, platforms, verify, analysisDurationSeconds, waitBeforeCaptureMs, restoreActiveBackend.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording. Required inputs: none. Optional inputs: sidwave, cpg, output, waitBeforeCaptureMs, analysisDurationSeconds, expectedSidwave, verifySilenceBefore, verifySilenceAfter, silenceDurationSeconds, silenceRmsThreshold, postSilenceWaitMs, silenceWaitMs.\n- analyze: Automatically analyze SID playback when verification is requested. Required inputs: request. Optional inputs: durationSeconds, expectedSidwave.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics. Required inputs: durationSeconds. Optional inputs: expectedSidwave.",
+  "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. Required inputs: none. Optional inputs: count, encoding.\n- set_volume: Set the SID master volume register at $D418 (0-15). Required inputs: volume.\n- reset: Soft or hard reset of SID registers to clear glitches. Required inputs: none. Optional inputs: hard.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch. Required inputs: none. Optional inputs: voice, note, frequencyHz, system, waveform, pulseWidth, attack, decay, sustain, release.\n- note_off: Release a SID voice by clearing its gate bit. Required inputs: voice.\n- silence_all: Silence all SID voices with optional audio verification. Required inputs: none. Optional inputs: verify.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem. Required inputs: path. Optional inputs: songnr.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player. Required inputs: path.\n- generate: Generate a lightweight SID arpeggio playback sequence. Required inputs: none. Optional inputs: root, pattern, steps, tempoMs, waveform, preset.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately. Required inputs: none. Optional inputs: sidwave, cpg, format, output, dryRun.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven. Required inputs: none. Optional inputs: preset, platforms, verify, analysisDurationSeconds, waitBeforeCaptureMs, restoreActiveBackend.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording. Required inputs: none. Optional inputs: sidwave, cpg, output, waitBeforeCaptureMs, analysisDurationSeconds, expectedSidwave, verifySilenceBefore, verifySilenceAfter, silenceDurationSeconds, silenceRmsThreshold, postSilenceWaitMs, silenceWaitMs.\n- analyze: Automatically analyze SID playback when verification is requested. Required inputs: request. Optional inputs: durationSeconds, expectedSidwave.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends. Required inputs: durationSeconds. Optional inputs: expectedSidwave.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -815,7 +816,7 @@
               "string",
               "null"
             ],
-            "description": "Playback target format.",
+            "description": "Playback target format. PRG works on all backends; SID playback requires C64U/U64 or U2 (SID export with dryRun works everywhere).",
             "enum": [
               "prg",
               "sid"
@@ -876,7 +877,8 @@
               "minLength": 1,
               "enum": [
                 "vice",
-                "c64u"
+                "c64u",
+                "u2"
               ]
             }
           },
@@ -885,7 +887,7 @@
               "boolean",
               "null"
             ],
-            "description": "Capture and analyze audio on supported backends after playback starts.",
+            "description": "Capture and analyze audio after playback starts: native streaming on C64U/U64, host audio input on U2/VICE (PortAudio required).",
             "default": true
           },
           "analysisDurationSeconds": {
@@ -969,7 +971,7 @@
               "string",
               "null"
             ],
-            "description": "Playback artifact format.",
+            "description": "Playback artifact format. PRG works on all backends; SID attachment playback requires C64U/U64 or U2.",
             "enum": [
               "prg",
               "sid"
@@ -1119,7 +1121,7 @@
     },
     {
       "op": "record_analyze",
-      "description": "Record audio for a fixed duration and return SID analysis metrics.",
+      "description": "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends.",
       "required": [
         "durationSeconds"
       ],
@@ -1128,7 +1130,7 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Record audio for a fixed duration and return SID analysis metrics.",
+        "description": "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends.",
         "properties": {
           "durationSeconds": {
             "type": "number",

package/mcp/schemas/c64_system.schema.json

@@ -91,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- 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.",
+  "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: Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off. 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": [
     {
@@ -172,12 +172,12 @@
     },
     {
       "op": "poweroff",
-      "description": "Request a controlled shutdown via the Ultimate firmware.",
+      "description": "Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off.",
       "required": [],
       "optional": [],
       "inputSchema": {
         "type": "object",
-        "description": "Request a controlled shutdown via the Ultimate firmware.",
+        "description": "Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off.",
         "properties": {
           "op": {
             "const": "poweroff"

package/mcp/server.json

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

package/mcp/tools.json

@@ -191,8 +191,7 @@
               "boolean",
               "null"
             ],
-            "description": "Capture debugreg state",
-            "default": true
+            "description": "Capture Ultimate debug registers (C64U/U64 only). Defaults to true on C64U/U64 and false on U2/VICE."
           },
           "platforms": {
             "type": [
@@ -205,13 +204,10 @@
               "minLength": 1,
               "enum": [
                 "vice",
-                "c64u"
+                "c64u",
+                "u2"
               ]
-            },
-            "default": [
-              "vice",
-              "c64u"
-            ]
+            }
           },
           "messageTemplate": {
             "type": [
@@ -227,7 +223,7 @@
               "boolean",
               "null"
             ],
-            "description": "Capture a framebuffer screenshot and save it as a PNG per backend.",
+            "description": "Capture a framebuffer screenshot on C64U/U64 or VICE. U2 skips screenshots by default; explicitly requesting one on U2 fails before execution.",
             "default": true
           },
           "restoreActiveBackend": {
@@ -629,8 +625,7 @@
                     "boolean",
                     "null"
                   ],
-                  "description": "Capture debugreg state",
-                  "default": true
+                  "description": "Capture Ultimate debug registers (C64U/U64 only). Defaults to true on C64U/U64 and false on U2/VICE."
                 },
                 "op": {
                   "const": "bundle_run"
@@ -673,13 +668,10 @@
                     "minLength": 1,
                     "enum": [
                       "vice",
-                      "c64u"
+                      "c64u",
+                      "u2"
                     ]
-                  },
-                  "default": [
-                    "vice",
-                    "c64u"
-                  ]
+                  }
                 },
                 "messageTemplate": {
                   "type": [
@@ -703,7 +695,7 @@
                     "boolean",
                     "null"
                   ],
-                  "description": "Capture a framebuffer screenshot and save it as a PNG per backend.",
+                  "description": "Capture a framebuffer screenshot on C64U/U64 or VICE. U2 skips screenshots by default; explicitly requesting one on U2 fails before execution.",
                   "default": true
                 },
                 "outputPath": {
@@ -815,10 +807,6 @@
           "run_crt": [
             "c64u",
             "u2"
-          ],
-          "bundle_run": [
-            "c64u",
-            "u2"
           ]
         }
       }
@@ -1829,7 +1817,7 @@
               "string",
               "null"
             ],
-            "description": "Playback target format.",
+            "description": "Playback target format. PRG works on all backends; SID playback requires C64U/U64 or U2 (SID export with dryRun works everywhere).",
             "enum": [
               "prg",
               "sid"
@@ -1855,7 +1843,8 @@
               "minLength": 1,
               "enum": [
                 "vice",
-                "c64u"
+                "c64u",
+                "u2"
               ]
             }
           },
@@ -1969,7 +1958,7 @@
         "required": [
           "op"
         ],
-        "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. Required inputs: none. Optional inputs: count, encoding.\n- set_volume: Set the SID master volume register at $D418 (0-15). Required inputs: volume.\n- reset: Soft or hard reset of SID registers to clear glitches. Required inputs: none. Optional inputs: hard.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch. Required inputs: none. Optional inputs: voice, note, frequencyHz, system, waveform, pulseWidth, attack, decay, sustain, release.\n- note_off: Release a SID voice by clearing its gate bit. Required inputs: voice.\n- silence_all: Silence all SID voices with optional audio verification. Required inputs: none. Optional inputs: verify.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem. Required inputs: path. Optional inputs: songnr.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player. Required inputs: path.\n- generate: Generate a lightweight SID arpeggio playback sequence. Required inputs: none. Optional inputs: root, pattern, steps, tempoMs, waveform, preset.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately. Required inputs: none. Optional inputs: sidwave, cpg, format, output, dryRun.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven. Required inputs: none. Optional inputs: preset, platforms, verify, analysisDurationSeconds, waitBeforeCaptureMs, restoreActiveBackend.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording. Required inputs: none. Optional inputs: sidwave, cpg, output, waitBeforeCaptureMs, analysisDurationSeconds, expectedSidwave, verifySilenceBefore, verifySilenceAfter, silenceDurationSeconds, silenceRmsThreshold, postSilenceWaitMs, silenceWaitMs.\n- analyze: Automatically analyze SID playback when verification is requested. Required inputs: request. Optional inputs: durationSeconds, expectedSidwave.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics. Required inputs: durationSeconds. Optional inputs: expectedSidwave.",
+        "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. Required inputs: none. Optional inputs: count, encoding.\n- set_volume: Set the SID master volume register at $D418 (0-15). Required inputs: volume.\n- reset: Soft or hard reset of SID registers to clear glitches. Required inputs: none. Optional inputs: hard.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch. Required inputs: none. Optional inputs: voice, note, frequencyHz, system, waveform, pulseWidth, attack, decay, sustain, release.\n- note_off: Release a SID voice by clearing its gate bit. Required inputs: voice.\n- silence_all: Silence all SID voices with optional audio verification. Required inputs: none. Optional inputs: verify.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem. Required inputs: path. Optional inputs: songnr.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player. Required inputs: path.\n- generate: Generate a lightweight SID arpeggio playback sequence. Required inputs: none. Optional inputs: root, pattern, steps, tempoMs, waveform, preset.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately. Required inputs: none. Optional inputs: sidwave, cpg, format, output, dryRun.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven. Required inputs: none. Optional inputs: preset, platforms, verify, analysisDurationSeconds, waitBeforeCaptureMs, restoreActiveBackend.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording. Required inputs: none. Optional inputs: sidwave, cpg, output, waitBeforeCaptureMs, analysisDurationSeconds, expectedSidwave, verifySilenceBefore, verifySilenceAfter, silenceDurationSeconds, silenceRmsThreshold, postSilenceWaitMs, silenceWaitMs.\n- analyze: Automatically analyze SID playback when verification is requested. Required inputs: request. Optional inputs: durationSeconds, expectedSidwave.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends. Required inputs: durationSeconds. Optional inputs: expectedSidwave.",
         "additionalProperties": false,
         "x-c64bridge-operations": [
           {
@@ -2421,7 +2410,7 @@
                     "string",
                     "null"
                   ],
-                  "description": "Playback target format.",
+                  "description": "Playback target format. PRG works on all backends; SID playback requires C64U/U64 or U2 (SID export with dryRun works everywhere).",
                   "enum": [
                     "prg",
                     "sid"
@@ -2482,7 +2471,8 @@
                     "minLength": 1,
                     "enum": [
                       "vice",
-                      "c64u"
+                      "c64u",
+                      "u2"
                     ]
                   }
                 },
@@ -2491,7 +2481,7 @@
                     "boolean",
                     "null"
                   ],
-                  "description": "Capture and analyze audio on supported backends after playback starts.",
+                  "description": "Capture and analyze audio after playback starts: native streaming on C64U/U64, host audio input on U2/VICE (PortAudio required).",
                   "default": true
                 },
                 "analysisDurationSeconds": {
@@ -2575,7 +2565,7 @@
                     "string",
                     "null"
                   ],
-                  "description": "Playback artifact format.",
+                  "description": "Playback artifact format. PRG works on all backends; SID attachment playback requires C64U/U64 or U2.",
                   "enum": [
                     "prg",
                     "sid"
@@ -2725,7 +2715,7 @@
           },
           {
             "op": "record_analyze",
-            "description": "Record audio for a fixed duration and return SID analysis metrics.",
+            "description": "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends.",
             "required": [
               "durationSeconds"
             ],
@@ -2734,7 +2724,7 @@
             ],
             "inputSchema": {
               "type": "object",
-              "description": "Record audio for a fixed duration and return SID analysis metrics.",
+              "description": "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends.",
               "properties": {
                 "durationSeconds": {
                   "type": "number",
@@ -2838,13 +2828,18 @@
           ],
           "pipeline": [
             "c64u",
-            "u2"
+            "u2",
+            "vice"
           ],
           "analyze": [
-            "c64u"
+            "c64u",
+            "u2",
+            "vice"
           ],
           "record_analyze": [
-            "c64u"
+            "c64u",
+            "u2",
+            "vice"
           ]
         }
       }
@@ -2946,7 +2941,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- 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.",
+        "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: Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off. 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": [
           {
@@ -3027,12 +3022,12 @@
           },
           {
             "op": "poweroff",
-            "description": "Request a controlled shutdown via the Ultimate firmware.",
+            "description": "Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off.",
             "required": [],
             "optional": [],
             "inputSchema": {
               "type": "object",
-              "description": "Request a controlled shutdown via the Ultimate firmware.",
+              "description": "Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off.",
               "properties": {
                 "op": {
                   "const": "poweroff"
@@ -3338,6 +3333,10 @@
           "vice"
         ],
         "operationPlatforms": {
+          "poweroff": [
+            "c64u",
+            "vice"
+          ],
           "pause": [
             "c64u",
             "u2"
@@ -4183,7 +4182,13 @@
           "c64u",
           "u2",
           "vice"
-        ]
+        ],
+        "operationPlatforms": {
+          "capture_frame": [
+            "c64u",
+            "vice"
+          ]
+        }
       }
     },
     {
@@ -5732,7 +5737,7 @@
               "boolean",
               "null"
             ],
-            "description": "When true, save the restored configuration to flash immediately.",
+            "description": "When true, save the restored configuration to flash immediately (C64U/U64 and U2 only).",
             "default": false
           },
           "root": {
@@ -6131,7 +6136,7 @@
                     "boolean",
                     "null"
                   ],
-                  "description": "When true, save the restored configuration to flash immediately.",
+                  "description": "When true, save the restored configuration to flash immediately (C64U/U64 and U2 only).",
                   "default": false
                 },
                 "op": {
@@ -6954,8 +6959,16 @@
           "Summarise output file paths or sample counts so users can inspect artifacts quickly."
         ],
         "platforms": [
-          "c64u"
-        ]
+          "c64u",
+          "u2",
+          "vice"
+        ],
+        "operationPlatforms": {
+          "fs_stats": [
+            "c64u",
+            "u2"
+          ]
+        }
       }
     },
     {

package/mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "entry": "dist/index.js",
   "type": "stdio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "mcpName": "io.github.chrisgleissner/c64bridge",
   "description": "C64 Bridge MCP server for Commodore 64 Ultimate hardware and VICE emulator control",
   "repository": {
@@ -68,10 +68,10 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "axios": "^1.19.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "axios": "^1.20.0",
     "date-fns": "^4.4.0",
-    "fastify": "^5.11.2",
+    "fastify": "^5.12.5",
     "jimp": "^1.6.1",
     "meyda": "^5.6.3",
     "octokit": "^5.0.5",

package/scripts/mockC64Server.mjs

@@ -44,6 +44,9 @@ function createDefaultConfigs() {
     Video: {
       Mode: "PAL",
     },
+    "U64 Specific Settings": {
+      "System Mode": "PAL",
+    },
   };
 }
 
@@ -127,6 +130,14 @@ function createInitialState() {
     },
     lastStreamAction: null,
     streamActionLog: [],
+    // Number of upcoming stream:start requests answered like firmware with an empty ARP entry.
+    streamHostResolveFailures: 0,
+    // When set, the audio emitter stops after this many packets to imitate UDP packet loss.
+    audioPacketLimit: null,
+    audioSignal: null,
+    streamStartResponseDelayMs: 0,
+    // Unlike the one-shot failure counter, this gate stays closed until a test's ping stub primes it.
+    streamNeighborReady: true,
   };
 }
 
@@ -329,7 +340,10 @@ export async function startMockC64Server(options = {}) {
     }
 
     const sendAudioPacket = () => {
-      const packet = buildMockAudioPacket(runtime.sequence, runtime.sampleIndex);
+      if (state.audioPacketLimit !== null && state.streams.audio.packetsSent >= state.audioPacketLimit) {
+        return;
+      }
+      const packet = buildMockAudioPacket(runtime.sequence, runtime.sampleIndex, state.audioSignal);
       runtime.sequence = (runtime.sequence + 1) & 0xffff;
       runtime.sampleIndex += 192;
       socket.send(packet, port, host);
@@ -713,7 +727,7 @@ export async function startMockC64Server(options = {}) {
 
     if (url.startsWith("/v1/configs/")) {
       const routeUrl = new URL(url, "http://mock.local");
-      const segments = routeUrl.pathname.split("/").filter(Boolean).slice(2); // remove v1 + configs
+      const segments = routeUrl.pathname.split("/").filter(Boolean).slice(2).map((segment) => decodeURIComponent(segment)); // remove v1 + configs
 
       if (segments.length === 1) {
         const [category] = segments;
@@ -730,7 +744,8 @@ export async function startMockC64Server(options = {}) {
         if (method === "GET") {
           const categoryData = state.configs[category] ?? {};
           const value = categoryData[item];
-          sendJson(res, { value });
+          // Firmware nests the item as { "<category>": { "<item>": { current } } }; `value` is kept for older callers.
+          sendJson(res, { value, [category]: { [item]: { current: value } } });
           return;
         }
 
@@ -762,10 +777,20 @@ export async function startMockC64Server(options = {}) {
         if (action === "start" && method === "PUT") {
           const body = await readJson(req);
           const target = routeUrl.searchParams.get("ip") ?? routeUrl.searchParams.get("target") ?? body?.ip ?? body?.target ?? null;
+          const neighborReady = typeof state.streamNeighborReady === "function" ? state.streamNeighborReady(target) : state.streamNeighborReady;
+          if (!neighborReady || state.streamHostResolveFailures > 0) {
+            if (state.streamHostResolveFailures > 0) state.streamHostResolveFailures -= 1;
+            state.streamActionLog.push({ action: "start-rejected", stream, target });
+            sendJson(res, { errors: ["Network Host Resolve Error"] }, 404);
+            return;
+          }
           state.streams[stream] = { active: true, target, packetsSent: 0 };
           state.lastStreamAction = { action: "start", stream, target };
           state.streamActionLog.push({ action: "start", stream, target });
           startStreamEmitter(stream, target);
+          if (state.streamStartResponseDelayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, state.streamStartResponseDelayMs));
+          }
           sendJson(res, { result: "started", stream, target });
           return;
         }
@@ -994,15 +1019,17 @@ function buildMockVideoFramePackets(frameNumber, sequenceStart) {
   return packets;
 }
 
-function buildMockAudioPacket(sequence, sampleIndex) {
+function buildMockAudioPacket(sequence, sampleIndex, signal = null) {
   const header = Buffer.alloc(2);
   header.writeUInt16LE(sequence & 0xffff, 0);
 
   const payload = Buffer.alloc(768);
   for (let index = 0; index < 192; index += 1) {
     const phase = ((sampleIndex + index) % 256) - 128;
-    const left = phase * 128;
-    const right = -left;
+    // Both channels carry the same sawtooth plus a different constant offset, like the real stream.
+    const wave = signal ? Math.sin(2 * Math.PI * signal.frequency * (sampleIndex + index) / signal.sampleRate) : phase * 128;
+    const left = signal ? Math.round(wave * signal.amplitude + signal.leftOffset) : wave + 8000;
+    const right = signal ? Math.round(wave * signal.amplitude * signal.rightGain + signal.rightOffset) : wave + 5000;
     payload.writeInt16LE(left, index * 4);
     payload.writeInt16LE(right, index * 4 + 2);
   }

package/scripts/validate-release-artifact.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import { validateReleaseMetadata } from './validate-release.mjs';
+import { startMockC64Server } from './mockC64Server.mjs';
+
+const packageDir = path.resolve(process.argv[2]);
+const version = process.argv[3];
+validateReleaseMetadata(packageDir, version, { packed: true });
+const temp = mkdtempSync(path.join(os.tmpdir(), 'c64bridge-release-smoke-'));
+const mock = await startMockC64Server();
+const config = path.join(temp, 'config.json');
+writeFileSync(config, JSON.stringify({ c64u: { baseUrl: mock.baseUrl } }));
+mock.state.audioSignal = { frequency: 440, sampleRate: 47982.8869047619, amplitude: 4000, leftOffset: 26900, rightOffset: 20000, rightGain: -1 };
+const client = new Client({ name: 'c64bridge-release-validation', version: '1.0.0' }, { capabilities: {} });
+const transport = new StdioClientTransport({
+  command: process.execPath,
+  args: [path.join(packageDir, 'scripts/cli.js')],
+  // Launch from a foreign directory, as an installed npm consumer would.
+  cwd: temp,
+  env: { ...process.env, C64BRIDGE_CONFIG: config, C64_MODE: 'c64u', C64BRIDGE_DISABLE_DIAGNOSTICS: '1' },
+  stderr: 'pipe',
+});
+let stderr = '';
+transport.stderr?.on('data', (chunk) => { stderr = (stderr + chunk.toString()).slice(-16384); });
+try {
+  await client.connect(transport);
+  assert.equal(client.getServerVersion().version, version, 'MCP runtime version differs from artifact');
+  const tools = await client.listTools();
+  for (const name of ['c64_program', 'c64_memory', 'c64_sound', 'c64_graphics']) {
+    assert.ok(tools.tools.some((tool) => tool.name === name), `Missing packaged tool ${name}`);
+  }
+  const call = async (name, args) => {
+    const result = await client.request({ method: 'tools/call', params: { name, arguments: args } }, CallToolResultSchema);
+    assert.notEqual(result.isError, true, JSON.stringify(result));
+    return result;
+  };
+  mock.state.streamHostResolveFailures = 1;
+  const samples = await call('c64_sound', { op: 'capture_samples', count: 256 });
+  assert.equal(samples.metadata.samplePairs, 256);
+  await call('c64_graphics', { op: 'capture_frame' });
+  const recorded = await call('c64_sound', { op: 'record_analyze', durationSeconds: 0.5 });
+  const analysis = JSON.parse(recorded.content.find((entry) => entry.type === 'text').text).analysis;
+  assert.equal(analysis.source, 'ultimate-stream');
+  assert.ok(analysis.global_metrics.average_rms > 0.08, 'Stereo audio cancelled to silence');
+  assert.equal(analysis.voices[0].detected_notes.find((note) => note.note)?.note, 'A4');
+  assert.equal(mock.state.streams.audio.active, false);
+  assert.equal(mock.state.streams.video.active, false);
+  console.log(`Packed c64bridge@${version}: CLI, MCP version/discovery, video, ARP retry, and stereo audio verified.`);
+} catch (error) {
+  console.error(stderr);
+  throw error;
+} finally {
+  await client.close();
+  await mock.close();
+  rmSync(temp, { recursive: true, force: true });
+}

package/scripts/validate-release.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function validateReleaseMetadata(root, version, { packed = false } = {}) {
+  assert.match(version, /^\d+\.\d+\.\d+$/, 'Expected a stable release version');
+  const read = (file) => JSON.parse(readFileSync(path.join(root, file), 'utf8'));
+  const pkg = read('package.json');
+  assert.equal(pkg.name, 'c64bridge', 'Wrong npm package');
+  assert.equal(pkg.version, version, 'package.json version does not match release tag');
+  assert.equal(pkg.private, undefined, 'Release package must be public');
+  assert.equal(pkg.main, 'dist/index.js', 'Wrong compiled entry point');
+  assert.equal(pkg.bin.c64bridge, 'scripts/cli.js', 'Wrong CLI entry point');
+  assert.equal(read('mcp.json').version, version, 'mcp.json version mismatch');
+  assert.equal(read('mcp/server.json').version, version, 'Generated MCP metadata version mismatch');
+  const server = read('server.json');
+  assert.equal(server.name, pkg.mcpName, 'MCP Registry server name mismatch');
+  assert.equal(server.version, version, 'MCP Registry version mismatch');
+  assert.equal(server.packages[0].identifier, pkg.name, 'MCP Registry npm name mismatch');
+  assert.equal(server.packages[0].version, version, 'MCP Registry npm version mismatch');
+  if (!packed) {
+    const lock = read('package-lock.json');
+    assert.equal(lock.name, pkg.name, 'Lockfile package name mismatch');
+    assert.equal(lock.version, version, 'Lockfile version mismatch');
+    assert.equal(lock.packages[''].version, version, 'Lockfile root version mismatch');
+    for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+      assert.deepEqual(lock.packages[''][section], pkg[section], `Lockfile ${section} differs from package.json`);
+    }
+    const changelog = readFileSync(path.join(root, 'CHANGELOG.md'), 'utf8');
+    assert.match(changelog, new RegExp(`^## ${version.replaceAll('.', '\\.')} - \\d{4}-\\d{2}-\\d{2}$`, 'm'), 'Missing release changelog entry');
+  }
+  return pkg;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  validateReleaseMetadata(process.cwd(), process.argv[2]);
+  console.log(`Release metadata agrees on c64bridge@${process.argv[2]}.`);
+}