Add LICENSE file and update README for PyPI
This commit is contained in:
parent
6805905287
commit
51b0863ba4
32
LICENSE
Normal file
32
LICENSE
Normal file
@ -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.
|
||||||
69
README.md
69
README.md
@ -1,4 +1,4 @@
|
|||||||
# DOSBox-X MCP Server
|
# mcdosbox-x
|
||||||
|
|
||||||
AI-assisted debugging of DOS binaries via the Model Context Protocol (MCP).
|
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
|
- Reading/writing CPU registers and memory
|
||||||
- Disassembling code at any address
|
- Disassembling code at any address
|
||||||
- Step-by-step instruction execution
|
- Step-by-step instruction execution
|
||||||
|
- Sending keyboard/mouse input
|
||||||
|
- Capturing screenshots and screen text
|
||||||
|
- Serial port communication for BBS/terminal programs
|
||||||
|
|
||||||
## Primary Use Case
|
## Primary Use Case
|
||||||
|
|
||||||
@ -15,19 +18,32 @@ This MCP server enables Claude to programmatically debug DOS programs running in
|
|||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Prerequisites
|
### Installation from PyPI
|
||||||
|
|
||||||
- Python 3.11+
|
```bash
|
||||||
- [uv](https://github.com/astral-sh/uv) package manager
|
# Install with uvx (recommended)
|
||||||
- Docker and Docker Compose
|
uvx mcdosbox-x
|
||||||
- X11 display (for DOSBox GUI) or use headless mode
|
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
# Clone the repository
|
# Clone the repository
|
||||||
git clone https://github.com/ryanmalloy/dosbox-mcp.git
|
git clone https://git.supported.systems/MCP/mcdosbox-x.git
|
||||||
cd dosbox-mcp
|
cd mcdosbox-x
|
||||||
|
|
||||||
# Install dependencies
|
# Install dependencies
|
||||||
uv sync
|
uv sync
|
||||||
@ -55,14 +71,17 @@ nc -zv localhost 1234
|
|||||||
docker compose logs -f
|
docker compose logs -f
|
||||||
```
|
```
|
||||||
|
|
||||||
### Register with Claude Code
|
### Running with Docker
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Add to Claude Code
|
# Allow X11 access for Docker (Linux)
|
||||||
claude mcp add dosbox-mcp -- uv run --directory /path/to/dosbox-mcp dosbox-mcp
|
xhost +local:docker
|
||||||
|
|
||||||
# Verify registration
|
# Start DOSBox-X with GDB server
|
||||||
claude mcp list
|
docker compose up -d
|
||||||
|
|
||||||
|
# View logs
|
||||||
|
docker compose logs -f
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage with Claude
|
## Usage with Claude
|
||||||
@ -172,22 +191,26 @@ Mainline DOSBox-X doesn't include a GDB server. The [lokkju/dosbox-x-remotedebug
|
|||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
dosbox-mcp/
|
mcdosbox-x/
|
||||||
├── src/dosbox_mcp/
|
├── src/mcdosbox_x/
|
||||||
│ ├── server.py # FastMCP server entry point
|
│ ├── server.py # FastMCP server entry point
|
||||||
│ ├── gdb_client.py # GDB Remote Serial Protocol client
|
│ ├── gdb_client.py # GDB Remote Serial Protocol client
|
||||||
│ ├── dosbox.py # DOSBox-X process/container management
|
│ ├── 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)
|
│ ├── state.py # Shared global state (manager, client)
|
||||||
│ ├── types.py # Type definitions (Registers, Breakpoint, etc.)
|
│ ├── types.py # Type definitions (Registers, Breakpoint, etc.)
|
||||||
│ ├── utils.py # Address parsing, format conversion
|
│ ├── utils.py # Address parsing, format conversion
|
||||||
│ └── tools/ # MCP tool implementations
|
│ ├── fonts/ # Bundled IBM PC TTF fonts (CC BY-SA 4.0)
|
||||||
│ ├── execution.py # launch, attach, continue, step, quit
|
│ └── tools/ # MCP tool implementations (47 tools)
|
||||||
|
│ ├── execution.py # launch, attach, continue, step, quit, fonts_list
|
||||||
│ ├── breakpoints.py # breakpoint_set, list, delete
|
│ ├── breakpoints.py # breakpoint_set, list, delete
|
||||||
│ ├── inspection.py # registers, memory, disassemble, stack
|
│ ├── inspection.py # registers, memory, disassemble, stack, screen
|
||||||
│ └── peripheral.py # screenshot, serial (stubs)
|
│ ├── 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
|
├── tests/ # pytest test suite
|
||||||
├── config/
|
|
||||||
│ └── dosbox.conf # DOSBox-X configuration with GDB enabled
|
|
||||||
├── dos/ # Mount point for DOS binaries
|
├── dos/ # Mount point for DOS binaries
|
||||||
├── Dockerfile # Multi-stage build for dosbox-x-remotedebug
|
├── Dockerfile # Multi-stage build for dosbox-x-remotedebug
|
||||||
├── docker-compose.yml # Container orchestration
|
├── docker-compose.yml # Container orchestration
|
||||||
@ -227,7 +250,7 @@ CONFIG_FILE=./config/dosbox.conf
|
|||||||
uv run pytest
|
uv run pytest
|
||||||
|
|
||||||
# Run tests with coverage
|
# Run tests with coverage
|
||||||
uv run pytest --cov=dosbox_mcp
|
uv run pytest --cov=mcdosbox_x
|
||||||
|
|
||||||
# Lint code
|
# Lint code
|
||||||
uv run ruff check src/
|
uv run ruff check src/
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user