AI导哈

Apple II 模拟器控制服务器

该MCP服务器通过AG-UI协议连接AI代理与Apple //e浏览器模拟器，实现自然语言控制模拟器操作、文件管理和代码编辑等功能。

  • by mikedaley
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 mikedaley/appleii-agent

使用说明

@retrotech71/appleii试剂

MCP服务器 Apple//e浏览器模拟器 --通过AG-UI协议使用AI代理控制仿真器。

它的作用

此MCP（模型上下文协议）服务器将Claude等AI代理与Apple//e浏览器模拟器连接起来。通过自然语言，代理人可以：

  • 管理窗口 --显示、隐藏和聚焦模拟器窗口（BASIC编辑器、CPU调试器、磁盘驱动器等）
  • 加载磁盘映像 --从文件系统插入软盘和SmartPort硬盘驱动器映像
  • 编写BASIC程序 --读取、编辑Applesoft BASIC程序并将其加载到模拟器中
  • 汇编代码 --写入65C02程序集、组装并加载到内存中
  • 控制仿真器 --打开/关闭电源、重置、键入文本、管理扩展插槽
  • 检查状态 --读取内存、CPU寄存器和仿真器状态
  • 捕捉屏幕 --将显示器（或打印纸）作为可视图像抓取
  • 从模拟器中保存 --将BASIC/ASM源代码、内存、磁盘映像或文件拉回到磁盘
  • 驱动多个模拟器 --一次连接多个浏览器选项卡，并为每个模拟器路由调用

先决条件

安装

来自npm

npm install -g @retrotech71/appleii-agent

来源

git clone https://github.com/mikedaley/appleii-agent.git
cd appleii-agent
npm install

配置

适用于克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%/Claude/claude_desktop_config.json （Windows）：

使用npx（推荐）：

{
  "mcpServers": {
    "appleii-agent": {
      "command": "npx",
      "args": ["-y", "@retrotech71/appleii-agent"]
    }
  }
}

使用bunx：

{
  "mcpServers": {
    "appleii-agent": {
      "command": "bunx",
      "args": ["-y", "@retrotech71/appleii-agent"]
    }
  }
}

来源：

{
  "mcpServers": {
    "appleii-agent": {
      "command": "node",
      "args": ["/absolute/path/to/appleii-agent/src/index.js"]
    }
  }
}

使用自定义沙盒配置位置：

{
  "mcpServers": {
    "appleii-agent": {
      "command": "npx",
      "args": ["-y", "@retrotech71/appleii-agent"],
      "env": {
        "APPLEII_AGENT_SANDBOX": "/path/to/custom/sandbox.config"
      }
    }
  }
}

给Claude代码

编辑 ~/.claude/mcp.json:

使用bunx（推荐）：

{
  "mcpServers": {
    "appleii-agent": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "@retrotech71/appleii-agent"]
    }
  }
}

来源：

{
  "mcpServers": {
    "appleii-agent": {
      "command": "node",
      "args": ["/path/to/appleii-agent/src/index.js"]
    }
  }
}

用法

  1. 在浏览器中启动Apple//e模拟器(npm run dev 在模拟器仓库中）
  2. 打开您的MCP客户端（例如，Claude Code）
  3. 当客户端连接时，MCP服务器会自动启动
  4. 单击模拟器工具栏中的闪烁图标以验证连接（黄色=已连接）

示例提示

Show the CPU debugger window
Load [disks]/ProDOS_2_4_2.dsk into drive 1
Load [zork]/zork1.dsk into drive 2
Write a BASIC program that draws a sine wave
Install the SmartPort card in slot 7
Load [games]/Total_Replay.hdv into SmartPort device 1
Turn on the emulator and boot from disk
Save the BASIC program to [basic]/sinewave.bas

您还可以使用完整路径：

Load ~/Documents/ProDOS.dsk into drive 1
Save assembly code to ~/code/program.s

可用工具

模拟器控制

工具 说明
emma_command 通用命令包装器——委托给任何前端应用程序工具（例如。 showWindow, hideWindow, focusWindow、BASIC/ASM编辑、内存访问）。接受可选 emulator param

窗口管理(showWindow, hideWindow, focusWindow)模拟器中的大多数操作都是前端工具——通过以下方式按名称调用它们 emma_command.

文件操作--加载

工具 说明
load_disk_image 加载软盘映像（.dsk、.do、.po、.nib、.woz）
load_smartport_image 加载SmartPort硬盘驱动器映像（.hdv、.po、.2mg）
load_file 加载任何文件（二进制为base64，文本为纯文本）

文件操作——从模拟器捕获/保存

工具 说明
get_screenshot 通过以下方式捕获屏幕（或打印纸张 source: "printer") → 可视图像
save_to 一步从模拟器源加载内容并将其保存到沙盒路径

