Amiberry MCP Server

Amiberry MCP服务器

用于控制的MCP（模型上下文协议）服务器 阿米伯里Amiga模拟器，来自任何兼容MCP的AI助手——Claude Desktop、Claude Code、Codex、Gemini（反重力）、Cursor、Cline、Windsurf等。

MCP与客户无关。 此README使用Claude Desktop作为工作示例，因为它的配置路径是众所周知的，但服务器本身通过stdio进行纯MCP通信，并与任何使用该协议的东西一起工作。如果安装程序检测到Claude Desktop、Claude Code、Codex和Gemini/Antigravity，则会自动配置它们；对于其他客户，请向他们指出相同的问题 python -m amiberry_mcp.server 命令（参见 其他MCP客户端 在......下面

特性

核心功能

• 浏览并启动Amiberry配置
• 搜索磁盘映像（ADF、HDF、DMS、LHA、ISO、CUE、CHD）
• 列出并管理存储区
• 查看和编辑配置文件内容
• 启动特定型号的模拟器（A500、A500+、A600、A1200、A4000、CD32、CDTV）
• 用于语音助手（Siri、Google Assistant）和自动化的HTTP API

运行控制

• 暂停/恢复：通过IPC控制运行仿真
• 保存/加载状态：运行时保存和还原状态
• 磁盘交换：将软盘/CD映像插入正在运行的模拟中
• 实时配置：在运行时查询和修改配置选项
• 截图：从运行模拟中捕获屏幕截图
• 键盘输入：发送按键或在模拟中键入文本
• 跨平台：适用于Linux、macOS和FreeBSD

开发/调试功能

• 日志捕获：启动时启用日志记录，并将输出捕获到文件中
• 原木尾矿：增量日志读取和基于模式的等待
• 碰撞检测：通过过程信号和日志扫描自动检测碰撞
• 配置编辑器：解析、修改和创建.uae配置文件
• 保存状态检查器：从.uss保存文件读取元数据
• 固件管理器：通过校验和识别和编目Kickstart ROM
• 内存访问：读取/写入用于调试的模拟Amiga内存

自主故障排除

• 整个生命周期：跟踪、监视、终止和重新启动Amiberry进程
• 健康检查：组合过程+IPC+仿真状态检查
• 启动并等待：启动Amiberry并等待IPC准备好接收命令
• 截图分析：使用返回的图像数据捕获屏幕截图以进行AI分析
• 故障恢复：检测崩溃、分析日志、自动重启

游戏启动器功能

• WHD加载启动器：从LHA档案中搜索并启动WHDLoad游戏
• CD映像启动器：推出具有自动检测功能的CD32/CDTV游戏
• 多磁盘支持：为多磁盘游戏配置磁盘切换器
• 配置模板：从预先制作的模型模板生成配置

需求

• Python 3.10或更高版本
• 已安装Amiberry模拟器：

- macOS：Amiberry.app in /Applications - Linux: amiberry PATH中的命令

• MCP兼容的AI客户端（克劳德桌面、克劳德代码、Codex、双子座/反重力、光标、Cline、风帆等）

项目结构

amiberry-mcp-server/
├── src/
│   └── amiberry_mcp/
│       ├── __init__.py
│       ├── config.py          # Platform detection and paths
│       ├── common.py          # Shared helpers (launch, scan, validation)
│       ├── shared_state.py    # Process state, IPC client caching, launch helpers
│       ├── server.py          # MCP server (80+ tools, data-driven dispatch)
│       ├── http_server.py     # HTTP API server (FastAPI)
│       ├── ipc_client.py      # IPC client with persistent connections
│       ├── uae_config.py      # Config file parser/generator
│       ├── savestate.py       # Savestate metadata parser
│       └── rom_manager.py     # ROM identification
├── scripts/
│   ├── install.sh             # MCP server installer
│   ├── install_http_api.sh    # HTTP API installer
│   ├── start_http_api.sh      # HTTP API launcher
│   ├── uninstall.sh           # Uninstaller
│   └── test_http_api.sh       # HTTP API tests
├── tests/
│   ├── test_server.py         # Server integration tests
│   ├── test_shared_state.py   # Shared state module tests
│   ├── test_mcp_connection.py # MCP protocol tests
│   ├── test_uae_config.py     # Config parser tests
│   ├── test_savestate.py      # Savestate parser tests
│   └── test_rom_manager.py    # ROM manager tests
├── docs/
│   ├── HTTP_API_GUIDE.md      # HTTP API documentation
│   └── QUICKSTART_HTTP_API.md
├── pyproject.toml
├── README.md
└── LICENSE

