VICE MCP

Servidor MCP incorporado no emulador VICE Commodore 64/128/VIC-20/PET, fornecendo a assistentes de IA acesso direto para ler/escrever memória, definir breakpoints, inspecionar registros VIC-II/SID/CIA e depurar assembly 6502 em tempo real com 63 ferramentas.

GitHub

Experimente este MCPPatrocinado

Documentação

VICE MCP - IA Encontra o Commodore 64

VICE MCP é um projeto da Walker Heavy Industries.

Um servidor MCP embutido diretamente no VICE, dando a agentes de IA e ferramentas modernas controle programático completo sobre o computador de 8 bits mais icônico do mundo.

Carregue uma imagem de disco. Defina breakpoints. Inspecione sprites. Leia registradores SID. Digite no teclado. Tire screenshots. Execute passo a passo o código 6502. Tudo através de uma API JSON-RPC limpa que qualquer cliente MCP pode falar.

Este é o VICE — o lendário emulador de Commodore — com um servidor Model Context Protocol embutido em seu núcleo. Não acoplado externamente. Não é um wrapper. ~17.000 linhas de C entrelaçadas no próprio emulador.

O Que Você Pode Fazer Com Isso?

Para Agentes de IA

Aponte qualquer cliente compatível com MCP - Claude Desktop, Cursor, seu próprio agente - para http://127.0.0.1:6510/mcp e você terá um Commodore 64 totalmente controlável. Seu agente pode:

Carregar e executar software — iniciar automaticamente PRGs e imagens de disco
Depurar código 6502 — breakpoints, watchpoints, quebras condicionais, execução passo a passo
Inspecionar tudo — registradores da CPU, bancos de memória, gráficos VIC-II, áudio SID, temporizadores CIA
Ver o que está na tela — tirar screenshots, ler bitmaps de sprites como arte ASCII
Interagir como um humano — digitar texto, pressionar teclas, mover joysticks
Medir desempenho — cronômetro com precisão de ciclo, rastreamento de execução, registro de interrupções
Salvar e restaurar estado — gerenciamento completo de snapshots com metadados

Para Desenvolvedores de C64

Se você escreve código para o Commodore 64, isso oferece um fluxo de trabalho de depuração moderno sem sair do seu editor:

Defina breakpoints a partir da sua IDE enquanto seu programa executa
Carregue arquivos de símbolos KickAssembler ou VICE e depure por nome de rótulo
Pesquise memória por padrões de bytes com suporte a curingas
Compare regiões de memória com snapshots salvos para encontrar o que mudou
Rastreie a execução com filtragem por faixa de PC para focar no seu código
Registre interrupções para entender o timing de IRQ/NMI
Agrupe breakpoints e alterne-os como um conjunto

Para Pesquisadores e Educadores

Automatize análise de ROM e engenharia reversa
Construa tutoriais interativos que controlam um C64 ao vivo
Capture estados de tela para documentação
Reproduza e analise software histórico

61 Ferramentas em 13 Categorias

Cada ferramenta segue as convenções MCP com validação completa de JSON Schema, erros significativos e nomenclatura consistente de parâmetros.

