https://github.com/richardkiss/6502_mcp
https://github.com/richardkiss/6502_mcp
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/richardkiss/6502_mcp
- Owner: richardkiss
- Created: 2025-07-13T23:16:39.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-07-13T23:16:42.000Z (3 months ago)
- Last Synced: 2025-08-17T00:46:43.360Z (about 2 months ago)
- Language: Python
- Size: 108 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 6502 MCP Server
An MCP (Model Context Protocol) server that provides tools for assembling, disassembling, and reverse engineering 6502 binary code. This server enables LLMs to work with 6502 binaries through a structured reverse engineering workflow.
## Quick Start
```bash
# Install uv and dependencies
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --dev
# Create and analyze a test binary
uv run python demo_cli.py create-test-binary test.bin
uv run python demo_cli.py workflow test.bin
# Or use interactive mode
uv run python demo_cli.py interactive
# Run the MCP server
uv run 6502-mcp-server
```
## Features
- **Disassembly**: Convert binary blobs to assembly code with configurable chunk sizes
- **Assembly**: Assemble 6502 code and verify byte-for-byte accuracy
- **Binary Comparison**: Compare assembled output with target binaries
- **Label Management**: Add and manage labels and comments in assembly code
- **Symbol Tables**: Extract and manage symbol tables
- **Hex Analysis**: Analyze binary data in hex format
- **Memory Layout**: Understand memory organization and addressing
## Reverse Engineering Workflow
The server supports a systematic reverse engineering approach:
1. **Initial Disassembly**: Disassemble binary chunks incrementally
2. **Assembly Verification**: Ensure each chunk assembles to identical binary
3. **Progressive Labeling**: Add labels and comments subroutine by subroutine
4. **Verification Loop**: Continuously verify assembly produces correct output
5. **Complete Reconstruction**: Build fully documented, readable assembly
## Installation
### Using uv (Recommended)
```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install the project and all dependencies (including py6502 from GitHub)
uv sync
# Or install in development mode
uv sync --dev
```
### Traditional pip
```bash
# Install in development mode
pip install -e .
# Or with development dependencies
pip install -e ".[dev]"
```
## Usage
### Demo CLI (Testing & Learning)
```bash
# Interactive mode (maintains state across commands)
uv run python demo_cli.py interactive
# Complete workflow demonstration
uv run python demo_cli.py create-test-binary test.bin
uv run python demo_cli.py workflow test.bin
```
### MCP Server (Production)
```bash
# Start the MCP server
uv run 6502-mcp-server
```
### Traditional Method
```bash
# Activate virtual environment (if using pip)
source .venv/bin/activate
# Run demo CLI or MCP server
python demo_cli.py interactive
6502-mcp-server
```
## Tools Provided
- `load_binary`: Load a binary file to begin reverse engineering
- `disassemble_chunk`: Disassemble a specific chunk of binary data
- `assemble_code`: Assemble 6502 assembly code to binary
- `compare_binaries`: Compare two binary blobs for differences
- `add_label`: Add a label at a specific address
- `add_comment`: Add a comment to an assembly line
- `extract_symbols`: Extract symbol table from assembly
- `analyze_hex`: Analyze hex data patterns
- `get_memory_layout`: Get memory layout information
- `find_subroutines`: Analyze code to identify potential subroutine boundaries
- `validate_assembly`: Verify assembly produces target binary
## Dependencies
- py6502: 6502 assembler, disassembler, and simulator library (from GitHub)
- mcp: Model Context Protocol framework
## Development
### Code Quality
```bash
# Lint and format code
uv run ruff check . # Check for issues
uv run ruff format . # Format code
uv run mypy src/ # Type checking
# Fix auto-fixable issues
uv run ruff check --fix .
```
### Testing
```bash
# Run all tests with pytest
uv run pytest
# Run tests with coverage
uv run pytest --cov=src --cov-report=html
# Quick basic tests (no pytest required)
uv run python run_tests.py
```