From 51b0863ba4440d1112083032fe494a4b05ef08c3 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Wed, 28 Jan 2026 12:41:15 -0700 Subject: [PATCH] Add LICENSE file and update README for PyPI --- LICENSE | 32 ++++++++++++++++++++++++++ README.md | 69 ++++++++++++++++++++++++++++++++++++------------------- 2 files changed, 78 insertions(+), 23 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c34498a --- /dev/null +++ b/LICENSE @@ -0,0 +1,32 @@ +MIT License + +Copyright (c) 2025 Ryan Malloy + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +## Bundled Fonts License + +The TrueType fonts in src/mcdosbox_x/fonts/ are from "The Ultimate Oldschool +PC Font Pack" by VileR (https://int10h.org/oldschool-pc-fonts/) and are +licensed under Creative Commons Attribution-ShareAlike 4.0 International +(CC BY-SA 4.0). + +See src/mcdosbox_x/fonts/LICENSE.TXT for full font license details. diff --git a/README.md b/README.md index e86fdfd..6eba353 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# DOSBox-X MCP Server +# mcdosbox-x AI-assisted debugging of DOS binaries via the Model Context Protocol (MCP). @@ -8,6 +8,9 @@ This MCP server enables Claude to programmatically debug DOS programs running in - Reading/writing CPU registers and memory - Disassembling code at any address - Step-by-step instruction execution +- Sending keyboard/mouse input +- Capturing screenshots and screen text +- Serial port communication for BBS/terminal programs ## Primary Use Case @@ -15,19 +18,32 @@ This MCP server enables Claude to programmatically debug DOS programs running in ## Quick Start -### Prerequisites +### Installation from PyPI -- Python 3.11+ -- [uv](https://github.com/astral-sh/uv) package manager -- Docker and Docker Compose -- X11 display (for DOSBox GUI) or use headless mode +```bash +# Install with uvx (recommended) +uvx mcdosbox-x -### Installation +# Or install with pip +pip install mcdosbox-x +``` + +### Register with Claude Code + +```bash +# Add to Claude Code +claude mcp add mcdosbox-x -- uvx mcdosbox-x + +# Verify registration +claude mcp list +``` + +### Development Installation ```bash # Clone the repository -git clone https://github.com/ryanmalloy/dosbox-mcp.git -cd dosbox-mcp +git clone https://git.supported.systems/MCP/mcdosbox-x.git +cd mcdosbox-x # Install dependencies uv sync @@ -55,14 +71,17 @@ nc -zv localhost 1234 docker compose logs -f ``` -### Register with Claude Code +### Running with Docker ```bash -# Add to Claude Code -claude mcp add dosbox-mcp -- uv run --directory /path/to/dosbox-mcp dosbox-mcp +# Allow X11 access for Docker (Linux) +xhost +local:docker -# Verify registration -claude mcp list +# Start DOSBox-X with GDB server +docker compose up -d + +# View logs +docker compose logs -f ``` ## Usage with Claude @@ -172,22 +191,26 @@ Mainline DOSBox-X doesn't include a GDB server. The [lokkju/dosbox-x-remotedebug ## Project Structure ``` -dosbox-mcp/ -├── src/dosbox_mcp/ +mcdosbox-x/ +├── src/mcdosbox_x/ │ ├── server.py # FastMCP server entry point │ ├── gdb_client.py # GDB Remote Serial Protocol client │ ├── dosbox.py # DOSBox-X process/container management +│ ├── fonts.py # Bundled TrueType font utilities +│ ├── resources.py # MCP resources (screenshots, screen) │ ├── state.py # Shared global state (manager, client) │ ├── types.py # Type definitions (Registers, Breakpoint, etc.) │ ├── utils.py # Address parsing, format conversion -│ └── tools/ # MCP tool implementations -│ ├── execution.py # launch, attach, continue, step, quit +│ ├── fonts/ # Bundled IBM PC TTF fonts (CC BY-SA 4.0) +│ └── tools/ # MCP tool implementations (47 tools) +│ ├── execution.py # launch, attach, continue, step, quit, fonts_list │ ├── breakpoints.py # breakpoint_set, list, delete -│ ├── inspection.py # registers, memory, disassemble, stack -│ └── peripheral.py # screenshot, serial (stubs) +│ ├── inspection.py # registers, memory, disassemble, stack, screen +│ ├── peripheral.py # screenshot, keyboard, mouse, joystick, serial +│ ├── control.py # pause, resume, reset, savestate, loadstate +│ ├── logging.py # DOSBox logging control +│ └── network.py # port mapping, modem dial/hangup ├── tests/ # pytest test suite -├── config/ -│ └── dosbox.conf # DOSBox-X configuration with GDB enabled ├── dos/ # Mount point for DOS binaries ├── Dockerfile # Multi-stage build for dosbox-x-remotedebug ├── docker-compose.yml # Container orchestration @@ -227,7 +250,7 @@ CONFIG_FILE=./config/dosbox.conf uv run pytest # Run tests with coverage -uv run pytest --cov=dosbox_mcp +uv run pytest --cov=mcdosbox_x # Lint code uv run ruff check src/