VICE MCP

Servidor MCP integrado en el emulador VICE de Commodore 64/128/VIC-20/PET, que brinda a los asistentes de IA acceso directo para leer/escribir memoria, establecer puntos de interrupción, inspeccionar registros VIC-II/SID/CIA y depurar ensamblador 6502 en tiempo real con 63 herramientas.

GitHub

Prueba este MCPPatrocinado

Documentación

VICE MCP - La IA se encuentra con la Commodore 64

VICE MCP es un proyecto de Walker Heavy Industries.

Un servidor MCP integrado directamente dentro de VICE, que brinda a agentes de IA y herramientas modernas control programático completo sobre la computadora de 8 bits más icónica del mundo.

Carga una imagen de disco. Establece puntos de interrupción. Inspecciona sprites. Lee registros SID. Escribe en el teclado. Toma capturas de pantalla. Avanza paso a paso por código 6502. Todo a través de una API JSON-RPC limpia que cualquier cliente MCP puede usar.

Este es VICE — el legendario emulador de Commodore — con un servidor Model Context Protocol integrado en su núcleo. No añadido externamente. No es un envoltorio. ~17,000 líneas de C entretejidas en el propio emulador.

¿Qué Puedes Hacer Con Esto?

Para Agentes de IA

Apunta cualquier cliente compatible con MCP — Claude Desktop, Cursor, tu propio agente — a http://127.0.0.1:6510/mcp y tendrás una Commodore 64 totalmente controlable. Tu agente puede:

Cargar y ejecutar software — autoiniciar PRGs e imágenes de disco
Depurar código 6502 — puntos de interrupción, puntos de vigilancia, interrupciones condicionales, ejecución paso a paso
Inspeccionar todo — registros de CPU, bancos de memoria, gráficos VIC-II, audio SID, temporizadores CIA
Ver lo que hay en pantalla — tomar capturas de pantalla, leer mapas de bits de sprites como arte ASCII
Interactuar como un humano — escribir texto, presionar teclas, mover joysticks
Medir rendimiento — cronómetro de precisión de ciclos, trazado de ejecución, registro de interrupciones
Guardar y restaurar estado — gestión completa de instantáneas con metadatos

Para Desarrolladores de C64

Si escribes código para la Commodore 64, esto te brinda un flujo de trabajo de depuración moderno sin salir de tu editor:

Establece puntos de interrupción desde tu IDE mientras tu programa se ejecuta
Carga archivos de símbolos de KickAssembler o VICE y depura por nombre de etiqueta
Busca en memoria patrones de bytes con soporte de comodines
Compara regiones de memoria contra instantáneas guardadas para encontrar qué cambió
Traza la ejecución con filtrado de rango de PC para enfocarte en tu código
Registra interrupciones para entender el tiempo de IRQ/NMI
Agrupa puntos de interrupción y actívalos o desactívalos como un conjunto

Para Investigadores y Educadores

Automatiza análisis de ROM e ingeniería inversa
Construye tutoriales interactivos que controlen una C64 en vivo
Captura estados de pantalla para documentación
Reproduce y analiza software histórico

61 Herramientas en 13 Categorías

Cada herramienta sigue las convenciones de MCP con validación completa de JSON Schema, errores significativos y nombres de parámetros consistentes.

Categoría	Herramientas	Qué Hacen
Ejecución	`vice.execution.run` `vice.execution.pause` `vice.execution.step` `vice.frame.advance` `vice.run_until`	Controlan la CPU — reanudar, pausar, paso a paso, avanzar fotogramas completos, ejecutar hasta dirección o conteo de ciclos
Registros	`vice.registers.get` `vice.registers.set`	Leer/escribir todos los registros 6502 (A, X, Y, SP, PC, banderas de estado)
Memoria	`vice.memory.read` `vice.memory.write` `vice.memory.banks` `vice.memory.search` `vice.memory.fill` `vice.memory.compare`	Acceso completo a memoria con selección de banco, búsqueda de patrones con comodines
Puntos de control	`vice.checkpoint.add` `vice.checkpoint.delete` `vice.checkpoint.list` `vice.checkpoint.toggle` `vice.checkpoint.set_condition` `vice.checkpoint.set_ignore_count` `vice.checkpoint.group.*`	Puntos de interrupción, puntos de vigilancia, puntos de trazado — con condiciones y grupos
Sprites	`vice.sprite.get` `vice.sprite.set` `vice.sprite.inspect`	Leer/escribir estado de sprites, visualización de mapas de bits como arte ASCII
VIC-II	`vice.vicii.get_state` `vice.vicii.set_state`	Acceso completo al chip de video de la C64 — raster, colores, scroll, banco
SID	`vice.sid.get_state` `vice.sid.set_state`	El legendario chip de sonido — voces, filtros, ADSR, formas de onda
CIA	`vice.cia.get_state` `vice.cia.set_state`	Estado del chip de temporizador y E/S — tanto CIA1 como CIA2
Disco	`vice.disk.attach` `vice.disk.detach` `vice.disk.list` `vice.disk.read_sector`	Montar imágenes D64/D71/D81, explorar directorios, leer sectores crudos
Máquina	`vice.machine.reset` `vice.machine.config.get` `vice.machine.config.set` `vice.autostart`	Reinicio duro/suave, control de recursos (warp, velocidad, modelo), carga de programas
Pantalla	`vice.display.screenshot` `vice.display.get_dimensions`	Captura de pantalla a archivo o base64, geometría de pantalla
Entrada	`vice.keyboard.type` `vice.keyboard.petscii` `vice.keyboard.key_press` `vice.keyboard.key_release` `vice.keyboard.restore` `vice.keyboard.matrix` `vice.keyboard.chord` `vice.joystick.set` `vice.joystick.tap`	Teclado y joystick — escritura de texto, teclas individuales, matriz directa, RESTORE/NMI
Depuración	`vice.disassemble` `vice.symbols.load` `vice.symbols.lookup` `vice.watch.add` `vice.backtrace` `vice.cycles.stopwatch`	Desensamblado, archivos de símbolos, pila de llamadas, temporización de precisión de ciclos
Instantáneas	`vice.snapshot.save` `vice.snapshot.load` `vice.snapshot.list`	Guardar/restaurar estado completo del emulador con metadatos JSON