安装

快速安装（推荐）

# Clone the repository
git clone https://github.com/midwan/amiberry-mcp-server.git
cd amiberry-mcp-server

# Run the installer
./scripts/install.sh

安装程序将：

1. 创建Python虚拟环境
2. 安装依赖项
3. 自动检测和配置以下任何一种：克劳德桌面、克劳德代码、Codex、双子座（反重力）

其他MCP客户端（Cursor、Cline、Windsurf等）不是自动配置的——请参阅 其他MCP客户端 以便将代码片段粘贴到他们的配置中。

手动安装

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install the package
pip install -e .

# Configure your MCP client manually (see below)

客户端配置

所有MCP客户端最终都需要相同的两件事：启动命令及其参数。对于此服务器：

克劳德桌面版

编辑您的Claude Desktop配置文件：

macOS：

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Linux：

nano ~/.config/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "amiberry": {
      "command": "/path/to/amiberry-mcp-server/venv/bin/python",
      "args": ["-m", "amiberry_mcp.server"]
    }
  }
}

然后重新启动Claude Desktop。

其他MCP客户端

相同的 command / args pair适用于任何stdio MCP客户端。将等效条目粘贴到：

• 克劳德代码 — ~/.claude.json （安装程序会自动处理此问题）
• 法典 — ~/.codex/config.toml，作为a [mcp_servers.amiberry] 块（安装程序处理此问题）
• 双子座/反重力 — ~/.gemini/antigravity/mcp_config.json （安装程序处理此问题）
• 光标 — ~/.cursor/mcp.json （或 .cursor/mcp.json 项目内部）
• 坚持/继续/风帆 --查看每个客户端的MCP设置UI；相同的命令/args
• MCP还知道什么 --指向它 python -m amiberry_mcp.server 通过stdio

验证

安装后，重新启动AI客户端。您应该看到Amiberry MCP工具可用（通常显示为工具/锤子图标，在 /mcp 或者在客户的工具检查器中）。

试着问你的助手：

• “我有什么Amiberry配置？”
• “显示我的磁盘映像”
• “推出A500型号的Amiberry”

默认目录结构

macOS

~/Documents/Amiberry/
├── Configurations/    # .uae config files
├── Floppies/         # .adf, .adz, .dms files
├── Harddrives/       # .hdf, .hdz files
├── Lha/              # .lha archives (WHDLoad games)
├── Savestates/       # .uss savestate files
├── Screenshots/
├── Kickstarts/       # Kickstart ROM files
└── logs/             # Captured log files

Linux

~/Amiberry/
├── conf/             # .uae config files
├── floppies/         # .adf, .adz, .dms files
├── harddrives/       # .hdf, .hdz files
├── lha/              # .lha archives (WHDLoad games)
├── savestates/       # .uss savestate files
├── screenshots/
├── kickstarts/       # Kickstart ROM files
└── logs/             # Captured log files

~/.config/amiberry/   # System configs (optional)

可用的MCP工具

核心工具

配置工具

启动工具

媒体工具

分析工具

运行时控制工具

仿真控制

媒体控制

状态管理

音频控制

显示控制

声音控制

操纵杆/输入控制

软盘控制

显示控制（附加）

输入控制（附加）

硬件/芯片组控制

内存配置

窗口/显示控制

WHD负载控制

调试和诊断

实例控制

状态

配置

输入控制

效用

流程生命周期管理

内存访问

