MCP-AmigaOS4

MCP-AmigaOS4

A Model Context Protocol server for driving AmigaOS 4.1 machines — both QEMU guests and real PowerPC hardware — from MCP-aware clients such as Claude Code, Claude Desktop, and IDE plugins.

At a glance

Brings AmigaOS 4.1 inside your AI client. From a single MCP session you can:

• Browse and edit files on the target Amiga, run AmigaDOS commands with captured stdout, upload large binaries with zlib compression and resumable chunks.
• Follow long-running commands — every command is a tracked job with an id, exit code and IoErr. One that outlives its timeout keeps running and can be checked, read or stopped later. The daemon's workers run above ordinary programs, so a busy one cannot starve it.
• Inspect live state — running tasks, opened libraries, mounted volumes, public screens, the last alert (decoded), CPU + cache + AttnFlags.
• Drive QEMU lifecycle — start, stop, screenshot the framebuffer, save / restore VM snapshots, attach a GDB stub for whole-system debug.
• Coordinate a fleet — run one method across any mix of QEMU guests and real hardware in parallel; barrier, quorum, or cross-target file relay.
• Install AmigaOS 4.1 FE end-to-end onto a blank volume — preflight, ISO mount, copy, LHA extract, Kicklayout patch, verify — via a single installer.run call.
• Live X5000 hardware introspection — board / CPU temperatures, voltages, fan PWM/RPM via the Cyrus MCU, plus CCSR registers, TLB walks, and IDebug-driven per-task crash snapshots.
• Out-of-band power control — with the FTDI USB-TTL cable wired to the X5000 P18 / A1222 P15 header, power.on / power.off / power.toggle_stream drive the MCU debug shell directly from MCP. Works regardless of AOS / MCPd state; the only software path to boot a fully-off X5000.
• Iterate on programs and drivers without power-cycling — sandbox.* wraps SandboxVM so a guest segfault no longer takes down the daemon. Edit → upload → run → read structured exit code + trap classification + captured stdout/stderr; load .device / .library drivers in resident-init mode and chain a test program against them, all in a single tool call.
• See the screen — wb.screenshot captures a Workbench screen to PNG on the Amiga and returns it, on real hardware as well as QEMU.
• Drive the UI — input.* synthesises keyboard and mouse events, so an agent can dismiss a requester or click through a GUI installer. Off by default, and openable only by a deliberate action on the target itself; see SECURITY.md.

143 typed MCP tools across 15 namespaces, 8 live resources, verified end-to-end on QEMU Pegasos2 and real AmigaOne X5000 hardware.

Quick start

Three steps: install the host server, put the daemon on the Amiga, point your MCP client at it.

# 1. Host server (Python 3.11+)
cd host && uv sync            # or: pip install -e .

# 2. Tell it about your machines. The wizard writes a validated
#    config.toml to the platform default location.
uv run amiga-fleet-mcp --init

# 3. Check it can reach them
uv run amiga-fleet-mcp --health-check

The Amiga side needs MCPd running on each target. Either deploy it from the host:

python scripts/install_mcpd_autostart.py <target-ip>:4322

or, on the Amiga itself, grab MCPd-<version>.lha from the latest release:

LhA x MCPd-<version>.lha
Execute MCPd/MCPd-Install

The archive is assembled on AmigaOS, so the protection bits are already correct — extract and the daemon runs. (A raw ELF copied over SMB or a USB stick arrives with the executable bit protected and has to be Protect +rwed-ed by hand.)

Either way MCPd lands in SYS:System/MCPd/, gains a watchdog, and auto-starts on boot. Then register the server with your client — for Claude Code:

claude mcp add amiga-fleet -- amiga-fleet-mcp

Full detail in INSTALL.md; configuration options in USAGE.md.

Documentation

Topic	Document
What you can do with it	USAGE.md
Full command / method / tool reference	COMMANDS.md
Installing pre-built artefacts	INSTALL.md
Setup spec for AI agents	AGENTS_SETUP.md
Building from source	BUILD.md
Host server (Python) — quickstart	host/README.md
Amiga daemon (C) — quickstart and source layout	mcpd/README.md
Change log	CHANGELOG.md
Contributing	CONTRIBUTING.md
Security policy	SECURITY.md
Credits	ACKNOWLEDGEMENTS.md
Licence	LICENSE (BSD-3-Clause)
Third-party dependencies	THIRD_PARTY_LICENSES.md

New here? Read USAGE.md for the architecture and tool surface, then INSTALL.md to install pre-built artefacts or BUILD.md to build from source.

Overview

MCP-AmigaOS4 is a two-piece system:

• amiga-fleet-mcp — a Python MCP server that runs on the user's workstation. It manages a fleet of one or more AmigaOS 4 targets, fans out operations across them in parallel, and bridges to QEMU for lifecycle, snapshots, and GDB.
• MCPd — a small C daemon running on each AmigaOS 4 target. It exposes filesystem, process, system, debug, and Workbench operations as JSON-RPC 2.0 methods over a 4-byte length-prefix framed TCP connection on port 4322, plus a UDP discovery responder on port 4323.

