AtariHackerMCP

Ferramentas que podem ser necessárias para hackear código Atari de 8 bits (arquivos .atr), incluindo dump hexadecimal, desmontador, tabelas de símbolos, etc.

GitHub
5

Documentação

AtariHackerMCP

Um servidor MCP local para engenharia reversa de binários Atari de 8 bits e imagens de disco ATR. Suporta análise de desmontagem em múltiplas passadas, separação de código/dados, saída ciente de segmentos, injeção de arquivos ATR, script em lote e uma tabela abrangente de símbolos de hardware Atari.

Requisitos

  • .NET SDK 10.0+
  • Linux, macOS ou Windows

Compilação

Restaure pacotes e compile:

dotnet build

Publique uma compilação de lançamento, se necessário:

dotnet publish -c Release -o publish

Execução

Este servidor usa transporte stdio MCP, portanto normalmente é iniciado por um cliente MCP em vez de ser executado interativamente.

Para testes locais:

dotnet run --no-build

Ou execute o executável publicado:

./publish/AtariHackerMCP

Configuração do Cliente MCP

Exemplo de entrada de servidor stdio:

{
  "mcpServers": {
    "atari-hacker": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/AtariHackerMCP/AtariHackerMCP.csproj",
        "--no-build"
      ]
    }
  }
}

Se preferir usar uma compilação publicada:

{
  "mcpServers": {
    "atari-hacker": {
      "command": "/absolute/path/to/AtariHackerMCP/publish/AtariHackerMCP",
      "args": []
    }
  }
}

Ferramentas Disponíveis

Ferramentas de arquivo e disco

  • load_rom — Carrega um binário ROM/XEX na sessão atual
  • rom_info — Exibe informações estruturais sobre o binário carregado
  • atr_info — Exibe informações estruturais sobre uma imagem de disco ATR
  • atr_header — Exibe os campos do cabeçalho ATR de uma imagem de disco
  • load_atr_file — Extrai um arquivo de um ATR e o carrega na sessão
  • load_atr_boot — Extrai setores de boot de um ATR e os carrega em $0700
  • list_atr_directory — Lista o diretório DOS de uma imagem de disco ATR
  • analyze_boot_sector — Decodifica o cabeçalho do setor de boot de um ATR
  • sector_dump — Despejo hexadecimal de setores de um ATR por número de setor lógico
  • search_boot_sector — Examina setores de boot em vários ATRs em busca de padrões/diferenças
  • extract_atr_file — Extrai um arquivo de um ATR e o salva em disco
  • inject_atr_file — Injeta um arquivo em um ATR (cópia ao gravar)
  • create_atr — Cria uma nova imagem de disco ATR do zero
  • write_atr_sector — Grava dados brutos em um setor específico de um ATR
  • write_atr_file — Grava um arquivo em um ATR com criação de entrada de diretório
  • define_filesystem — Define um layout de sistema de arquivos personalizado para ATRs não-DOS

Inspeção e desmontagem

  • hex_dump — Produz um despejo hexadecimal com deslocamentos de arquivo, endereços de memória e ASCII
  • disassemble — Desmonta código 6502 com análise opcional em múltiplas passadas (analyze=true)
    • Formatos suportados: listing, ca65, atasm, mac65
    • Quando analyze=true: gera rótulos significativos (sub_XXXX, data_XXXX, jmp_XXXX), separação código/dados, saída .segment/.proc/.endproc ciente de segmentos, formatação de strings ATASCII, comentários de cabeçalho de procedimentos
  • analyze_disassembly — Análise em múltiplas passadas que constrói um grafo de referências e identifica regiões de código/dados
    • Formatos: summary, graph, labels, full
  • define_segment — Define um segmento de memória por tipo (código, dados, gráficos, texto, zero_page)
  • remove_segment — Remove um segmento definido pelo nome
  • list_segments — Lista todos os segmentos de memória definidos (mostra lacunas)
  • clear_segments — Limpa todos os segmentos definidos
  • generate_linker_config — Gera uma configuração de linker cc65 a partir dos segmentos atuais

Ferramentas de análise

  • x_ref — Encontra referências cruzadas para um endereço na ROM
  • find_pattern — Procura um padrão de bytes com curingas
  • find_strings — Procura sequências de caracteres ASCII ou ATASCII imprimíveis
  • trace_control_flow — Rastreia estaticamente a execução a partir de um endereço inicial
  • probe_data — Analisa um intervalo de memória para identificar o tipo de dados (texto, gráficos, tabela, charset, lista de exibição, dados de sprite, dados de mapa) com pontuação de confiança
  • generate_callgraph — Gera um grafo de chamadas mostrando relações entre sub-rotinas (formato Mermaid ou texto)
  • analyze_coverage — Analisa cobertura de código: quais bytes são executados vs. dados
  • diff_roms — Compara dois arquivos ROM ou ATR (formato resumo, detalhado ou diff hexadecimal)