Categoria	Ferramentas	O Que Fazem
Execução	`vice.execution.run` `vice.execution.pause` `vice.execution.step` `vice.frame.advance` `vice.run_until`	Controlam a CPU — retomar, pausar, passo a passo, avançar frames inteiros, executar até endereço ou contagem de ciclos
Registradores	`vice.registers.get` `vice.registers.set`	Ler/gravar todos os registradores 6502 (A, X, Y, SP, PC, flags de status)
Memória	`vice.memory.read` `vice.memory.write` `vice.memory.banks` `vice.memory.search` `vice.memory.fill` `vice.memory.compare`	Acesso completo à memória com seleção de banco, busca de padrões com curingas
Checkpoints	`vice.checkpoint.add` `vice.checkpoint.delete` `vice.checkpoint.list` `vice.checkpoint.toggle` `vice.checkpoint.set_condition` `vice.checkpoint.set_ignore_count` `vice.checkpoint.group.*`	Breakpoints, watchpoints, tracepoints — com condições e grupos
Sprites	`vice.sprite.get` `vice.sprite.set` `vice.sprite.inspect`	Ler/gravar estado de sprites, visualização de bitmap como arte ASCII
VIC-II	`vice.vicii.get_state` `vice.vicii.set_state`	Acesso completo ao chip de vídeo do C64 — raster, cores, scroll, banco
SID	`vice.sid.get_state` `vice.sid.set_state`	O lendário chip de som — vozes, filtros, ADSR, formas de onda
CIA	`vice.cia.get_state` `vice.cia.set_state`	Estado do chip de temporizador e I/O — tanto CIA1 quanto CIA2
Disco	`vice.disk.attach` `vice.disk.detach` `vice.disk.list` `vice.disk.read_sector`	Montar imagens D64/D71/D81, navegar em diretórios, ler setores brutos
Máquina	`vice.machine.reset` `vice.machine.config.get` `vice.machine.config.set` `vice.autostart`	Reset forçado/suave, controle de recursos (warp, velocidade, modelo), carregamento de programas
Exibição	`vice.display.screenshot` `vice.display.get_dimensions`	Captura de tela para arquivo ou base64, geometria de exibição
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 e joystick — digitação de texto, teclas individuais, matriz direta, RESTORE/NMI
Depuração	`vice.disassemble` `vice.symbols.load` `vice.symbols.lookup` `vice.watch.add` `vice.backtrace` `vice.cycles.stopwatch`	Desmontagem, arquivos de símbolos, pilha de chamadas, timing com precisão de ciclo
Snapshots	`vice.snapshot.save` `vice.snapshot.load` `vice.snapshot.list`	Salvar/restaurar estado completo do emulador com metadados JSON

Arquitetura

Este não é um processo auxiliar ou um raspador de tela. O servidor MCP é compilado diretamente no VICE como um subsistema de primeira classe — em todas as máquinas que o VICE emula.

Máquinas Suportadas

Máquina	CPU	Hardware Notável
C64 / C64 SC	6510	VIC-II, SID, 2×CIA, Sprites
C128	8502/Z80	VIC-II, VDC 80 colunas, SID, 2×CIA
SCPU64	65816	Acelerador SuperCPU
C64 DTV	6510 (estendido)	Registradores específicos do DTV
VIC-20	6502	Vídeo VIC-I, memória de expansão
Plus/4 & C16	7501/8501	Chip de vídeo+áudio TED
PET	6502	Vídeo CRTC, I/O PIA/VIA
CBM-II	6509	CRTC, MOS 6526 CIA

O servidor MCP se adapta automaticamente à máquina em execução. Quando um agente de IA chama vice.machine.config.get, ele recebe a configuração real de hardware — quais chips estão presentes, quais bancos de memória existem, faixas de endereço válidas e recursos disponíveis. Um agente depurando um cartucho de VIC-20 obtém registradores VIC-I; o mesmo agente depurando um programa C128 obtém VIC-II e o display VDC de 80 colunas.

┌─────────────────────────────────────────────────┐
│                   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

Decisões-chave de design:

Despacho baseado em traps — Requisições HTTP são despachadas através do mecanismo de traps do VICE, garantindo que toda a lógica das ferramentas execute na thread principal do emulador. Sem condições de corrida, sem surpresas de locking.
Acesso zero-copy — As ferramentas leem diretamente das entranhas do emulador. Quando você pede o estado do VIC-II, você obtém os valores reais dos registradores, não uma aproximação em cache.
Respostas cientes da máquina — As ferramentas reportam capacidades de hardware, disponibilidade de chips e faixas de memória válidas para qualquer máquina em execução. O agente sempre sabe com o que está trabalhando.
Integração com monitor — Funciona junto com o monitor embutido do VICE. Se o emulador estiver pausado no monitor, requisições MCP executam diretamente sem traps.
Endpoint de eventos reservado — GET /events existe mas atualmente retorna 501 Not Implemented. Consulte o estado através de /mcp até o streaming de eventos chegar.

Início Rápido

Conecte-se ao VICE

Inicie qualquer máquina VICE com o 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

O servidor MCP inicia em 127.0.0.1:6510 por padrão. Clientes MCP conectam-se a:

http://127.0.0.1:6510/mcp

0.0.0.0 é um endereço de bind, não um endereço de cliente. Significa "ouvir em todas as interfaces". Um cliente no mesmo Mac ainda conecta-se a 127.0.0.1; um cliente em outra máquina conecta-se ao endereço IP LAN do Mac, por exemplo http://192.168.1.42:6510/mcp.

