c64bridge 1.0.2 → 1.0.3

package/mcp/tools.json

@@ -1969,7 +1969,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": [
           {
@@ -2725,7 +2725,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 +2734,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.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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.3",
   "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]}.`);
+}

package/server.json

@@ -8,12 +8,12 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/chrisgleissner/c64bridge",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "c64bridge",
-      "version": "1.0.2",
+      "version": "1.0.3",
       "transport": {
         "type": "stdio"
       },