MCP Integration

Regenerator 2000 supports the Model Context Protocol (MCP), allowing AI agents like Antigravity, Claude Code, and others to interact directly with your analysis project.

Through the MCP server, an AI assistant can:

Read disassembly, memory dump, and project state.
Modify comments, labels, and block types.
Navigate move cursor.
Analyze code structure and control flow.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI models to interact with local applications and contexts. Learn more at modelcontextprotocol.io.

Modes of Operation

Regenerator 2000 supports two MCP transport modes:

HTTP Mode (Streamable/SSE):
Runs the MCP server over HTTP using Server-Sent Events (SSE).
Allows concurrent TUI usage (User + AI working together).
Flag: --mcp-server (starts TUI + Server on port 3000)
Flag: --mcp-server --headless (starts Headless Server on port 3000)
Endpoint: http://127.0.0.1:3000/mcp
Recommended option!
Stdio Mode (Headless):
Starts a headless instance of Regenerator 2000.
Ideal for local assistants (e.g., Claude Desktop, Claude Code) that spawn the server as a subprocess.
Flag: --mcp-server-stdio, implies --headless.
Experimental mode, mostly used for testing.

Configuration

1. Start the Server

Before connecting any client, you must start Regenerator 2000 with MCP Server enabled. This opens the TUI and starts the HTTP server, allowing you to use the interface while the AI interacts with it.

# Open your project with the server enabled
regenerator2000 --mcp-server your_project.regen2000proj

The server will listen on http://127.0.0.1:3000/mcp by default.

2. Configure Client

Tip

Ensure the regenerator2000 application is running with --mcp-server before you start Claude Code or Antigravity as they will attempt to connect on startup.

Claude Code

To use Regenerator 2000 with Claude Code:

claude mcp add -t http regenerator2000 http://127.0.0.1:3000/mcp

Or, alternatively, add the following to your claude.json:

{
  "mcpServers": {
    "regenerator2000": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Antigravity CLI

To use Antigravity CLI with the running server, simply provide the URL to the connect command or configuration:

# Example connection command
agy mcp add regenerator2000 http://127.0.0.1:3000/mcp --scope user -t http

Or, alternatively, add the following to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "regenerator2000": {
      "serverUrl": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Accept": "application/json, text/event-stream",
        "Content-Type": "application/json"
      }
    }
  }
}

Common Workflows

The true power of the MCP server comes from combining the AI's semantic understanding with Regenerator 2000's analysis tools.

1. Analyze a Routine

Goal: Understand what a specific subroutine does, rename variables, and document it.

Prompt

"Analyze the routine at $C000. It seems to be checking sprite collisions. Rename variables accordingly and add comments explaining the logic."

What happens: The AI reads the disassembly at $C000, follows the code flow, identifies memory accesses (e.g., $D01E for sprite collision), and uses r2000_set_label_name and r2000_set_comment to update your project.

2. Identify Code vs. Data

Goal: You have a large binary and don't know where the code ends and graphics begin.

Prompt

"Scan the region from $2000 to $4000. Identify any valid code sequences and mark the rest as byte data. If you see patterns resembling text, mark them as PETSCII."

What happens: The AI uses r2000_read_region or r2000_get_blocks to inspect the memory. It then iteratively applies r2000_set_data_type with "data_type": "code" or "byte" based on its analysis.

3. Trace Cross-References

Goal: Find everywhere a specific global variable or function is used.

Prompt

"Find all JSR $FFD2 (CHROUT) calls. For each call, document what character or value is being printed before the call."