Arquitectura

Esto no es un proceso auxiliar ni un capturador de pantalla. El servidor MCP está compilado directamente dentro de VICE como un subsistema de primera clase — en cada máquina que VICE emula.

Máquinas Soportadas

Máquina	CPU	Hardware Notable
C64 / C64 SC	6510	VIC-II, SID, 2×CIA, Sprites
C128	8502/Z80	VIC-II, VDC 80-col, SID, 2×CIA
SCPU64	65816	Acelerador SuperCPU
C64 DTV	6510 (extendido)	Registros específicos de DTV
VIC-20	6502	Video VIC-I, memoria de expansión
Plus/4 y C16	7501/8501	Chip de video+audio TED
PET	6502	Video CRTC, E/S PIA/VIA
CBM-II	6509	CRTC, MOS 6526 CIA

El servidor MCP se adapta automáticamente a la máquina en ejecución. Cuando un agente de IA llama a vice.machine.config.get, recibe la configuración de hardware real — qué chips están presentes, qué bancos de memoria existen, rangos de direcciones válidos y recursos disponibles. Un agente depurando un cartucho de VIC-20 obtiene registros VIC-I; el mismo agente depurando un programa de C128 obtiene VIC-II y la pantalla VDC de 80 columnas.

┌─────────────────────────────────────────────────┐
│                   VICE Emulator                  │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │   CPU    │  │  Video   │  │    Audio     │  │
│  │ (varies) │  │ (varies) │  │   (varies)   │  │
│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │
│       │              │               │           │
│       └──────────┬───┴───────────────┘           │
│                  │                                │
│         ┌────────┴────────┐                      │
│         │  MCP Server     │                      │
│         │  (libmcp.a)     │                      │
│         │                 │                      │
│         │  JSON-RPC 2.0   │<---- POST /mcp -----│
│         │  libmicrohttpd  │---- GET /events 501>│
│         │  Trap Dispatch  │                      │
│         └─────────────────┘                      │
│                                                  │
└─────────────────────────────────────────────────┘
        127.0.0.1:6510 by default

Decisiones clave de diseño:

Despacho basado en trampas — Las solicitudes HTTP se despachan a través del mecanismo de trampas de VICE, asegurando que toda la lógica de herramientas se ejecute en el hilo principal del emulador. Sin condiciones de carrera, sin sorpresas de bloqueo.
Acceso de copia cero — Las herramientas leen directamente de los internos del emulador. Cuando pides estado de VIC-II, obtienes los valores de registro reales, no una aproximación en caché.
Respuestas conscientes de la máquina — Las herramientas informan capacidades de hardware, disponibilidad de chips y rangos de memoria válidos para cualquier máquina en ejecución. El agente siempre sabe con qué está trabajando.
Integración con monitor — Funciona junto al monitor integrado de VICE. Si el emulador está pausado en el monitor, las solicitudes MCP se ejecutan directamente sin trampas.
Endpoint de eventos reservado — GET /events existe pero actualmente devuelve 501 Not Implemented. Consulta el estado a través de /mcp hasta que llegue la transmisión de eventos.

Inicio Rápido

Conectar a VICE

Inicia cualquier máquina VICE con el servidor MCP habilitado:

# C64 (cycle-exact)
x64sc -mcpserver

# C128
x128 -mcpserver

# VIC-20
xvic -mcpserver

# Listen on all network interfaces, port 7000
x64sc -mcpserver -mcpserverhost 0.0.0.0 -mcpserverport 7000

El servidor MCP se inicia en 127.0.0.1:6510 por defecto. Los clientes MCP se conectan a:

http://127.0.0.1:6510/mcp

