Appleii Agent

@appleii/mcp试剂

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

它的作用

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

• 管理窗口 --显示、隐藏和聚焦模拟器窗口（BASIC编辑器、CPU调试器、磁盘驱动器等）
• 加载磁盘映像 --从文件系统插入软盘和SmartPort硬盘驱动器映像
• 编写BASIC程序 --读取、编辑Applesoft BASIC程序并将其加载到模拟器中
• 汇编代码 --写入65C02程序集、组装并加载到内存中
• 控制仿真器 --打开/关闭电源、重置、键入文本、管理扩展插槽
• 检查状态 --读取内存、CPU寄存器和仿真器状态

先决条件

• Node.js 18+
• 这 苹果//e模拟器 在浏览器中运行

安装

来自npm

npm install -g @appleii/mcp-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/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

可用工具

模拟器控制

文件操作

服务器管理

沙盒路径

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

配置

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_basic_file - [basic]/program.bas
• save_asm_file - [asm]/code.s
• save_disk_file - [files]/output.bin

环境变量

运作原理

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卡安装在扩展插槽中
• 磁盘工具在加载之前验证文件格式

许可证

麻省理工学院