What happens: The AI queries r2000_get_cross_references for $FFD2, then inspects the instructions immediately preceding each call to deduce the arguments (e.g., LDA #$05).

Goal: Move around the project using natural language descriptions instead of addresses.

Prompt

"Jump to the high score table."

"Go to the interrupt handler."

What happens: The AI searches the symbol table or analyzes the code to find the likely candidate, then uses r2000_jump_to_address to move your viewport.

Agent Skills

Skills are reusable instruction sets that guide the AI through complex, multi-step tasks. They live in your project's .agent/skills/ directory and are automatically discovered by compatible AI agents (e.g., Antigravity).

Installation

To install all available skills at once, run:

cp -r .agent/skills/r2000* /path/to/your/project/.agent/skills/

The resulting layout should look like:

your_project/
└── .agent/
    └── skills/
        └── r2000-analyze-blocks/   (or whichever skill you copied)
            └── SKILL.md

Claude Code users

Claude Code looks for skills in .claude/ rather than .agent/. A symlink is the easiest fix:

ln -s .agent .claude

This lets both Antigravity and Claude Code discover the same skills without duplicating files.

Recommended Workflow

For the best results, we recommend applying these skills in the following order:

Macro Analysis: Use r2000-analyze-blocks to break down the binary into code and data regions.
Micro Analysis (Control Flow): Use r2000-analyze-routine to understand the logic of individual subroutines.
Micro Analysis (Data Flow): Use r2000-analyze-symbol to identify variables, pointers, and hardware registers.

Or, use r2000-analyze-program to run all three steps automatically in the correct order, with parallel subagents for throughput.

Skill: `r2000-analyze-program`

Orchestrates a full end-to-end analysis of the loaded binary. Runs block classification first, then launches parallel subagents to analyze every unanalyzed subroutine and data symbol.

What it does:

Phase 0 — Gather Context: Collects binary info, existing blocks, all symbols, and line comments.
Phase 1 — Classify Blocks: Runs r2000-analyze-blocks to classify all memory regions (code, data, text, tables), then refreshes state.
Phase 2 — Analyze Routines: Identifies unanalyzed subroutines — s_XXXX labels, JSR targets without a line comment, p_XXXX labels inside Code blocks (pointer-to-code, e.g. chained IRQ handlers), and the start entry point. Launches a rolling window of up to 10 parallel subagents, each running r2000-analyze-routine. As each subagent completes, the next routine is immediately launched into the freed slot.
Phase 3 — Analyze Symbols: Identifies unanalyzed data symbols — auto-generated names with prefixes zpp_, zpf_, zpa_ (zero page) and p_, f_, a_ (non-zero page). Excludes s_ (routines, handled in Phase 2), b_ ( branches), e_ (external targets), and p_ labels in Code blocks (handled as routines in Phase 2). Launches up to 10 parallel subagents, each running r2000-analyze-symbol to classify and rename one symbol.
Phase 4 — Save & Report: Saves the project and produces a summary report with tables of all routines analyzed, symbols renamed, and any uncertain items flagged for manual review.

Prompt

"Analyze this program", "Full analysis", "Analyze everything"

Skill: `r2000-analyze-blocks`

Scans a memory range (or the entire binary) and converts each region to the correct block type — separating code from data, text from tables, and pointers from raw bytes. This is the foundational reverse-engineering pass you run on a freshly loaded binary.

What it does:

Determines the scope (user-specified range or full binary via r2000_get_binary_info).
Reads existing block classifications with r2000_get_blocks.
Performs multiple passes: traces code from entry points, identifies text strings, detects data tables, and classifies remaining regions.
Applies conversions in batches using r2000_batch_execute for efficiency.
Uses r2000_toggle_splitter to correctly separate adjacent tables of the same type.
Optionally labels and comments notable regions (entry points, strings, jump tables).
Reports a summary of all blocks found and flags ambiguous regions for human review.

Supported block types: Code, Byte, Word, Address, PETSCII Text, Screencode Text, Lo/Hi Address, Hi/Lo Address, Lo/Hi Word, Hi/Lo Word, External File, Undefined.

Prompt

"Analyze blocks", "Convert blocks", "Identify data regions", "Classify the program"

Skill: `r2000-analyze-routine`

Analyzes a disassembly subroutine to determine its purpose by examining code, cross-references, and memory usage.

What it does:

Identifies the bounds of the routine (entry point → RTS/JMP/RTI).
Reads and interprets the instructions, detecting loops, KERNAL calls, and hardware register accesses.
Checks cross-references to understand the call context.
Analyzes data usage (Zero Page variables, hardware registers, etc.).
Synthesizes a summary of purpose, inputs, outputs, and side effects.
Optionally documents the routine by adding a structured comment block above the entry point and renaming the label.

Prompt

"Analyze this routine", "What does this function do?"

Skill: `r2000-analyze-symbol`

Analyzes a specific memory address or label to determine its purpose (variable, flag, pointer, hardware register) by examining its cross-references and usage patterns.

What it does:

Determines the target address/label and the system (C64, VIC-20, etc.).
Checks if the address corresponds to a known hardware register.
Analyzes all cross-references to see how the symbol is used (read, write, modify).
Identifies patterns: Pointers (indirect indexed), Flags (boolean checks), Counters (loops), State variables.
Renames the symbol to a descriptive name (snake_case for variables, CapsExpr for hardware/constants).
Adds comments using r2000_set_comment (type "line" for definitions, type "side" for usages) to document the data flow.

Prompt

"Analyze this label", "What is this variable?", "Trace this address"

Available Tools

The server currently exposes 28 tools.

`r2000_add_scope`

Adds a scope covering the specified memory range. Useful for a piece of code that is a routine. Starts a lexical level where all new symbols within this range are in the local lexical level and are accessible from outside only via explicit scope specification. Nested scopes are not supported.

Arguments:

Name	Type	Description	Required
`end_address`	`integer`	End address of the scope (inclusive), decimal.	Yes
`start_address`	`integer`	Start address of the scope (inclusive), decimal.	Yes

`r2000_apply_enum_usage`

Applies an enum definition to format the immediate operand or constant reference at a specific address. If name is omitted or empty, clears the enum usage.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The target instruction address (decimal).	Yes
`name`	`string`	The unique name of the enum to apply (e.g., 'vic_registers'). Omit or send empty to clear.	No

`r2000_batch_execute`

Executes multiple tool calls sequentially in a single request. Use only when you have 5+ independent operations to perform at once (e.g. marking many regions, renaming many labels). Do not use for operations that depend on each other's results.

Arguments:

Name	Type	Description	Required
`calls`	`array`	List of tool calls to execute sequentially.	Yes

`r2000_create_project_enum`

Creates a new project-specific enum definition embedded in the project file.

Arguments:

Name	Type	Description	Required
`description`	`string`	Optional summary explaining the enum's purpose.	No
`name`	`string`	Unique alphanumeric identifier.	Yes
`variants`	`object`	Variant mapping where keys are numeric strings (decimal, hex 0x/$, bin 0b/%) and values are variant names.	Yes

`r2000_delete_project_enum`

Deletes a project-specific enum from the project.

Arguments:

Name	Type	Description	Required
`force`	`boolean`	If false, fails if the enum has active usages in the disassembly. Set to true to override.	No
`name`	`string`	The name of the enum to delete.	Yes

`r2000_disassemble`

Performs a control flow disassembly starting at a specific memory address, tracing execution paths and automatically converting identified regions to Code blocks.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The target start address for the disassembly flow analysis (decimal).	Yes

`r2000_get_address_details`

Returns detailed information about a specific memory address: instruction semantics, cross-references, labels, comments, and block type.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The memory address to inspect (decimal).	Yes

`r2000_get_binary_info`

Returns the origin address, size in bytes, target platform (e.g. 'Commodore 64'), filename, user-provided description, entropy of the binary (values higher than 7.5 suggest the binary might be compressed), and whether the binary may contain undocumented opcodes (a hint, not guaranteed).

No arguments.

`r2000_get_blocks`

Returns all memory blocks with their address range and type (Code, Byte, Word, Address, PETSCII, Screencode, Lo/Hi Address, Hi/Lo Address, Lo/Hi Word, Hi/Lo Word, External File, Undefined). Respects splitters.

Arguments:

Name	Type	Description	Required
`block_type`	`string`	Optional filter to return only blocks of a specific type. Case-insensitive.	No

`r2000_get_comments`

Returns user-defined comments and their addresses. Each entry has 'address' (integer), 'type' ('line' or 'side'), and ' comment' (string). With no arguments returns ALL comments. Provide optional filters to narrow results: 'addresses' returns comments at specific addresses, 'start_address'/'end_address' limits to an address range, 'type' filters by comment type. Filters are combined (AND logic).

Arguments:

Name	Type	Description	Required
`addresses`	`array`	Optional list of specific addresses (decimal) to retrieve comments from. Only comments at these addresses are returned.	No
`end_address`	`integer`	Optional upper bound (inclusive) of the address range to filter by (decimal).	No
`start_address`	`integer`	Optional lower bound (inclusive) of the address range to filter by (decimal).	No
`type`	`string`	Optional filter to return only 'line' comments or only 'side' comments.	No

`r2000_get_cross_references`

Get a list of addresses that reference the given address (e.g. JSRs, JMPs, loads).

Arguments:

Name	Type	Description	Required
`address`	`integer`	The target address to find references to (decimal).	Yes

`r2000_get_disassembly_cursor`

Returns the memory address of the current cursor position in the disassembly view.

No arguments.

`r2000_get_symbols`

Returns defined labels (user and/or platform) and their addresses. With no arguments returns ALL symbols. Provide optional filters to narrow results: 'names' resolves specific label names to addresses, 'start_address'/'end_address' limits to an address range, 'kind' filters by label kind. Filters are combined (AND logic).

Arguments:

Name	Type	Description	Required
`end_address`	`integer`	Optional upper bound (inclusive) of the address range to filter by (decimal).	No
`kind`	`string`	Optional filter to return only labels of a given kind. 'user' = user-defined labels, 'system' = predefined system labels (e.g. KERNAL, hardware registers), 'auto' = auto-generated labels (e.g. s_C000).	No
`names`	`array`	Optional list of label names to look up. Only symbols whose name matches one of these strings are returned. Case-sensitive.	No
`start_address`	`integer`	Optional lower bound (inclusive) of the address range to filter by (decimal).	No

`r2000_jump_to_address`

Moves the disassembly cursor to a specific memory address and scrolls the view to make it visible. Also keeps the jump history.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The target address to jump to (decimal).	Yes

`r2000_read_region`

Get disassembly or hexdump text for a specific memory range.

Arguments:

Name	Type	Description	Required
`end_address`	`integer`	End address (inclusive), decimal.	Yes
`start_address`	`integer`	Start address (inclusive), decimal.	Yes
`view`	`string`	The view to return. Default: 'disasm'.	No

`r2000_read_selected`

Get disassembly or hexdump for the range currently selected in the UI. If nothing is selected, returns the instruction/row under the cursor.

Arguments:

Name	Type	Description	Required
`view`	`string`	The view to return. Default: 'disasm'.	No

`r2000_redo`

Redoes the latest undone operation.

No arguments.

`r2000_save_project`

Saves the current project state to the existing .regen2000proj file. Only works if the project was previously loaded from or saved to a project file.

No arguments.

`r2000_search_disassembly`

Search the disassembly text for a query string or regular expression. Returns a list of matching addresses with context (label, mnemonic, operand, comment). Searches labels, comments, and instructions by default; individual fields can be disabled.

Arguments:

Name	Type	Description	Required
`max_results`	`integer`	Maximum number of matching addresses to return. Defaults to 50.	No
`query`	`string`	The search query. Interpreted as a plain case-insensitive substring by default, or as a regex when 'use_regex' is true.	Yes
`search_comments`	`boolean`	Include side and line comments in the search. Defaults to true.	No
`search_instructions`	`boolean`	Include mnemonic and operand text in the search. Defaults to true.	No
`search_labels`	`boolean`	Include label names in the search. Defaults to true.	No
`use_regex`	`boolean`	When true the query is compiled as a case-insensitive regular expression ((?i) is prepended automatically). Defaults to false.	No

`r2000_search_memory`

Search for a sequence of bytes or a text string in the memory. Returns a list of addresses where the sequence is found.

Arguments:

Name	Type	Description	Required
`encoding`	`string`	Encoding for the query. 'text' searches both PETSCII and Screencode. 'hex' for raw byte patterns. Defaults to 'hex' if query looks like hex bytes, otherwise 'text'.	No
`query`	`string`	The search query. For hex: space-separated bytes, e.g. 'A9 00'. For text: plain string.	Yes

`r2000_set_comment`

Adds a comment at a specific address. 'line' comments appear on their own line before the instruction (supports multi-line). 'side' comments appear inline on the same line as the instruction.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The memory address for the comment (decimal, e.g. 4096 for $1000).	Yes
`comment`	`string`	The comment text. Do not include the ';' prefix.	Yes
`type`	`string`	'line' = comment on its own line before the instruction. 'side' = inline comment on the same line.	Yes

`r2000_set_data_type`

Sets the data type for a memory region. Use this to mark regions as code, bytes, addresses, text, split tables, etc.

Arguments:

Name	Type	Description	Required
`data_type`	`string`	code=MOS 6502 instructions; byte=raw 8-bit data (sprites, charset, tables, unknowns); word=16-bit LE values; address=16-bit LE pointers (creates X-Refs, use for jump tables/vectors); petscii=PETSCII text; screencode=Screen code text (data written to $0400); lo_hi_address=split address table, low bytes first then high bytes (even count required); hi_lo_address=split address table, high bytes first (even count required); lo_hi_word=split word table, low bytes first (e.g. SID freq tables); hi_lo_word=split word table, high bytes first; external_file=large binary blob (SID, bitmap, charset) to export as-is; undefined=reset region to unknown state.	Yes
`end_address`	`integer`	End of the memory region (inclusive), decimal.	Yes
`start_address`	`integer`	Start of the memory region (inclusive), decimal.	Yes

`r2000_set_immediate_format`

Sets the display format for immediate values (operands) at a specific address. Supports hexadecimal, decimal, binary, and Low/High byte references to a 16-bit address.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The address of the instruction (decimal).	Yes
`format`	`string`	hex=$00, decimal=0, binary=%00000000, low_byte=#p_ADDRESS.	Yes
`target_address`	`integer`	The 16-bit target address decimal (e.g. 60000 for $EA31). Required when format is 'low_byte' or 'high_byte'.	No

`r2000_set_label_name`

Sets a user-defined label at a specific MOS 6502 memory address. Use this to name functions, variables, or jump targets to make the disassembly more readable.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The memory address where the label should be set (decimal, e.g. 4096 for $1000).	Yes
`name`	`string`	The label name (e.g. 'init_screen', 'loop_start').	Yes

`r2000_toggle_splitter`

Toggles a Splitter at a specific address. Splitters prevent the auto-merger from combining adjacent blocks of the same type. Crucial for separating adjacent Lo/Hi table halves.

Arguments:

Name	Type	Description	Required
`address`	`integer`	The memory address where the splitter should be toggled (decimal).	Yes

`r2000_undo`

Undoes the latest operation.

No arguments.

`r2000_unpack_binary`

Unpacks the currently loaded binary. WARNING: This is a DESTRUCTIVE action! All existing comments, labels, and blocks will be completely deleted, as the project starts from scratch with the new unpacked binary. Unpacking may take up to 10 seconds or more.

No arguments.

`r2000_update_project_enum`

Updates or renames an existing project-specific enum.

Arguments:

Name	Type	Description	Required
`description`	`string`	Optional updated summary explaining the enum's purpose.	No
`name`	`string`	Existing name of the enum to update.	Yes
`new_name`	`string`	Optional new name if renaming the enum.	No
`variants`	`object`	Optional complete updated variants mapping.	No

MCP Integration

Modes of Operation

Configuration

1. Start the Server

2. Configure Client

Claude Code

Antigravity CLI

Common Workflows

1. Analyze a Routine

2. Identify Code vs. Data

3. Trace Cross-References

4. Semantic Navigation

Agent Skills

Installation

Recommended Workflow

Skill: r2000-analyze-program

Skill: r2000-analyze-blocks

Skill: r2000-analyze-routine

Skill: r2000-analyze-symbol

Available Tools

r2000_add_scope

r2000_apply_enum_usage

r2000_batch_execute

r2000_create_project_enum

r2000_delete_project_enum

r2000_disassemble

r2000_get_address_details

r2000_get_binary_info

r2000_get_blocks

r2000_get_comments

r2000_get_cross_references

r2000_get_disassembly_cursor

r2000_get_symbols

r2000_jump_to_address

r2000_read_region

r2000_read_selected

r2000_redo

r2000_save_project

r2000_search_disassembly

r2000_search_memory

r2000_set_comment

r2000_set_data_type

r2000_set_immediate_format

r2000_set_label_name

r2000_toggle_splitter

r2000_undo

r2000_unpack_binary

r2000_update_project_enum

Skill: `r2000-analyze-program`

Skill: `r2000-analyze-blocks`

Skill: `r2000-analyze-routine`

Skill: `r2000-analyze-symbol`

`r2000_add_scope`

`r2000_apply_enum_usage`

`r2000_batch_execute`

`r2000_create_project_enum`

`r2000_delete_project_enum`

`r2000_disassemble`

`r2000_get_address_details`

`r2000_get_binary_info`

`r2000_get_blocks`

`r2000_get_comments`

`r2000_get_cross_references`

`r2000_get_disassembly_cursor`

`r2000_get_symbols`

`r2000_jump_to_address`

`r2000_read_region`

`r2000_read_selected`

`r2000_redo`

`r2000_save_project`

`r2000_search_disassembly`

`r2000_search_memory`

`r2000_set_comment`

`r2000_set_data_type`

`r2000_set_immediate_format`

`r2000_set_label_name`

`r2000_toggle_splitter`

`r2000_undo`

`r2000_unpack_binary`

`r2000_update_project_enum`