Receitas de Conexão

Caso de uso	Inicie o VICE com	URL do cliente	Cabeçalho de autenticação
Mesmo Mac, padrão	`x64sc -mcpserver`	`http://127.0.0.1:6510/mcp`	Nenhum
Mesmo Mac, porta personalizada	`x64sc -mcpserver -mcpserverport 7000`	`http://127.0.0.1:7000/mcp`	Nenhum
Acesso LAN, rede confiável	`x64sc -mcpserver -mcpserverhost 0.0.0.0`	`http://<mac-lan-ip>:6510/mcp`	Nenhum
Acesso LAN com token bearer	`x64sc -mcpserver -mcpserverhost 0.0.0.0 -mcpservertoken secret`	`http://<mac-lan-ip>:6510/mcp`	`Authorization: Bearer secret`
Aplicativo de navegador com CORS	`x64sc -mcpserver -mcpservercorsorigin http://localhost:3000 -mcpservertoken secret`	`http://127.0.0.1:6510/mcp`	`Authorization: Bearer secret`

As regras de token são intencionalmente simples:

Nenhum token configurado: clientes MCP que não sejam de navegador podem conectar sem um cabeçalho Authorization.
Token configurado: toda requisição MCP deve incluir Authorization: Bearer <token>.
CORS configurado: um token é obrigatório. CORS curinga (*) é rejeitado.
Vincular a 0.0.0.0 sem um token é permitido para compatibilidade retroativa, mas o VICE registra um aviso porque clientes remotos podem controlar o emulador.

Fale Com Ele

Todas as requisições HTTP vão para /mcp, devem usar Content-Type: application/json, e devem 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" }
  }
}'

Quando um token está configurado, adicione o cabeçalho bearer a cada requisição:

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"}'

Uso com Claude Desktop

Adicione isto à sua configuração MCP do Claude Desktop:

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

Então é só conversar: "Carregue o jogo na unidade 8 e me mostre o que está na tela."

Se o VICE foi iniciado com -mcpservertoken, o cliente deve enviar Authorization: Bearer <token> em cada requisição. Se o seu cliente MCP não conseguir configurar cabeçalhos HTTP, não use um token para sessões 127.0.0.1 somente locais.

Compilando a Partir do Código-Fonte

Pré-requisitos

Plataforma	Instalação
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)

Binários Pré-compilados

Binários pré-compilados estão disponíveis na página de Releases.

Plataforma	GUI	Headless	Notas
Linux x86_64	Sim	Sim	Interface GTK3
macOS arm64	Sim	Sim	Interface GTK3 (Apple Silicon)
Windows x86_64	Não	Sim	Somente headless — compilado cruzadamente via MinGW-w64

O Windows não inclui uma compilação GUI. A compilação cruzada GTK3 para Windows não é suportada pelo sistema de build do VICE. Se você precisar de uma GUI no Windows, compile a partir do código-fonte nativamente usando MSYS2.

Cliente Python

Um cliente Python resiliente está incluído com lógica de nova tentativa, pooling de conexões e um método de conveniência para cada ferramenta:

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)

Suíte de Testes de Protocolo

167 testes em 25 classes de teste validam cada ferramenta, cada parâmetro e cada condição de erro:

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

Uso no Mundo Real

sim6502 — Testes Unitários para Assembly 6502

sim6502 é um framework de testes unitários para assembly 6502/6510/65C02 que usa o VICE MCP como backend de execução. Escreva testes em um DSL personalizado, execute-os contra uma instância VICE ao vivo com hardware com precisão de ciclo:

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
    }
}

O sim6502 conecta-se via MCP para carregar programas, definir breakpoints, ler registradores, comparar memória e capturar/restaurar estado entre testes — trazendo práticas modernas de CI/CD para o desenvolvimento de computação retrô.

Fluxos de Trabalho com Agentes de IA

Qualquer cliente compatível com MCP pode dirigir o VICE diretamente:

Claude Desktop / Cursor — "Carregue esta imagem de disco, encontre o loop principal e explique o que o manipulador de IRQ faz"
Agentes personalizados — Análise automatizada de ROM, testes de regressão, captura de screenshots
Ferramentas de pesquisa — Exploração sistemática do comportamento de software histórico

Segurança

O servidor MCP é somente localhost por padrão (127.0.0.1). Com as configurações padrão, apenas programas na mesma máquina podem conectar.

