c64bridge 0.7.4 → 0.8.0

package/doc/reviews/vice-support-review.md

@@ -0,0 +1,185 @@
+# VICE Support Review
+
+Date: 2026-03-08
+Reviewer: GitHub Copilot
+Scope: PR #103 (`feat/vice`) plus all VICE-related source, grouped tools, tests, docs, generated MCP interface metadata, and CI wiring.
+
+## Verdict
+
+Not production-ready.
+
+The branch introduces useful VICE backend work, but the published MCP compatibility contract is not trustworthy yet. The highest-risk issue is that grouped-tool per-operation platform metadata is not enforced centrally, so several operations declared as c64u-only execute on VICE anyway. That breaks the generated MCP surface, README compatibility tables, and the implied contract relied on by clients and prompts.
+
+## Findings
+
+### VICE-001: Grouped per-operation platform support is metadata-only, and multiple c64u-only operations execute on VICE anyway
+
+- Severity: high
+- Confidence: high
+
+Evidence:
+
+- `src/tools/types.ts:296` publishes `operationPlatforms` into metadata, but `defineToolModule().invoke()` only checks the merged tool-level platforms at `src/tools/types.ts:316-317`.
+- `src/tools/registry/program.ts:110` declares `load_prg` and `run_crt` as c64u-only, but `src/tools/registry/program.ts:29` and `src/tools/registry/program.ts:47` wire them directly to raw handlers (`groupedProgramHandlers.load_prg` / `run_crt`) instead of routing through `programRunnersModule.invoke()`.
+- The raw handlers themselves do not perform a platform check. `executeLoadPrg()` and `executeRunCrt()` in `src/tools/programRunners.ts:634` and `src/tools/programRunners.ts:701` call the client directly.
+- Runtime probe on VICE using `node --loader ts-node/esm` showed both grouped operations succeed instead of raising `unsupported_platform`:
+
+```text
+{"called":"loadPrgFile","path":"//USB0/demo.prg"}
+{"op":"load_prg","isError":false,"error":null,"success":true}
+{"called":"runCrtFile","path":"//USB0/game.crt"}
+{"op":"run_crt","isError":false,"error":null,"success":true}
+```
+
+- The same pattern exists in other grouped tools:
+  - `src/tools/registry/drive.ts:89` marks `load_rom` c64u-only, but `src/tools/storage.ts:454` has no per-tool platform restriction. Runtime probe on VICE succeeded.
+  - `src/tools/registry/disk.ts:365` marks `file_info` c64u-only, but `src/tools/storage.ts:542` has no per-tool platform restriction. Runtime probe on VICE succeeded.
+  - `src/tools/registry/sound.ts:156-157` marks `play_sid_file` / `play_mod_file` c64u-only, but `src/tools/audio.ts:770` and `src/tools/audio.ts:811` have no per-tool platform restriction. Runtime probe on VICE succeeded.
+
+Why this matters:
+
+- MCP clients, generated schemas, prompts, and README tables will all believe those operations are unavailable on VICE, while runtime execution may still proceed.
+- The failure mode is especially dangerous because it is silent contract drift, not an obvious exception.
+- The current design makes correctness depend on whether a grouped operation happens to route through a legacy tool that already has its own per-tool platform guard.
+
+Recommended fix:
+
+- Enforce `operationPlatforms` inside the grouped dispatcher path rather than treating it as documentation-only metadata.
+- Avoid raw handler reuse for grouped operations when the original module-level invocation path is responsible for platform checks.
+- Add explicit grouped-tool tests for every c64u-only operation exposed through grouped tools on the VICE platform.
+
+### VICE-002: Capability declarations, implementation, tests, and docs disagree on whether VICE supports drive and storage management
+
+- Severity: high
+- Confidence: high
+
+Evidence:
+
+- `src/platform.ts:31` declares VICE limited by `no-drive-management`.
+- The backend itself still rejects several storage/drive operations on VICE:
+  - `src/device.ts:625` rejects `driveLoadRom`
+  - `src/device.ts:681` rejects `filesInfo`
+  - `src/device.ts:682-685` reject disk-image creation
+- These unsupported backend paths are covered by tests in:
+  - `test/device.test.mjs:247` (`driveLoadRom throws unsupported`)
+  - `test/device.test.mjs:308` (`filesInfo throws unsupported`)
+- Yet the grouped MCP suite expects success for grouped VICE drive/storage calls that the public compatibility tables mark as unavailable on VICE:
+  - `test/suites/mcpServerCallToolSuite.mjs:239` expects `c64_drive` `load_rom` success
+  - `test/suites/mcpServerCallToolSuite.mjs:255` expects `c64_disk` `file_info` success
+- README compatibility tables currently mark those operations as unavailable on VICE:
+  - `README.md:297` `file_info`
+  - `README.md:309` `load_rom`
+
+Why this matters:
+
+- The codebase currently contains three mutually inconsistent stories:
+  1. Platform metadata says VICE has no drive management.
+  2. The grouped runtime can still execute selected drive/storage operations on VICE.
+  3. The raw backend still rejects a substantial subset of drive/storage operations on VICE.
+- This inconsistency makes it impossible to reason safely about platform parity or to generate correct client behavior.
+
+Recommended fix:
+
+- Decide whether VICE drive/storage support is a real supported feature or a phase-one experiment.
+- If it is supported, remove the stale `no-drive-management` limitation, align docs, and add real-device coverage.
+- If it is not supported, close the grouped-tool escape hatches and update the tests that currently encode success on VICE.
+
+### VICE-003: Real VICE coverage is materially weaker than the published feature surface, and mock-only behavior is being presented as platform support
+
+- Severity: medium
+- Confidence: high
+
+Evidence:
+
+- In `test/device.test.mjs`, the resource-backed drive/config tests only run under `useViceMock`:
+  - drive tests are guarded under the mock-only block starting near `test/device.test.mjs:187`
+  - config read/write tests are also guarded under the mock-only block starting near `test/device.test.mjs:269`
+- The same file only verifies unsupported behavior for the real-VICE path on several operations (`loadPrgFile`, `runCrtFile`, `sidplayFile`, `driveLoadRom`, `filesInfo`, flash config operations).
+- CI does run both VICE mock tests and VICE device tests (`.github/workflows/build-and-test.yaml:24-31`), but the real-device job does not prove the full grouped feature matrix claimed in README or generated metadata.
+- My targeted existing test run passed cleanly (`70 passed / 0 failed`) even though the grouped-tool contract violations above are real. That means the current suite is not protecting the public grouped MCP surface sufficiently.
+
+Why this matters:
+
+- The mock server is currently doing more than emulating a thin transport boundary. It is effectively defining platform behavior for features that are not yet validated on real VICE.
+- The branch therefore risks shipping mock-server parity instead of real emulator parity.
+
+Recommended fix:
+
+- Split the VICE matrix into clearly labeled categories: real-device supported, mock-only experimental, and unsupported.
+- Add grouped-tool regression tests for the actual public MCP operations on VICE, not just backend/facade tests.
+- Avoid advertising VICE support in README/generated tables for operations that have only been validated against the mock server.
+
+### VICE-004: The README and generated compatibility surface overstate confidence in VICE support
+
+- Severity: medium
+- Confidence: high
+
+Evidence:
+
+- README currently presents a crisp compatibility matrix for grouped tools, including VICE columns for operations such as:
+  - `README.md:367-368` `load_prg`, `run_crt`
+  - `README.md:394-395` `play_mod_file`, `play_sid_file`
+  - `README.md:297` `file_info`
+  - `README.md:309` `load_rom`
+- Because `operationPlatforms` is not authoritative at runtime, the tables are currently descriptive rather than contractual.
+- The generated MCP tool metadata is built from the same source of truth, so this drift is not isolated to the README.
+
+Why this matters:
+
+- Consumers will treat those tables and generated schemas as API contract, not as aspirational guidance.
+- When the documented matrix diverges from live runtime behavior, automation and prompts become unsafe.
+
+Recommended fix:
+
+- Treat generated compatibility output as release-blocking and validate it with runtime tests.
+- Do not publish per-operation platform tables until grouped dispatch enforces them.
+
+## Validation Performed
+
+- Reviewed implementation across `src/device.ts`, `src/vice/viceClient.ts`, `src/vice/process.ts`, `src/vice/readiness.ts`, grouped tool registries, legacy tool modules, docs, CI, and tests.
+- Ran targeted tests:
+
+```text
+runTests: test/groupedToolsShims.test.mjs
+runTests: test/programRunnersModule.test.mjs
+runTests: test/device.test.mjs
+Result: 70 passed, 0 failed
+```
+
+- Ran targeted runtime probes with `node --loader ts-node/esm` against the checked-out TypeScript sources on platform `vice`.
+- Confirmed that grouped `c64_program.load_prg`, `c64_program.run_crt`, `c64_drive.load_rom`, `c64_disk.file_info`, `c64_sound.play_sid_file`, and `c64_sound.play_mod_file` execute successfully on VICE despite being declared c64u-only in grouped tool metadata.
+
+## Coverage Assessment
+
+Coverage is not sufficient for the grouped public MCP contract.
+
+- Strengths:
+  - Core VICE monitor protocol parsing and request/response handling are exercised well.
+  - The VICE smoke test covers basic run-and-readiness flow.
+  - Some backend unsupported paths are explicitly tested.
+
+- Gaps:
+  - The grouped MCP operations are not exhaustively tested against their per-operation platform declarations.
+  - Real-VICE coverage does not match the feature surface advertised in grouped tool metadata and README.
+  - Several regressions are only detectable with end-to-end grouped-tool invocation, not backend-only tests.
+
+## Documentation Assessment
+
+Documentation is not yet reliable enough for release.
+
+- The README compatibility matrix is more precise than the runtime enforcement actually is.
+- `platform.ts` still advertises `no-drive-management` for VICE while grouped docs/tests/runtime partially expose drive operations.
+- The branch needs a single explicit statement of what is supported on real VICE, what is mock-only, and what remains phase-one unsupported.
+
+## Duplication and Architectural Fit
+
+- The broad `C64Facade` abstraction remains workable, but VICE support is currently split across backend restrictions, grouped metadata, README generation, and mock-server behavior without a single authoritative enforcement point.
+- The highest-value simplification is to move per-operation platform enforcement into one place in grouped dispatch and make documentation generation consume that authoritative runtime rule.
+
+## What I Did Not Fully Verify
+
+- I did not run the full `npm run test:matrix` or a full build during this review.
+- I did not validate every drive/config resource behavior against a real installed VICE instance.
+- I did not audit every generated file under `mcp/` line-by-line after tracing the metadata source.
+
+Those limitations do not change the main verdict because the highest-severity issues were verified directly in source and with targeted runtime probes.

