dosbox-mcp 0.1.0__tar.gz

dosbox_mcp-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+dosbox-mcp License
+------------------
+
+dosbox-mcp is licensed under the GNU General Public License
+version 2 or later (GPL-2.0-or-later).
+
+The full license text is in licenses/GPL-2.0-or-later.txt.
+
+Third-party dependencies are listed in THIRD_PARTY_LICENSES.txt.
+
+Exception: PROTOCOL.md (the dosbox-mcp protocol specification) is
+licensed under Creative Commons Attribution-ShareAlike 4.0
+(CC-BY-SA-4.0). The full license text is in licenses/CC-BY-SA-4.0.txt.

dosbox_mcp-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include PROTOCOL.md
+include THIRD_PARTY_LICENSES.txt
+recursive-include feelies *.md
+recursive-include licenses *.txt

dosbox_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: dosbox-mcp
+Version: 0.1.0
+Summary: MCP server for dosbox-automation: drive a DOS machine from an AI agent
+Author-email: dosbox-mcp contributors <dosbox-mcp@trinity2k.net>
+License-Expression: GPL-2.0-or-later
+Project-URL: Homepage, https://dosbox-automation.org
+Project-URL: Repository, https://github.com/dosbox-automation/dosbox-mcp
+Project-URL: Issues, https://github.com/dosbox-automation/dosbox-mcp/issues
+Keywords: dosbox,mcp,model-context-protocol,automation,emulator,dos
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/GPL-2.0-or-later.txt
+License-File: licenses/CC-BY-SA-4.0.txt
+License-File: THIRD_PARTY_LICENSES.txt
+Requires-Dist: mcp>=1.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4
+Requires-Dist: tomlkit>=0.13
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: bandit; extra == "dev"
+Dynamic: license-file
+
+# dosbox-mcp
+
+MCP server for [dosbox-automation](https://dosbox-automation.org):
+drive a DOS machine from an AI agent.
+
+dosbox-automation is a DOSBox fork with a built-in automation API.
+This bridge connects any MCP-capable agent runtime (Claude Code and
+friends) to a running emulator. The agent can type into DOS programs,
+read the screen, capture frames and video, run sandboxed Lua scripts,
+and inspect memory: everything the automation API offers, as MCP tools.
+
+## Quick start
+
+1. Install dosbox-automation and start it with the API enabled. The
+   [manual](https://dosbox-automation.org) covers setup for all
+   platforms.
+
+2. Add the bridge to your MCP client. For Claude Code:
+
+   ```
+   claude mcp add dosbox -- uvx dosbox-mcp
+   ```
+
+   Or in a JSON MCP configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "dosbox": { "command": "uvx", "args": ["dosbox-mcp"] }
+     }
+   }
+   ```
+
+   `pipx install dosbox-mcp` or `pip install dosbox-mcp` work just as
+   well; the command is `dosbox-mcp` either way.
+
+That's it. The bridge finds the running emulator, checks what it can
+do, and registers the matching tools. Ask your agent for `bridge_status`
+to confirm the connection.
+
+## Configuration
+
+Optional. Write a commented config file to tune the port, spawn an
+emulator on demand, or limit what an agent may do:
+
+```
+dosbox-mcp setup --init
+```
+
+The comments in the generated file explain each setting. Environment
+variables `DOSBOX_API_URL` and `DOSBOX_API_TOKEN` override it. The
+bridge talks to loopback addresses only; it will not reach out to a
+remote machine.
+
+## What the agent gets
+
+Tools for session control, screen text and captures, video recording,
+Lua scripting, keyboard and mouse input, and memory access. You choose
+how much reach an agent has, from read-only observation to full
+control.
+
+## An open protocol
+
+The contract between this bridge and the emulator is written down in
+[PROTOCOL.md](PROTOCOL.md) and versioned independently. dosbox-automation
+is the reference implementation; any DOSBox variant that speaks the
+protocol works with this bridge.
+
+## In the box
+
+Like the games it drives, this one ships with its paper. The `feelies/`
+folder holds the manual, a reference card for every tool, an install
+sheet, and a tech-support page.
+
+## Requirements
+
+- Python 3.11 or newer
+- A running dosbox-automation (0.84-da2 or newer) on the same machine
+
+## License
+
+GPL-2.0-or-later. See LICENSE. The protocol specification
+(PROTOCOL.md) is licensed CC-BY-SA-4.0.
+
+---
+This project is developed with tooled assistance, but tested, reviewed and
+signed off by a human developer.

dosbox_mcp-0.1.0/PROTOCOL.md

@@ -0,0 +1,166 @@
+# The dosbox-mcp Protocol
+
+Version 1.0.0 (2026-07-17)
+
+This document specifies the contract between an MCP bridge and a
+DOSBox-family emulator that exposes the automation REST API. The bridge
+declares what the protocol can do; the engine delivers it. The reference
+implementation of the engine side is dosbox-automation
+(https://dosbox-automation.org); any other DOSBox variant that
+implements this contract is a valid peer.
+
+License: this specification is licensed under Creative Commons
+Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0). You may
+implement it under any license you like - the license covers this
+document, not your code. If you publish a modified version of the
+specification itself, the modification must carry the same license and
+credit the dosbox-mcp project. Full text: licenses/CC-BY-SA-4.0.txt in
+this repository, or https://creativecommons.org/licenses/by-sa/4.0/
+
+
+## Versioning
+
+The specification is versioned MAJOR.MINOR.PATCH:
+
+- MAJOR changes break existing shapes. Peers with different majors are
+  incompatible.
+- MINOR changes are additive: a new route group, route, or field.
+  Nothing existing changes meaning.
+- PATCH changes fix or clarify the text without changing behavior.
+  They never appear on the wire.
+
+On the wire, only "major.minor" travels. An engine advertises its
+version in the info payload (below) as the string field `mcp_protocol`,
+for example `"1.0"`. Two peers are compatible when their majors match;
+the effective contract between them is the smaller of the two minors.
+
+Backward compatibility rule: an engine whose info payload has no
+`mcp_protocol` field but does have a `features` object is treated as
+implicit version 1.0, because 1.0 is defined as exactly the surface
+those engines ship. An info payload with neither field is not a
+protocol peer.
+
+
+## Transport and security
+
+- HTTP (optionally HTTPS) on a loopback address only. Engines must bind
+  to 127.0.0.1 (or ::1); bridges must refuse any non-loopback URL.
+  Operation across a network is out of scope for protocol 1.x.
+- Every request except the hello route (below) carries a bearer token:
+  `Authorization: Bearer <token>`. The engine generates the token at
+  startup; with the engine setting `webserver_token_file = true` it is
+  written to a token file that local clients read. The token must never
+  be passed on a command line or echoed in error responses.
+- Clients should identify themselves with an `X-Client` header (the
+  bridge sends `X-Client: mcp`). Engines may use it to drive on-screen
+  activity indicators; they must not grant anything based on it.
+
+
+## Discovery
+
+### GET /api/v1/hello (unauthenticated)
+
+Added in 1.0 as an optional route; engines that predate it simply
+answer 404 and are treated as implicit 1.0. When implemented, it
+returns exactly three fields and nothing else:
+
+```json
+{"name": "dosbox-automation", "version": "0.84-da3", "mcp_protocol": "1.0"}
+```
+
+Its purpose is diagnostics before authentication: a client can
+distinguish "no instance on this port" from "instance present, token
+missing" and report precisely. Because it is unauthenticated, it must
+never expose configuration, state, or anything beyond these three
+fields.
+
+### GET /api/v1/dosbox/info (authenticated)
+
+The identification payload. Required fields for a protocol peer:
+
+- `version` (string): the engine's own version.
+- `features` (object): capability flags, see below.
+- `mcp_protocol` (string, "major.minor"): the protocol version.
+  Absent on pre-1.0-advertisement engines (implicit 1.0 rule).
+
+### Feature flags
+
+`features` reports which optional capability groups the running build
+supports. Version 1.0 defines these flags, all boolean:
+
+| Flag | Grants |
+|---|---|
+| memory | memory read/write/search, freeze, DOS memory map |
+| input | keyboard and input injection |
+| cpu_registers | CPU register reads |
+| cpu_control | CPU register writes |
+| port_io | x86 I/O port read/write |
+| freeze | per-frame value locks |
+| debugger | execution control (reserved; no 1.0 engine ships it) |
+
+A flag that is absent counts as false. Flags gate at call time: a
+client may know a route exists in the contract while the running build
+has it disabled.
+
+
+## The 1.0 contract surface
+
+The route groups below, under the `/api/v1/` prefix, are the 1.0
+contract. The machine-readable OpenAPI document served at
+`/openapi.json` is part of the contract surface: it is normative for
+the exact request and response schemas of these routes, and clients
+verify the advertised contract against it.
+
+| Group | Routes | Notes |
+|---|---|---|
+| session | `status`, `program/state`, `dosbox/info`, `dosbox/shutdown` | machine and program state; shutdown is irreversible |
+| screen | `video/frame`, `video/frame/info`, `video/text` | frame capture (clean emulator output) and text-mode screen reading |
+| capture | `capture/video/start`, `capture/video/stop`, `capture/video/status` | video recording control |
+| input | `input/sequence`, `input/type` | named-key sequences; paced string typing (feature: input) |
+| memory | `memory/{offset}/{length}` GET, `memory/{offset}` PUT, `memory/search` | guest physical memory (feature: memory) |
+| freeze | `memory/freeze` POST/GET/DELETE | per-frame value locks (feature: freeze) |
+| dos | `dos/internals` | DOS internals incl. the MCB memory map (feature: memory) |
+| cpu | `cpu/register` PUT | register writes (feature: cpu_control) |
+| io | `io/port` GET/PUT | port I/O (feature: port_io) |
+| script | `script/load`, `script/start`, `script/status`, `script/stop` | sandboxed Lua; `script/load` takes the raw source as a text/plain body |
+| media | `drive/swap`, mount routes | disk image swapping; mount policy applies underneath |
+
+Semantics that are part of the contract, not just the schemas:
+
+- Memory routes address guest physical memory with plain integer
+  offsets; JSON output (base64 payload) is selected with an
+  `Accept: application/json` header, binary is the default.
+- The frame returned by `video/frame` is the clean emulator output:
+  on-screen overlays the engine draws for the human watching are never
+  in it.
+- Validation lives engine-side. The engine is the trust boundary;
+  a client talking HTTP directly must be subject to exactly the same
+  limits as one going through a bridge.
+
+
+## Conformance
+
+An engine conforms to protocol 1.0 when it:
+
+1. serves the session, screen, capture, and script groups,
+2. serves `dosbox/info` with a `features` object and (from now on)
+   the `mcp_protocol` field,
+3. gates optional groups behind their feature flags,
+4. authenticates every route except `hello` with the bearer token,
+5. binds to loopback only,
+6. serves its OpenAPI document at `/openapi.json`.
+
+A client (bridge) conforms when it negotiates the version as specified,
+refuses non-loopback targets, treats feature flags as call-time gates,
+and keeps the token out of command lines, logs, and outputs.
+
+
+## Changelog
+
+Every revision of this specification gets an entry here stating what
+changed and the version it produces.
+
+- **1.0.0 (2026-07-17)** - initial specification: versioning and
+  negotiation rules, transport and token requirements, hello route,
+  feature flags, and the 1.0 route groups as shipped by
+  dosbox-automation 0.84.

dosbox_mcp-0.1.0/README.md

@@ -0,0 +1,87 @@
+# dosbox-mcp
+
+MCP server for [dosbox-automation](https://dosbox-automation.org):
+drive a DOS machine from an AI agent.
+
+dosbox-automation is a DOSBox fork with a built-in automation API.
+This bridge connects any MCP-capable agent runtime (Claude Code and
+friends) to a running emulator. The agent can type into DOS programs,
+read the screen, capture frames and video, run sandboxed Lua scripts,
+and inspect memory: everything the automation API offers, as MCP tools.
+
+## Quick start
+
+1. Install dosbox-automation and start it with the API enabled. The
+   [manual](https://dosbox-automation.org) covers setup for all
+   platforms.
+
+2. Add the bridge to your MCP client. For Claude Code:
+
+   ```
+   claude mcp add dosbox -- uvx dosbox-mcp
+   ```
+
+   Or in a JSON MCP configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "dosbox": { "command": "uvx", "args": ["dosbox-mcp"] }
+     }
+   }
+   ```
+
+   `pipx install dosbox-mcp` or `pip install dosbox-mcp` work just as
+   well; the command is `dosbox-mcp` either way.
+
+That's it. The bridge finds the running emulator, checks what it can
+do, and registers the matching tools. Ask your agent for `bridge_status`
+to confirm the connection.
+
+## Configuration
+
+Optional. Write a commented config file to tune the port, spawn an
+emulator on demand, or limit what an agent may do:
+
+```
+dosbox-mcp setup --init
+```
+
+The comments in the generated file explain each setting. Environment
+variables `DOSBOX_API_URL` and `DOSBOX_API_TOKEN` override it. The
+bridge talks to loopback addresses only; it will not reach out to a
+remote machine.
+
+## What the agent gets
+
+Tools for session control, screen text and captures, video recording,
+Lua scripting, keyboard and mouse input, and memory access. You choose
+how much reach an agent has, from read-only observation to full
+control.
+
+## An open protocol
+
+The contract between this bridge and the emulator is written down in
+[PROTOCOL.md](PROTOCOL.md) and versioned independently. dosbox-automation
+is the reference implementation; any DOSBox variant that speaks the
+protocol works with this bridge.
+
+## In the box
+
+Like the games it drives, this one ships with its paper. The `feelies/`
+folder holds the manual, a reference card for every tool, an install
+sheet, and a tech-support page.
+
+## Requirements
+
+- Python 3.11 or newer
+- A running dosbox-automation (0.84-da2 or newer) on the same machine
+
+## License
+
+GPL-2.0-or-later. See LICENSE. The protocol specification
+(PROTOCOL.md) is licensed CC-BY-SA-4.0.
+
+---
+This project is developed with tooled assistance, but tested, reviewed and
+signed off by a human developer.