0.0.0.0 es una dirección de enlace, no una dirección de cliente. Significa "escuchar en cada interfaz". Un cliente en el mismo Mac aún se conecta a 127.0.0.1; un cliente en otra máquina se conecta a la dirección IP LAN del Mac, por ejemplo http://192.168.1.42:6510/mcp.

Recetas de Conexión

Caso de uso	Iniciar VICE con	URL del cliente	Cabecera de autenticación
Mismo Mac, predeterminado	`x64sc -mcpserver`	`http://127.0.0.1:6510/mcp`	Ninguna
Mismo Mac, puerto personalizado	`x64sc -mcpserver -mcpserverport 7000`	`http://127.0.0.1:7000/mcp`	Ninguna
Acceso LAN, red confiable	`x64sc -mcpserver -mcpserverhost 0.0.0.0`	`http://<mac-lan-ip>:6510/mcp`	Ninguna
Acceso LAN con token portador	`x64sc -mcpserver -mcpserverhost 0.0.0.0 -mcpservertoken secret`	`http://<mac-lan-ip>:6510/mcp`	`Authorization: Bearer secret`
Aplicación de navegador con CORS	`x64sc -mcpserver -mcpservercorsorigin http://localhost:3000 -mcpservertoken secret`	`http://127.0.0.1:6510/mcp`	`Authorization: Bearer secret`

Las reglas de token son intencionalmente simples:

Sin token configurado: los clientes MCP que no son de navegador pueden conectarse sin una cabecera Authorization.
Token configurado: cada solicitud MCP debe incluir Authorization: Bearer <token>.
CORS configurado: se requiere un token. El CORS comodín (*) se rechaza.
Vincular a 0.0.0.0 sin token está permitido por compatibilidad hacia atrás, pero VICE registra una advertencia porque clientes remotos pueden controlar el emulador.

Hablar con Él

Todas las solicitudes HTTP van a /mcp, deben usar Content-Type: application/json, y deben enviar Accept: application/json.

# Direct JSON-RPC call
curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "vice.ping"
}'

# Standard MCP tools/call form, used by Claude Code and other MCP clients
curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "vice_ping", "arguments": {} }
}'

# Read the BASIC ROM entry point
curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "vice_memory_read",
    "arguments": { "address": "0xA000", "size": 16, "encoding": "hex" }
  }
}'

Cuando se configura un token, agrega la cabecera portadora a cada solicitud:

curl -sS http://127.0.0.1:6510/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer secret' \
  --data '{"jsonrpc":"2.0","id":1,"method":"vice.ping"}'

Usar con Claude Desktop

Agrega esto a tu configuración MCP de Claude Desktop:

{
  "mcpServers": {
    "vice": {
      "url": "http://127.0.0.1:6510/mcp"
    }
  }
}

Luego simplemente habla con él: "Carga el juego en la unidad 8 y muéstrame lo que hay en pantalla."

Si VICE se inició con -mcpservertoken, el cliente debe enviar Authorization: Bearer <token> en cada solicitud. Si tu cliente MCP no puede configurar cabeceras HTTP, no uses un token para sesiones 127.0.0.1 solo locales.

Compilar desde el Código Fuente

Requisitos Previos

Plataforma	Instalación
Debian/Ubuntu	`apt install build-essential autoconf automake pkg-config libmicrohttpd-dev libgtk-3-dev libglew-dev libevdev-dev libcurl4-openssl-dev libpulse-dev xa65 flex byacc dos2unix`
macOS	`brew install autoconf automake pkg-config libmicrohttpd gtk+3 xa lame`
Windows (MSYS2)	`pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-libmicrohttpd mingw-w64-x86_64-gtk3 autoconf automake pkg-config`

Compilar

cd vice
./autogen.sh
mkdir build && cd build
../configure --enable-mcp-server --enable-gtk3ui
make -j$(nproc)

Verificar

# MCP flags should appear in help output
src/x64sc -help | grep mcp

# Expected:
# -mcpserver          Enable MCP server
# -mcpserverport <port>  Set MCP server port (default: 6510)
# -mcpserverhost <host>  Set MCP server host (default: 127.0.0.1)

Binarios Precompilados

Los binarios precompilados están disponibles en la página de Lanzamientos.

Plataforma	GUI	Sin interfaz gráfica	Notas
Linux x86_64	Sí	Sí	Interfaz GTK3
macOS arm64	Sí	Sí	Interfaz GTK3 (Apple Silicon)
Windows x86_64	No	Sí	Solo sin interfaz gráfica — compilación cruzada vía MinGW-w64

Windows no incluye una compilación con GUI. La compilación cruzada de GTK3 para Windows no está soportada por el sistema de compilación de VICE. Si necesitas una GUI de Windows, compila desde el código fuente de forma nativa usando MSYS2.

Cliente Python

Se incluye un cliente Python resistente con lógica de reintento, agrupación de conexiones y un método de conveniencia para cada herramienta:

from tools.resilience.vice_mcp_resilient import ViceMCPClient