package/doc/troubleshooting-mcp.md

@@ -8,16 +8,37 @@ Field notes for the stdio-based Model Context Protocol server. Use these checks
 # 1. Is the MCP server running?
 ps -ef | grep "c64bridge" | grep -v grep
 
-# 2. Do startup logs show the connectivity probe?
+# 2. Do startup logs show the diagnostics file and connectivity probe?
 tail -n20 ~/.c64bridge.log  # or the terminal running npm start
 
-# 3. Can we reach the configured REST endpoint directly?
+# 3. Inspect the persistent MCP diagnostics trail
+ls -1t ~/.c64bridge/diagnostics | head
+tail -n50 ~/.c64bridge/diagnostics/<latest-file>.ndjson
+
+# 4. Can we reach the configured REST endpoint directly?
 curl -s http://<your-c64-host>/v1/info | jq .version
 
-# 4. When using the mock server
+# 5. When using the mock server
 npm test -- --mock
 ```
 
+## Persistent Diagnostics
+
+The MCP server now writes a newline-delimited JSON diagnostics file for each session.
+
+- Default location: `~/.c64bridge/diagnostics/`
+- Override location: set `C64BRIDGE_DIAGNOSTICS_DIR=/path/to/dir`
+- Disable only if necessary: set `C64BRIDGE_DISABLE_DIAGNOSTICS=1`
+
+Each file records:
+
+- MCP startup and readiness
+- tool, prompt, and resource request lifecycle events
+- unhandled rejections, warnings, and uncaught exceptions
+- VICE/Xvfb startup failures with captured stderr and stdout tails
+
+When VS Code or Copilot appears to crash, preserve the newest `.ndjson` file before restarting. It is the fastest way to tell whether the MCP server was failing, hanging, or repeatedly restarting.
+
 ## Common Issues & Fixes
 
 ### 1. Server Starts Without Connectivity Logs
@@ -47,6 +68,13 @@ npm test -- --mock
 2. Verify the settings JSON matches the snippet in `AGENTS.md` (`command`, `args`, `type: "stdio"`).
 3. Keep `npm start` (or `npx c64bridge`) running; Copilot terminates the stdio process when the chat closes.
 4. Inspect the Copilot output channel for connection errors and ensure the stdio server entry is configured and running.
+5. Correlate the VS Code/Copilot timestamp with the newest file under `~/.c64bridge/diagnostics/`.
+
+If the entire VS Code window crashes rather than just the MCP session, also collect:
+
+- VS Code logs from `Help` -> `Open Logs Folder`
+- extension host logs and crash dumps from the same time window
+- the matching `.ndjson` file from `~/.c64bridge/diagnostics/`
 
 ### 3. Tests Fail Because Mock Server Is Missing
 
@@ -151,9 +179,10 @@ Use these checks to validate the full stack:
 ## Key Lessons Learned
 
 1. Connectivity logs are the fastest signal—watch the console during startup.
-2. Keep configuration files small and explicit; mismatched hosts cause silent timeouts.
-3. Automated tests cover most workflows; run `npm test` before suspecting hardware.
-4. Copilot Chat terminates the stdio server when the session ends—restart `npm start` as needed.
+2. The diagnostics `.ndjson` file is now the authoritative crash trail for MCP sessions.
+3. Keep configuration files small and explicit; mismatched hosts cause silent timeouts.
+4. Automated tests cover most workflows; run `npm test` before suspecting hardware.
+5. Copilot Chat terminates the stdio server when the session ends—restart `npm start` as needed.
 
 ## Emergency Recovery
 

package/doc/vice/support-matrix.md

@@ -0,0 +1,54 @@
+# VICE Support Matrix
+
+This document is the source of truth for VICE support in the public MCP surface.
+
+## Decision Rules
+
+- `supported`: part of the public VICE contract, enforced at runtime, documented in generated compatibility tables, and covered by regression tests.
+- `mock-only experimental`: may exist in test scaffolding or backend experiments, but must not appear as supported in public MCP metadata or README compatibility tables.
+- `unsupported`: blocked at runtime on VICE with `unsupported_platform`.
+
+## Phase-One Decisions
+
+- Resource-backed VICE drive operations are supported in phase one: `list_drives`, `mount`, `unmount`, `reset`, `power_on`, `power_off`, and `set_mode`.
+- Grouped operations already declared c64u-only remain c64u-only on VICE and must be blocked at runtime.
+- Mock-only behavior must not appear in public compatibility tables before it is intentionally promoted to supported status.
+- For this phase, there are no public `mock-only experimental` operations in the grouped MCP contract. Any such behavior remains internal to tests or backend experiments until explicitly reclassified here.
+
+## Public VICE Contract
+
+### Supported
+
+| Tool | Operations |
+| --- | --- |
+| `c64_program` | `run_prg`, `upload_run_basic`, `upload_run_asm`, `batch_run` |
+| `c64_memory` | `read`, `read_screen`, `wait_for_text`, `write` |
+| `c64_system` | `reset`, `reboot`, `poweroff`, `start_task`, `stop_task`, `stop_all_tasks`, `list_tasks` |
+| `c64_graphics` | `render_petscii_art`, `render_bitmap`, `render_sprite`, `render_petscii_text` |
+| `c64_rag` | `basic`, `asm` |
+| `c64_disk` | `list_drives`, `mount`, `unmount` |
+| `c64_drive` | `reset`, `power_on`, `power_off`, `set_mode` |
+| `c64_config` | `list`, `get`, `set`, `batch_update`, `info`, `version`, `snapshot`, `restore`, `diff` |
+| `c64_sound` | `set_volume`, `reset`, `note_on`, `note_off`, `silence_all`, `generate`, `compile_play` |
+| `c64_debug` | all operations |
+| `c64_vice` | all operations |
+
+### Unsupported
+
+| Tool | Operations |
+| --- | --- |
+| `c64_program` | `load_prg`, `run_crt`, `bundle_run` |
+| `c64_disk` | `file_info`, `create_image`, `find_and_run` |
+| `c64_drive` | `load_rom` |
+| `c64_sound` | `play_sid_file`, `play_mod_file`, `pipeline`, `analyze`, `record_analyze` |
+| `c64_config` | `load_flash`, `save_flash`, `reset_defaults`, `read_debugreg`, `write_debugreg`, `shuffle` |
+| `c64_system` | `pause`, `resume`, `menu` |
+| `c64_stream` | all operations |
+| `c64_printer` | all operations |
+| `c64_extract` | all operations |
+
+## Notes
+
+- `supported` means supported on the public grouped MCP surface. It does not imply parity with Ultimate firmware internals.
+- VICE still has platform limits such as `no-rest-api`, `no-firmware-filesystem`, `no-flash-config`, and `limited-sid`.
+- When this matrix changes, update runtime enforcement, tests, README-generated compatibility tables, and generated `mcp/*.json` artifacts together.

package/mcp/prompts.json

@@ -0,0 +1,292 @@
+{
+  "prompts": [
+    {
+      "name": "hello-world",
+      "title": "Hello World Workflow",
+      "description": "Route ultra-fast hello-world and smoke-test requests to the canonical greeting skill.",
+      "_meta": {
+        "requiredResources": [
+          "c64://context/bootstrap",
+          "c64://context/fast-paths",
+          "c64://docs/index"
+        ],
+        "optionalResources": [],
+        "tools": [
+          "c64_program"
+        ],
+        "tags": [
+          "hello",
+          "demo",
+          "greeting",
+          "smoke-test"
+        ],
+        "argumentOptions": {}
+      }
+    },
+    {
+      "name": "basic-program",
+      "title": "BASIC Program Workflow",
+      "description": "Route bespoke Commodore BASIC v2 requests to the canonical BASIC skill.",
+      "_meta": {
+        "requiredResources": [
+          "c64://specs/basic",
+          "c64://context/bootstrap",
+          "c64://docs/index"
+        ],
+        "optionalResources": [
+          "c64://context/fast-paths"
+        ],
+        "tools": [
+          "c64_program",
+          "c64_memory"
+        ],
+        "tags": [
+          "basic",
+          "program"
+        ],
+        "argumentOptions": {}
+      }
+    },
+    {
+      "name": "cross-platform-demo",
+      "title": "Cross-Platform Demo Workflow",
+      "description": "Route quick visible demo requests to the cross-platform demo skill.",
+      "_meta": {
+        "requiredResources": [
+          "c64://context/bootstrap",
+          "c64://context/fast-paths",
+          "c64://docs/index"
+        ],
+        "optionalResources": [],
+        "tools": [
+          "c64_program"
+        ],
+        "tags": [
+          "demo",
+          "platform",
+          "greeting"
+        ],
+        "argumentOptions": {}
+      }
+    },
+    {
+      "name": "preset-music-demo",
+      "title": "Preset Music Demo Workflow",
+      "description": "Route quick recognizable tune requests to the SID music skill.",
+      "_meta": {
+        "requiredResources": [
+          "c64://specs/sid",
+          "c64://specs/sidwave",
+          "c64://context/fast-paths"
+        ],
+        "optionalResources": [
+          "c64://docs/sid/best-practices"
+        ],
+        "tools": [
+          "c64_sound"
+        ],
+        "tags": [
+          "sid",
+          "music",
+          "demo"
+        ],
+        "argumentOptions": {}
+      }
+    },
+    {
+      "name": "assembly-program",
+      "title": "Assembly Program Workflow",
+      "description": "Route 6502/6510 routine requests to the canonical assembly skill.",
+      "arguments": [
+        {
+          "name": "hardware",
+          "description": "Optional focus area for the routine (sid, vic, cia, or multi for combined work).",
+          "options": [
+            "sid",
+            "vic",
+            "cia",
+            "multi"
+          ]
+        }
+      ],
+      "_meta": {
+        "requiredResources": [
+          "c64://specs/assembly",
+          "c64://specs/vic",
+          "c64://specs/sid",
+          "c64://context/bootstrap"
+        ],
+        "optionalResources": [
+          "c64://docs/sid/best-practices"
+        ],
+        "tools": [
+          "c64_program",
+          "c64_memory"
+        ],
+        "tags": [
+          "assembly",
+          "program"
+        ],
+        "argumentOptions": {
+          "hardware": [
+            "sid",
+            "vic",
+            "cia",
+            "multi"
+          ]
+        }
+      }
+    },
+    {
+      "name": "sid-music",
+      "title": "SID Composition Workflow",
+      "description": "Route SID playback and composition work to the canonical SID skill.",
+      "_meta": {
+        "requiredResources": [
+          "c64://specs/sid",
+          "c64://specs/sidwave",
+          "c64://docs/sid/file-structure",
+          "c64://docs/sid/best-practices"
+        ],
+        "optionalResources": [
+          "c64://context/fast-paths"
+        ],
+        "tools": [
+          "c64_sound"
+        ],
+        "tags": [
+          "sid",
+          "music"
+        ],
+        "argumentOptions": {}
+      }
+    },
+    {
+      "name": "graphics-demo",
+      "title": "Graphics Demo Workflow",
+      "description": "Route graphics requests to the canonical graphics skill.",
+      "arguments": [
+        {
+          "name": "mode",
+          "description": "Target VIC-II technique (text, multicolour, bitmap, or sprite).",
+          "options": [
+            "text",
+            "multicolour",
+            "bitmap",
+            "sprite"
+          ]
+        }
+      ],
+      "_meta": {
+        "requiredResources": [
+          "c64://specs/vic",
+          "c64://context/bootstrap"
+        ],
+        "optionalResources": [
+          "c64://specs/assembly",
+          "c64://specs/charset",
+          "c64://docs/petscii-style"
+        ],
+        "tools": [
+          "c64_program",
+          "c64_memory",
+          "c64_graphics"
+        ],
+        "tags": [
+          "graphics",
+          "vic"
+        ],
+        "argumentOptions": {
+          "mode": [
+            "text",
+            "multicolour",
+            "bitmap",
+            "sprite"
+          ]
+        }
+      }
+    },
+    {
+      "name": "printer-job",
+      "title": "Printer Job Workflow",
+      "description": "Route printer work to the canonical printer skill.",
+      "arguments": [
+        {
+          "name": "printerType",
+          "description": "Select Commodore (device 4) or Epson FX workflow helpers.",
+          "options": [
+            "commodore",
+            "epson"
+          ]
+        }
+      ],
+      "_meta": {
+        "requiredResources": [
+          "c64://specs/printer",
+          "c64://docs/printer/guide",
+          "c64://docs/printer/prompts"
+        ],
+        "optionalResources": [
+          "c64://docs/printer/commodore-text",
+          "c64://docs/printer/commodore-bitmap",
+          "c64://docs/printer/epson-text",
+          "c64://docs/printer/epson-bitmap"
+        ],
+        "tools": [
+          "c64_printer"
+        ],
+        "tags": [
+          "printer"
+        ],
+        "argumentOptions": {
+          "printerType": [
+            "commodore",
+            "epson"
+          ]
+        }
+      }
+    },
+    {
+      "name": "memory-debug",
+      "title": "Memory Debug Workflow",
+      "description": "Route reversible memory inspection or patching work to the canonical memory skill.",
+      "_meta": {
+        "requiredResources": [
+          "c64://context/bootstrap",
+          "c64://specs/assembly",
+          "c64://docs/index"
+        ],
+        "optionalResources": [],
+        "tools": [
+          "c64_memory",
+          "c64_system"
+        ],
+        "tags": [
+          "memory",
+          "debug"
+        ],
+        "argumentOptions": {}
+      }
+    },
+    {
+      "name": "drive-manager",
+      "title": "Drive Manager Workflow",
+      "description": "Route disk-image and drive-state requests to the canonical drive skill.",
+      "_meta": {
+        "requiredResources": [
+          "c64://context/bootstrap"
+        ],
+        "optionalResources": [],
+        "tools": [
+          "c64_disk",
+          "c64_drive"
+        ],
+        "tags": [
+          "drive",
+          "storage"
+        ],
+        "argumentOptions": {}
+      }
+    }
+  ]
+}

package/mcp/protocol-examples.json

@@ -0,0 +1,46 @@
+{
+  "protocolVersion": "2025-06-18",
+  "examples": {
+    "initialize": {
+      "description": "Client initialization request sent immediately after connecting to the stdio MCP server.",
+      "request": {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+          "protocolVersion": "2025-06-18",
+          "capabilities": {
+            "resources": {},
+            "tools": {},
+            "prompts": {}
+          },
+          "clientInfo": {
+            "name": "c64bridge-static-interface-generator",
+            "version": "1.0.0"
+          }
+        }
+      }
+    },
+    "tools/list": {
+      "description": "Enumerates the full tool catalog and input schemas exposed by the server.",
+      "request": {
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/list",
+        "params": {}
+      }
+    },
+    "tools/call": {
+      "description": "Invokes the c64_program tool with deterministic example arguments.",
+      "request": {
+        "jsonrpc": "2.0",
+        "id": 3,
+        "method": "tools/call",
+        "params": {
+          "name": "c64_program",
+          "arguments": {}
+        }
+      }
+    }
+  }
+}