DOSBox-X MCP Debugger

English | 繁體中文

An experimental MCP integration that lets AI agents inspect and control the native DOSBox-X debugger through a bounded, auditable tool interface.

The project is intended for DOS program debugging and reverse-engineering research, including investigation of legacy game data flows such as runtime text decoding, phrase composition, script execution, and rendering pipelines.

Why this project exists

Traditional AI-assisted debugging often requires a person to act as a manual relay:

1. the AI suggests a breakpoint or debugger action;

2. the person performs it in the GUI;

3. the person copies registers, memory, or disassembly back to the AI;

4. the process repeats one instruction at a time.

DOSBox-X MCP Debugger removes that relay. An agent can use native MCP tools to observe and control the same DOSBox-X debugger and guest CPU that a human sees, while every request remains bounded and traceable.

Related MCP server: gdb and rr Debugging

Architecture

flowchart LR
    A["AI agent"] -->|MCP over stdio| B["Bounded MCP server"]
    B --> C["DOSBoxClient"]
    C -->|TCP on 127.0.0.1:9876| D["Native AI bridge"]
    D --> E["DOSBox-X debugger and guest CPU"]

The project deliberately does not introduce:

• GUI automation;

• a second CPU emulator;

• a parallel breakpoint implementation;

• fabricated debugger state.

Breakpoints, stepping, execution control, register reads, memory reads, and disassembly are backed by the native DOSBox-X debugger mechanisms.

Agent-visible tools

