c64bridge 0.5.0

package/dist/tools/streaming.js

@@ -0,0 +1,132 @@
+import { defineToolModule } from "./types.js";
+import { objectSchema, stringSchema } from "./schema.js";
+import { textResult } from "./responses.js";
+import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+const streamIdentifierSchema = stringSchema({
+    description: "Stream type to control (video/audio/debug).",
+    enum: ["video", "audio", "debug"],
+});
+const streamStartArgsSchema = objectSchema({
+    description: "Arguments for starting an Ultimate streaming session.",
+    properties: {
+        stream: streamIdentifierSchema,
+        target: stringSchema({
+            description: "Destination host:port or UDP target understood by the firmware.",
+            minLength: 3,
+        }),
+    },
+    required: ["stream", "target"],
+    additionalProperties: false,
+});
+const streamStopArgsSchema = objectSchema({
+    description: "Arguments for stopping an Ultimate streaming session.",
+    properties: {
+        stream: streamIdentifierSchema,
+    },
+    required: ["stream"],
+    additionalProperties: false,
+});
+function toRecord(details) {
+    if (details && typeof details === "object") {
+        return details;
+    }
+    return undefined;
+}
+export const streamingModule = defineToolModule({
+    domain: "streaming",
+    summary: "Long-running or streaming workflows such as audio capture or SID playback monitoring.",
+    resources: [
+        "c64://specs/sid",
+        "c64://docs/index",
+    ],
+    prompts: ["sid-music"],
+    defaultLifecycle: "stream",
+    defaultTags: ["stream", "monitoring"],
+    workflowHints: [
+        "Use streaming tools for long-running capture or monitoring workflows such as audio verification.",
+        "Clarify that streams keep running until stopped so the user can manage resources.",
+    ],
+    tools: [
+        {
+            name: "stream_start",
+            description: "Start an Ultimate streaming session (video/audio/debug) targeting a host:port destination. See c64://docs/index for usage notes.",
+            summary: "Validates stream arguments and forwards the request to firmware, returning status metadata.",
+            inputSchema: streamStartArgsSchema.jsonSchema,
+            tags: ["stream", "start"],
+            prerequisites: [],
+            examples: [
+                { name: "Start audio", description: "Send audio to localhost:9000", arguments: { stream: "audio", target: "127.0.0.1:9000" } },
+            ],
+            workflowHints: [
+                "Use when the user wants to begin audio/video capture; restate the destination target so they know where to listen.",
+                "Remind them to stop the stream after gathering enough data.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    const parsed = streamStartArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Starting Ultimate stream", {
+                        stream: parsed.stream,
+                        target: parsed.target,
+                    });
+                    const result = await ctx.client.streamStart(parsed.stream, parsed.target);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while starting stream", {
+                            details: toRecord(result.details),
+                        });
+                    }
+                    return textResult(`Stream ${parsed.stream} started toward ${parsed.target}.`, {
+                        success: true,
+                        stream: parsed.stream,
+                        target: parsed.target,
+                        details: toRecord(result.details) ?? null,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "stream_stop",
+            description: "Stop an Ultimate streaming session (video/audio/debug).",
+            summary: "Requests the firmware to stop the specified stream and returns completion metadata.",
+            inputSchema: streamStopArgsSchema.jsonSchema,
+            tags: ["stream", "stop"],
+            prerequisites: ["stream_start"],
+            examples: [
+                { name: "Stop audio", description: "Stop audio stream", arguments: { stream: "audio" } },
+            ],
+            workflowHints: [
+                "Call after a monitoring session to release resources; confirm whether the firmware acknowledged the stop.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    const parsed = streamStopArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Stopping Ultimate stream", {
+                        stream: parsed.stream,
+                    });
+                    const result = await ctx.client.streamStop(parsed.stream);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while stopping stream", {
+                            details: toRecord(result.details),
+                        });
+                    }
+                    return textResult(`Stream ${parsed.stream} stop requested.`, {
+                        success: true,
+                        stream: parsed.stream,
+                        details: toRecord(result.details) ?? null,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+    ],
+});

package/dist/tools/types.js

