# VICE Next MCP

`vice-next-mcp` is a Python 3.11+ control layer for VICE's version-2 binary
monitor. It provides supervised emulator instances, MCP-facing operation
schemas, a synchronous monitor client, and isolation primitives for concurrent
test and automation workloads.

See [MANUAL.md](MANUAL.md) for the published protocol and capability model.
The project is GPL-2.0-or-later; see [COPYING](COPYING).

## Highlights

- Supervised VICE launch with an exclusively reserved loopback monitor port,
  generation-aware instances, and process-tree teardown.
- Per-instance artifacts for logs, traces, screenshots, snapshots, and mutable
  media, including cross-process port leases and stale-lease reclamation.
- Binary-monitor support for memory, register discovery/read/write, reset,
  keyboard-buffer input, snapshots, screenshots, autostart, resume, pause, and
  instruction stepping.
- Correct autostart request framing (`run`, uint16 file index, byte filename
  length, filename) and isolated VICE process groups/sessions.
- Counted CPU-neutral stepping via command `0x71` with its required three-byte
  request body: step-over flag plus little-endian uint16 count.
- An explicit monitor-enter/pause command (`0xAB`) for instrumented VICE builds;
  resume is command `0xAA`.
- Native C64 RESTORE state through command `0x74` using a one-byte press/release
  payload, after the instrumented VICE rebuild is installed.

Physical keyboard-matrix injection is intentionally not advertised: the stock
binary monitor has no stable matrix-input protocol. `vice.keyboard.type` uses
VICE's documented keyboard-buffer command (`0x72`), not physical key events.

## Install and quick start

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e .[dev]
py -m pytest -q
```

Set `VICE_X64SC` to the desired `x64sc.exe`. `Supervisor` launches VICE with
`-default`, an automatically reserved version-2 binary-monitor endpoint, and a
headless SDL configuration by default. On Windows it creates a new process
group; on POSIX it starts a new session, so a detached caller does not terminate
the emulator unexpectedly.

For the lower-level validated launcher, `ProcessController.validate()` checks
that the executable matches the selected machine (for example, C64 requires
`x64sc`, C128 requires `x128`).

## Monitor client example

```python
from vice_next_mcp.supervisor import Supervisor

supervisor = Supervisor(executable=r"..\..\vice-instrumented\dist\HeadlessVICE-windows-x86_64\x64sc.exe")
try:
    instance = supervisor.create("x64sc")
    monitor = instance.monitor
    monitor.pause()
    monitor.step_instruction(10)
    registers = monitor.registers()
    monitor.resume()
finally:
    supervisor.close()
```

`Supervisor.create` also accepts `autostart=<PRG-or-D64-path>`; filename paths
are limited to 255 encoded bytes by the VICE protocol.

## MCP surface

The MCP server is constructed with `McpServer(resolver)`. After `initialize`,
call `tools/list` and `tools/call`. Each call must include an `operation_id`, a
target containing instance id, generation, and lease token, and a deadline.
Capabilities are reported per instance; operations lacking a verified monitor or
instrumented-backend implementation are rejected rather than silently emulated.

Example configuration:

```json
{
  "mcpServers": {
    "vice-next": {
      "command": "py",
      "args": ["-m", "vice_next_mcp.server"]
    }
  }
}
```

## Batch execution and artifacts

Run the included single-instance smoke example:

```powershell
py examples/single_smoke.py
```

Or execute a JSON case matrix:

```powershell
vice-next batch --cases examples/cases.json --workers 2 --base-port 6510
```

Use `VICE_MCP_BASE_PORT=0` (or omit `--base-port`) for ephemeral ports. Each
case receives a stable ID, an isolated artifact directory, and a serial
reproduction hint in `results.json`.

## Instrumented VICE features

Set `VICE_MCP_INSTRUMENTED=1` when launching a compatible rebuilt VICE binary.
This enables the explicitly advertised extension capabilities, including native
RESTORE injection and IEC capture. Each instance receives a unique
`VICE_IEC_TRACE_FILE` beneath its artifact directory. IEC capture responses
report completeness limits honestly: the current recorder has no source
overflow counter, so it reports `source_overflow_supported=false`.

The runtime executable is not committed to this repository. Build artifacts
must be validated against the intended VICE source revision before being used
for RESTORE or pause-dependent workflows.

## Development

```powershell
py -m pytest -q
py -m ruff check src tests
```

Live tests require a configured VICE executable and are marked `live`.
See [BUGS.md](BUGS.md) for outstanding binary-rebuild verification work.