AtariHackerMCP

A local MCP server for reverse-engineering Atari 8-bit binaries and ATR disk images. Supports multi-pass disassembly analysis, code/data separation, segment-aware output, ATR file injection, batch scripting, and a comprehensive Atari hardware symbol table.

This server uses MCP stdio transport, so it is normally launched by an MCP client rather than run interactively.

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

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

- load_rom— Load a ROM/XEX binary into the current session
- rom_info— Display structural info about the loaded binary
- atr_info— Display structural info about an ATR disk image
- atr_header— Display the ATR header fields for a disk image
- load_atr_file— Extract a file from an ATR and load it into the session
- load_atr_boot— Extract boot sectors from an ATR and load them at $0700
- list_atr_directory— List the DOS directory of an ATR disk image
- analyze_boot_sector— Decode the boot sector header from an ATR
- sector_dump— Hex dump sectors from an ATR by logical sector number
- search_boot_sector— Scan boot sectors across multiple ATRs for patterns/differences
- extract_atr_file— Extract a file from an ATR and save it to disk
- inject_atr_file— Inject a file into an ATR (copy-on-write)
- create_atr— Create a new ATR disk image from scratch
- write_atr_sector— Write raw data to a specific sector of an ATR
- write_atr_file— Write a file to an ATR with directory entry creation
- define_filesystem— Define a custom filesystem layout for non-DOS ATRs

- hex_dump— Produce a hex dump with file offsets, memory addresses, and ASCII
- disassemble— Disassemble 6502 code with optional multi-pass analysis (analyze=true)

- Supports formats:listing,ca65,atasm,mac65
- Whenanalyze=true: generates meaningful labels (sub_XXXX,data_XXXX,jmp_XXXX), code/data separation, segment-aware.segment/.proc/.endprocoutput, ATASCII string formatting, procedure header comments

- Formats:summary,graph,labels,full

- x_ref— Find cross-references to an address in the ROM
- find_pattern— Search for a byte pattern with wildcards
- find_strings— Search for runs of printable ASCII or ATASCII characters
- trace_control_flow— Statically trace execution from a starting address
- probe_data— Analyze a memory range to identify data type (text, graphics, table, charset, display list, sprite data, map data) with confidence scoring
- generate_callgraph— Generate a call graph showing subroutine relationships (Mermaid or text format)
- analyze_coverage— Analyze code coverage: which bytes are executed vs. data
- diff_roms— Compare two ROM or ATR files (summary, verbose, or hex diff format)

- define_symbol— Add or update a named label for a memory address
- remove_symbol— Remove a user-defined symbol
- lookup_symbol— Look up the symbol entry for an address
- list_symbols— List symbols in the symbol table
- set_symbols— Enable/disable symbol groups (hardware, OS variables, OS ROM, user labels) to control which names appear in disassembly
- load_labels— Load labels and segments from a sidecar file
- save_labels— Save current labels and segments to a sidecar file
- annotate_zero_page— Add or update a zero-page annotation
- show_zero_page_map— Display current zero-page annotations

- run_script— Execute a sequence of commands from a script file (supports 33 commands)

- calculate— Evaluate mathematical expressions with hex literals ($prefix)
- hex_to_decimal— Convert hex to decimal
- decimal_to_hex— Convert decimal to hex

Whenanalyze=trueis passed todisassemble, the engine performs three passes:
- Pass 1 — Reference Collection: Scans all instruction boundaries across the ROM, recording JSR targets, JMP targets, branch targets, indirect jump targets, and absolute/indirect data references into aReferenceGraph.
- Pass 2 — Code Region Tracing: Starting from each code entry point, traces execution flow (following JSR, JMP, branches, stopping at RTS/RTI/BRK) to mark bytes as code or data.
- Pass 3 — Label Generation: Produces meaningful labels (sub_XXXX,jmp_XXXX,data_XXXX,L_XXXX) with proper priority ordering (user > subroutine > data > hardware > OS > branch).

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

The built-in symbol table covers over 200 entries across all major Atari components:

Symbol groups can be toggled withset_symbolsto avoid conflicts when user code overlaps OS address ranges.

The ATR write subsystem provides copy-on-write disk image modification:

Therun_scripttool executes sequences of commands from text files:

# 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

probe_datauses 7 heuristics to identify data types in memory ranges:

- String detection— ATASCII/ASCII printable runs,$9B-terminated, null-terminated
- Padding detection— Runs of$00,$FF,$1A(ATASCII EOL)
- Character set detection— 1024-byte (128×8) and 512-byte (64×8) blocks
- Table detection— 2-byte address tables, 1-byte lookup tables
- Display list detection— ANTIC display list opcodes with LMS extraction
- Sprite data detection— 8/16/32-byte aligned blocks with byte variety analysis
- Map data detection— 2D grid patterns with consistent row lengths

Each result includes a confidence level (High/Medium/Low) and supporting details.
- Load a file withload_rom,load_atr_file, orload_atr_boot.
- Inspect structure withrom_infooratr_info.
- Usehex_dumpto examine raw bytes,find_stringsto locate text.
- Disassemble withdisassemble(basic mode).
- load_rom→ Load the binary.
- analyze_disassembly format=summary→ Get code/data overview.
- analyze_disassembly format=labels→ View all auto-generated labels.
- probe_data start=$1712 end=$1AD4→ Identify data regions.
- define_segment name=main_code start=$0C00 end=$1CFF type=code
- define_segment name=game_data start=$1D00 end=$BBA4 type=data
- disassemble offset=$0C00 numBytes=5376 format=ca65 analyze=true→ Segment-aware output.
- generate_callgraph start=$1540 depth=5 format=mermaid→ Visualize structure.
- Iterate:define_symbol→disassemble analyze=true→ review.
- load_rom→ initial disassembly with auto-labels.
- analyze_disassembly→ identify code/data regions.
- define_symbol→ annotate key addresses.
- define_segment→ mark code/data regions.
- save_labels→ persist annotations.
- disassemble analyze=true→ re-disassemble with annotations.
- Review, repeat steps 3-6 as needed.
- create_atr output=build/disk.atr sectors=720 density=sd→ blank disk.
- write_atr_sector filePath=build/disk.atr sector=1 input=boot.bin→ write boot sector.
- write_atr_file filePath=build/disk.atr name=AGENT.OBJ input=build/AGENT.OBJ→ add file.
- extract_atr_file filePath=game.atr name=AGENT.OBJ output=extracted/AGENT.OBJ→ extract file.
- inject_atr_file filePath=game.atr name=AGENT.OBJ input=build/AGENT.OBJ→ replace file.

User-defined symbols, zero-page annotations, and segment definitions are saved automatically to a sidecar JSON file next to the loaded target:

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

- Version field for forward compatibility
- SHA-256 ROM hash for integrity checking
- Segments (name, type, start, end, comment)
- Custom filesystem definitions

v3 sidecar files (without version field) are read transparently and upgraded on save.

This sendsinitializeandtools/listdirectly over 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

- Logs are written to stderr so stdout remains clean for MCP JSON-RPC traffic.
- Thedisassembletool withanalyze=false(default) behaves exactly as in v3 — full backward compatibility.
- Self-modifying code and jump table dispatch (JMP (table,X)) cannot be resolved statically; usedefine_segmentto mark those regions manually.
- For full design details, seedocs/version4-design.mdand thev4 specification.

This project is licensed under the MIT License. See theLICENSEfile for details.

Real-time stock heatmaps and investment tools delivered as interactive React components.