save_to 来源(from): basic-editor, asm-editor, basic-memory, file-explorer, disk （驱动器的完整磁盘映像）， memory-range, screen, printer, raw.为 file-explorer/disk, drive 选择Apple II硬盘 1 或 2 （默认值 1).默认为 direct: true （静默保存，仅返回元数据——base64从不发送到LLM）和 overwrite: false.

多仿真器

工具 说明
list_connections 列出所有连接的模拟器，包括名称、状态和默认状态
set_default_emulator 设置没有时哪个仿真器接收呼叫 emulator 参数已给出

与仿真器通信的工具(emma_command, get_screenshot, save_to)接受可选 emulator param：一个名称， "all" 以广播或省略使用默认路由。

服务器管理

工具 说明
server_control 启动、停止、重新启动或检查服务器状态
set_https 切换HTTPS模式
set_debug 切换调试日志记录
get_state 获取当前服务器+模拟器状态
get_version 获取MCP服务器版本信息
reload_sandbox 重新加载sandbox.config而不重新启动
shutdown_remote_server 关闭同一端口上的另一个MCP服务器实例
disconnect_clients 优雅地断开所有连接的模拟器客户端

沙盒路径

沙盒路径为频繁访问的目录提供了方便的快捷方式。您可以在配置文件中定义沙盒，并在所有文件操作中使用它们，而不是键入完整路径。

配置

  1. 创建沙盒配置文件 你喜欢的任何地方（例如。， ~/sandbox.config):
# Apple //e Agent - Sandbox Paths Configuration
# Format: [key]@/path/to/directory

[disks]@~/Documents/Apple2/Disks
[games]@~/Documents/Apple2/Games
[zork]@~/Games/Zork
[basic]@~/Documents/Apple2/BASIC
[files]@~/Documents/Apple2/Files
  1. 设置 APPLEII_AGENT_SANDBOX 环境变量 指向MCP客户端配置中的配置文件（有关示例，请参阅上面的配置部分）。

用法

所有文件加载/保存工具都支持沙盒语法和完整路径：

使用沙盒路径：

Load [disks]/ProDOS.dsk into drive 1
Load [zork]/zork1.dsk into drive 2
Save BASIC program to [basic]/hello.bas
Load [games]/total-replay.hdv into SmartPort device 1

完整路径：

Load ~/Documents/game.dsk into drive 1
Save assembly to ~/code/program.s

支持的工具

沙盒路径适用于：

  • load_disk_image - [disks]/game.dsk
  • load_smartport_image - [games]/hd.hdv
  • load_file - [files]/data.bin
  • save_to - [basic]/program.bas, [asm]/code.s, [files]/output.bin

路径遍历(../)被封锁，以及 save_to 默认为 overwrite: false.

环境变量

变量 默认值 描述
PORT 3033 HTTP服务器端口
HTTPS false 设置为 true 对于HTTPS模式

运作原理

Claude Code ──MCP (stdio)──> MCP Server ──HTTP/SSE──> Browser Emulator
                                  │
                          AG-UI Protocol
                     (event-based, bidirectional)

MCP服务器通过stdio（标准MCP传输）与Claude Code通信，并使用服务器发送事件（AG-UI协议）通过HTTP与浏览器模拟器通信。来自AI代理的工具调用被转发到模拟器前端，模拟器前端执行这些调用并返回结果。

HTTPS模式

对于HTTPS支持：

# Generate self-signed certificate
npm run generate-cert

# Start with HTTPS
HTTPS=true npm start

或者在运行时通过以下方式切换 set_https 工具。

故障排除

MCP服务器无法连接

  • 确保已安装Node.js 18+
  • 检查MCP配置中的路径是否正确
  • 重新启动MCP客户端

模拟器显示断开连接（灰色闪烁）

  • 确保模拟器在浏览器中运行
  • 单击闪耀图标查看连接详细信息
  • 检查端口3033是否未被其他进程使用

回收Apple II代理端口（多个MCP实例）

  • MCP服务器优雅地处理端口冲突，不会失败
  • 使用 server_control 随着行动 status 检查端口是否正在使用中
  • 使用 shutdown_remote_server 通过停止另一个实例来收回端口
  • 关机后，使用 server_control 随着行动 start 在回收的端口上启动此实例
  • 注意：服务器已通过以下方式停止 shutdown_remote_server 只能由其所属的MCP实例重新启动

工具返回错误

  • 模拟器必须通电才能使大多数工具工作
  • SmartPort工具要求将SmartPort卡安装在扩展插槽中
  • 磁盘工具在加载之前验证文件格式

许可证

麻省理工学院

相关 MCP