DOSBox-X MCP Debugger

English | 繁體中文

Give AI agents direct, structured access to the real DOSBox-X debugger.

DOSBox-X MCP Debugger connects AI agents to the native DOSBox-X debugger through the Model Context Protocol (MCP). Instead of asking a person to copy registers, memory dumps, disassembly, and breakpoint results back and forth, an agent can inspect and control the same guest CPU and debugger state directly.

It is built for legacy DOS debugging and reverse engineering, especially investigations where runtime evidence matters: discovering how text is decoded or assembled, following script execution, tracing rendering pipelines, watching memory changes, and reproducing input-dependent behavior.

What it enables

The current general-purpose MCP interface exposes 37 tools across the debugging workflow:

See the AI Agent Usage Guide for setup, the complete tool reference, error behavior, and example workflows.

Related MCP server: gdb_mcp

Why this is different

This is not GUI automation and it does not simulate debugger output. MCP calls travel through a Python client and a native loopback bridge into DOSBox-X's existing debugger and input-handling mechanisms. Breakpoints, execution state, registers, memory, disassembly, frames, and event observations come from the running emulator.

That makes the project useful for work such as:

• tracing how a legacy game forms a line of text before rendering;

• identifying code and data involved in runtime decoding or phrase composition;

• observing memory changes around a reproducible event;

• correlating keyboard or mouse input with execution, frames, and DOS file I/O;

• producing an auditable trail of observations, inferences, and open questions.

Project maturity

The project also retains a separate bounded 12-tool research surface for controlled acceptance testing. It intentionally excludes register and memory writes and enforces session-level tool and execution budgets.

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 39-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 8 (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 -- 39 tools spanning debugger state, memory/registers/VGA I/O ports, a side-effect-free VGA VRAM snapshot, 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 39-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.