c64bridge 0.9.2 → 0.9.3

package/dist/c64Client.js

@@ -59,7 +59,6 @@ export class C64Client {
             }).then((sel) => sel.facade);
             this.allFacades.set("c64u", this.facadePromise);
             this.initPromise = Promise.resolve();
-            void this.primeGreetingDd00Cache(["c64u"]);
             return;
         }
         const allFacadesPromise = createAllFacades(undefined, {
@@ -76,12 +75,6 @@ export class C64Client {
                 this.allFacades.set(secondaryType, Promise.resolve(secondary));
             }
         });
-        void this.initPromise.then(async () => {
-            if (this.allFacades.has("vice")) {
-                await this.prewarmBackends(["vice"]);
-            }
-            void this.primeGreetingDd00Cache();
-        }).catch(() => { });
     }
     async requireViceBackend() {
         const facade = await this.facadePromise;

package/dist/config.js

@@ -7,6 +7,7 @@ const DEFAULT_CONFIG = {
     c64_host: DEFAULT_HOST,
     baseUrl: buildBaseUrl(DEFAULT_HOST, DEFAULT_PORT),
     c64_port: DEFAULT_PORT,
+    vicePrewarm: false,
 };
 let cachedConfig = null;
 export function loadConfig() {
@@ -35,6 +36,7 @@ export function loadConfig() {
     rawConfig ?? (rawConfig = {});
     // New schema: prefer c64u.{host,port,baseUrl}; keep legacy fields as fallback
     const c64u = rawConfig?.c64u;
+    const vice = rawConfig?.vice;
     const parsedC64uHost = parseEndpoint(configuredString(c64u?.host));
     const parsedC64uHostname = parseEndpoint(configuredString(c64u?.hostname));
     const parsedLegacyHost = parseEndpoint(configuredString(rawConfig?.c64_host));
@@ -73,6 +75,7 @@ export function loadConfig() {
         baseUrl,
         c64_port: port,
         networkPassword: firstDefined(configuredString(process.env.C64U_PASSWORD), configuredString(c64u?.networkPassword), configuredString(rawConfig?.networkPassword)),
+        vicePrewarm: firstDefined(configuredBoolean(process.env.VICE_PREWARM), configuredBoolean(vice?.prewarm), configuredBoolean(rawConfig?.vicePrewarm)) ?? false,
     };
     cachedConfig = config;
     return config;
@@ -92,6 +95,25 @@ function configuredPort(value) {
     }
     return undefined;
 }
+function configuredBoolean(value) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (value === 1)
+            return true;
+        if (value === 0)
+            return false;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["1", "true", "yes", "on"].includes(normalized))
+            return true;
+        if (["0", "false", "no", "off"].includes(normalized))
+            return false;
+    }
+    return undefined;
+}
 function normaliseBaseUrl(value) {
     const input = configuredString(value);
     if (!input)

package/dist/mcp-server.js

@@ -60,6 +60,7 @@ async function main() {
     writeDiagnosticEvent("config_loaded", {
         baseUrl,
         hasNetworkPassword: Boolean(config.networkPassword),
+        vicePrewarm: config.vicePrewarm,
     });
     // Initialize C64 client (reuse existing)
     const client = await withDiagnosticSpan("startup", "create_client", { baseUrl }, async () => new C64Client(baseUrl, {
@@ -69,11 +70,22 @@ async function main() {
     const initialBackendType = await withDiagnosticSpan("startup", "resolve_active_backend", {}, () => client.getActiveBackendType());
     setPlatform(initialBackendType);
     writeDiagnosticEvent("platform_initialised", { platform: initialBackendType });
-    void withDiagnosticSpan("startup", "prewarm_backends", { backends: ["vice"] }, () => client.prewarmBackends(["vice"])).then((results) => {
-        writeDiagnosticEvent("backend_prewarm_complete", { results });
-    }).catch((error) => {
-        writeDiagnosticEvent("backend_prewarm_failed", { error });
-    });
+    if (config.vicePrewarm) {
+        const availableBackends = client.getAvailableBackends();
+        if (availableBackends.includes("vice")) {
+            writeDiagnosticEvent("vice_prewarm_start");
+            void client.prewarmBackends(["vice"])
+                .then((result) => {
+                writeDiagnosticEvent("vice_prewarm_complete", { result });
+            })
+                .catch((error) => {
+                writeDiagnosticEvent("vice_prewarm_failed", { error });
+            });
+        }
+        else {
+            writeDiagnosticEvent("vice_prewarm_skipped", { reason: "vice_not_configured" });
+        }
+    }
     const rag = createLazyRagRetriever(() => initRag(), {
         onInitStart() {
             writeDiagnosticEvent("rag_init_start");

package/dist/rag/knowledgeIndex.js

@@ -286,7 +286,14 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.io.cia.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "hardware"],
             },
             {
@@ -298,19 +305,48 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "zero-page"],
             },
+            {
+                uri: RESOURCE_URIS.basic.romRoutines,
+                name: "BASIC ROM Routines Memory Map",
+                description: "Memory-map-style breakdown of BASIC ROM routines, tables, parser helpers, and entry points.",
+                relativePath: "data/basic/rom-routines.md",
+                priority: "reference",
+                summary: "Maps BASIC ROM landmarks, reusable interpreter routines, numeric helpers, string helpers, and C64-specific BASIC continuation entries.",
+                prompts: ["memory-debug", "assembly-program", "basic-program"],
+                tools: ["read", "verify_and_write_memory"],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.basic.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
+                tags: ["memory", "basic", "rom"],
+            },
             {
                 uri: RESOURCE_URIS.kernal.romRoutines,
-                name: "KERNAL Memory Map",
-                description: "Detailed breakdown of KERNAL ROM routines and entry points.",
-                relativePath: "data/memory/kernal-memory-map.md",
+                name: "KERNAL ROM Routines Memory Map",
+                description: "Memory-map-style breakdown of KERNAL ROM routines, vectors, tables, and entry points.",
+                relativePath: "data/kernal/rom-routines.md",
                 priority: "reference",
-                summary: "Lists KERNAL ROM vectors and service routines for OS-level functionality.",
+                summary: "Maps KERNAL ROM vectors, jump table entries, internal routines, serial/tape/screen services, and reset handlers.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "kernal"],
             },
             {
@@ -322,7 +358,12 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read", "debugreg_write"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.io.cia.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["io", "hardware"],
             },
             {
@@ -334,7 +375,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read"],
-                relatedResources: [RESOURCE_URIS.io.spec, RESOURCE_URIS.memory.map],
+                relatedResources: [
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                ],
                 tags: ["io", "hardware"],
             },
         ],

package/dist/rag/resourceUris.js

@@ -10,6 +10,7 @@ export const RESOURCE_URIS = {
     basic: {
         spec: "c64://basic/spec",
         pitfalls: "c64://basic/pitfalls",
+        romRoutines: "c64://basic/rom-routines",
     },
     assembly: {
         spec6510: "c64://assembly/6510-spec",
@@ -80,6 +81,7 @@ export const CANONICAL_KNOWLEDGE_RESOURCE_URIS = Object.freeze([
     RESOURCE_URIS.graphics.spriteCharset.bestPractices,
     RESOURCE_URIS.memory.map,
     RESOURCE_URIS.memory.zeroPageAndWorkspace,
+    RESOURCE_URIS.basic.romRoutines,
     RESOURCE_URIS.kernal.romRoutines,
     RESOURCE_URIS.io.spec,
     RESOURCE_URIS.io.cia.spec,

package/doc/developer.md

@@ -124,9 +124,10 @@ Environment knobs: `RAG_EMBEDDINGS_DIR`, `RAG_BUILD_ON_START`, `RAG_REINDEX_INTE
 
 Tagging a release through the GitHub release UI triggers [`.github/workflows/release.yaml`](../.github/workflows/release.yaml), which publishes the npm package and then publishes the same version to the MCP Registry.
 
-- Required GitHub secret: `NPM_TOKEN`
+- npm publication now uses trusted publishing over GitHub OIDC rather than an `NPM_TOKEN` secret
+- One-time npm setup is required in the package settings for `c64bridge`: provider `GitHub Actions`, repository `chrisgleissner/c64bridge`, workflow `.github/workflows/release.yaml`, and allowed action `npm publish`
 - No dedicated MCP Registry secret is required for the GitHub-driven flow; the workflow uses `mcp-publisher login github-oidc`
-- The release workflow must grant `id-token: write` so GitHub Actions can mint the short-lived OIDC token used by `mcp-publisher`
+- The release workflow must grant `id-token: write` so GitHub Actions can mint the short-lived OIDC tokens used by both npm trusted publishing and `mcp-publisher`
 - Keep [`package.json`](../package.json) `mcpName` aligned with [`server.json`](../server.json) `name`
 - The root [`server.json`](../server.json) is the MCP Registry manifest; [`mcp/server.json`](../mcp/server.json) remains generated MCP interface output
 

package/mcp/resources.json

@@ -522,6 +522,11 @@
         },
         "order": 0,
         "relatedResources": [
+          "c64://memory/zero-page-and-workspace",
+          "c64://basic/rom-routines",
+          "c64://kernal/rom-routines",
+          "c64://io/spec",
+          "c64://io/cia/spec",
           "c64://assembly/6510-spec"
         ]
       }
@@ -557,19 +562,60 @@
         "order": 1,
         "relatedResources": [
           "c64://memory/map",
+          "c64://basic/rom-routines",
+          "c64://kernal/rom-routines",
           "c64://assembly/6510-spec"
         ]
       }
     },
     {
-      "name": "KERNAL Memory Map",
+      "name": "BASIC ROM Routines Memory Map",
+      "uri": "c64://basic/rom-routines",
+      "description": "Memory-map-style breakdown of BASIC ROM routines, tables, parser helpers, and entry points.",
+      "mimeType": "text/markdown",
+      "_meta": {
+        "domain": "memory",
+        "priority": "reference",
+        "summary": "Maps BASIC ROM landmarks, reusable interpreter routines, numeric helpers, string helpers, and C64-specific BASIC continuation entries.",
+        "prompts": [
+          "memory-debug",
+          "assembly-program",
+          "basic-program"
+        ],
+        "tools": [
+          "read",
+          "verify_and_write_memory"
+        ],
+        "tags": [
+          "memory",
+          "basic",
+          "rom"
+        ],
+        "bundle": {
+          "id": "memory",
+          "title": "Memory & I/O Reference",
+          "summary": "Critical tables for RAM layout, zero-page vectors, and peripheral I/O registers.",
+          "order": 5
+        },
+        "order": 2,
+        "relatedResources": [
+          "c64://memory/map",
+          "c64://memory/zero-page-and-workspace",
+          "c64://kernal/rom-routines",
+          "c64://basic/spec",
+          "c64://assembly/6510-spec"
+        ]
+      }
+    },
+    {
+      "name": "KERNAL ROM Routines Memory Map",
       "uri": "c64://kernal/rom-routines",
-      "description": "Detailed breakdown of KERNAL ROM routines and entry points.",
+      "description": "Memory-map-style breakdown of KERNAL ROM routines, vectors, tables, and entry points.",
       "mimeType": "text/markdown",
       "_meta": {
         "domain": "memory",
         "priority": "reference",
-        "summary": "Lists KERNAL ROM vectors and service routines for OS-level functionality.",
+        "summary": "Maps KERNAL ROM vectors, jump table entries, internal routines, serial/tape/screen services, and reset handlers.",
         "prompts": [
           "memory-debug",
           "assembly-program"
@@ -588,9 +634,12 @@
           "summary": "Critical tables for RAM layout, zero-page vectors, and peripheral I/O registers.",
           "order": 5
         },
-        "order": 2,
+        "order": 3,
         "relatedResources": [
           "c64://memory/map",
+          "c64://memory/zero-page-and-workspace",
+          "c64://basic/rom-routines",
+          "c64://io/spec",
           "c64://assembly/6510-spec"
         ]
       }
@@ -625,9 +674,11 @@
           "summary": "Critical tables for RAM layout, zero-page vectors, and peripheral I/O registers.",
           "order": 5
         },
-        "order": 3,
+        "order": 4,
         "relatedResources": [
           "c64://memory/map",
+          "c64://memory/zero-page-and-workspace",
+          "c64://io/cia/spec",
           "c64://assembly/6510-spec"
         ]
       }
@@ -661,10 +712,11 @@
           "summary": "Critical tables for RAM layout, zero-page vectors, and peripheral I/O registers.",
           "order": 5
         },
-        "order": 4,
+        "order": 5,
         "relatedResources": [
           "c64://io/spec",
-          "c64://memory/map"
+          "c64://memory/map",
+          "c64://memory/zero-page-and-workspace"
         ]
       }
     },
@@ -919,6 +971,7 @@
           "c64://graphics/sprite-charset/best-practices",
           "c64://memory/map",
           "c64://memory/zero-page-and-workspace",
+          "c64://basic/rom-routines",
           "c64://kernal/rom-routines",
           "c64://io/spec",
           "c64://io/cia/spec",

package/mcp/server.json

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

package/mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "entry": "dist/index.js",
   "type": "stdio",
@@ -129,7 +129,7 @@
       "default": "6502"
     },
     "VICE_VISIBLE": {
-      "description": "Launch VICE visibly on the desktop instead of headless/Xvfb when possible",
+      "description": "Launch VICE as a desktop window when true; use headless/Xvfb managed launch when false",
       "default": "true"
     },
     "VICE_WARP": {
@@ -137,15 +137,19 @@
       "default": "false when visible, true when headless"
     },
     "VICE_ARGS": {
-      "description": "Extra command-line arguments forwarded to managed VICE launches",
+      "description": "Extra command-line arguments forwarded to managed VICE launches, such as -minimized for a visible window that starts iconified",
       "default": ""
     },
+    "VICE_PREWARM": {
+      "description": "Set to 1 to start/connect VICE in the background during MCP startup; disabled by default so VICE starts lazily on first use",
+      "default": "0"
+    },
     "VICE_RUN_TIMEOUT_MS": {
       "description": "Timeout for headless VICE runs in milliseconds",
       "default": "10000"
     },
     "FORCE_XVFB": {
-      "description": "Set to 1 to force managed VICE launches to run under Xvfb",
+      "description": "Set to 1 to force managed VICE launches to use Xvfb even when a graphical session is detected",
       "default": "0"
     },
     "DISABLE_XVFB": {

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "c64bridge",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "mcpName": "io.github.chrisgleissner/c64bridge",
   "description": "C64 Bridge MCP server for Commodore 64 Ultimate hardware and VICE emulator control",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrisgleissner/c64bridge.git"
+  },
   "type": "module",
   "main": "dist/index.js",
   "packageManager": "bun@1.3.1",
@@ -63,22 +67,22 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "axios": "^1.16.0",
-    "date-fns": "^4.1.0",
-    "fastify": "^5.8.5",
+    "axios": "^1.18.1",
+    "date-fns": "^4.4.0",
+    "fastify": "^5.10.0",
     "jimp": "^1.6.1",
     "meyda": "^5.6.3",
     "octokit": "^5.0.5",
     "pitchfinder": "^2.3.4",
     "reflect-metadata": "^0.2.2",
-    "yaml": "^2.8.4"
+    "yaml": "^2.9.0"
   },
   "optionalDependencies": {
     "naudiodon": "^2.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "tsx": "^4.21.0",
+    "@types/node": "^25.9.5",
+    "tsx": "^4.23.0",
     "typescript": "^6.0.3"
   },
   "files": [

package/scripts/update-readme.ts

@@ -86,6 +86,7 @@ function resolveJsonConfigKey(name: string): string {
     VICE_VISIBLE: "vice.visible",
     VICE_WARP: "vice.warp",
     VICE_ARGS: "vice.args",
+    VICE_PREWARM: "vice.prewarm",
   };
   return map[name] ?? "—";
 }

package/server.json

@@ -4,16 +4,16 @@
   "title": "C64 Bridge",
   "description": "MCP server for Commodore 64 Ultimate hardware and VICE emulator control.",
   "repository": {
-    "url": "https://github.com/chrisgleissner/c64bridge",
+    "url": "git+https://github.com/chrisgleissner/c64bridge.git",
     "source": "github"
   },
   "websiteUrl": "https://github.com/chrisgleissner/c64bridge",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "c64bridge",
-      "version": "0.9.2",
+      "version": "0.9.3",
       "transport": {
         "type": "stdio"
       },