Ele não tem TLS. Tem autenticação opcional por token bearer. É projetado para desenvolvimento local em primeiro lugar, e a exposição à rede deve ser deliberada.

Se você precisar de acesso remoto, coloque-o atrás de um proxy reverso com autenticação adequada:

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

Vincular a 0.0.0.0 é suportado via -mcpserverhost. Isso faz o VICE ouvir em todas as interfaces de rede. Não significa que clientes conectam-se a 0.0.0.0; clientes remotos conectam-se ao endereço IP real do host Mac/Linux/Windows.

Use esta lista de verificação para sessões remotas:

Inicie o VICE com -mcpserverhost 0.0.0.0.
Prefira adicionar -mcpservertoken <token> a menos que a rede já seja confiável.
Configure a URL do cliente como http://<host-ip>:6510/mcp.
Se um token estiver configurado, configure o cliente para enviar Authorization: Bearer <token>.
Para clientes baseados em navegador, configure também exatamente um -mcpservercorsorigin <origin> e um token. CORS sem token é rejeitado.

Relação com o VICE Upstream

Este é um fork do espelho SVN do VICE. O servidor MCP é implementado como um subsistema autocontido em src/mcp/ — ele toca nas entranhas do VICE através de interfaces bem definidas, mas não modifica a lógica central de emulação.

O branch main rastreia o VICE upstream. O branch mcp-server contém todas as adições do MCP. O objetivo é contribuir com este trabalho de volta ao projeto VICE. A implementação está estruturada para exportar de forma limpa como diffs unificados para submissão via SVN.

Referência de Ferramentas

Clique para expandir a referência completa de todas as 61 ferramentas

Controle de Execução

`vice.ping`

Verifica se o VICE está respondendo. Sem parâmetros.

`vice.execution.run`

Retoma a execução. Sem parâmetros.

`vice.execution.pause`

Pausa a execução. Sem parâmetros.

`vice.execution.step`

Executa uma ou mais instruções. Em uma máquina parada, a chamada retorna após a execução, com completed: true e o PC. Se um checkpoint parar a máquina primeiro, a resposta traz stopped_early: true e o PC naquele ponto; se a execução não terminar após 2 segundos (uma execução sobre uma sub-rotina lenta), a máquina é pausada no próximo limite de instrução e a resposta traz timed_out: true. De qualquer forma, o restante da execução é descartado. Em uma máquina em execução, a chamada arma a execução e retorna imediatamente.

Parâmetro	Tipo	Obrigatório	Descrição
`count`	number		Instruções a executar (padrão: 1, máximo: 10000)
`stepOver`	boolean		Executar sobre sub-rotinas

`vice.frame.advance`

Executa frames inteiros a partir de uma máquina parada e para novamente, no primeiro limite de instrução após a sincronização vertical que encerra o último frame, com registradores exportados. O estado de joystick e teclado definido enquanto parado é mantido durante a execução dos frames, o que permite um loop de entrada frame a frame: definir entrada, avançar um frame, ler memória, repetir. A máquina já deve estar parada (por vice.execution.pause, um checkpoint de parada ou vice.execution.step); caso contrário, a chamada retorna erro -32001. Se um checkpoint parar a máquina antes do limite, a resposta traz stopped_early: true e o número de frames inteiros executados. Um frame que não terminar após 2 segundos é abandonado: a máquina é pausada no próximo limite de instrução e a resposta também traz timed_out: true.

Parâmetro	Tipo	Obrigatório	Descrição
`frames`	number		Frames inteiros a executar antes de parar novamente (padrão: 1, máximo: 1000)

`vice.run_until`

Executa até um endereço ou por N ciclos com tempo limite.

Parâmetro	Tipo	Obrigatório	Descrição
`address`	string		Endereço alvo (hex, decimal ou nome de símbolo)
`cycles`	number		Máximo de ciclos a executar

Registradores

`vice.registers.get`

Obtém todos os registradores da CPU (A, X, Y, SP, PC, flags de status). Sem parâmetros.

`vice.registers.set`

Define o valor de um registrador da CPU.

Parâmetro	Tipo	Obrigatório	Descrição
`register`	string	sim	Nome do registrador: `PC` `A` `X` `Y` `SP` `N` `V` `B` `D` `I` `Z` `C`
`value`	number	sim	Valor a definir