运行时配置

截图分析

原木尾部和碰撞检测

工作流程自动化

注： 运行时控制需要Amiberry构建 USE_IPC_SOCKET=ON

使用示例

基本用法

问你的AI助手：

• “列出我的Amiberry配置”
• “显示所有工作台磁盘映像”
• “推出A1200型号的Amiberry”
• “我有什么专长？”
• “查找包含“野兽的阴影”的磁盘映像”

WHDLoad游戏

• “启动WHDLoad游戏《Turrican》”
• “搜索名称中包含‘Adventure’的WHDLoad游戏”

CD32/CDTV游戏

• “列出我的CD映像”
• “从/path/to/game.iso启动CD32游戏”

配置管理

• “解析我的A500配置文件并显示内存设置”
• “使用8MB快速RAM创建新的A1200配置”
• “在我的游戏配置中将软盘速度更改为800”

调试

• “在启用日志记录的情况下启动Amiberry”
• “显示上次捕获的日志文件”
• “我有什么ROM可用？”
• “检查我昨天的财产”

保存状态分析

• “我的存储空间使用的是什么CPU和芯片组？”
• “显示“野兽之影”保存库中的元数据”

运行控制

• “暂停模拟”
• “截取当前状态的屏幕截图”
• “将游戏状态保存到checkpoint.us”
• “快速保存到插槽0”
• “从插槽1快速加载”
• “将磁盘2插入驱动器DF0”
• “从驱动器0弹出软盘”
• “列出所有软盘驱动器中的内容”
• “列出已装载的硬盘驱动器”
• “当前仿真状态如何？”
• “将软盘速度设置为800”
• “将音量设置为50%”
• “将音频静音”
• “切换全屏模式”
• “启用扭曲模式”
• “切换到NTSC模式”
• “将显示设置为全屏模式”
• “将声音模式设置为立体声”
• “获取操纵杆端口0模式”
• “将端口0设置为操纵杆模式”
• “在端口0上启用自动点火”
• “获取LED状态”
• “前进一帧”
• “Amiberry的版本是什么？”
• “Ping Amiberry检查连接”
• “将软盘速度设置为最大”
• “目前的FPS是多少？”
• “切换RTG显示”
• “切换到AGA芯片组”
• “CPU的速度是多少？”
• “将CPU设置为最大速度”
• “显示内存配置”
• “切换鼠标抓取”
• “保护驱动器0中的磁盘”
• “将芯片RAM设置为2MB”
• “将快速RAM设置为8MB”
• “使用的是哪种CPU型号？”
• “切换到68030 CPU”
• “将窗口大小设置为800x600”
• “将缩放模式设置为线性”
• “将线模式设置为扫描线”
• “切换到招聘决议”
• “启用自动拖放”
• “是否启用自动拖放？”
• “加载Turrican WHDLoad游戏”
• “加载了什么WHDLoad游戏？”
• “弹出WHDLoad游戏”

键盘输入

• “按空格键”
• “键入'dir'并按Return键”
• “按F1”
• “新闻逃逸”
• “按住Ctrl键并按C键”
• 键入“list”，然后按Enter键

调试和诊断

• “激活调试器”
• “调试器状态如何？”
• “单步10指令”
• “继续执行”
• “停用调试器”
• “显示CPU寄存器”
• “在地址0xFC0000处进行拆解”
• “获取自定义芯片寄存器”
• “在0x400处设置断点”
• “列出所有断点”
• “清除0x400处的断点”
• “清除所有断点”
• “获得铜州”
• “获得布利特州”
• “获取软盘驱动器0状态”
• “获取音频通道状态”
• “获取DMA状态”

HTTP API

通过REST API控制Amiberry，用于语音助手和自动化。

快速开始

# Install HTTP API dependencies
./scripts/install_http_api.sh

# Start the server
./scripts/start_http_api.sh

API运行于 http://localhost:8080.查看文档 http://localhost:8080/docs.

示例命令

Siri/语音：

• “嘿Siri，启动Amiga 500”
• “嘿Siri，拦住Amiberry”