with ViceMCPClient("http://127.0.0.1:6510") as vice:
    # Load a program
    vice.autostart("/path/to/game.prg")

    # Set a breakpoint at the main loop
    vice.checkpoint_add(start_address=0x0810, stop_address=0x0810)

    # Run until it hits
    vice.execution_run()

    # Read the screen
    regs = vice.registers_get()
    screenshot = vice.display_screenshot(format="base64")

    # Inspect a sprite
    art = vice.sprite_inspect(sprite_number=0)
    print(art)

Suite de Pruebas de Protocolo

167 pruebas en 25 clases de prueba validan cada herramienta, cada parámetro y cada condición de error:

# Requires a running VICE instance with MCP enabled
pytest tools/tests/test_mcp_protocol.py -v

Uso en el Mundo Real

sim6502 — Pruebas Unitarias para Ensamblador 6502

sim6502 es un marco de pruebas unitarias para ensamblador 6502/6510/65C02 que usa VICE MCP como backend de ejecución. Escribe pruebas en un DSL personalizado, ejecútalas contra una instancia VICE en vivo con hardware de precisión de ciclos:

suite "sprite collision" {
    load "game.prg"

    test "player hits enemy" {
        jsr setup_sprites
        poke $d015, #$03          ; enable sprites 0 and 1
        poke $d000, #$80          ; sprite 0 x = 128
        poke $d002, #$80          ; sprite 1 x = 128
        jsr main_loop
        assert $d01e & #$03 != 0  ; collision register set
    }
}

sim6502 se conecta a través de MCP para cargar programas, establecer puntos de interrupción, leer registros, comparar memoria y guardar/restaurar estado entre pruebas — llevando prácticas modernas de CI/CD al desarrollo de computación retro.

Flujos de Trabajo de Agentes de IA

Cualquier cliente compatible con MCP puede controlar VICE directamente:

Claude Desktop / Cursor — "Carga esta imagen de disco, encuentra el bucle principal y explica qué hace el manejador de IRQ"
Agentes personalizados — Análisis automatizado de ROM, pruebas de regresión, captura de capturas de pantalla
Herramientas de investigación — Exploración sistemática del comportamiento de software histórico

Seguridad

El servidor MCP es solo localhost por defecto (127.0.0.1). Con la configuración predeterminada, solo los programas en la misma máquina pueden conectarse.

No tiene TLS. Tiene autenticación opcional de token portador. Está diseñado para desarrollo local primero, y la exposición a la red debe ser deliberada.

Si necesitas acceso remoto, colócalo detrás de un proxy inverso con autenticación adecuada:

nginx/caddy -> auth -> https -> 127.0.0.1:6510

Vincular a 0.0.0.0 está soportado vía -mcpserverhost. Eso hace que VICE escuche en cada interfaz de red. No significa que los clientes se conecten a 0.0.0.0; los clientes remotos se conectan a la dirección IP real del host Mac/Linux/Windows.

Usa esta lista de verificación para sesiones remotas:

Inicia VICE con -mcpserverhost 0.0.0.0.
Prefiere agregar -mcpservertoken <token> a menos que la red ya sea confiable.
Configura la URL del cliente como http://<host-ip>:6510/mcp.
Si se configura un token, configura el cliente para enviar Authorization: Bearer <token>.
Para clientes basados en navegador, también configura exactamente un -mcpservercorsorigin <origin> y un token. CORS sin token se rechaza.

Relación con VICE Ascendente

Este es un fork del espejo SVN de VICE. El servidor MCP está implementado como un subsistema autocontenido en src/mcp/ — toca los internos de VICE a través de interfaces bien definidas pero no modifica la lógica central de emulación.

La rama main rastrea el VICE ascendente. La rama mcp-server contiene todas las adiciones de MCP. El objetivo es contribuir con este trabajo de vuelta al proyecto VICE. La implementación está estructurada para exportarse limpiamente como diffs unificados para el envío a SVN.

Referencia de Herramientas

Haz clic para expandir la referencia completa de las 61 herramientas

Control de Ejecución

`vice.ping`

Comprueba si VICE está respondiendo. Sin parámetros.

`vice.execution.run`

Reanudar la ejecución. Sin parámetros.

`vice.execution.pause`

Pausar la ejecución. Sin parámetros.

`vice.execution.step`

Ejecutar una o más instrucciones. En una máquina detenida, la llamada regresa después del paso, con completed: true y el PC. Si un checkpoint detiene la máquina primero, la respuesta lleva stopped_early: true y el PC en ese punto; si el paso no ha terminado después de 2 segundos (un paso sobre una subrutina lenta), la máquina se pausa en el siguiente límite de instrucción y la respuesta lleva timed_out: true. En cualquier caso, el resto del paso se descarta. En una máquina en ejecución, la llamada arma el paso y regresa de inmediato.

Parámetro	Tipo	Requerido	Descripción
`count`	number		Instrucciones a ejecutar (predeterminado: 1, máximo: 10000)
`stepOver`	boolean		Ejecutar paso a paso sobre subrutinas

