Ryan Malloy
170eba0843
MCP server for AI-assisted debugging of DOS binaries via GDB protocol. Features: - GDB remote protocol client for DOSBox-X debugging - 16 debugging tools: launch, attach, breakpoint management, registers, memory read/write, disassemble, step, continue, etc. - Docker container with DOSBox-X for consistent environment - Support for DOS segment:offset addressing - Comprehensive test suite (49 tests) Primary use case: Reverse engineering the unpublished Bezier algorithm in RIPTERM.EXE for the RIPscrip graphics protocol project.
204 lines
5.0 KiB
Markdown
204 lines
5.0 KiB
Markdown
# DOSBox-X MCP Server
|
|
|
|
AI-assisted debugging of DOS binaries via the Model Context Protocol (MCP).
|
|
|
|
This MCP server enables Claude to programmatically debug DOS programs running in DOSBox-X by providing tools for:
|
|
|
|
- Setting breakpoints
|
|
- Reading/writing registers and memory
|
|
- Stepping through code
|
|
- Tracing execution
|
|
|
|
## Primary Use Case
|
|
|
|
**Reverse engineering classic DOS programs** - specifically, tracing the unpublished Bezier curve algorithm in RIPTERM.EXE for the RIPscrip graphics protocol research project.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.11+
|
|
- [uv](https://github.com/astral-sh/uv) package manager
|
|
- Docker (for DOSBox-X container)
|
|
- X11 display (for DOSBox GUI)
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/yourusername/dosbox-mcp.git
|
|
cd dosbox-mcp
|
|
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Build Docker image
|
|
make build
|
|
|
|
# Create DOS directory
|
|
make init
|
|
```
|
|
|
|
### Running
|
|
|
|
```bash
|
|
# Allow X11 access for Docker
|
|
xhost +local:docker
|
|
|
|
# Start DOSBox-X
|
|
make up
|
|
|
|
# Register MCP server with Claude Code
|
|
make register
|
|
```
|
|
|
|
### Usage with Claude
|
|
|
|
Once registered, Claude can use these tools:
|
|
|
|
```
|
|
# Launch DOSBox-X with a binary
|
|
launch("/path/to/GAME.EXE")
|
|
|
|
# Connect to debugger
|
|
attach("localhost", 1234)
|
|
|
|
# Set a breakpoint
|
|
breakpoint_set("1234:0100")
|
|
|
|
# Run until breakpoint
|
|
continue_execution()
|
|
|
|
# Read registers
|
|
registers()
|
|
|
|
# Read memory
|
|
memory_read("DS:0100", 64)
|
|
|
|
# Step through code
|
|
step(10)
|
|
|
|
# Clean up
|
|
quit()
|
|
```
|
|
|
|
## Tools Reference
|
|
|
|
### Execution Control
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `launch` | Start DOSBox-X with optional binary |
|
|
| `attach` | Connect to GDB stub |
|
|
| `continue_execution` | Run until breakpoint |
|
|
| `step` | Step N instructions |
|
|
| `step_over` | Step over CALL instructions |
|
|
| `quit` | Stop DOSBox-X |
|
|
|
|
### Breakpoints
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `breakpoint_set` | Set breakpoint at address |
|
|
| `breakpoint_list` | List all breakpoints |
|
|
| `breakpoint_delete` | Remove breakpoint(s) |
|
|
|
|
### Inspection
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `registers` | Read all CPU registers |
|
|
| `memory_read` | Read memory region |
|
|
| `memory_write` | Write to memory |
|
|
| `disassemble` | Simple disassembly view |
|
|
| `stack` | Dump stack contents |
|
|
| `status` | Get debugger status |
|
|
|
|
### Address Formats
|
|
|
|
The server supports multiple address formats:
|
|
|
|
- **Segment:offset**: `1234:5678` (standard DOS format)
|
|
- **Flat hex**: `0x12345` or `12345h`
|
|
- **Decimal**: `#65536`
|
|
- **Register-based**: `DS:SI`, `CS:IP`
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ Claude Code │────▶│ DOSBox-X MCP │────▶│ DOSBox-X │
|
|
│ │ MCP │ Server │ GDB │ (GDB stub) │
|
|
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────┐
|
|
│ GDB Remote │
|
|
│ Protocol │
|
|
│ (TCP :1234) │
|
|
└──────────────────┘
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run tests
|
|
make test
|
|
|
|
# Lint code
|
|
make lint
|
|
|
|
# Format code
|
|
make format
|
|
|
|
# View logs
|
|
make logs
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
dosbox-mcp/
|
|
├── src/dosbox_mcp/
|
|
│ ├── server.py # FastMCP server (tools)
|
|
│ ├── gdb_client.py # GDB protocol client
|
|
│ ├── dosbox.py # DOSBox-X management
|
|
│ ├── types.py # Type definitions
|
|
│ └── utils.py # Utilities
|
|
├── tests/
|
|
├── examples/
|
|
├── Dockerfile # DOSBox-X with GDB
|
|
└── docker-compose.yml
|
|
```
|
|
|
|
## Technical Details
|
|
|
|
### GDB Remote Protocol
|
|
|
|
This server implements a client for the [GDB Remote Serial Protocol](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Remote-Protocol.html), which provides:
|
|
|
|
- Register read/write (`g`, `G`, `p`, `P`)
|
|
- Memory read/write (`m`, `M`)
|
|
- Software breakpoints (`Z0`, `z0`)
|
|
- Execution control (`c`, `s`, `?`)
|
|
|
|
### Real Mode Addressing
|
|
|
|
DOS uses real mode with segment:offset addressing:
|
|
|
|
```
|
|
Physical Address = (Segment << 4) + Offset
|
|
```
|
|
|
|
This gives a 20-bit address space (1MB), though only 640KB is conventional memory.
|
|
|
|
## Related Projects
|
|
|
|
- [RIPscrip Research](../rpmesh/) - Parent project for RIPscrip graphics protocol
|
|
- [dosbox-x-gdb](https://github.com/hezi/dosbox-x-gdb) - DOSBox-X fork with GDB support
|
|
- [FastMCP](https://gofastmcp.com/) - MCP server framework
|
|
|
|
## License
|
|
|
|
MIT License
|