DOS MCP

DOS MCP lets a modern MCP client observe and control DOS systems without putting MCP, JSON, HTTP, or an AI runtime on the retro machine. The modern Python bridge owns MCP, credentials, retries, target routing, policy, and structured results. DOS runs a small packet-driver endpoint.

Two DOS executables are retained:

• RAGENT.EXE: the original foreground command-shell endpoint;
• RA-TSR.EXE: a loadable/unloadable resident endpoint for background observation, BIOS keyboard insertion, sandboxed file transfer, and raw standard graphics capture.

PicoMEM/PicoMEM2-specific code is intentionally absent.

Implemented MCP tools

• dos.list_targets
• dos.get_status
• dos.get_capabilities
• dos.capture_screen
• dos.capture_graphics
• dos.send_keys
• dos.download_file
• dos.upload_file

All target-taking tools accept an optional target selector. It may be omitted only when the bridge knows exactly one system.

Target matrix

Capability	Linux PTY	UDP simulator	RAGENT	RA-TSR
Status/capabilities	Yes	Yes	Yes	Yes
80×25 text capture	Yes	Yes	Yes	Yes
Keyboard input	terminal	UDP	BIOS queue	BIOS queue
Sandboxed file read/write	opt-in	opt-in	No	opt-in
Raw graphics capture	No	fixture-dependent	No	CGA/Herc/EGA/VGA
Background operation	host process	host process	No	Yes
Load/unload	process	process	process	DOS TSR
Named local discovery	No	No	No	Yes

RA-TSR is built with 8086 instruction generation for 8088 through 486-class machines. DOSBox-X verifies the complete resident path, including exact text/VGA capture, keyboard-driven VER, binary upload/download, and unload. Physical adapter, BIOS, video-card, and 4.77 MHz timing coverage remains an explicit hardware-verification item.

Architecture

MCP client
    │ MCP over stdio
    ▼
Python DOS MCP bridge
    │ target registry + transport-independent Backend operations
    ├── Linux PTY backend
    ├── configured UDP target(s)
    └── validated local discovery records
             │ authenticated protocol v2 over UDP
             ├── Linux simulator
             ├── RAGENT.EXE
             └── RA-TSR.EXE
                    │ FTP/Crynwr packet driver
                    └── Ethernet adapter

Discovery is only an unauthenticated address hint. Every target operation still performs the configured credentialed handshake. RA-TSR announcements use Ethernet/IP limited broadcast and TTL 1, and stop while connected.

Quick start: local Linux backend

Requirements are Linux, Python 3.12+, and uv:

uv sync
uv run dos-mcp

Select a shell and starting directory:

DOS_MCP_ROOT=/path/to/workspace \
DOS_MCP_SHELL=/bin/bash \
uv run dos-mcp

The starting directory is not an OS sandbox; the child retains the bridge user's permissions.

Quick start: Linux-backed UDP simulator

# terminal 1
uv run dos-mcp-simulator \
  --bind 127.0.0.1:21300 \
  --password 'local-test-only' \
  --root "$PWD" \
  --allow-file-read \
  --allow-file-write

# terminal 2
DOS_MCP_TARGET=127.0.0.1:21300 \
DOS_MCP_PASSWORD='local-test-only' \
DOS_MCP_ALLOW_FILE_READ=1 \
DOS_MCP_ALLOW_FILE_WRITE=1 \
uv run dos-mcp

Quick start: DOS

Build with Open Watcom 2:

make -C dos WATCOM=/path/to/watcom all

Foreground:

RAGENT pass:UniqueLabPass 192.168.10.55 21300 0x60

Resident, named, with an explicit file root:

MD C:\REMOTE
RA-TSR pass:UniqueLabPass 192.168.10.55 21300 0x60 C:\REMOTE RW WORKBENCH-386

Connect directly:

DOS_MCP_TARGET=192.168.10.55:21300 \
DOS_MCP_PASSWORD=UniqueLabPass \
DOS_MCP_ALLOW_FILE_READ=1 \
DOS_MCP_ALLOW_FILE_WRITE=1 \
uv run dos-mcp

Or listen for disconnected RA-TSRs:

DOS_MCP_DISCOVERY=1 \
DOS_MCP_PASSWORD=UniqueLabPass \
uv run dos-mcp

For multiple fixed machines:

DOS_MCP_TARGETS='{"desk8088":"192.168.10.21","lab386":"192.168.10.38"}' \
DOS_MCP_PASSWORD=UniqueLabPass \
uv run dos-mcp

The bridge currently uses one UDP credential per process. Separate bridge processes are recommended when targets have different secrets.

Credentials

A password/passphrase of any nonzero length supported by the invoking command line is deterministically reduced to a 128-bit key. A legacy 32-hex raw key is still accepted. The credential is optional on both peers; omission selects conspicuous open mode.

Open mode is unauthenticated and suitable only for an isolated test network. Credentialed protocol v2 authenticates but does not encrypt traffic and uses a deliberately short 32-bit packet tag for 8088 feasibility. Use a trusted private LAN, a unique high-entropy credential per deployment, and never forward the DOS operation port to the Internet.

Test

uv run ruff check .
uv run python tools/check_docs.py
uv run pytest
make -C dos WATCOM=/path/to/watcom all

Foreground and resident DOSBox-X harnesses:

WATCOM=/path/to/watcom \
DOSBOX_X=/path/to/dosbox-x \
PACKET_DRIVER=/path/to/NE2000.COM \
tools/test_dosbox_x.sh

WATCOM=/path/to/watcom \
DOSBOX_X=/path/to/dosbox-x \
PACKET_DRIVER=/path/to/NE2000.COM \
tools/test_dosbox_x_tsr.sh

Documentation

Start with Documentation:

• Getting started
• Configuration
• MCP tools
• DOS executables
• RA-TSR
• Discovery and multiple targets
• Protocol v2
• Architecture
• Security model
• DOS reentrancy
• Video capture
• Testing
• Roadmap

PROJECT.md is the original brief. AGENTS.md contains the current contributor constraints.

License

A final open-source license has not yet been selected. Third-party packet drivers are not redistributed by this repository.