`vice.frame.advance`

Ejecutar fotogramas completos desde una máquina detenida y detenerse de nuevo, en el primer límite de instrucción después de la sincronización vertical que termina el último fotograma, con los registros exportados. El estado del joystick y del teclado establecido mientras está detenido se mantiene mientras se ejecutan los fotogramas, lo que permite un bucle de entrada fotograma a fotograma: establecer entrada, avanzar un fotograma, leer memoria, repetir. La máquina ya debe estar detenida (por vice.execution.pause, un checkpoint de detención o vice.execution.step); de lo contrario, la llamada devuelve el error -32001. Si un checkpoint detiene la máquina antes del límite, la respuesta lleva stopped_early: true y el número de fotogramas completos que se ejecutaron. Un fotograma que no ha terminado después de 2 segundos se abandona: la máquina se pausa en el siguiente límite de instrucción y la respuesta también lleva timed_out: true.

Parámetro	Tipo	Requerido	Descripción
`frames`	number		Fotogramas completos a ejecutar antes de detenerse de nuevo (predeterminado: 1, máximo: 1000)

`vice.run_until`

Ejecutar hasta una dirección o durante N ciclos con tiempo de espera.

Parámetro	Tipo	Requerido	Descripción
`address`	string		Dirección objetivo (hexadecimal, decimal o nombre de símbolo)
`cycles`	number		Ciclos máximos a ejecutar

Registros

`vice.registers.get`

Obtener todos los registros de la CPU (A, X, Y, SP, PC, banderas de estado). Sin parámetros.

`vice.registers.set`

Establecer un valor de registro de la CPU.

Parámetro	Tipo	Requerido	Descripción
`register`	string	sí	Nombre del registro: `PC` `A` `X` `Y` `SP` `N` `V` `B` `D` `I` `Z` `C`
`value`	number	sí	Valor a establecer

Memoria

`vice.memory.read`

Leer un rango de memoria con selección opcional de banco.

Parámetro	Tipo	Requerido	Descripción
`address`	string	sí	Dirección: número, hexadecimal (`$1000`) o nombre de símbolo
`size`	number	sí	Bytes a leer (1-65535)
`bank`	string		Nombre del banco de memoria (usa `vice.memory.banks` para listar)

`vice.memory.write`

Escribir bytes en la memoria.

Parámetro	Tipo	Requerido	Descripción
`address`	string	sí	Dirección: número, hexadecimal (`$1000`) o nombre de símbolo
`data`	number[]	sí	Bytes a escribir (0-255 cada uno)

`vice.memory.banks`

Listar los bancos de memoria disponibles para la máquina actual. Sin parámetros.

`vice.memory.search`

Buscar patrones de bytes con máscara de comodín opcional.

Parámetro	Tipo	Requerido	Descripción
`start`	string	sí	Dirección de inicio
`end`	string	sí	Dirección de fin
`pattern`	number[]	sí	Patrón de bytes, p. ej. `[0x4C, 0x00, 0xA0]`
`mask`	number[]		Máscara por byte: `0xFF`=exacto, `0x00`=comodín
`max_results`	number		Máximo de coincidencias (predeterminado: 100, máximo: 10000)

`vice.memory.fill`

Rellenar un rango de memoria con un patrón de bytes repetido.

Parámetro	Tipo	Requerido	Descripción
`start`	string	sí	Dirección de inicio
`end`	string	sí	Dirección de fin (inclusive)
`pattern`	number[]	sí	Patrón de bytes a repetir

`vice.memory.compare`

Comparar dos rangos de memoria o comparar contra una instantánea.

Parámetro	Tipo	Requerido	Descripción
`mode`	string	sí	`ranges` o `snapshot`
`range1_start`	string	rangos	Inicio del primer rango
`range1_end`	string	rangos	Fin del primer rango
`range2_start`	string	rangos	Inicio del segundo rango
`snapshot_name`	string	instantánea	Instantánea contra la que comparar
`start`	string	instantánea	Dirección de inicio para comparar
`end`	string	instantánea	Dirección de fin para comparar
`max_differences`	number		Máximo de diferencias a devolver (predeterminado: 100)

Checkpoints y Puntos de Interrupción

`vice.checkpoint.add`

Añadir un checkpoint (punto de interrupción, punto de vigilancia o punto de rastreo).

Parámetro	Tipo	Requerido	Descripción
`start`	string	sí	Dirección de inicio
`end`	string		Dirección de fin (predeterminado = inicio)
`stop`	boolean		Detener al alcanzar (predeterminado: true)
`load`	boolean		Interrumpir en lectura de memoria (predeterminado: false)
`store`	boolean		Interrumpir en escritura de memoria (predeterminado: false)
`exec`	boolean		Interrumpir en ejecución (predeterminado: true)

`vice.checkpoint.delete`

Eliminar un checkpoint.

Parámetro	Tipo	Requerido	Descripción
`checkpoint_num`	number	sí	Número de checkpoint