卷曲：

# Basic operations
curl -X POST http://localhost:8080/quick-launch/A500
curl -X POST http://localhost:8080/stop
curl http://localhost:8080/configs

# Launch with logging
curl -X POST http://localhost:8080/launch-with-logging \
  -H "Content-Type: application/json" \
  -d '{"model": "A500"}'

# Create a config
curl -X POST "http://localhost:8080/configs/create/my-config?model=A1200"

# Launch WHDLoad game
curl -X POST "http://localhost:8080/launch-whdload?search=Turrican"

# Launch CD image
curl -X POST http://localhost:8080/launch-cd \
  -H "Content-Type: application/json" \
  -d '{"cd_path": "/path/to/game.iso"}'

# Inspect savestate
curl http://localhost:8080/savestates/mysave.uss/inspect

# List ROMs
curl http://localhost:8080/roms

# Runtime control (requires Amiberry with USE_IPC_SOCKET=ON)
curl http://localhost:8080/runtime/status
curl -X POST http://localhost:8080/runtime/pause
curl -X POST http://localhost:8080/runtime/resume
curl -X POST http://localhost:8080/runtime/screenshot \
  -H "Content-Type: application/json" \
  -d '{"filename": "/tmp/screenshot.png"}'
curl -X POST http://localhost:8080/runtime/insert-floppy \
  -H "Content-Type: application/json" \
  -d '{"drive": 0, "image_path": "/path/to/disk2.adf"}'
curl -X POST http://localhost:8080/runtime/eject-floppy \
  -H "Content-Type: application/json" \
  -d '{"drive": 0}'
curl http://localhost:8080/runtime/list-floppies

# Audio control
curl http://localhost:8080/runtime/volume
curl -X POST http://localhost:8080/runtime/volume \
  -H "Content-Type: application/json" \
  -d '{"volume": 50}'
curl -X POST http://localhost:8080/runtime/mute
curl -X POST http://localhost:8080/runtime/unmute

# Display control
curl -X POST http://localhost:8080/runtime/fullscreen
curl http://localhost:8080/runtime/warp
curl -X POST http://localhost:8080/runtime/warp \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Display mode (0=window, 1=fullscreen, 2=fullwindow)
curl http://localhost:8080/runtime/display-mode
curl -X POST http://localhost:8080/runtime/display-mode \
  -H "Content-Type: application/json" \
  -d '{"mode": 1}'

# Video mode (PAL/NTSC)
curl http://localhost:8080/runtime/ntsc
curl -X POST http://localhost:8080/runtime/ntsc \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Sound mode (0=off, 1=normal, 2=stereo, 3=best)
curl http://localhost:8080/runtime/sound-mode
curl -X POST http://localhost:8080/runtime/sound-mode \
  -H "Content-Type: application/json" \
  -d '{"mode": 2}'

# Quick save/load (slots 0-9)
curl -X POST http://localhost:8080/runtime/quicksave \
  -H "Content-Type: application/json" \
  -d '{"slot": 0}'
curl -X POST http://localhost:8080/runtime/quickload \
  -H "Content-Type: application/json" \
  -d '{"slot": 0}'

# Joystick port control (port 0-3, mode: 0=default, 2=mouse, 3=joy, 7=cd32)
curl http://localhost:8080/runtime/joyport/0
curl -X POST http://localhost:8080/runtime/joyport \
  -H "Content-Type: application/json" \
  -d '{"port": 0, "mode": 3}'

# Autofire control (0=off, 1=normal, 2=toggle, 3=always)
curl http://localhost:8080/runtime/autofire/0
curl -X POST http://localhost:8080/runtime/autofire \
  -H "Content-Type: application/json" \
  -d '{"port": 0, "mode": 1}'

# Status
curl http://localhost:8080/runtime/led-status
curl http://localhost:8080/runtime/harddrives

# Floppy speed control
curl http://localhost:8080/runtime/floppy-speed
curl -X POST http://localhost:8080/runtime/floppy-speed \
  -H "Content-Type: application/json" \
  -d '{"speed": 800}'