Memória

`vice.memory.read`

Lê um intervalo de memória com seleção opcional de banco.

Parâmetro	Tipo	Obrigatório	Descrição
`address`	string	sim	Endereço: número, hex (`$1000`) ou nome de símbolo
`size`	number	sim	Bytes a ler (1-65535)
`bank`	string		Nome do banco de memória (use `vice.memory.banks` para listar)

`vice.memory.write`

Escreve bytes na memória.

Parâmetro	Tipo	Obrigatório	Descrição
`address`	string	sim	Endereço: número, hex (`$1000`) ou nome de símbolo
`data`	number[]	sim	Bytes a escrever (0-255 cada)

`vice.memory.banks`

Lista os bancos de memória disponíveis para a máquina atual. Sem parâmetros.

`vice.memory.search`

Busca por padrões de bytes com máscara curinga opcional.

Parâmetro	Tipo	Obrigatório	Descrição
`start`	string	sim	Endereço inicial
`end`	string	sim	Endereço final
`pattern`	number[]	sim	Padrão de bytes, ex.: `[0x4C, 0x00, 0xA0]`
`mask`	number[]		Máscara por byte: `0xFF`=exato, `0x00`=curinga
`max_results`	number		Máximo de correspondências (padrão: 100, máximo: 10000)

`vice.memory.fill`

Preenche um intervalo de memória com um padrão de bytes repetido.

Parâmetro	Tipo	Obrigatório	Descrição
`start`	string	sim	Endereço inicial
`end`	string	sim	Endereço final (inclusivo)
`pattern`	number[]	sim	Padrão de bytes a repetir

`vice.memory.compare`

Compara dois intervalos de memória ou compara contra um snapshot.

Parâmetro	Tipo	Obrigatório	Descrição
`mode`	string	sim	`ranges` ou `snapshot`
`range1_start`	string	ranges	Início do primeiro intervalo
`range1_end`	string	ranges	Fim do primeiro intervalo
`range2_start`	string	ranges	Início do segundo intervalo
`snapshot_name`	string	snapshot	Snapshot para comparar
`start`	string	snapshot	Endereço inicial para comparar
`end`	string	snapshot	Endereço final para comparar
`max_differences`	number		Máximo de diferenças a retornar (padrão: 100)

Checkpoints e Breakpoints

`vice.checkpoint.add`

Adiciona um checkpoint (breakpoint, watchpoint ou tracepoint).

Parâmetro	Tipo	Obrigatório	Descrição
`start`	string	sim	Endereço inicial
`end`	string		Endereço final (padrão = inicial)
`stop`	boolean		Parar ao atingir (padrão: true)
`load`	boolean		Parar em leitura de memória (padrão: false)
`store`	boolean		Parar em escrita de memória (padrão: false)
`exec`	boolean		Parar em execução (padrão: true)

`vice.checkpoint.delete`

Exclui um checkpoint.

Parâmetro	Tipo	Obrigatório	Descrição
`checkpoint_num`	number	sim	Número do checkpoint

`vice.checkpoint.list`

Lista todos os checkpoints. Sem parâmetros.

`vice.checkpoint.toggle`

Habilita ou desabilita um checkpoint.

Parâmetro	Tipo	Obrigatório	Descrição
`checkpoint_num`	number	sim	Número do checkpoint
`enabled`	boolean	sim	Habilitar ou desabilitar

`vice.checkpoint.set_condition`

Define uma expressão de condição em um checkpoint.

Parâmetro	Tipo	Obrigatório	Descrição
`checkpoint_num`	number	sim	Número do checkpoint
`condition`	string	sim	Expressão, ex.: `A == $42`

`vice.checkpoint.set_ignore_count`

Define quantas ocorrências ignorar antes de parar.

Parâmetro	Tipo	Obrigatório	Descrição
`checkpoint_num`	number	sim	Número do checkpoint
`count`	number	sim	Ocorrências a ignorar

`vice.checkpoint.group.create`

Cria um grupo de checkpoints nomeado.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome do grupo
`checkpoint_ids`	number[]		IDs iniciais de checkpoints

`vice.checkpoint.group.add`

Adiciona checkpoints a um grupo existente.

Parâmetro	Tipo	Obrigatório	Descrição
`group`	string	sim	Nome do grupo
`checkpoint_ids`	number[]	sim	IDs de checkpoints a adicionar