`vice.checkpoint.list`

Listar todos los checkpoints. Sin parámetros.

`vice.checkpoint.toggle`

Habilitar o deshabilitar un checkpoint.

Parámetro	Tipo	Requerido	Descripción
`checkpoint_num`	number	sí	Número de checkpoint
`enabled`	boolean	sí	Habilitar o deshabilitar

`vice.checkpoint.set_condition`

Establecer una expresión de condición en un checkpoint.

Parámetro	Tipo	Requerido	Descripción
`checkpoint_num`	number	sí	Número de checkpoint
`condition`	string	sí	Expresión, p. ej. `A == $42`

`vice.checkpoint.set_ignore_count`

Establecer cuántos aciertos ignorar antes de detenerse.

Parámetro	Tipo	Requerido	Descripción
`checkpoint_num`	number	sí	Número de checkpoint
`count`	number	sí	Aciertos a ignorar

`vice.checkpoint.group.create`

Crear un grupo de checkpoints con nombre.

Parámetro	Tipo	Requerido	Descripción
`name`	string	sí	Nombre del grupo
`checkpoint_ids`	number[]		IDs iniciales de checkpoint

`vice.checkpoint.group.add`

Añadir checkpoints a un grupo existente.

Parámetro	Tipo	Requerido	Descripción
`group`	string	sí	Nombre del grupo
`checkpoint_ids`	number[]	sí	IDs de checkpoint a añadir

`vice.checkpoint.group.toggle`

Habilitar o deshabilitar todos los checkpoints en un grupo.

Parámetro	Tipo	Requerido	Descripción
`group`	string	sí	Nombre del grupo
`enabled`	boolean	sí	Habilitar o deshabilitar todos

`vice.checkpoint.group.list`

Listar todos los grupos de checkpoints. Sin parámetros.

Sprites (C64/C128/DTV)

`vice.sprite.get`

Obtener el estado del sprite.

Parámetro	Tipo	Requerido	Descripción
`sprite`	number		Número de sprite 0-7 (omitir para todos)

`vice.sprite.set`

Establecer propiedades del sprite.

Parámetro	Tipo	Requerido	Descripción
`sprite`	number	sí	Número de sprite 0-7
`x`	number		Posición X 0-511
`y`	number		Posición Y 0-255
`enabled`	boolean		Habilitar sprite
`multicolor`	boolean		Modo multicolor
`expand_x`	boolean		Doble ancho
`expand_y`	boolean		Doble alto
`priority_foreground`	boolean		Dibujar sobre el fondo
`color`	number		Color del sprite 0-15

`vice.sprite.inspect`

Representación visual en arte ASCII del bitmap de un sprite.

Parámetro	Tipo	Requerido	Descripción
`sprite_number`	number	sí	Número de sprite 0-7
`format`	string		`ascii` (predeterminado), `binary` o `png_base64`

Estado del Chip

`vice.vicii.get_state`

Obtener el estado interno del VIC-II. Sin parámetros.

`vice.vicii.set_state`

Establecer registros del VIC-II.

Parámetro	Tipo	Requerido	Descripción
`registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x2E)

`vice.sid.get_state`

Obtener el estado del SID (voces, filtro, ADSR). Sin parámetros.

`vice.sid.set_state`

Establecer registros del SID.

Parámetro	Tipo	Requerido	Descripción
`registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x1C)

`vice.cia.get_state`

Obtener el estado del CIA (temporizadores, puertos).

Parámetro	Tipo	Requerido	Descripción
`cia`	number		Número de CIA: 1 o 2 (omitir para ambos)

`vice.cia.set_state`

Establecer registros del CIA.

Parámetro	Tipo	Requerido	Descripción
`cia1_registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x0F)
`cia2_registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x0F)

Gestión de Discos

`vice.disk.attach`

Adjuntar una imagen de disco a una unidad.

Parámetro	Tipo	Requerido	Descripción
`unit`	number	sí	Unidad (8-11)
`path`	string	sí	Ruta a la imagen de disco (.d64, .g64, etc.)

`vice.disk.detach`

Desadjuntar una imagen de disco.

Parámetro	Tipo	Requerido	Descripción
`unit`	number	sí	Unidad (8-11)

`vice.disk.list`

Listar el contenido del directorio de un disco adjunto.

Parámetro	Tipo	Requerido	Descripción
`unit`	number	sí	Unidad (8-11)

`vice.disk.read_sector`

Leer datos de sector en bruto.

Parámetro	Tipo	Requerido	Descripción
`unit`	number	sí	Unidad (8-11)
`track`	number	sí	Número de pista (1-42 para D64)
`sector`	number	sí	Número de sector

Control de la Máquina

`vice.autostart`

Iniciar automáticamente una imagen PRG o de disco.

Parámetro	Tipo	Requerido	Descripción
`path`	string	sí	Ruta a .prg, .d64, .g64, etc.
`program`	string		Nombre del programa a cargar desde el disco
`run`	boolean		Ejecutar después de cargar (predeterminado: true)
`index`	number		Índice del programa en el disco, basado en 0