@@ -0,0 +1,99 @@
+import { getPlatformStatus, isPlatformSupported, setPlatform, } from "../platform.js";
+import { ToolUnsupportedPlatformError } from "./errors.js";
+export function defineToolModule(config) {
+    const defaultLifecycle = config.defaultLifecycle ?? "request-response";
+    const defaultTags = Object.freeze([...(config.defaultTags ?? [])]);
+    const defaultResources = Object.freeze([...(config.resources ?? [])]);
+    const defaultPrompts = Object.freeze([...(config.prompts ?? [])]);
+    const defaultWorkflowHints = Object.freeze([...(config.workflowHints ?? [])]);
+    const defaultPrerequisites = Object.freeze([...(config.prerequisites ?? [])]);
+    const defaultPlatforms = config.supportedPlatforms
+        ? Object.freeze([...(config.supportedPlatforms)])
+        : Object.freeze(["c64u"]);
+    const toolMap = new Map(config.tools.map((tool) => [tool.name, tool]));
+    return {
+        domain: config.domain,
+        summary: config.summary,
+        defaultTags,
+        workflowHints: defaultWorkflowHints.length > 0 ? defaultWorkflowHints : undefined,
+        describeTools() {
+            return config.tools.map((tool) => {
+                const workflowHints = mergeOptionalStrings(defaultWorkflowHints, tool.workflowHints);
+                const prerequisites = mergeOptionalStrings(defaultPrerequisites, tool.prerequisites);
+                const platforms = mergePlatforms(defaultPlatforms, tool.supportedPlatforms);
+                const metadata = {
+                    domain: config.domain,
+                    summary: tool.summary ?? tool.description,
+                    lifecycle: tool.lifecycle ?? defaultLifecycle,
+                    resources: mergeUnique(defaultResources, tool.relatedResources),
+                    prompts: mergeUnique(defaultPrompts, tool.relatedPrompts),
+                    examples: tool.examples,
+                    tags: mergeUnique(defaultTags, tool.tags),
+                    ...(workflowHints ? { workflowHints } : {}),
+                    ...(prerequisites ? { prerequisites } : {}),
+                    ...(platforms ? { platforms } : {}),
+                };
+                return {
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                    metadata,
+                };
+            });
+        },
+        async invoke(name, args, ctx) {
+            const tool = toolMap.get(name);
+            if (!tool) {
+                throw new Error(`Unknown tool: ${name}`);
+            }
+            const platforms = mergePlatforms(defaultPlatforms, tool.supportedPlatforms) ?? defaultPlatforms;
+            const status = ctx.platform ?? getPlatformStatus();
+            const setter = ctx.setPlatform ?? setPlatform;
+            if (!isPlatformSupported(status.id, platforms)) {
+                throw new ToolUnsupportedPlatformError(name, status.id, platforms);
+            }
+            const enrichedCtx = {
+                ...ctx,
+                platform: status,
+                setPlatform: setter,
+            };
+            return tool.execute(args, enrichedCtx);
+        },
+    };
+}
+function mergeUnique(base, extra) {
+    if (!extra || extra.length === 0) {
+        return base;
+    }
+    const set = new Set(base);
+    for (const item of extra) {
+        set.add(item);
+    }
+    return Array.from(set);
+}
+function mergeOptionalStrings(base, extra) {
+    if ((!base || base.length === 0) && (!extra || extra.length === 0)) {
+        return base && base.length > 0 ? base : undefined;
+    }
+    const set = new Set(base ?? []);
+    if (extra) {
+        for (const item of extra) {
+            set.add(item);
+        }
+    }
+    const merged = Array.from(set);
+    return merged.length > 0 ? merged : undefined;
+}
+function mergePlatforms(base, extra) {
+    if ((!base || base.length === 0) && (!extra || extra.length === 0)) {
+        return base && base.length > 0 ? base : undefined;
+    }
+    const set = new Set(base ?? []);
+    if (extra) {
+        for (const item of extra) {
+            set.add(item);
+        }
+    }
+    const merged = Array.from(set);
+    return merged.length > 0 ? merged : undefined;
+}

package/dist/viceRunner.js