Ferramentas de símbolos e zero-page

  • define_symbol — Adiciona ou atualiza um rótulo nomeado para um endereço de memória
  • remove_symbol — Remove um símbolo definido pelo usuário
  • lookup_symbol — Consulta a entrada de símbolo para um endereço
  • list_symbols — Lista símbolos na tabela de símbolos
  • set_symbols — Ativa/desativa grupos de símbolos (hardware, variáveis do SO, ROM do SO, rótulos do usuário) para controlar quais nomes aparecem na desmontagem
  • load_labels — Carrega rótulos e segmentos de um arquivo auxiliar
  • save_labels — Salva rótulos e segmentos atuais em um arquivo auxiliar
  • annotate_zero_page — Adiciona ou atualiza uma anotação de zero-page
  • show_zero_page_map — Exibe anotações atuais de zero-page

Ferramentas de script

  • run_script — Executa uma sequência de comandos de um arquivo de script (suporta 33 comandos)

Ferramentas utilitárias

  • calculate — Avalia expressões matemáticas com literais hexadecimais (prefixo $)
  • hex_to_decimal — Converte hexadecimal para decimal
  • decimal_to_hex — Converte decimal para hexadecimal

Desmontagem em Múltiplas Passadas

Quando analyze=true é passado para disassemble, o mecanismo executa três passadas:

  1. Passada 1 — Coleta de Referências: Examina todos os limites de instrução na ROM, registrando alvos de JSR, alvos de JMP, alvos de desvios, alvos de saltos indiretos e referências de dados absolutas/indiretas em um ReferenceGraph.
  2. Passada 2 — Rastreamento de Regiões de Código: A partir de cada ponto de entrada de código, rastreia o fluxo de execução (seguindo JSR, JMP, desvios, parando em RTS/RTI/BRK) para marcar bytes como código ou dados.
  3. Passada 3 — Geração de Rótulos: Produz rótulos significativos (sub_XXXX, jmp_XXXX, data_XXXX, L_XXXX) com ordenação de prioridade adequada (usuário > sub-rotina > dados > hardware > SO > desvio).

Exemplo

; --------------------------------------------------
; Generated by Atari Hacker MCP v4
; --------------------------------------------------

.segment "MAIN_CODE"
.org $0C00

; --------------------------------------------------
; Subroutine: game_init
; Calls:     load_ag_obj, load_ag_dat, main_loop
; --------------------------------------------------
.proc game_init
    LDA #$00
    STA $D400          ; DMACTL
    ...
.endproc

; String table at $1712
credits_text:
    .byte "Scholastic", $9B    ; $9B = ATASCII EOL
    .byte "Wizware", $9B
    .byte $00

Tabela de Símbolos de Hardware Atari

A tabela de símbolos integrada cobre mais de 200 entradas em todos os principais componentes Atari:

GrupoFaixaEntradas
GTIA$D000–$D01F22 registradores (gráficos de jogador/míssil, cor, controle)
POKEY$D200–$D21F32 registradores (som, E/S, reservados, aliasing de leitura/gravação)
PIA$D300–$D3034 registradores (E/S paralela)
ANTIC$D400–$D41F20 registradores (DMA, lista de exibição, NMI, reservados)
ROM do SO$C000–$FFFF13 pontos de entrada (SIO, CIO, vetores)
Zero page do SO$00–$FF~220 variáveis (temporizadores, controle de E/S, ponto flutuante, tela, paddles, joysticks)

Grupos de símbolos podem ser alternados com set_symbols para evitar conflitos quando o código do usuário se sobrepõe às faixas de endereço do SO.

Operações de Gravação em ATR

O subsistema de gravação ATR fornece modificação de imagem de disco com cópia ao gravar:

OperaçãoDescrição
extract_atr_fileExtrai um arquivo DOS de um ATR para o sistema de arquivos do host
inject_atr_fileSubstitui os dados da entrada de um arquivo em um ATR (cria cópia .modified)
create_atrCria um ATR em branco com contagem de setores e densidade especificados
write_atr_sectorGrava dados binários brutos em um setor específico
write_atr_fileCria uma nova entrada de arquivo DOS com alocação de setores
define_filesystemDescreve um layout de sistema de arquivos não-DOS para discos de formato personalizado

Script em Lote

A ferramenta run_script executa sequências de comandos de arquivos de texto:

