AtariHackerMCP

A local MCP server for reverse-engineering Atari 8-bit binaries and ATR disk images.

Requirements

• .NET SDK 10.0+

• Linux, macOS, or Windows

Build

Restore packages and compile:

dotnet build

Publish a release build if needed:

dotnet publish -c Release -o publish

Run

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

For local testing:

dotnet run --no-build

Or run the published executable:

./publish/AtariHackerMCP

MCP Client Configuration

Example stdio server entry:

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

If you prefer using a published build:

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

Available Tools

File and disk tools

• load_rom

• rom_info

• atr_info

• atr_header

• load_atr_file

• load_atr_boot

• list_atr_directory

• analyze_boot_sector

• sector_dump

• search_boot_sector

Inspection and disassembly

• hex_dump

• disassemble

Utility tools

• calculate

• hex_to_decimal

• decimal_to_hex

Symbol and zero-page tools

• define_symbol

• remove_symbol

• lookup_symbol

• list_symbols

• annotate_zero_page

• show_zero_page_map

Analysis tools

• x_ref

• find_pattern

• find_strings

• trace_control_flow

Typical Workflow

1. Load a file with load_rom, load_atr_file, or load_atr_boot.

2. Inspect structure with rom_info or atr_info.

3. For ATR disk images: use atr_header for container metadata, list_atr_directory for DOS file listings, analyze_boot_sector to decode the boot header, sector_dump to inspect raw sectors, and search_boot_sector to compare boot code across images.

4. Review bytes with hex_dump.

5. Decode code with disassemble.

6. Add labels with define_symbol and annotate_zero_page.

7. Search with x_ref, find_pattern, find_strings, and trace_control_flow.

Persistence

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

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

This file is loaded automatically the next time the same target is opened.

Example MCP Smoke Test

This sends initialize and tools/list directly 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

Notes

• Logs are written to stderr so stdout remains clean for MCP JSON-RPC traffic.

• The current build may show a NuGet compatibility warning for NCalc, but the server builds and runs successfully.

License

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