c64bridge 0.5.0

package/doc/rest/c64-rest-api.md

@@ -0,0 +1,106 @@
+# C64 REST API Reference
+
+Authoritative source: [Ultimate 64 REST API](https://1541u-documentation.readthedocs.io/en/latest/api/api_calls.html) for devices such as Commodore 64 Ultimate and Ultimate 64.
+
+## Conventions
+
+- Base path: `/v1`.
+- URL format: `/v1/<route>/<path>:<command>?<arguments>`.
+- Responses are JSON unless noted and **always** include an `errors` array.
+- Attachments: `POST` variants accept binary payloads using `multipart/form-data` or `application/octet-stream`.
+- Firmware ≥ 3.12 can require `X-Password: <network-password>` on every request; missing/incorrect passwords yield `403`.
+
+## About
+
+| Method | Path | Parameters | Description |
+| --- | --- | --- | --- |
+| GET | `/v1/version` | – | Returns the REST API version, e.g. `{ "version": "0.1", "errors": [] }`. |
+| GET | `/v1/info` | – | Basic device information (product, firmware/core versions, hostname, optional unique ID). |
+
+## Runners
+
+| Method | Path | Parameters | Description |
+| --- | --- | --- | --- |
+| PUT | `/v1/runners:sidplay` | `file` (path), `songnr?` | Play a SID file from the device filesystem; optional song selection. |
+| POST | `/v1/runners:sidplay` | `songnr?` | Play an uploaded SID attachment, optional second attachment for song lengths. |
+| PUT | `/v1/runners:modplay` | `file` (path) | Play an Amiga MOD from the filesystem. |
+| POST | `/v1/runners:modplay` | – | Play an uploaded MOD attachment. |
+| PUT | `/v1/runners:load_prg` | `file` (path) | Reset, DMA-load PRG from disk into memory; does **not** run. |
+| POST | `/v1/runners:load_prg` | – | Reset, DMA-load uploaded PRG attachment; does **not** run. |
+| PUT | `/v1/runners:run_prg` | `file` (path) | Reset, DMA-load PRG from disk, then run. |
+| POST | `/v1/runners:run_prg` | – | Reset, DMA-load uploaded PRG attachment, then run. |
+| PUT | `/v1/runners:run_crt` | `file` (path) | Reset with cartridge image from filesystem active. |
+| POST | `/v1/runners:run_crt` | – | Reset with uploaded cartridge attachment active. |
+
+## Configuration
+
+| Method | Path | Parameters | Description |
+| --- | --- | --- | --- |
+| GET | `/v1/configs` | – | List configuration categories. Supports wildcards via query string. |
+| GET | `/v1/configs/{category}` | – | List items within a category (wildcards allowed). |
+| GET | `/v1/configs/{category}/{item}` | – | Inspect specific config entries (wildcards allowed). |
+| PUT | `/v1/configs/{category}/{item}` | `value` | Update a single config item; full path or wildcard selectors accepted. |
+| POST | `/v1/configs` | JSON body | Batch update config categories/items using returned JSON shape. |
+| PUT | `/v1/configs:load_from_flash` | – | Load saved configuration from non-volatile storage. |
+| PUT | `/v1/configs:save_to_flash` | – | Persist current configuration to non-volatile storage. |
+| PUT | `/v1/configs:reset_to_default` | – | Restore factory defaults (does not touch saved flash values). |
+
+## Machine Control
+
+| Method | Path | Parameters | Description |
+| --- | --- | --- | --- |
+| PUT | `/v1/machine:reset` | – | Soft reset; config unchanged. |
+| PUT | `/v1/machine:reboot` | – | Restart cartridge + soft reset. |
+| PUT | `/v1/machine:pause` | – | Assert DMA pause (halts CPU, timers continue). |
+| PUT | `/v1/machine:resume` | – | Release DMA pause. |
+| PUT | `/v1/machine:poweroff` | – | Power down (U64 only, response may be absent). |
+| PUT | `/v1/machine:menu_button` | – | Toggle Ultimate menu as if pressing the hardware button. |
+| PUT | `/v1/machine:writemem` | `address`, `data` (hex) | DMA-write ≤ 128 bytes supplied as hex string. |
+| POST | `/v1/machine:writemem` | `address` (hex), binary body | DMA-write attachment beginning at `address`; must not wrap `$FFFF`. |
+| GET | `/v1/machine:readmem` | `address` (hex), `length?` | DMA-read; firmware may return binary or base64/array payload. Default length 256 bytes. |
+| GET | `/v1/machine:debugreg` | – | Read `$D7FF` debug register (U64 only). |
+| PUT | `/v1/machine:debugreg` | `value` (hex) | Write then return the `$D7FF` debug register (U64 only). |
+
+## Floppy Drives
+
+| Method | Path | Parameters | Description |
+| --- | --- | --- | --- |
+| GET | `/v1/drives` | – | Enumerate internal drives, mounted images, and SoftIEC partitions. |
+| PUT | `/v1/drives/{drive}:mount` | `image` (path), `type?`, `mode?` | Mount existing image (`d64/g64/d71/g71/d81`) with mode `readwrite/readonly/unlinked`. |
+| POST | `/v1/drives/{drive}:mount` | `type?`, `mode?`, attachment | Mount uploaded image attachment. |
+| PUT | `/v1/drives/{drive}:reset` | – | Reset selected drive. |
+| PUT | `/v1/drives/{drive}:remove` | – | Eject mounted image; when mounted in unlinked mode it simply drops the link so further writes are discarded. |
+| PUT | `/v1/drives/{drive}:on` | – | Power on (or reset) the drive. |
+| PUT | `/v1/drives/{drive}:off` | – | Power off the drive (removes it from IEC bus). |
+| PUT | `/v1/drives/{drive}:load_rom` | `file` (path) | Temporarily load ROM image from filesystem (16 K/32 K). |
+| POST | `/v1/drives/{drive}:load_rom` | attachment | Temporarily load ROM from uploaded binary. |
+| PUT | `/v1/drives/{drive}:set_mode` | `mode` (`1541\|1571\|1581`) | Change drive mode; resets and reloads ROM. |
+
+## Data Streams (U64 only)
+
+| Method | Path | Parameters | Description |
+| --- | --- | --- | --- |
+| PUT | `/v1/streams/{stream}:start` | `ip` (`addr[:port]`) | Start video/audio/debug stream to destination (`video`→11000, `audio`→11001, `debug`→11002 if port omitted). Starting video stops debug. |
+| PUT | `/v1/streams/{stream}:stop` | – | Stop the specified stream (`video`, `audio`, or `debug`). |
+
+## File Manipulation
+
+| Method | Path | Parameters | Description |
+| --- | --- | --- | --- |
+| GET | `/v1/files/{path}:info` | – | Return file metadata (size, extension). Wildcards allowed. *(Alpha status)* |
+| PUT | `/v1/files/{path}:create_d64` | `tracks?` (35/40), `diskname?` | Create D64 image at specified filesystem path. |
+| PUT | `/v1/files/{path}:create_d71` | `diskname?` | Create 70-track D71 image. |
+| PUT | `/v1/files/{path}:create_d81` | `diskname?` | Create 160-track D81 image. |
+| PUT | `/v1/files/{path}:create_dnp` | `tracks` (≤255), `diskname?` | Create DNP image; each track has 256 sectors (≤ ~16 MB). |
+
+## Error Handling
+
+- `400`: malformed request (invalid parameters, body, or file attachment).
+- `403`: missing or incorrect `X-Password` when network password enforced.
+- `404`: route not present on current hardware/firmware.
+- `500`: device reported internal failure—inspect `errors` array for details.
+
+## Assets in Repository
+
+- `doc/rest/c64-openapi.yaml` captures the full API surface in OpenAPI 3.1 format for mock generation and tooling.
+- Firmware change log: <https://1541u-documentation.readthedocs.io/en/latest/api/changelog.html>

package/doc/troubleshooting-mcp.md

@@ -0,0 +1,177 @@
+# MCP Troubleshooting Guide
+
+Field notes for the stdio-based Model Context Protocol server. Use these checks when the C64 Bridge surface does not respond or CI fails the connectivity probe.
+
+## Quick Diagnosis Checklist
+
+```bash
+# 1. Is the MCP server running?
+ps -ef | grep "c64bridge" | grep -v grep
+
+# 2. Do startup logs show the connectivity probe?
+tail -n20 ~/.c64bridge.log  # or the terminal running npm start
+
+# 3. Can we reach the configured REST endpoint directly?
+curl -s http://<your-c64-host>/v1/info | jq .version
+
+# 4. When using the mock server
+npm test -- --mock
+```
+
+## Common Issues & Fixes
+
+### 1. Server Starts Without Connectivity Logs
+
+**Symptoms:**
+
+- `npm start` prints the banner but omits `Connectivity check succeeded`.
+- CI job `Validate MCP server logs` fails.
+
+**Resolution:**
+
+1. Confirm the REST base URL in `.c64bridge.json` or `C64BRIDGE_CONFIG` matches a reachable device.
+2. Run `curl -I http://<host>/v1/info` to confirm HTTP reachability.
+3. Review `src/mcp-server.ts` connectivity logging; ensure no local edits suppressed `logConnectivity`.
+4. If hardware is offline, expect `Skipping direct REST connectivity probe` in the logs—CI treats this as success.
+
+### 2. VS Code (Copilot Chat) Cannot See Tools
+
+**Symptoms:**
+
+- Copilot Chat shows "No MCP server" messages.
+- Tool invocations fail silently.
+
+**Resolution:**
+
+1. Restart VS Code after changing MCP settings.
+2. Verify the settings JSON matches the snippet in `doc/MCP_SETUP.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.
+
+### 3. Tests Fail Because Mock Server Is Missing
+
+**Symptoms:**
+
+- `npm test` exits with ENOENT for `test/mockC64Server.mjs` or cannot bind to port 18064.
+
+**Resolution:**
+
+1. Ensure dev dependencies are installed (`npm install`).
+2. Verify nothing else occupies the mock server port: `lsof -i :18064`.
+3. Run `npm test -- --verbose` to see which suite fails; the harness spins up the mock server automatically.
+
+### 4. C64 Hardware Connection Issues
+
+**Check C64 Configuration:**
+
+```bash
+# Verify config file exists and has correct IP
+cat .c64bridge.json
+```
+
+Expected structure:
+
+```json
+{
+  "c64u": {
+    "host": "c64u",
+    "port": 80
+  }
+}
+```
+
+Example with explicit host:
+
+```json
+{
+  "c64u": {
+    "host": "192.168.1.13",
+    "port": 80
+  }
+}
+```
+
+**Test C64 Connectivity:**
+
+Please note that the following IP address is just given as an example.
+
+```bash
+# Test Ultimate 64 REST API directly
+curl -s http://192.168.1.13/v1/info
+curl -s http://c64u/v1/info
+
+# If both fail, check network/Ultimate 64 power
+ping 192.168.1.13
+```
+
+### 5. Missing Dependencies
+
+**Symptoms:**
+
+- Server fails to start
+- TypeScript compilation errors
+- Missing modules
+
+**Solutions:**
+
+```bash
+# Reinstall dependencies
+npm install
+
+# Verify TypeScript can compile (optional check)
+npx tsc --noEmit src/index.ts
+```
+
+### 6. Transport
+
+Only stdio transport is supported for MCP. HTTP transport is not supported.
+
+## Working Test Sequence
+
+Use these checks to validate the full stack:
+
+1. `npm test` — run the mock suite end-to-end via stdio MCP.
+2. `npm test -- --real --base-url=$C64_BASE` — exercise real hardware (override `C64_BASE` to match your device).
+3. `curl -s "$C64_BASE"/v1/info | jq .version` — confirm the Ultimate 64 REST endpoint responds (hardware connectivity; unrelated to MCP transport).
+4. `npm run start-mock` — optional mock C64 server for local experiments.
+
+## VS Code MCP Setup Checklist
+
+- [ ] GitHub Copilot extension installed and active
+- [ ] MCP experimental feature enabled (Copilot Chat ≥ v1.214)
+- [ ] Settings JSON matches `doc/MCP_SETUP.md`
+- [ ] `npm start` (or packaged CLI) running in a terminal
+- [ ] Connectivity logs confirm the REST endpoint is reachable
+- [ ] Hardware (or mock server) is online and accessible
+
+## 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.
+
+## Emergency Recovery
+
+If nothing works:
+
+```bash
+# Nuclear option: kill everything and restart
+pkill -f npm
+pkill -f node
+pkill -f c64bridge
+
+# Wait a few seconds
+sleep 3
+
+# Clean restart
+cd /path/to/c64bridge
+npm start
+
+# If using HTTP mode, test immediately
+curl -s http://localhost:8000/tools/info
+```
+
+---
+
+*Keep this guide updated whenever new MCP workflows or diagnostics land in the project.*