dosbox_mcp-0.1.0/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,30 @@
+================================================================================
+dosbox-mcp THIRD-PARTY LICENSES
+================================================================================
+
+Runtime dependencies, installed from PyPI:
+
+  httpx          HTTP client for Python
+                 Copyright (c) Tom Christie
+                 License: BSD-3-Clause
+                 Homepage: https://github.com/encode/httpx
+
+  mcp            Model Context Protocol SDK
+                 Copyright (c) Anthropic, PBC.
+                 License: MIT
+                 Homepage: https://modelcontextprotocol.io
+
+  platformdirs   Platform-specific user directories
+                 Copyright (c) 2010-202x The platformdirs developers
+                 License: MIT
+                 Homepage: https://github.com/tox-dev/platformdirs
+
+  tomlkit        Style-preserving TOML library
+                 Copyright (c) Sebastien Eustace
+                 License: MIT
+                 Homepage: https://github.com/python-poetry/tomlkit
+
+All licenses are compatible with GPL-2.0-or-later.
+
+END OF THIRD-PARTY LICENSES
+================================================================================

dosbox_mcp-0.1.0/dosbox_mcp/__init__.py

@@ -0,0 +1,3 @@
+# This file is part of the dosbox-mcp Project.
+# License: GPL-2.0-or-later. Contact: dosbox-mcp@trinity2k.net
+#