`vice.machine.reset`

Reiniciar la máquina.

Parámetro	Tipo	Requerido	Descripción
`mode`	string		`soft` (predeterminado) o `hard` (ciclo de encendido)
`run_after`	boolean		Reanudar después del reinicio (predeterminado: true)

`vice.machine.config.get`

Obtener la configuración de la máquina — chips, mapa de memoria, recursos. Sin parámetros.

`vice.machine.config.set`

Establecer recursos de la máquina.

Parámetro	Tipo	Requerido	Descripción
`resources`	object	sí	Pares de nombre/valor de recursos, p. ej. `{"WarpMode": 1}`

Pantalla

`vice.display.screenshot`

Capturar la pantalla.

Parámetro	Tipo	Descripción
`path`	string	Ruta del archivo para guardar
`format`	string	`PNG` (predeterminado) o `BMP`
`return_base64`	boolean	Devolver como URI de datos base64

`vice.display.get_dimensions`

Obtener las dimensiones de la pantalla. Sin parámetros.

Entrada

`vice.keyboard.type`

Escribir texto con conversión automática de PETSCII.

Parámetro	Tipo	Obligatorio	Descripción
`text`	string	sí	Texto a escribir (`\n` para Retorno)
`petscii_upper`	boolean		Mapeo de mayúsculas (predeterminado: true)

`vice.keyboard.key_press`

Pulsar una tecla.

Parámetro	Tipo	Obligatorio	Descripción
`key`	string	sí	Nombre de la tecla o un solo carácter
`modifiers`	string[]		`shift`, `control`, `alt`, `meta`, etc.
`hold_frames`	number		Duración de pulsación en fotogramas (1-300)
`hold_ms`	number		Duración de pulsación en ms (1-5000)

`vice.keyboard.key_release`

Soltar una tecla.

Parámetro	Tipo	Obligatorio	Descripción
`key`	string	sí	Nombre de la tecla o un solo carácter
`modifiers`	string[]		Modificadores a soltar

`vice.keyboard.restore`

Pulsar/soltar la tecla RESTORE (activa NMI).

Parámetro	Tipo	Obligatorio	Descripción
`pressed`	boolean		true=pulsar, false=soltar (predeterminado: true)

`vice.keyboard.matrix`

Control directo de la matriz del teclado para juegos.

Parámetro	Tipo	Descripción
`key`	string	Nombre de la tecla: `A`-`Z`, `0`-`9`, `SPACE`, `RETURN`, etc.
`row`	number	Fila de la matriz 0-7 (alternativa a la tecla)
`col`	number	Columna de la matriz 0-7 (alternativa a la tecla)
`pressed`	boolean	Estado de la tecla (predeterminado: true)
`hold_frames`	number	Duración de pulsación en fotogramas
`hold_ms`	number	Duración de pulsación en ms

`vice.joystick.set`

Establecer el estado del joystick.

Parámetro	Tipo	Descripción
`port`	number	Puerto 1 o 2 (predeterminado: 1)
`direction`	string	`up`, `down`, `left`, `right`, `center`
`fire`	boolean	Botón de disparo (predeterminado: false)

`vice.joystick.tap`

Tocar el joystick.

Parámetro	Tipo	Descripción
`port`	number	Puerto 1 o 2 (predeterminado: 1)
`direction`	string	`up`, `down`, `left`, `right`, `center`
`fire`	boolean	Botón de disparo (predeterminado: false)
`duration_frames`	number	Duración del toque en fotogramas (predeterminado: 3)
`duration_ms`	number	Duración del toque en ms (predeterminado: 0)

Depuración avanzada

`vice.disassemble`

Desensamblar memoria en instrucciones 6502.

Parámetro	Tipo	Obligatorio	Descripción
`address`	string	sí	Dirección de inicio
`count`	number		Instrucciones a desensamblar (predeterminado: 10, máximo: 100)
`show_symbols`	boolean		Mostrar nombres de símbolos (predeterminado: true)

`vice.symbols.load`

Cargar un archivo de símbolos/etiquetas.

Parámetro	Tipo	Obligatorio	Descripción
`path`	string	sí	Ruta al archivo .sym o .lbl
`format`	string		`auto`, `kickasm`, `vice` o `simple`

`vice.symbols.lookup`

Buscar un símbolo por nombre o dirección.

Parámetro	Tipo	Obligatorio	Descripción
`name`	string		Nombre del símbolo (devuelve la dirección)
`address`	number		Dirección (devuelve el nombre del símbolo)

`vice.watch.add`

Añadir un punto de vigilancia de memoria.

Parámetro	Tipo	Obligatorio	Descripción
`address`	string	sí	Dirección a vigilar
`size`	number		Bytes a vigilar (predeterminado: 1)
`type`	string		`read`, `write` o `both` (predeterminado: `write`)
`load`	boolean		Alternativa a `type`: vigilar lecturas, como en `vice.checkpoint.add`
`store`	boolean		Alternativa a `type`: vigilar escrituras, como en `vice.checkpoint.add`
`stop`	boolean		Detener al alcanzar (predeterminado: true); `false` cuenta los aciertos sin detenerse
`condition`	string		Condición, p. ej. `A == $42`