@@ -0,0 +1,239 @@
+/*
+ * VICE Runner Utility (x64sc) with optional xvfb-run wrapper for headless CI
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+export class ViceExecutionError extends Error {
+    constructor(options) {
+        const first = options.stderr.subarray(0, 1000).toString("utf8");
+        const last = options.stderr.length > 1000
+            ? options.stderr.subarray(options.stderr.length - 1000).toString("utf8")
+            : "";
+        super(`${options.message}\n` +
+            `command: ${options.command}\n` +
+            `exitCode: ${String(options.exitCode)}\n` +
+            `stderr(first 1000):\n${first}\n` +
+            (last ? `stderr(last 1000):\n${last}\n` : "") +
+            `wav: exists=${options.wavExists}, size=${options.wavSize}`);
+        this.name = "ViceExecutionError";
+        this.command = options.command;
+        this.exitCode = options.exitCode;
+        this.stderrFirst = first;
+        this.stderrLast = last;
+        this.wavExists = options.wavExists;
+        this.wavSize = options.wavSize;
+    }
+}
+function resolveMode(input) {
+    const envMode = (process.env.VICE_MODE || "").toLowerCase();
+    const raw = (input || envMode || "ntsc").toLowerCase();
+    return raw === "pal" ? "pal" : "ntsc";
+}
+function resolveLimitCycles(input) {
+    const fromEnv = Number(process.env.VICE_LIMIT_CYCLES);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return Math.floor(fromEnv);
+    if (typeof input === "number" && input > 0)
+        return Math.floor(input);
+    return 120000000;
+}
+function resolveBinary(input) {
+    return process.env.VICE_BINARY || input || "x64sc";
+}
+function which(binary) {
+    const hasSep = binary.includes("/") || binary.includes("\\");
+    if (hasSep) {
+        try {
+            if (fs.existsSync(binary))
+                return binary;
+        }
+        catch { }
+        return null;
+    }
+    const envPath = process.env.PATH || "";
+    for (const dir of envPath.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, binary);
+        try {
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        catch { }
+    }
+    return null;
+}
+function shouldUseXvfb() {
+    if (process.env.FORCE_XVFB === "1")
+        return true;
+    const ciValue = (process.env.CI || "").toLowerCase();
+    return ciValue === "true" || ciValue === "1" || ciValue === "yes";
+}
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+function buildViceArgs(params) {
+    const args = [
+        `-${params.mode}`,
+        "-sounddev", "wav",
+        "-soundarg", `output=${params.wavPath}`,
+        "-soundarg", "bits=16",
+        "-soundrate", "44100",
+        "-soundvol", "100",
+        "-limitcycles", String(params.limitCycles),
+    ];
+    if (typeof params.tune === "number" && Number.isFinite(params.tune)) {
+        args.push("-tune", String(Math.floor(params.tune)));
+    }
+    args.push(params.sidPath);
+    return args;
+}
+function buildCommand(binary, args) {
+    const useXvfb = shouldUseXvfb();
+    if (useXvfb) {
+        const file = "xvfb-run";
+        const wrappedArgs = ["-a", binary, ...args];
+        const display = [file, ...wrappedArgs.map(quoteArg)].join(" ");
+        return { file, args: wrappedArgs, display };
+    }
+    const display = [binary, ...args.map(quoteArg)].join(" ");
+    return { file: binary, args, display };
+}
+function quoteArg(a) {
+    if (/^[A-Za-z0-9_\-\.\/]+$/.test(a))
+        return a;
+    return `'${a.replace(/'/g, "'\\''")}'`;
+}
+function parseWavHeader(buffer) {
+    if (buffer.length < 44)
+        throw new Error("WAV too small");
+    if (buffer.toString("ascii", 0, 4) !== "RIFF")
+        throw new Error("WAV missing RIFF header");
+    if (buffer.toString("ascii", 8, 12) !== "WAVE")
+        throw new Error("WAV missing WAVE header");
+    let offset = 12;
+    let fmt = null;
+    let dataBytes = 0;
+    while (offset + 8 <= buffer.length) {
+        const id = buffer.toString("ascii", offset, offset + 4);
+        const size = buffer.readUInt32LE(offset + 4);
+        offset += 8;
+        if (id === "fmt ") {
+            const audioFormat = buffer.readUInt16LE(offset + 0);
+            const numChannels = buffer.readUInt16LE(offset + 2);
+            const sampleRate = buffer.readUInt32LE(offset + 4);
+            const bitsPerSample = buffer.readUInt16LE(offset + 14);
+            fmt = { audioFormat, numChannels, sampleRate, bitsPerSample, dataBytes: 0 };
+        }
+        else if (id === "data") {
+            dataBytes = size;
+        }
+        offset += size;
+    }
+    if (!fmt)
+        throw new Error("WAV missing fmt chunk");
+    if (dataBytes <= 0)
+        throw new Error("WAV missing data chunk");
+    fmt.dataBytes = dataBytes;
+    return fmt;
+}
+export async function runSidToWav(params) {
+    const mode = resolveMode(params.mode);
+    const limitCycles = resolveLimitCycles(params.limitCycles);
+    const binary = resolveBinary(params.binary);
+    if (!params.sidPath)
+        throw new Error("sidPath is required");
+    if (!params.wavPath)
+        throw new Error("wavPath is required");
+    if (!fs.existsSync(params.sidPath))
+        throw new Error(`SID not found: ${params.sidPath}`);
+    ensureParentDir(params.wavPath);
+    const full = {
+        sidPath: params.sidPath,
+        wavPath: params.wavPath,
+        mode,
+        limitCycles,
+        tune: typeof params.tune === "number" ? params.tune : undefined,
+        binary,
+    };
+    // Validate binary availability to produce clearer 127 semantics even when wrapped by xvfb-run
+    const binaryPath = which(full.binary);
+    if (!binaryPath) {
+        const msg = Buffer.from(`${full.binary} not found in PATH`);
+        throw new ViceExecutionError({
+            message: "VICE binary is not installed",
+            command: full.binary,
+            exitCode: 127,
+            stderr: msg,
+            wavExists: false,
+            wavSize: 0,
+        });
+    }
+    const args = buildViceArgs({ ...full });
+    const cmd = buildCommand(binaryPath, args);
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const exitCode = await new Promise((resolve) => {
+        const child = spawn(cmd.file, cmd.args, { stdio: ["ignore", "pipe", "pipe"] });
+        child.stdout?.on("data", (c) => stdoutChunks.push(Buffer.from(c)));
+        child.stderr?.on("data", (c) => stderrChunks.push(Buffer.from(c)));
+        child.on("error", (err) => {
+            // Map ENOENT to 127-like semantics
+            const enoent = (err && typeof err === "object" && "code" in err && err.code === "ENOENT");
+            // Push a hint into stderr buffer
+            const hint = Buffer.from(String(err?.message || err || "spawn error"));
+            stderrChunks.push(hint);
+            resolve(enoent ? 127 : 1);
+        });
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+    const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+    const stderrBuf = Buffer.concat(stderrChunks);
+    const stderr = stderrBuf.toString("utf8");
+    const wavExists = fs.existsSync(full.wavPath);
+    const wavStat = wavExists ? fs.statSync(full.wavPath) : null;
+    const wavSize = wavStat?.size ?? 0;
+    if (exitCode !== 0) {
+        throw new ViceExecutionError({
+            message: "VICE failed (non-zero exit code)",
+            command: cmd.display,
+            exitCode,
+            stderr: stderrBuf,
+            wavExists,
+            wavSize,
+        });
+    }
+    if (!wavExists || wavSize === 0) {
+        throw new ViceExecutionError({
+            message: "VICE did not produce a WAV file",
+            command: cmd.display,
+            exitCode,
+            stderr: stderrBuf,
+            wavExists,
+            wavSize,
+        });
+    }
+    const header = fs.readFileSync(full.wavPath);
+    const info = parseWavHeader(header);
+    if (info.audioFormat !== 1 || info.sampleRate !== 44100 || info.bitsPerSample !== 16) {
+        throw new ViceExecutionError({
+            message: `Unexpected WAV format (expected PCM 16-bit @ 44100 Hz); got format=${info.audioFormat}, bits=${info.bitsPerSample}, rate=${info.sampleRate}`,
+            command: cmd.display,
+            exitCode,
+            stderr: stderrBuf,
+            wavExists,
+            wavSize,
+        });
+    }
+    return {
+        command: cmd.display,
+        exitCode: exitCode ?? 0,
+        stdout,
+        stderr,
+        wavPath: full.wavPath,
+        wavInfo: info,
+    };
+}

package/doc/MCP_SETUP.md

@@ -0,0 +1,153 @@
+# MCP Setup Guide
+
+Step-by-step instructions for installing, configuring, and running the Commodore 64 MCP server with the official Model Context Protocol SDK.
+
+## Audience
+
+This guide targets engineers and advanced users who need to bring the C64 Bridge server online, wire it into an MCP-capable client (such as GitHub Copilot Chat), and verify connectivity against either real hardware or the bundled mock server.
+
+## Prerequisites
+
+- Node.js 18 or newer (Node 20 recommended)
+- npm (ships with Node)
+- Optional: Ultimate 64 or Commodore 64 Ultimate hardware reachable over HTTP
+- macOS, Linux, or WSL are fully supported. Windows works when the shell supports stdio transports.
+
+## 1. Install Dependencies
+
+```bash
+npm install
+```
+
+The install step pulls the MCP SDK, test tooling, and the generated REST client stubs.
+
+## 2. Configure the C64 Endpoint
+
+The server looks for configuration in the following order (first match wins):
+
+1. JSON file referenced by the `C64BRIDGE_CONFIG` environment variable (if the variable is unset, the default path is `~/.c64bridge.json`)
+2. `.c64bridge.json` in the repository root
+3. Built-in defaults (`host=c64u`, `port=80`)
+
+Recommended configuration file:
+
+```json
+{
+  "c64u": {
+    "host": "c64u",
+    "port": 80
+  }
+}
+```
+
+## 3. Run the MCP Server (source tree)
+
+For active development against TypeScript sources:
+
+```bash
+npm start
+```
+
+`npm start` locates `src/mcp-server.ts`, loads the config, and launches the stdio transport. Successful startup prints:
+
+```text
+> c64bridge@0.4.0 start
+> node scripts/start.mjs
+
+Starting c64bridge MCP server...
+[c64u] GET http://192.168.1.64 status=200 bytes=41608 latencyMs=177
+Connectivity check succeeded for c64 device at http://192.168.1.64
+[c64u] GET /v1/machine:readmem status=200 bytes=1 latencyMs=31
+Zero-page probe @ $0000: $00
+c64bridge MCP server running on stdio
+```
+
+When TypeScript is unavailable (for example inside a packaged release tarball) use the compiled entry point:
+
+```bash
+npm run build
+node dist/index.js
+```
+
+The npm package also exposes a CLI named `c64bridge`; `npx c64bridge` or an installed binary launches the same stdio server.
+
+## 4. Connect an MCP Client
+
+### GitHub Copilot Chat (VS Code)
+
+1. Enable MCP support: Settings > Extensions > GitHub Copilot > Chat > Experimental: MCP.
+2. Add the server entry (Command Palette > Preferences: Open Settings (JSON)).
+
+   When running from the cloned repository after `npm run build`:
+
+   ```json
+   {
+     "github.copilot.chat.experimental.mcp": {
+       "servers": [
+         {
+           "name": "c64bridge",
+           "command": "node",
+           "args": ["./dist/index.js"],
+           "type": "stdio"
+         }
+       ]
+     }
+   }
+   ```
+
+   When using the published npm package instead of the local build:
+
+   ```json
+   {
+     "github.copilot.chat.experimental.mcp": {
+       "servers": [
+         {
+           "name": "c64bridge",
+           "command": "node",
+           "args": ["./node_modules/c64bridge/dist/index.js"],
+           "type": "stdio"
+         }
+       ]
+     }
+   }
+   ```
+
+3. Keep `npm start` or the CLI running in the background.
+4. In Copilot Chat, reference tools naturally (for example, "Read the current screen" or "Upload and run this BASIC program").
+
+## 5. Verify Operation
+
+Run the automated test suites against the mock hardware:
+
+```bash
+npm test
+```
+
+To exercise a real device, ensure your config points at the desired host/port and append `-- --real`:
+
+```bash
+npm test -- --real
+```
+
+`npm run coverage` captures c8 coverage for CI parity.
+
+## 6. Common Tasks
+
+- Rebuild TypeScript output: `npm run build`
+- Regenerate REST client from OpenAPI: `npm run api:generate`
+- Refresh RAG embeddings after updating `data/`: `npm run rag:rebuild`
+- Smoke test the packaged tarball (used in CI): `npm run verify-package`
+
+## 7. Troubleshooting
+
+- Confirm connectivity logs appear on startup; missing logs indicate the REST endpoint is unreachable.
+- If `npm start` exits immediately, ensure Node can locate `ts-node/register` (installed via dev dependencies).
+- When GitHub Copilot cannot see tools, restart VS Code after editing MCP settings.
+- Additional guidance lives in `doc/troubleshooting-mcp.md`.
+
+## 8. Where to Go Next
+
+- Architecture and contribution details: `doc/developer.md`
+- MCP tooling deep dive: `doc/tasks/use-mcp-sdk.md`
+- Agent personas and context layering: `AGENTS.md`
+- Knowledge base surfaced to LLMs: `data/` markdown files and specs

package/doc/README.md

@@ -0,0 +1,7 @@
+# Documentation Folder
+
+This directory contains **developer and extended user documentation** for this Model Context Protocol (MCP) server.  
+
+Unlike the [`data`](../data/README.md) folder, which provides domain-specific C64 knowledge, this directory focuses on **implementation details** and  **usage guides** relevant to developers of this project, and end users.
+
+All documents in this folder are included in the **Retrieval-Augmented Generation (RAG)** index to allow the MCP’s AI components to retrieve and reason about internal design and operational aspects.