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 for the published protocol and capability model. The project is GPL-2.0-or-later; see 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.

Related MCP server: Commodore 64 Ultimate Computer MCP Server

Install and quick start

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

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:

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

Batch execution and artifacts

Run the included single-instance smoke example:

py examples/single_smoke.py

Or execute a JSON case matrix:

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

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

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