dosbox_mcp-0.1.0/dosbox_mcp/capabilities.py

@@ -0,0 +1,26 @@
+# This file is part of the dosbox-mcp Project.
+# License: GPL-2.0-or-later. Contact: dosbox-mcp@trinity2k.net
+#
+
+# Maps a bridge tool group to the feature flag that must be true for it
+# to register. Groups always present (session, screen, script, media)
+# are not gated.
+GROUP_CAPABILITY = {
+    "memory": "memory",
+    "input": "input",
+    "freeze": "freeze",
+    "cpu_registers": "cpu_registers",
+    "cpu_control": "cpu_control",
+    "port_io": "port_io",
+    "debugger": "debugger",
+}
+
+ALWAYS_ON = {"session", "screen", "script", "media"}
+
+
+def registered_groups(features: dict) -> set:
+    groups = set(ALWAYS_ON)
+    for group, flag in GROUP_CAPABILITY.items():
+        if features.get(flag) is True:
+            groups.add(group)
+    return groups

dosbox_mcp-0.1.0/dosbox_mcp/cli.py

@@ -0,0 +1,177 @@
+# This file is part of the dosbox-mcp Project.
+# License: GPL-2.0-or-later. Contact: dosbox-mcp@trinity2k.net
+#
+
+"""Command line entry point.
+
+`dosbox-mcp` with no arguments serves MCP over stdio (what an MCP client
+spawns). `setup` and `probe` are the human-facing configuration
+commands; there is deliberately no interactive dialog - the commented
+config template plays that role.
+"""
+
+import argparse
+import json
+import sys
+
+
+from .client import DosboxClient
+from .config import (
+    Config,
+    default_config_path,
+    update_config_file,
+    write_config_template,
+)
+from .connection import Connection, NotConnected
+from .lifecycle import InstanceManager, LifecycleError
+from .protocol import BRIDGE_PROTOCOL
+
+
+def _serve() -> int:
+    # Local import: the MCP server pulls in asyncio machinery the other
+    # subcommands never need.
+    from .server import main as serve_main
+    serve_main()
+    return 0
+
+
+def _connection_factory(config: Config) -> Connection:
+    return Connection(config)
+
+
+def _cmd_setup(args) -> int:
+    path = default_config_path()
+    if args.init:
+        try:
+            write_config_template(path)
+        except FileExistsError as e:
+            print(str(e), file=sys.stderr)
+            return 2
+        print(f"wrote {path} - edit it to suit; commented lines show defaults")
+        return 0
+
+    changes = {}
+    for key in ("binary", "port", "protocol", "mode", "token_file"):
+        value = getattr(args, key)
+        if value is not None:
+            changes[key] = value
+    if args.headless is not None:
+        changes["headless"] = args.headless
+
+    if not changes:
+        config = Config.load()
+        current = {
+            "config_file": str(path),
+            "binary": str(config.binary) if config.binary else None,
+            "port": config.port,
+            "headless": config.headless,
+            "protocol": config.protocol,
+            "mode": config.mode,
+            "token_file": str(config.token_file) if config.token_file else None,
+        }
+        print(json.dumps(current, indent=2))
+        return 0
+
+    try:
+        update_config_file(path, changes)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+    print(f"saved to {path}")
+    return 0
+
+
+def _cmd_probe(args) -> int:
+    try:
+        config = Config.load()
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+
+    print(f"bridge protocol: {BRIDGE_PROTOCOL}")
+    print(f"config file:     {default_config_path()}")
+    print(f"target:          {config.base_url} (mode {config.mode})")
+
+    if config.binary is not None:
+        return _probe_binary(config)
+    print("no binary configured - trying to attach to a running instance")
+    return _probe_attach(config)
+
+
+def _probe_binary(config: Config) -> int:
+    def attach(base_url, token):
+        client = DosboxClient(base_url, token)
+        return client.get("/api/v1/dosbox/info")
+
+    manager = InstanceManager(config, attach=attach)
+    try:
+        info = manager.start()
+    except LifecycleError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    try:
+        print(f"binary:          {config.binary}")
+        print(f"engine version:  {info.get('version', '?')}")
+        print(f"engine protocol: {info.get('mcp_protocol', 'implicit 1.0')}")
+    finally:
+        manager.stop()
+    return 0
+
+
+def _probe_attach(config: Config) -> int:
+    conn = _connection_factory(config)
+    try:
+        conn.ensure_connected()
+    except NotConnected as e:
+        print(f"not connected: {e}")
+        return 1
+    status = conn.status()
+    print(f"engine version:  {status['engine_version']}")
+    print(f"protocol:        {status['protocol']}")
+    print(f"features:        {json.dumps(status['features'])}")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dosbox-mcp",
+        description="MCP bridge for dosbox. Without a subcommand, serves "
+                    "MCP over stdio.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    setup = sub.add_parser(
+        "setup",
+        help="write config values; --init writes a commented template; "
+             "no flags prints the current configuration",
+    )
+    setup.add_argument("--init", action="store_true",
+                       help="write the commented default config")
+    setup.add_argument("--binary", help="dosbox binary that bridge_start spawns")
+    setup.add_argument("--port", type=int, help="webserver port on 127.0.0.1")
+    setup.add_argument("--headless", action=argparse.BooleanOptionalAction,
+                       default=None, help="spawn without a window")
+    setup.add_argument("--protocol", help='protocol pin, "major.minor"')
+    setup.add_argument("--mode", help="capability mode: observe/interact/full")
+    setup.add_argument("--token-file", dest="token_file",
+                       help="token file of an already-running instance")
+
+    sub.add_parser(
+        "probe",
+        help="validate the config and probe the binary (or a running "
+             "instance) for version and protocol",
+    )
+    return parser
+
+
+def main(argv=None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "setup":
+        return _cmd_setup(args)
+    if args.command == "probe":
+        return _cmd_probe(args)
+    return _serve()
+
+
+if __name__ == "__main__":
+    sys.exit(main())