`vice.checkpoint.group.toggle`

Habilita ou desabilita todos os checkpoints em um grupo.

Parâmetro	Tipo	Obrigatório	Descrição
`group`	string	sim	Nome do grupo
`enabled`	boolean	sim	Habilitar ou desabilitar todos

`vice.checkpoint.group.list`

Lista todos os grupos de checkpoints. Sem parâmetros.

Sprites (C64/C128/DTV)

`vice.sprite.get`

Obtém o estado do sprite.

Parâmetro	Tipo	Obrigatório	Descrição
`sprite`	number		Número do sprite 0-7 (omitir para todos)

`vice.sprite.set`

Define propriedades do sprite.

Parâmetro	Tipo	Obrigatório	Descrição
`sprite`	number	sim	Número do sprite 0-7
`x`	number		Posição X 0-511
`y`	number		Posição Y 0-255
`enabled`	boolean		Habilitar sprite
`multicolor`	boolean		Modo multicolor
`expand_x`	boolean		Largura dupla
`expand_y`	boolean		Altura dupla
`priority_foreground`	boolean		Desenhar sobre o fundo
`color`	number		Cor do sprite 0-15

`vice.sprite.inspect`

Representação visual em arte ASCII do bitmap de um sprite.

Parâmetro	Tipo	Obrigatório	Descrição
`sprite_number`	number	sim	Número do sprite 0-7
`format`	string		`ascii` (padrão), `binary` ou `png_base64`

Estado dos Chips

`vice.vicii.get_state`

Obtém o estado interno do VIC-II. Sem parâmetros.

`vice.vicii.set_state`

Define registradores do VIC-II.

Parâmetro	Tipo	Obrigatório	Descrição
`registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x2E)

`vice.sid.get_state`

Obtém o estado do SID (vozes, filtro, ADSR). Sem parâmetros.

`vice.sid.set_state`

Define registradores do SID.

Parâmetro	Tipo	Obrigatório	Descrição
`registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x1C)

`vice.cia.get_state`

Obtém o estado do CIA (temporizadores, portas).

Parâmetro	Tipo	Obrigatório	Descrição
`cia`	number		Número do CIA: 1 ou 2 (omitir para ambos)

`vice.cia.set_state`

Define registradores do CIA.