Capabilities

A summary follows; the full list of tools, resources, methods, and helper scripts lives in COMMANDS.md, with narrative context in USAGE.md.

• 143 typed MCP tools across fs.*, exec.*, sys.*, wb.*, debug.*, qemu.*, fleet.*, tests.*, events.wait, app.notify, notify.*, installer.*, serial.*, power.*, sandbox.*, and input.*, plus a namespace dispatcher per group. Every tool takes a target, so the same call works against a QEMU guest or a real machine. (events.subscribe, events.unsubscribe, and events.test_emit are exposed only as daemon RPC methods, not MCP tools — clients call them directly through the transport.)
• Eight live MCP resources for fleet status, per-target system snapshots, capability reports, and serial logs.
• Parallel multi-target operations (fleet.run_on_all, fleet.barrier, fleet.quorum_run, fleet.relay) with optional per-target tag filters.
• LAN-local target discovery (UDP broadcast).
• QEMU lifecycle management plus snapshot save/load/list/delete.
• IDebug-driven per-task introspection: register / memory read and write, symbolicated stack traces, breakpoint control.
• Live system-state reporting: CPU model, caches, AttnFlags, resource probes, mounted volumes, active assigns, library list, public screens, application registry.
• Crash-survivable program and driver iteration (sandbox.*): run a guest ELF or a resident .library / .device inside SandboxVM and get back a structured exit code, a trap classification, and the captured output — without the machine going down with it. Any exec_cmd can also run its program sandboxed, as a tracked job.
• Tracked command jobs (exec.*): status, incremental output, break signals, and a per-call or configured task priority.
• Screen capture to PNG on the target (wb.screenshot) — works on real hardware, where a QMP framebuffer dump is not an option.
• Keyboard and mouse injection (input.*) for driving Workbench and GUI installers, disabled by default at the daemon.
• Server-pushed events (events.subscribe) plus a long-poll alternative (events.wait).
• Auto-start install integration: a single command deploys MCPd to SYS:System/MCPd/, registers a watchdog wrapper, and patches S:Network-Startup. Boot-to-bind is approximately eleven seconds on an AmigaOne X5000. The daemon announces itself in the kernel debug ring once the port is actually accepting connections, so a boot-time start is observable without a Shell — see mcpd/README.md.
• Per-tool parameter defaults via a [defaults] block in config.toml (dest_volume, sources_dir, machine, iso_filename, exec_priority). Set frequently-repeated values once and skip them in subsequent tool calls; explicit per-call values always override. See USAGE.md § Per-tool defaults.
• Native AmigaOS 4.1 FE installer pipeline (installer.*): preflight, ISO mount, recursive copy, LHA extraction, Kicklayout patching, per-machine staged install, and post-install verification.
• Host-side serial-capture service (serial.*): start / stop / tail background captures of a target's debug UART for kernel-debug output during boot or crash investigation.
• Live X5000 hardware introspection (real-hardware only): Cyrus MCU supervisor protocol over UART (sys.mcu_cmd), Freescale QorIQ CCSR reads (sys.read_ccsr), TLB1 dump (sys.tlb_dump), and (with appropriate care) supervisor-mode physical-address reads (sys.read_pa).

Supported targets

Target	Status
QEMU Pegasos2	Verified end to end, including the installer pipeline
QEMU AmigaOne, SAM460ex	Supported
AmigaOne X5000 (Freescale P5020 / E5500)	Verified on hardware, including power.*, the SoC introspection methods, and UI injection
AmigaOne A1222 / Tabor	Supported; board detection and the simplified install path are in place
AmigaOne X1000 / Nemo	Recognised by board detection

sandbox.* needs a machine with ExtMem, so it is available on X5000, A1222, X1000 and QEMU AmigaOne but not on Pegasos2. power.* and the QorIQ introspection methods are real-hardware features by nature.

See INSTALL.md for runtime requirements per target and the auto-start install procedure, or BUILD.md for cross-compiling MCPd from source.

Requirements

Host: Python 3.11, 3.12, or 3.13, on Windows, Linux, or macOS, with git on PATH at install time. The server is built on the mcp 2.x Python SDK. QEMU features additionally need a qemu-system-ppc binary; power.* needs an FTDI USB-TTL cable wired to the target's MCU header; serial.* needs a serial cable to the target's debug UART.

Target: AmigaOS 4.1 Final Edition with TCP/IP (Roadshow) and z.library v53+. The daemon is a single ~300 KiB PowerPC executable with no other dependencies.

Everything degrades per feature rather than per install: a target without the MCU cable simply reports NotCapable for power.* and keeps the rest of the surface. INSTALL.md § Per-feature prerequisites lists what each group needs.

Licence

BSD 3-Clause. Copyright © 2026 Richard Gibbs.

Third-party dependencies retain their own permissive licences; the full index is in THIRD_PARTY_LICENSES.md. See ACKNOWLEDGEMENTS.md for credits.