This section covers the bounded Phase 5C research surface specifically (used for this project's own controlled acceptance testing). For the general-purpose, unbounded 37-tool surface a normal agent should actually connect to, see the AI Agent Usage Guide.

The current bounded Phase 5C surface exposes 12 tools:

get_cpu_state returns a register snapshot. It does not, by itself, prove that execution is stopped. Agents requiring running/stopped evidence must call get_debug_status.

Register and memory write capabilities are intentionally not exposed by the Phase 5C agent-facing MCP server.

Bounded sessions

Each bounded debugging session owns its own:

• allowed-tool policy;

• total-call budget;

• execution-operation budget;

• monotonic watchdog deadline;

• terminal state;

• machine-readable evidence log.

A rejected request must stop before DOSBoxClient, must not reach the native bridge, and must not change DOSBox-X state.

Current project status

Development has progressed through Phase 7 (see CHANGELOG.md for the full, phase-by-phase history, in English and Traditional Chinese together). The general-purpose, unbounded MCP surface described in the AI Agent Usage Guide -- 37 tools spanning debugger state, memory/registers, breakpoints (including byte-change memory watchpoints), execution control, keyboard/mouse input injection, frame capture, mouse capture and absolute positioning, input dispatch receipts, bounded execution tracing around a stop, and a DOS file I/O event log -- is the current, actively developed way to use this project. The bounded 12-tool Phase 5C surface described above under "Agent-visible tools" remains a separate, narrower research surface used only for this project's own controlled acceptance testing.

Capabilities added since the Phase 5C audit

Three native-bridge bugs found and fixed along the way, each documented in CHANGELOG.md: a Windows double-bind risk when two DOSBox-X instances listen on the same port, a debugger-console crash under piped/redirected stdio, and a command-line parsing bug where -defaultdir (used without its own path argument) could silently swallow the next option, including -break-start.

Every Phase 6/7 capability was verified live against a running dosbox-x.exe build as part of its own change -- see that phase's CHANGELOG.md entry and linked design doc for the specific test performed -- rather than through a single bulk regression suite.

Phase 5C result (formal bounded-agent acceptance audit)

The recurring C4 failure was narrow but meaningful: two independent fresh agents completed the intended breakpoint/run/register workflow, but used get_cpu_state as their final observation without independently confirming the stopped state through get_debug_status.

This result is preserved as a historical acceptance-audit snapshot rather than hidden or repeatedly rerun until a pass. It covers the bounded, 12-tool Phase 5C surface specifically -- the current 37-tool general-purpose surface did not exist yet at the time of this audit and has not itself been put through an equivalent formal acceptance process.

Regression evidence at the Phase 5C closeout

• Phase 5C deterministic suite: 23/23 passed

• Phase 5A live regression: 16/16 passed

• Phase 5B regression: 40/40 passed

• Offline debugger regression: 17/17 passed

The Phase 5C implementation checkpoint is commit 8357b435c39d5ad2e589bc611ce15f868fa78cdf.

Intended workflow

A typical reverse-engineering investigation is expected to look like this:

1. A human reproduces a target event in a DOS program or game.

2. The agent inspects the debugger and installs candidate breakpoints.

3. The human triggers the event when necessary.

4. The agent follows execution, memory, and disassembly through native MCP tools.

5. The session produces an evidence trace separating observations, inferences, and unresolved questions.

The first planned real-game proof-of-value pilot will investigate how one reproducible line of game text is formed before it reaches the renderer: as a complete string, a sequence of appended phrases, a token stream, or a template with runtime substitutions.

Repository layout

ai/                 MCP servers and DOSBox client integration
docs/               architecture, phase designs, and acceptance reports
tests/phase5a/       tool-awareness acceptance infrastructure
tests/phase5b/       bounded-autonomy acceptance infrastructure
tests/phase5c/       real-MCP transport and evidence tests
dosbox-src/          DOSBox-X Native AI Bridge fork, tracked as a git submodule

Getting started

dosbox-src is a git submodule pointing at pmanyeh/dosbox-x, branch ai-mcp-bridge, currently pinned at commit f27fb08fc0a1b831d8cad47a8bb134302ee7e762 (the Native AI Bridge, through Phase 7E, on top of an unmodified upstream DOSBox-X base). Cloning to that exact commit and building it was verified live as part of this session's own work; a disposable-fresh-clone re-verification of the full clone-to-build path at this specific commit, in the style docs/phase5c-final-report.md performed for the original Phase 5C pin, has not been repeated since.

Clone

git config --global core.longpaths true

git clone --recurse-submodules https://github.com/pmanyeh/DOSBox-X-MCP-Debugger.git

(or, if already cloned without --recurse-submodules: git submodule update --init.)

Python environment (verified against requirements.txt)

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

This installs the pinned mcp==2.0.0 SDK and pytest.

Building the native bridge

dosbox-src builds the same way upstream DOSBox-X does on Windows -- this project changes source files, not the build system. Follow dosbox-src/README.development-in-Windows (Visual Studio 2019+, the vs/dosbox-x.sln solution). A from-scratch build on a fresh machine has not been independently re-verified as part of this audit -- what has been verified this session is running the already-built binary against the current bridge source (63/63 native-bridge protocol checks, plus the full Phase 5A/5B/5C test suites, all passing). Please report any build friction.

Health checks

bin/ (the build output, including dosbox-x.conf) is not tracked by dosbox-src -- it's produced by the build above. On first launch, DOSBox-X will prompt once for a working directory; choose the repository root and (optionally) save it so future launches skip the prompt:

dosbox-src\bin\x64\Release\dosbox-x.exe -defaultdir -break-start drive_c\STEP.COM
.venv\Scripts\python.exe tests\test_native_bridge.py

63/63 checks should pass. Then, optionally, the fuller suites:

.venv\Scripts\python.exe -m pytest tests\phase5c -q
.venv\Scripts\python.exe -m pytest tests\phase5b -q
.venv\Scripts\python.exe -m pytest tests\test_debugger.py -q

(tests/phase5c and tests/phase5b's live cases need a freshly-launched DOSBox-X per the scenario's target program, STEP.COM or TEST.COM -- see tests/phase5c/scenario_setup.py for the exact launch/positioning helpers this project's own test runs use.)

Cleanup

Nothing under scratchpad/ (session-local: campaign traces, generated MCP configs, OAuth/preflight artifacts, evidence logs) is meant to persist or be committed -- it's safe to delete at any time and is already .gitignored.

Security and privacy

• The native bridge binds to loopback (127.0.0.1) rather than a public interface.

• MCP tool availability is controlled per bounded session.

• Rejected operations are recorded but not forwarded.

• Credentials, OAuth state, generated MCP configs, local traces, virtual environments, and build products must not be committed.

• Commercial game executables, data, saves, manuals, screenshots, and extracted assets are not part of this repository.

Documentation

• AI Agent Usage Guide -- required environment, installation, every MCP tool an agent can call, error codes, and example workflows. Start here if you're connecting an agent to this project.

• Changelog -- notable changes by development phase, in English and Traditional Chinese together.

• Phase 7 observability and autonomous-control requirements -- the design entry point for the current (Phase 6/7) capability set, with links out to each phase's own design doc (memory watchpoints, input injection, frame capture, mouse capture, input receipts, execution trace, DOS I/O event log).

• Dark Sun GPLI debugging case study (Traditional Chinese only) -- a worked example of using several of these tools together against a real commercial game.

• Phase 5C transport design

• Phase 5C final report

• Phase 5C implemented-state checkpoint

Project scope

This repository provides a general debugger integration. Game-specific research, translations, extracted data, and patches should live in separate repositories and should connect to this tool through project-level MCP configuration.

License and affiliation

The dosbox-src submodule (pmanyeh/dosbox-x) is a fork of upstream DOSBox-X and remains under upstream's own GNU General Public License v2 (see dosbox-src/COPYING); the Native AI Bridge changes carry the same GPL-2.0 header and copyright attribution as the files they extend, and no upstream license or copyright notice has been altered.

This project is independent and is not an official DOSBox-X project or an official product of any AI model or service provider.