# 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