# disassemble_all.txt
load_rom filePath=game.xex
define_symbol address=$1540 label=game_init
define_segment name=boot_loader start=$0700 end=$087F type=code
define_segment name=main_code start=$0C00 end=$1CFF type=code
disassemble offset=$0700 numBytes=384 format=ca65 analyze=true
generate_linker_config output=game.cfg
save_labels filePath=game.annotations.json

Sondagem de Dados

probe_data usa 7 heurísticas para identificar tipos de dados em faixas de memória:

  • Detecção de strings — Sequências imprimíveis ATASCII/ASCII, terminadas por $9B, terminadas por nulo
  • Detecção de preenchimento — Sequências de $00, $FF, $1A (EOL ATASCII)
  • Detecção de conjunto de caracteres — Blocos de 1024 bytes (128×8) e 512 bytes (64×8)
  • Detecção de tabelas — Tabelas de endereços de 2 bytes, tabelas de consulta de 1 byte
  • Detecção de lista de exibição — Opcodes de lista de exibição ANTIC com extração de LMS
  • Detecção de dados de sprite — Blocos alinhados de 8/16/32 bytes com análise de variedade de bytes
  • Detecção de dados de mapa — Padrões de grade 2D com comprimentos de linha consistentes

Cada resultado inclui um nível de confiança (Alto/Médio/Baixo) e detalhes de suporte.

Fluxo de Trabalho Típico

Exploração básica

  1. Carregue um arquivo com load_rom, load_atr_file ou load_atr_boot.
  2. Inspecione a estrutura com rom_info ou atr_info.
  3. Use hex_dump para examinar bytes brutos, find_strings para localizar texto.
  4. Desmonte com disassemble (modo básico).

Desmontagem orientada por análise

  1. load_rom → Carregue o binário.
  2. analyze_disassembly format=summary → Obtenha visão geral de código/dados.
  3. analyze_disassembly format=labels → Veja todos os rótulos gerados automaticamente.
  4. probe_data start=$1712 end=$1AD4 → Identifique regiões de dados.
  5. define_segment name=main_code start=$0C00 end=$1CFF type=code
  6. define_segment name=game_data start=$1D00 end=$BBA4 type=data
  7. disassemble offset=$0C00 numBytes=5376 format=ca65 analyze=true → Saída ciente de segmentos.
  8. generate_callgraph start=$1540 depth=5 format=mermaid → Visualize a estrutura.
  9. Itere: define_symbol → disassemble analyze=true → revise.

Fluxo de trabalho de refinamento iterativo

  1. load_rom → desmontagem inicial com rótulos automáticos.
  2. analyze_disassembly → identifique regiões de código/dados.
  3. define_symbol → anote endereços-chave.
  4. define_segment → marque regiões de código/dados.
  5. save_labels → persista anotações.
  6. disassemble analyze=true → re-desmonte com anotações.
  7. Revise, repita os passos 3-6 conforme necessário.

Fluxo de trabalho de modificação de ATR

  1. create_atr output=build/disk.atr sectors=720 density=sd → disco em branco.
  2. write_atr_sector filePath=build/disk.atr sector=1 input=boot.bin → grave setor de boot.
  3. write_atr_file filePath=build/disk.atr name=AGENT.OBJ input=build/AGENT.OBJ → adicione arquivo.
  4. extract_atr_file filePath=game.atr name=AGENT.OBJ output=extracted/AGENT.OBJ → extraia arquivo.
  5. inject_atr_file filePath=game.atr name=AGENT.OBJ input=build/AGENT.OBJ → substitua arquivo.

Persistência

Símbolos definidos pelo usuário, anotações de zero-page e definições de segmentos são salvos automaticamente em um arquivo JSON auxiliar ao lado do alvo carregado:

<rom-or-synthetic-path>.atarihacker.json

O formato auxiliar v4 inclui:

  • Campo de versão para compatibilidade futura
  • Hash SHA-256 da ROM para verificação de integridade
  • Segmentos (nome, tipo, início, fim, comentário)
  • Definições de sistema de arquivos personalizados

Arquivos auxiliares v3 (sem campo de versão) são lidos de forma transparente e atualizados ao salvar.

Exemplo de Teste Rápido MCP

Isso envia initialize e tools/list diretamente via stdio:

(
  printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0"}}}\n'
  sleep 0.2
  printf '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n'
  sleep 1
) | dotnet run --no-build

Notas

  • Logs são gravados em stderr para que stdout permaneça limpo para tráfego JSON-RPC MCP.
  • A ferramenta disassemble com analyze=false (padrão) se comporta exatamente como na v3 — compatibilidade total com versões anteriores.
  • Código automodificável e despacho por tabela de saltos (JMP (table,X)) não podem ser resolvidos estaticamente; use define_segment para marcar essas regiões manualmente.
  • Para detalhes completos do design, consulte docs/version4-design.md e a especificação v4.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para detalhes.