c64bridge 0.9.1 → 0.9.2

package/README.md

@@ -14,6 +14,7 @@ Your AI Command Bridge for the Commodore 64.
 [![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=io.github.chrisgleissner%2Fc64bridge&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D&quality=insiders)
 [![Install in Visual Studio](https://img.shields.io/badge/Install_in-Visual_Studio-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D)
 [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=io.github.chrisgleissner%2Fc64bridge&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImM2NGJyaWRnZSJdLCJlbnYiOnsiQzY0X01PREUiOiJjNjR1IiwiQzY0VV9IT1NUIjoiYzY0dSIsIlZJQ0VfQklOQVJZIjoiL3Vzci9sb2NhbC9iaW4veDY0c2MiLCJWSUNFX0RJUkVDVE9SWSI6Ii91c3IvbG9jYWwvc2hhcmUvdmljZSIsIlZJQ0VfVklTSUJMRSI6InRydWUiLCJWSUNFX1dBUlAiOiJmYWxzZSJ9fQ==)
+[![Use with Claude Code](https://img.shields.io/badge/Use_with-Claude_Code-D97757?style=flat-square&logo=anthropic&logoColor=white)](#claude-code)
 
 C64 Bridge is an MCP server for controlling and working with a Commodore 64 from an AI client.
 
@@ -52,6 +53,7 @@ C64 Bridge is listed in the [Official MCP Registry](https://registry.modelcontex
       - [SID Playback](#sid-playback)
       - [RAG](#rag)
       - [Testing](#testing)
+  - [Claude Code](#claude-code)
   - [Example Workflow](#example-workflow)
   - [HTTP Invocation](#http-invocation)
   - [Build and Test](#build-and-test)
@@ -59,12 +61,14 @@ C64 Bridge is listed in the [Official MCP Registry](https://registry.modelcontex
   - [Static MCP Interface](#static-mcp-interface)
   - [MCP API Reference](#mcp-api-reference)
     - [Tools](#tools)
+      - [c64\_batch](#c64_batch)
       - [c64\_config](#c64_config)
       - [c64\_debug](#c64_debug)
       - [c64\_disk](#c64_disk)
       - [c64\_drive](#c64_drive)
       - [c64\_extract](#c64_extract)
       - [c64\_graphics](#c64_graphics)
+      - [c64\_input](#c64_input)
       - [c64\_memory](#c64_memory)
       - [c64\_printer](#c64_printer)
       - [c64\_program](#c64_program)
@@ -191,9 +195,14 @@ The detailed lookup order, merge rules, backend examples, and override model are
 
 ### 4. Connect from an MCP Client
 
-If you use VS Code, follow the [VS Code MCP Setup](#vs-code-mcp-setup) section below.
+C64 Bridge ships a single canonical `stdio` entry point that every MCP client uses:
 
-If you use another MCP client, point it at the `stdio` server entry point and pass any required environment variables exactly as documented in this README and in [mcp.json](./mcp.json).
+- **VS Code (GitHub Copilot)** — see [VS Code MCP Setup](#vs-code-mcp-setup).
+- **Claude Code (CLI and VS Code plugin)** — see [Claude Code](#claude-code).
+- **Cursor, Visual Studio, VS Code Insiders** — use the install badges at the top of this README.
+- **Any other MCP client** — point it at the same `stdio` server, with the environment variables documented in [Runtime Environment Variable Reference](#runtime-environment-variable-reference) and the registry manifest in [mcp.json](./mcp.json).
+
+The startup command is the same across clients: `npx -y c64bridge@latest` for the published package, or `node scripts/start.mjs` from a local checkout. Backend selection (`c64u` vs `vice`) and credentials live in the shared [Configuration](#configuration) files and environment variables — clients only need to know the command.
 
 ## Configuration
 
@@ -265,6 +274,9 @@ Prompt illustration (issued via Copilot in VS Code, using GPT 5.4 Medium):
 
 ```text
 c64u: write a small BASIC program that clears the screen and prints HELLO C64U
+```
+
+```text
 vice: write a small BASIC program that clears the screen and prints HELLO VICE
 ```
 
@@ -277,6 +289,8 @@ The screenshots below were captured from actual backend bitmap responses after t
 
 ## VS Code MCP Setup
 
+This section covers the GitHub Copilot integration that ships with VS Code. For the Claude Code VS Code plugin, see [Claude Code](#claude-code) — it reads `.mcp.json`, not `.vscode/mcp.json`.
+
 If this repository is checked out locally, open the prepared [.vscode/mcp.json](./.vscode/mcp.json).
 
 Otherwise, put the following into your own `.vscode/mcp.json`:
@@ -483,6 +497,24 @@ Every runtime environment variable documented in `mcp.json` can be set in your M
 
 <!-- AUTO-GENERATED:ENV-VARS-END -->
 
+## Claude Code
+
+[Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) is supported as a first-class MCP client. It uses the same canonical start command and the same backend [Configuration](#configuration) files and environment variables as every other client — only the discovery file differs.
+
+**Claude Code CLI** — register the published server in one command:
+
+```bash
+claude mcp add c64bridge -- npx -y c64bridge@latest
+```
+
+Use `--scope user` to make it available across all your projects, or `--scope project` to write a `.mcp.json` next to the current repo. Backend selection (`c64u` vs `vice`), host, port, and password come from the same files documented in [Configuration](#configuration); per-shell overrides come from the variables in [Runtime Environment Variable Reference](#runtime-environment-variable-reference).
+
+**Project-scoped discovery** — this repository ships a checked-in [.mcp.json](./.mcp.json) that points Claude Code at the local source via `node scripts/start.mjs`. When you open the repo with `claude` (CLI or VS Code plugin), Claude Code prompts to enable the project-scoped server on first run. Approve it once and the `c64_*` tools become discoverable in that workspace.
+
+**Claude Code VS Code plugin** — the plugin reads the same `.mcp.json` and the same user-scope `claude mcp add` registrations as the CLI. No extra setup is required beyond installing the plugin and approving the project server prompt. The existing [.vscode/mcp.json](./.vscode/mcp.json) is read by GitHub Copilot, not by Claude Code; the two files coexist without conflict because they target different clients with different config schemas.
+
+**Verify it works** — after registration, run `claude mcp list` (CLI) or open the MCP panel (plugin) and look for `c64bridge`. Then ask Claude Code something like *“use vice: write a small BASIC program that clears the screen and prints HELLO CLAUDE”* — it should call `c64_select_backend` and `c64_program` directly. If tools do not appear, confirm Node 24+ is on `PATH`, that the server was approved at the requested scope, and that the backend is reachable per the [Configuration](#configuration) section.
+
 ## Example Workflow
 
 Compose a children’s song with ChatGPT and VS Code:

package/data/assembly/assembly-spec.md

@@ -506,4 +506,4 @@ Screen-code conversion
 
 - If input is ASCII uppercase 'A'..'Z', convert: screen = PETSCII - $40 (e.g. $41→$01). Implement in a small loop if needed.
 
-This file is intentionally minimal: use `basicConverter` / `assemblyConverter` in `src/` for tokenization/PRG building and `data/graphics/character-set.csv` for exact screen-code mappings.
+This file is intentionally minimal: use `src/tools/basicTokenizer.ts` / `src/tools/assembler.ts` for tokenization/PRG building and `data/graphics/character-set.csv` for exact screen-code mappings.

package/data/context/bootstrap.md

@@ -17,12 +17,12 @@ Do not assume the current backend is correct without checking
 
 ## Fast Paths
 
-- Grouped MCP tools are never called bare. For tools such as `c64_program`, `c64_memory`, `c64_graphics`, `c64_sound`, and `c64_system`, always send an object with `op` first.
-- Wrong: `c64_program {}`. Correct: `c64_program { op: "cross_platform_greeting" }`.
+- Grouped MCP tools are never called bare. For tools such as `c64_program`, `c64_memory`, `c64_graphics`, `c64_sound`, and `c64_system`, call the tool with flat arguments that include `op`.
+- Wrong: `c64_program {}` or `{ "c64_program": { "op": "cross_platform_greeting" } }`. Correct: call tool `c64_program` with `{ "op": "cross_platform_greeting" }`.
 - For simple visible confirmation on `vice`, `c64u`, or both, prefer `c64_program` with `op: "cross_platform_greeting"`.
 - For trivial hello-world and smoke-test requests, route to `.github/skills/hello-world/SKILL.md` and let that skill use the shortest greeting workflow.
 - That workflow switches backends internally, writes a platform-customized BASIC greeting, captures screenshots, and verifies the rendered text without extra tool composition.
-- Use manual `c64_select_backend` plus `upload_run_basic` only when the user needs custom program logic beyond a quick greeting or text demo.
+- Use manual `c64_select_backend` with `op: "select"` plus `c64_program` with `op: "upload_run_basic"` only when the user needs custom program logic beyond a quick greeting or text demo.
 - On local machines with a graphical session, assume VICE should be visible by default. Only expect Xvfb or other headless fallback in CI or when no framebuffer/display session exists.
 - For manual visible VICE BASIC runs, avoid immediate `read_screen` or `wait_for_text` calls, because Binary Monitor traffic traps execution while servicing requests.
 

package/data/context/fast-paths.md

@@ -27,6 +27,8 @@ Use these routing shortcuts when the user wants a quick visible or audible resul
 
 Example:
 
+Call tool `c64_sound` with:
+
 ```json
 {
   "op": "play_preset",
@@ -41,4 +43,4 @@ Example:
 ## Verification Order
 
 1. Trust the verification defined by the selected skill first.
-2. Use captured artifacts or follow-up inspection only when the selected skill indicates that extra verification is needed.
+2. Use captured artifacts or follow-up inspection only when the selected skill indicates that extra verification is needed.

package/data/graphics/petscii-style-guide.md

@@ -63,7 +63,7 @@ Conversion: Screen code ≠ PETSCII code. Use charset reference (c64://graphics/
 
 - BASIC/printing: Use PETSCII codes with CHR$() or PRINT
 - Direct screen memory: Use screen codes with POKE to $0400+offset
-- Tools: `c64_graphics` (`render_petscii_art`) returns both `petsciiCodes` array and screen memory data
+- Tools: `c64_graphics` with `op: "render_petscii_art"` returns both `petsciiCodes` array and screen memory data
 
 ## Essential PETSCII Symbols
 

package/data/graphics/sprite-charset-best-practices.md

@@ -246,13 +246,14 @@ Custom charsets have minimal performance impact:
 ### Using render_sprite
 
 ```javascript
-{
-  spriteData: "base64-encoded-63-bytes",
+await callTool("c64_graphics", {
+  op: "render_sprite",
+  sprite: "base64-encoded-63-bytes",
   x: 160,           // Center horizontally
   y: 100,           // Center vertically  
-  colour: 1,        // White
+  color: 1,         // White
   multicolour: false
-}
+})
 ```
 
 The tool:
@@ -270,26 +271,26 @@ When working with sprites and charsets:
 1. Use memory ranges documented in c64://memory/map
 2. Avoid BASIC program area ($0801-$9FFF) unless controlling it
 3. Preserve zero page ($0000-$00FF) and stack ($0100-$01FF)
-4. Use the `c64_memory` operations `read` and `write` for safe access
+4. Use `c64_memory` with `op: "read"` and `op: "write"` for safe access
 
 ## Example Workflows
 
 ### Simple Sprite Display
 
 1. Prepare 24×21 sprite bitmap
-2. Call `render_sprite` with sprite data
+2. Call `c64_graphics` with `op: "render_sprite"` and sprite data
 3. Tool writes sprite data and patches VIC-II state automatically
-4. Use `read_screen` to verify appearance
-5. Optionally call `c64_memory` `write` to adjust position/colour
+4. Use `c64_memory` with `op: "read_screen"` to verify appearance
+5. Optionally call `c64_memory` with `op: "write"` to adjust position/colour
 
 ### Custom Charset Installation
 
 1. Design character set (full or partial)
 2. Encode to 8-byte-per-char format
-3. Use `c64_memory` `write` to copy the charset to $2000
+3. Use `c64_memory` with `op: "write"` to copy the charset to $2000
 4. POKE $D018 to point VIC-II at new charset
-5. Use `upload_run_basic` to test character display
-6. Verify with `read_screen`
+5. Use `c64_program` with `op: "upload_run_basic"` to test character display
+6. Verify with `c64_memory` and `op: "read_screen"`
 
 ### Animated Sprite Sequence
 
@@ -297,13 +298,13 @@ When working with sprites and charsets:
 2. Upload all frames to consecutive memory locations
 3. Generate BASIC program that cycles sprite pointer
 4. Use raster timing for smooth animation
-5. Verify frame timing with `c64_memory` `read` checks
+5. Verify frame timing with `c64_memory` and `op: "read"` checks
 
 ## Best Practices Summary
 
 1. **Plan Memory Layout**: Map out sprite and charset locations before coding
 2. **Test Incrementally**: Display one sprite/char before adding more
-3. **Use Tools**: Leverage `render_sprite` and memory tools
+3. **Use Tools**: Leverage `c64_graphics` with `op: "render_sprite"` and `c64_memory` operations
 4. **Document State**: Note which sprites/chars are active
 5. **Handle Errors**: Check return values and screen output
 6. **Optimize Last**: Get it working, then optimize if needed

package/data/sound/sid-file-structure.md

@@ -5,12 +5,12 @@ This guide summarizes the High Voltage SID Collection (HVSC) "PSID file format"
 - A header containing metadata and playback parameters
 - The actual 6502 machine code and data that the player runs on the C64
 
-You can play a SID file on a connected device using the REST API via the MCP tool `sidplay_file`.
+You can play a SID file on a connected device with the MCP tool `c64_sound` and `op: "play_sid_file"`.
 
-## Quick start: play a SID via REST/MCP
+## Quick start: play a SID via MCP
 
-- Endpoint: `POST /tools/sidplay_file`
-- Body: `{ "path": "/flash/music/Example.sid", "songnr": 1 }` (optional `songnr`)
+- Tool: `c64_sound`
+- Arguments: `{ "op": "play_sid_file", "path": "/flash/music/Example.sid", "songnr": 1 }` (optional `songnr`)
 
 Refer to `doc/c64u/c64-rest-api.md` for the underlying device endpoint and options.
 
@@ -85,7 +85,7 @@ SID files do not embed duration. HVSC ships a `Songlengths.md5` database mapping
 
 ## Related API and tools
 
-- Play from device filesystem: `sidplay_file` (see generated `mcp-manifest.json` and `src/index.ts`)
+- Play from device filesystem: `c64_sound` with `op: "play_sid_file"` (see generated `mcp/tools.json` and `mcp/schemas/c64_sound.schema.json`)
 - Low-level SID register programming: see `data/sound/sid-spec.md`
 
 References for further reading: HVSC PSID v2NG file format (spec), community resources, and project notes from implementations like SIDman.

package/data/sound/sid-programming-best-practices.md

@@ -126,18 +126,18 @@ This solution was developed through:
 
 ```bash
 curl -X POST -H 'Content-Type: application/json' \
-  -d '{"program": "... BASIC program ..."}' \
-  http://localhost:8000/tools/upload_run_basic
+  -d '{"op": "upload_run_basic", "program": "... BASIC program ..."}' \
+  http://localhost:8000/tools/c64_program
 ```
 
 ### Future Audio Analysis
 
-The working scale can now be used with the `analyze_audio` tool:
+The working scale can now be used with `c64_sound` and `op: "analyze"`:
 
 ```bash
 curl -X POST -H 'Content-Type: application/json' \
-  -d '{"request": "verify the scale sounds correct"}' \
-  http://localhost:8000/tools/analyze_audio
+  -d '{"op": "analyze", "request": "verify the scale sounds correct"}' \
+  http://localhost:8000/tools/c64_sound
 ```
 
 ## Musical Expression Example: "Alle meine Entchen"

package/data/vice/vice-binary-monitor-spec.md

@@ -15,7 +15,7 @@ Recommended C64 Bridge entry points:
 | Debug registers and checkpoints | `c64_debug` | `get_registers`, `set_registers`, `create_checkpoint`, `list_checkpoints`, `step`, `step_return` |
 | Send keyboard or joystick input | `c64_input` | `write_text`, `key`, `joystick` |
 | Capture emulator display | `c64_graphics` | `capture_frame` |
-| Reset or resume execution | `c64_system` | `reset`, `resume` |
+| Reset or continue execution | `c64_system`, `c64_debug` | `reset`, `continue_execution` |
 | Read or write VICE resources | `c64_vice` | `resource_get`, `resource_set` |
 
 ---
@@ -633,7 +633,7 @@ C64 Bridge mapping:
 
 | MCP tool     | Operation |
 | ------------ | --------- |
-| `c64_system` | `resume`  |
+| `c64_debug` | `continue_execution` |
 
 ---
 
@@ -797,7 +797,7 @@ Usually emitted with `request_id = 0xffffffff`.
 | Palette Get          | `0x91` |                   `0x91` | internal display support                                                            |
 | Joyport Set          | `0xa2` |                   `0xa2` | `c64_input.joystick`                                                                |
 | Userport Set         | `0xb2` |                   `0xb2` | internal or unmapped                                                                |
-| Exit                 | `0xaa` |                   `0xaa` | `c64_system.resume`                                                                 |
+| Exit                 | `0xaa` |                   `0xaa` | `c64_debug.continue_execution`                                                       |
 | Quit                 | `0xbb` |                   `0xbb` | managed VICE lifecycle                                                              |
 | Reset                | `0xcc` |                   `0xcc` | `c64_system.reset`, `c64_system.reboot`, `c64_drive.reset`                          |
 | Autostart / Autoload | `0xdd` |                   `0xdd` | `c64_program.run_prg`, `c64_program.upload_run_basic`, `c64_program.upload_run_asm` |
@@ -827,17 +827,16 @@ Examples:
 | Read PC and A                   | `c64_debug` with `op = get_registers`     |
 | Step one instruction            | `c64_debug` with `op = step`              |
 | Step until return               | `c64_debug` with `op = step_return`       |
-| Continue execution              | `c64_system` with `op = resume`           |
+| Continue execution              | `c64_debug` with `op = continue_execution` |
 | Reset VICE                      | `c64_system` with `op = reset`            |
 | Change a VICE setting           | `c64_vice` with `op = resource_set`       |
 
 ## Backend Selection
 
-If both C64 Ultimate and VICE are configured, use `c64_select_backend` before making VICE-specific requests.
+If both C64 Ultimate and VICE are configured, call `c64_select_backend` with these arguments before making VICE-specific requests:
 
 ```json
 {
-  "tool": "c64_select_backend",
   "op": "select",
   "backend": "vice"
 }