# Disk write protection
curl http://localhost:8080/runtime/disk-write-protect/0
curl -X POST http://localhost:8080/runtime/disk-write-protect \
  -H "Content-Type: application/json" \
  -d '{"drive": 0, "protected": true}'

# RTG and status line
curl -X POST http://localhost:8080/runtime/toggle-rtg
curl -X POST http://localhost:8080/runtime/toggle-status-line

# FPS monitoring
curl http://localhost:8080/runtime/fps

# Mouse grab
curl -X POST http://localhost:8080/runtime/toggle-mouse-grab
curl http://localhost:8080/runtime/mouse-speed

# Chipset control
curl http://localhost:8080/runtime/chipset
curl -X POST http://localhost:8080/runtime/chipset \
  -H "Content-Type: application/json" \
  -d '{"chipset": "AGA"}'

# CPU speed
curl http://localhost:8080/runtime/cpu-speed
curl -X POST http://localhost:8080/runtime/cpu-speed \
  -H "Content-Type: application/json" \
  -d '{"speed": -1}'

# Memory configuration
curl http://localhost:8080/runtime/memory-config

# Memory management (changes require reset)
curl -X POST http://localhost:8080/runtime/chip-mem \
  -H "Content-Type: application/json" \
  -d '{"size_kb": 2048}'
curl -X POST http://localhost:8080/runtime/fast-mem \
  -H "Content-Type: application/json" \
  -d '{"size_kb": 8192}'
curl -X POST http://localhost:8080/runtime/slow-mem \
  -H "Content-Type: application/json" \
  -d '{"size_kb": 512}'
curl -X POST http://localhost:8080/runtime/z3-mem \
  -H "Content-Type: application/json" \
  -d '{"size_mb": 64}'

# CPU model
curl http://localhost:8080/runtime/cpu-model
curl -X POST http://localhost:8080/runtime/cpu-model \
  -H "Content-Type: application/json" \
  -d '{"model": 68030}'

# Window size
curl http://localhost:8080/runtime/window-size
curl -X POST http://localhost:8080/runtime/window-size \
  -H "Content-Type: application/json" \
  -d '{"width": 800, "height": 600}'

# Scaling mode (-1=auto, 0=nearest, 1=linear, 2=integer)
curl http://localhost:8080/runtime/scaling
curl -X POST http://localhost:8080/runtime/scaling \
  -H "Content-Type: application/json" \
  -d '{"mode": 1}'

# Line mode (single, double, scanlines)
curl http://localhost:8080/runtime/line-mode
curl -X POST http://localhost:8080/runtime/line-mode \
  -H "Content-Type: application/json" \
  -d '{"mode": "scanlines"}'

# Resolution (lores, hires, superhires)
curl http://localhost:8080/runtime/resolution
curl -X POST http://localhost:8080/runtime/resolution \
  -H "Content-Type: application/json" \
  -d '{"mode": "hires"}'

# Autocrop
curl http://localhost:8080/runtime/autocrop
curl -X POST http://localhost:8080/runtime/autocrop \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# WHDLoad
curl http://localhost:8080/runtime/whdload
curl -X POST http://localhost:8080/runtime/whdload \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/game.lha"}'
curl -X DELETE http://localhost:8080/runtime/whdload

# Debugging and Diagnostics
curl -X POST http://localhost:8080/runtime/debug/activate
curl http://localhost:8080/runtime/debug/status
curl -X POST http://localhost:8080/runtime/debug/step \
  -H "Content-Type: application/json" \
  -d '{"count": 10}'
curl -X POST http://localhost:8080/runtime/debug/continue
curl -X POST http://localhost:8080/runtime/debug/deactivate
curl http://localhost:8080/runtime/cpu/regs
curl http://localhost:8080/runtime/custom/regs
curl -X POST http://localhost:8080/runtime/disassemble \
  -H "Content-Type: application/json" \
  -d '{"address": "0xFC0000", "count": 10}'