Parâmetro	Tipo	Obrigatório	Descrição
`cia1_registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x0F)
`cia2_registers`	object[]		Matriz de `{offset, value}` (offset 0x00-0x0F)

Gerenciamento de Disco

`vice.disk.attach`

Anexa uma imagem de disco a uma unidade.

Parâmetro	Tipo	Obrigatório	Descrição
`unit`	number	sim	Unidade (8-11)
`path`	string	sim	Caminho para a imagem de disco (.d64, .g64, etc.)

`vice.disk.detach`

Desanexa uma imagem de disco.

Parâmetro	Tipo	Obrigatório	Descrição
`unit`	number	sim	Unidade (8-11)

`vice.disk.list`

Lista o conteúdo do diretório de um disco anexado.

Parâmetro	Tipo	Obrigatório	Descrição
`unit`	number	sim	Unidade (8-11)

`vice.disk.read_sector`

Lê dados brutos de setor.

Parâmetro	Tipo	Obrigatório	Descrição
`unit`	number	sim	Unidade (8-11)
`track`	number	sim	Número da trilha (1-42 para D64)
`sector`	number	sim	Número do setor

Controle da Máquina

`vice.autostart`

Inicia automaticamente uma imagem PRG ou de disco.

Parâmetro	Tipo	Obrigatório	Descrição
`path`	string	sim	Caminho para .prg, .d64, .g64, etc.
`program`	string		Nome do programa a carregar do disco
`run`	boolean		Executar após carregar (padrão: true)
`index`	number		Índice do programa no disco, baseado em 0

`vice.machine.reset`

Reinicia a máquina.

Parâmetro	Tipo	Obrigatório	Descrição
`mode`	string		`soft` (padrão) ou `hard` (ciclo de energia)
`run_after`	boolean		Retomar após reiniciar (padrão: true)

`vice.machine.config.get`

Obtém a configuração da máquina — chips, mapa de memória, recursos. Sem parâmetros.

`vice.machine.config.set`

Define recursos da máquina.

Parâmetro	Tipo	Obrigatório	Descrição
`resources`	object	sim	Pares de nome/valor de recursos, ex.: `{"WarpMode": 1}`

Exibição

`vice.display.screenshot`

Captura a tela.

Parâmetro	Tipo	Descrição
`path`	string	Caminho do arquivo para salvar
`format`	string	`PNG` (padrão) ou `BMP`
`return_base64`	boolean	Retornar como URI de dados base64

`vice.display.get_dimensions`

Obtém as dimensões da tela. Sem parâmetros.

Entrada

`vice.keyboard.type`

Digita texto com conversão automática de PETSCII.

Parâmetro	Tipo	Obrigatório	Descrição
`text`	string	sim	Texto a digitar (`\n` para Return)
`petscii_upper`	boolean		Mapeamento de maiúsculas (padrão: true)

`vice.keyboard.key_press`

Pressiona uma tecla.

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	sim	Nome da tecla ou caractere único
`modifiers`	string[]		`shift`, `control`, `alt`, `meta`, etc.
`hold_frames`	number		Duração do pressionamento em frames (1-300)
`hold_ms`	number		Duração do pressionamento em ms (1-5000)

`vice.keyboard.key_release`

Solta uma tecla.

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	sim	Nome da tecla ou caractere único
`modifiers`	string[]		Modificadores a soltar

`vice.keyboard.restore`

Pressiona/solta a tecla RESTORE (aciona NMI).

Parâmetro	Tipo	Obrigatório	Descrição
`pressed`	boolean		true=pressionar, false=soltar (padrão: true)

`vice.keyboard.matrix`

Controle direto da matriz do teclado para jogos.

Parâmetro	Tipo	Descrição
`key`	string	Nome da tecla: `A`-`Z`, `0`-`9`, `SPACE`, `RETURN`, etc.
`row`	number	Linha da matriz 0-7 (alternativa à tecla)
`col`	number	Coluna da matriz 0-7 (alternativa à tecla)
`pressed`	boolean	Estado da tecla (padrão: true)
`hold_frames`	number	Duração do pressionamento em frames
`hold_ms`	number	Duração do pressionamento em ms

`vice.joystick.set`

Define o estado do joystick.

Parâmetro	Tipo	Descrição
`port`	number	Porta 1 ou 2 (padrão: 1)
`direction`	string	`up`, `down`, `left`, `right`, `center`
`fire`	boolean	Botão de fogo (padrão: false)

`vice.joystick.tap`

Toque no joystick.

Parâmetro	Tipo	Descrição
`port`	number	Porta 1 ou 2 (padrão: 1)
`direction`	string	`up`, `down`, `left`, `right`, `center`
`fire`	boolean	Botão de fogo (padrão: false)
`duration_frames`	number	Duração do toque em frames (padrão: 3)
`duration_ms`	number	Duração do toque em ms (padrão: 0)

Depuração Avançada

`vice.disassemble`

Desmonta memória em instruções 6502.

Parâmetro	Tipo	Obrigatório	Descrição
`address`	string	sim	Endereço inicial
`count`	number		Instruções a desmontar (padrão: 10, máx: 100)
`show_symbols`	boolean		Mostrar nomes de símbolos (padrão: true)

`vice.symbols.load`

Carrega um arquivo de símbolos/rótulos.

Parâmetro	Tipo	Obrigatório	Descrição
`path`	string	sim	Caminho para arquivo .sym ou .lbl
`format`	string		`auto`, `kickasm`, `vice`, ou `simple`

`vice.symbols.lookup`

Busca um símbolo por nome ou endereço.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string		Nome do símbolo (retorna endereço)
`address`	number		Endereço (retorna nome do símbolo)

`vice.watch.add`

Adiciona um ponto de observação de memória.

Parâmetro	Tipo	Obrigatório	Descrição
`address`	string	sim	Endereço a observar
`size`	number		Bytes a observar (padrão: 1)
`type`	string		`read`, `write`, ou `both` (padrão: `write`)
`load`	boolean		Alternativa a `type`: observar leituras, como em `vice.checkpoint.add`
`store`	boolean		Alternativa a `type`: observar escritas, como em `vice.checkpoint.add`
`stop`	boolean		Parar ao atingir (padrão: true); `false` conta ocorrências sem parar
`condition`	string		Condição, ex.: `A == $42`

`vice.backtrace`

Mostra pilha de chamadas a partir de endereços de retorno JSR.

Parâmetro	Tipo	Obrigatório	Descrição
`depth`	number		Máx. de frames (padrão: 16, máx: 64)

`vice.cycles.stopwatch`

Mede ciclos de CPU decorridos.

Parâmetro	Tipo	Obrigatório	Descrição
`action`	string	sim	`reset`, `read`, ou `reset_and_read`

Snapshots

`vice.snapshot.save`

Salva o estado completo do emulador.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome do snapshot (alfanumérico, `_`, `-`)
`description`	string		O que este snapshot captura
`include_roms`	boolean		Incluir ROMs (padrão: false)
`include_disks`	boolean		Incluir estado do disco (padrão: false)

`vice.snapshot.load`

Restaura o estado do emulador a partir de um snapshot.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome do snapshot

`vice.snapshot.list`

Lista todos os snapshots com metadados. Sem parâmetros.

Status do Projeto

Este é um software ativo e funcional. O servidor MCP compila e roda em Linux, macOS e Windows. Todas as 61 ferramentas estão implementadas e testadas. A CI produz binários para as três plataformas a cada push.

O que está sólido:

Suíte completa de ferramentas — execução, memória, breakpoints, sprites, estado de chips, disco, entrada, depuração
Respostas cientes da máquina em todas as plataformas emuladas pelo VICE
Cliente Python com lógica de retry e cobertura completa de testes
Builds multiplataforma: Linux x86_64 (GUI + headless), macOS arm64 (GUI + headless), Windows x86_64 (headless)
Pipeline automatizado de CI/CD com lançamentos de binários

O que está em andamento:

Streaming de eventos. GET /events está reservado, mas retorna 501 Not Implemented hoje.
Rastreamento de execução e hooks de log de interrupções no núcleo da CPU do VICE

Contribuindo

"Atravessem, crianças. Todos são bem-vindos. Todos são bem-vindos." — Tangina Barrons, falando aos contribuidores sobre este repositório

Este projeto conecta duas comunidades que raramente se sobrepõem: computação retrô e ferramentas modernas de IA. Contribuições de qualquer um dos mundos (ou de ambos) são bem-vindas.

Áreas onde a ajuda seria especialmente apreciada:

Internals do VICE — Conectar rastreamento de execução e log de interrupções ao núcleo da CPU
Transporte de streaming de eventos — Adicionar notificações em tempo real de breakpoints e mudanças de estado
Suporte adicional a máquinas — Testar e ajustar ferramentas para PET, CBM-II, Plus/4
Bibliotecas de cliente — Clientes TypeScript, Rust, Go
Documentação — Tutoriais, fluxos de trabalho de exemplo, demonstrações em vídeo
Testes — Executar a suíte de testes de protocolo contra casos extremos

O servidor MCP está inteiramente contido em vice/src/mcp/. Comece por aí.

Versionamento e lançamentos

Este repositório segue o Padrão de Build e Lançamento da Walker Heavy Industries:

Conventional Commits são obrigatórios. O versionamento é automatizado com Cocogitto — feat: incrementa o minor, fix: o patch, e um !/BREAKING CHANGE incrementa o major. Instale o hook de commit local uma vez com cog install-hook --all (a CI também valida commits).
A cada push para main, a CI executa cog bump --auto, que marca a próxima vX.Y.Z, atualiza CHANGELOG.md e publica um GitHub Release com as notas de changelog geradas.
A matriz de builds multi-OS (Linux/macOS/Windows) anexa seus artefatos a esse Release. A tag v mais recente / Release é a única fonte de verdade para a versão — não há compute-version.sh e nenhum prefixo de tag vice-mcp-*.

Licença

O VICE é lançado sob a GNU General Public License v2. As adições do servidor MCP seguem a mesma licença.

Agradecimentos

A Equipe VICE por mais de 30 anos do melhor emulador de 8 bits já escrito
Anthropic pela especificação do Model Context Protocol
A comunidade Commodore 64 — ainda forte após quatro décadas

Parte da suíte

O VICE MCP faz parte do toolchain retrô da Walker Heavy Industries — ferramentas modernas para o ecossistema retrô de 8 e 16 bits.

Hub da casa: https://whi.dev
Irmãos: VICE Mac · VICE MCP · FamiForge · NESBasic · Novus · Miggy Draw · NovaVM