`vice.backtrace`

Mostrar la pila de llamadas desde las direcciones de retorno JSR.

Parámetro	Tipo	Obligatorio	Descripción
`depth`	number		Máximo de fotogramas (predeterminado: 16, máximo: 64)

`vice.cycles.stopwatch`

Medir ciclos de CPU transcurridos.

Parámetro	Tipo	Obligatorio	Descripción
`action`	string	sí	`reset`, `read` o `reset_and_read`

Instantáneas

`vice.snapshot.save`

Guardar el estado completo del emulador.

Parámetro	Tipo	Obligatorio	Descripción
`name`	string	sí	Nombre de la instantánea (alfanumérico, `_`, `-`)
`description`	string		Qué captura esta instantánea
`include_roms`	boolean		Incluir ROMs (predeterminado: false)
`include_disks`	boolean		Incluir estado del disco (predeterminado: false)

`vice.snapshot.load`

Restaurar el estado del emulador desde una instantánea.

Parámetro	Tipo	Obligatorio	Descripción
`name`	string	sí	Nombre de la instantánea

`vice.snapshot.list`

Listar todas las instantáneas con metadatos. Sin parámetros.

Estado del proyecto

Este es software activo y funcional. El servidor MCP compila y se ejecuta en Linux, macOS y Windows. Las 61 herramientas están implementadas y probadas. CI produce binarios para las tres plataformas en cada push.

Lo que es sólido:

Suite completa de herramientas: ejecución, memoria, puntos de interrupción, sprites, estado de chips, disco, entrada, depuración
Respuestas conscientes de la máquina en todas las plataformas emuladas por VICE
Cliente Python con lógica de reintento y cobertura de pruebas completa
Compilaciones multiplataforma: Linux x86_64 (GUI + headless), macOS arm64 (GUI + headless), Windows x86_64 (headless)
Pipeline CI/CD automatizado con lanzamientos de binarios

Lo que está en progreso:

Transmisión de eventos. GET /events está reservado pero devuelve 501 Not Implemented hoy.
Trazado de ejecución y enlaces de registro de interrupciones en el núcleo de CPU de VICE

Contribuciones

"Crucen, niños. Todos son bienvenidos. Todos bienvenidos." — Tangina Barrons, hablando a los contribuyentes sobre este repositorio

Este proyecto une dos comunidades que a menudo no se superponen: la informática retro y las herramientas modernas de IA. Las contribuciones de cualquiera de los dos mundos (o ambos) son bienvenidas.

Áreas donde la ayuda sería especialmente apreciada:

Internos de VICE: enlazar el trazado de ejecución y el registro de interrupciones en el núcleo de CPU
Transporte de transmisión de eventos: añadir notificaciones en tiempo real de puntos de interrupción y cambios de estado
Soporte adicional de máquinas: probar y ajustar herramientas para PET, CBM-II, Plus/4
Bibliotecas de cliente: clientes TypeScript, Rust, Go
Documentación: tutoriales, flujos de trabajo de ejemplo, demostraciones en video
Pruebas: ejecutar la suite de pruebas del protocolo contra casos límite

El servidor MCP está completamente contenido en vice/src/mcp/. Empieza ahí.

Versionado y lanzamientos

Este repositorio sigue el Estándar de Compilación y Lanzamiento de Walker Heavy Industries:

Conventional Commits son obligatorios. El versionado está automatizado con Cocogitto: feat: incrementa la menor, fix: la de parche, y un !/BREAKING CHANGE incrementa la mayor. Instala el hook de commit local una vez con cog install-hook --all (CI también valida los commits).
En cada push a main, CI ejecuta cog bump --auto, que etiqueta la siguiente vX.Y.Z, actualiza CHANGELOG.md y publica un GitHub Release con las notas de changelog generadas.
La matriz de compilación multi-OS (Linux/macOS/Windows) adjunta sus artefactos a ese Release. La última etiqueta v / Release es la única fuente de verdad para la versión: no hay compute-version.sh ni prefijo de etiqueta vice-mcp-*.

Licencia

VICE se publica bajo la GNU General Public License v2. Las adiciones del servidor MCP siguen la misma licencia.

Agradecimientos

El Equipo VICE por más de 30 años del mejor emulador de 8 bits jamás escrito
Anthropic por la especificación del Model Context Protocol
La comunidad de Commodore 64: aún fuerte después de cuatro décadas

Parte de la suite

VICE MCP es parte de la cadena de herramientas retro de Walker Heavy Industries: herramientas modernas para el ecosistema retro de 8 y 16 bits.

Centro de la casa: https://whi.dev
Hermanos: VICE Mac · VICE MCP · FamiForge · NESBasic · Novus · Miggy Draw · NovaVM