curl http://localhost:8080/runtime/breakpoints
curl -X POST http://localhost:8080/runtime/breakpoints \
  -H "Content-Type: application/json" \
  -d '{"address": "0x400"}'
curl -X DELETE http://localhost:8080/runtime/breakpoints \
  -H "Content-Type: application/json" \
  -d '{"address": "ALL"}'
curl http://localhost:8080/runtime/copper/state
curl http://localhost:8080/runtime/blitter/state
curl "http://localhost:8080/runtime/drive/state?drive=0"
curl http://localhost:8080/runtime/audio/state
curl http://localhost:8080/runtime/dma/state

# Keyboard input
curl -X POST http://localhost:8080/runtime/key \
  -H "Content-Type: application/json" \
  -d '{"keycode": 64, "state": 1}'   # Press SPACE (keycode 64)
curl -X POST http://localhost:8080/runtime/key \
  -H "Content-Type: application/json" \
  -d '{"keycode": 64, "state": 0}'   # Release SPACE

# Type text into emulation
curl -X POST http://localhost:8080/runtime/type \
  -H "Content-Type: application/json" \
  -d '{"text": "dir\n", "delay_ms": 50}'

# Utility
curl http://localhost:8080/runtime/version
curl http://localhost:8080/runtime/ping

API终点

核心终点

配置端点

启动端点

媒体端点

分析终点

运行时控制端点

仿真控制

媒体控制

状态管理

音频控制

显示控制

声音控制

操纵杆/输入控制

软盘控制

显示控制（附加）

输入控制（附加）

硬件/芯片组控制

内存配置

窗口/显示控制

WHD负载控制

调试和诊断

状态

配置

输入控制

效用

注： 运行时端点需要Amiberry构建 USE_IPC_SOCKET=ON

看 docs/HTTP_API_GUIDE.md文件 以获取完整的文档。

自动启动

macOS：

launchctl load ~/Library/LaunchAgents/com.amiberry.httpapi.plist

Linux：

systemctl --user enable amiberry-http-api.service
systemctl --user start amiberry-http-api.service

发展

# Clone and setup
git clone https://github.com/midwan/amiberry-mcp-server.git
cd amiberry-mcp-server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install with dev dependencies
pip install -e ".[all]"

# Run tests
pytest tests/ -v

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

故障排除

MCP工具未出现在您的客户端中

• 完全重新启动MCP客户端（退出并重新打开）——大多数客户端仅在启动时加载MCP服务器
• 检查 command 客户端配置中的路径指向此项目的 venv/bin/python
• 验证虚拟环境是否存在(ls venv/bin/python)
• 跑 python -m amiberry_mcp.server 直接——它应该等待stdio输入。如果出现错误，请先修复。
• 检查客户的MCP日志：

- 克劳德桌面（macOS）： ~/Library/Logs/Claude/mcp*.log - 克劳德代码： claude mcp list 然后检查服务器的stderr - 光标：查看→ 输出→ “MCP”频道

“找不到命令”错误

• Linux：确保 amiberry 在你的路径中
• macOS：验证Amiberry.app是否在 /Applications

权限错误

• 检查脚本是否可执行： chmod +x scripts/*.sh

查看捕获的Amiberry日志

# macOS
ls ~/Documents/Amiberry/logs/

# Linux
ls ~/Amiberry/logs/

运行时控制不起作用

• 确保Amiberry是用 USE_IPC_SOCKET=ON （CMake选项）
• 检查插座是否存在： ls /tmp/amiberry.sock （或 $XDG_RUNTIME_DIR/amiberry.sock 在Linux上）
• 在使用运行时控制工具之前，请验证Amiberry是否正在运行
• 直接测试插座： echo "GET_STATUS" | nc -U /tmp/amiberry.sock

卸载

./scripts/uninstall.sh

贡献

欢迎投稿！请打开问题或拉取请求。

许可证

GPL-3.0许可证-请参阅 许可证 文件。

资源

• MCP文件
• Amiberry项目
• FastAPI文档