Agentbridge

AgentBridge

让 AI 与 Classic Mac 对话。

AgentBridge 是一款原生 Classic Mac OS 应用，可让 AI Agent（如 Claude）通过结构化命令和响应与 Mac OS 7–9 交互。它可在真实硬件和模拟器上运行，无需修改 Mac。

将 AgentBridge 放入共享文件夹，在 Mac 上启动它，AI Agent 就能列出窗口、打开应用、输入文本、读取剪贴板、浏览文件等，所有操作都通过简单的文本协议完成。

工作原理

┌──────────────────────┐
│    Claude / AI Agent │
│         │            │
│    MCP Protocol      │
│         │            │
│    MCP Server (Node) │
│         │            │
│    Shared Folder I/O │
└────────┬─────────────┘
         │  reads/writes text files
         │
    ┌────┴──────────────────────────┐
    │  Shared Volume (NAS / AFP /   │
    │  SMB / emulator extfs)        │
    │                               │
    │  AgentBridge-MyMac/           │
    │  ├── inbox/   ← commands in   │
    │  ├── outbox/  ← responses out │
    │  ├── assets/  ← file staging  │
    │  └── heartbeat                │
    └────┬──────────────────────────┘
         │
┌────────┴─────────────────────────┐
│  Classic Mac OS 7 / 8 / 9        │
│                                  │
│  AgentBridge.app                 │
│  - Polls inbox for commands      │
│  - Executes via Mac Toolbox      │
│  - Writes responses to outbox    │
│  - Heartbeat every 2 seconds     │
└──────────────────────────────────┘

传输方式只是一个文件夹。如何在 AI 和 Mac 之间共享该文件夹，由你决定：

• NAS／文件服务（AFP 或 SMB）——多台 Mac 和你的现代电脑都挂载同一个共享目录
• 模拟器共享文件夹——BasiliskII 和 SheepShaver 都支持共享主机目录
• 任何其他共享文件系统——只要双方都能读取和写入文件，就能正常工作

无需 SSH，无需特殊驱动，也无需修改 Mac 系统。AgentBridge 是一个普通应用——启动它，退出它，就这么简单。

MCP 工具参考

MCP 服务会向 AI Agent 暴露以下工具。如果设备群中只有一个目标，所有工具的 target 参数均为可选。

系统与状态

classic_mac_list_targets 列出所有已配置的 Classic Mac 目标及其状态（心跳存活／失效）。 无参数。

classic_mac_ping 健康检查——如果 AgentBridge 正在响应，则返回 pong。

参数	必填	说明
target	否	目标 ID 或别名

classic_mac_heartbeat 读取心跳文件——显示运行时间、前台应用、可用内存和时间戳。

参数	必填	说明
target	否	目标 ID 或别名

classic_mac_get_about 系统信息——操作系统版本、机器类型、RAM、可用内存和运行时间。

参数	必填	说明
target	否	目标 ID 或别名

窗口与进程

classic_mac_list_windows 枚举所有应用中的可见窗口。返回窗口索引、标题、边界（左、上、右、下）以及前／后层级。

参数	必填	说明
target	否	目标 ID 或别名

classic_mac_get_front_window 获取最前方窗口的详细信息——标题、边界和所属应用。

参数	必填	说明
target	否	目标 ID 或别名

classic_mac_list_processes 列出正在运行的应用及其名称、创建者代码、PID 和内存分区。

参数	必填	说明
target	否	目标 ID 或别名

菜单

classic_mac_list_menus 列出最前方应用的菜单栏条目。

参数	必填	说明
target	否	目标 ID 或别名

classic_mac_get_menu_items 按名称获取指定菜单中的条目。

参数	必填	说明
target	否	目标 ID 或别名
menu	是	菜单标题（例如 "File"、"Edit"）

classic_mac_menu_select 按名称激活菜单项。适用于带有键盘快捷键的菜单项。

参数	必填	说明
target	否	目标 ID 或别名
menu	是	菜单标题
item	是	菜单项名称

鼠标和键盘

classic_mac_click 在屏幕坐标处单击。

参数	必填	描述
target	否	目标 ID 或别名
x	是	X 坐标（距左侧的像素数）
y	是	Y 坐标（距顶部的像素数）
clicks	否	单击次数（默认值为 1，双击请使用 2）

classic_mac_mouse_move 移动光标，不执行单击。

参数	必填	描述
target	否	目标 ID 或别名
x	是	X 坐标
y	是	Y 坐标

classic_mac_mouse_drag 从一个点单击并拖动到另一个点。

参数	必填	描述
target	否	目标 ID 或别名
x1	是	起点 X 坐标
y1	是	起点 Y 坐标
x2	是	终点 X 坐标
y2	是	终点 Y 坐标

classic_mac_type_text 在最前端的应用程序中输入一段文本。

参数	必填	描述
target	否	目标 ID 或别名
text	是	要输入的文本

classic_mac_key_press 按下单个按键，可选带修饰键。

参数	必填	描述
target	否	目标 ID 或别名
key	是	按键名称：单个字符，或 return、enter、tab、space、delete、escape、left、right、up、down、home、end、pageup、pagedown、f1–f5
modifiers	否	以逗号分隔：cmd、opt、shift、ctrl（例如 "cmd,shift"）

剪贴板

classic_mac_get_clipboard 读取当前剪贴板中的文本内容。

参数	必填	描述
target	否	目标 ID 或别名

classic_mac_set_clipboard 设置剪贴板中的文本内容。

参数	必填	描述
target	否	目标 ID 或别名
text	是	要放入剪贴板的文本

应用程序控制

classic_mac_launch_app 通过 HFS 路径或创建者代码启动应用程序。

参数	必填	描述
target	否	目标 ID 或别名
path	否*	HFS 路径（例如 "Macintosh HD:Applications:SimpleText"）
creator	否*	4 个字符的创建者代码（例如 "ttxt"）

*必须提供 path 或 creator 其中之一。

classic_mac_activate_app 将正在运行的应用程序切换到最前端。

参数	必填	描述
target	否	目标 ID 或别名
name	是	应用程序名称

classic_mac_quit_app 向正在运行的应用程序发送退出 Apple Event。

参数	必填	描述
target	否	目标 ID 或别名
name	是	应用程序名称

classic_mac_send_appleevent 向正在运行的应用程序发送通用 Apple Event。

参数	必填	描述
target	否	目标 ID 或别名
app	是	目标应用程序名称或 4 个字符的创建者代码
event	是	事件类型：oapp、quit

文件和宗卷

classic_mac_get_volumes 列出所有已装载宗卷的名称、可用空间和总容量。

参数	必填	描述
target	否	目标 ID 或别名

classic_mac_list_folder 通过 HFS 路径列出文件夹内容。返回名称、类型代码、创建者代码、大小以及每个项目是否为文件夹。

参数	必填	描述
target	否	目标 ID 或别名
path	是	HFS 路径（例如 "Macintosh HD:System Folder:"）

兼容性

环境	架构	操作系统版本	状态
68k Macs	68k	System 7.0–8.1	✅ 已在 System 7.6.1 上测试
PowerPC Macs	PowerPC	Mac OS 8.5–9.2.2	可构建，未经测试
BasiliskII	68k	System 7.0–8.1	✅ 已在 System 7.6.1 上测试
SheepShaver	PowerPC	Mac OS 8.5–9.2.2	可构建，未经测试

AgentBridge 需要 System 7.0 或更高版本（以支持 Apple Events）。

快速开始

预构建二进制文件

从 Releases 页面下载：

• AgentBridge-68k.bin — 适用于 68k Macs 的 MacBinary（System 7–8.1）
• AgentBridge-68k.dsk — 适用于 68k Macs 的 HFS 磁盘映像（System 7–8.1）
• AgentBridge-ppc.bin — 适用于 PowerPC Macs 的 MacBinary（OS 8.5–9.2.2）
• AgentBridge-ppc.dsk — 适用于 PowerPC Macs 的 HFS 磁盘映像（OS 8.5–9.2.2）

设置

1. 创建一个共享文件夹，让你的 Mac 和现代计算机都能访问。可以是 NAS 共享目录、模拟器的主机目录，或任何共享文件系统。

2. 在共享文件夹内创建目录结构：

   AgentBridge/
   └── AgentBridge-YourMacName/
       ├── inbox/
       ├── outbox/
       └── assets/
   

3. 将 AgentBridge 复制到该文件夹中，与 inbox/outbox/assets 并列。

4. **在 Classic Mac 上启动 AgentBridge。**它会自动找到自己的文件夹，并开始轮询命令。

5. 从现代计算机发送测试命令：

   printf "BRIDGE 1.0.1\rSEQ 00001\rCMD ping\rTS 20260308T170000\r---\r" > /path/to/shared/AgentBridge-YourMacName/inbox/C00001.msg
   

6. 读取响应：

   cat /path/to/shared/AgentBridge-YourMacName/outbox/R00001.msg | tr '\r' '\n'
   

   你应该会看到 RESULT pong 和 STATUS ok。

多台 Mac

每台 Mac 都有自己的子文件夹，并在其中放置各自的 AgentBridge 副本：

NAS Share/
└── AgentBridge/
    ├── AgentBridge-SE30/          ← Mac SE/30 running System 7
    │   ├── AgentBridge (app)
    │   ├── inbox/
    │   ├── outbox/
    │   └── assets/
    ├── AgentBridge-G4/            ← Power Mac G4 running OS 9
    │   ├── AgentBridge (app)
    │   ├── inbox/
    │   ├── outbox/
    │   └── assets/
    └── AgentBridge-BasiliskII/    ← Emulator
        ├── AgentBridge (app)
        ├── inbox/
        ├── outbox/
        └── assets/

AgentBridge 会将自身的启动位置用作工作目录，无需配置。

MCP 服务

MCP 服务会将 AgentBridge 命令作为工具提供给 Claude 等 AI Agent。它是一个通过 stdio（标准 MCP 传输）通信的 Node.js TypeScript 服务。

通过 npm 安装

npm install -g classic-mac-mcp

或者直接使用 npx 运行（无需安装）：

npx -y classic-mac-mcp --config /path/to/fleet.json

从源代码安装

git clone https://github.com/SeanFDZ/agentbridge.git
cd agentbridge
npm install
npm run build

配置

创建 fleet.json 文件，指定你的共享文件夹：

{
  "fleet": [
    {
      "id": "my-classic-mac",
      "alias": "Classic Mac",
      "arch": "68k",
      "os_version": "7.6.1",
      "shared_folder": "/Volumes/NASShare/AgentBridge/AgentBridge-MyMac"
    }
  ]
}

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "classic-mac": {
      "command": "npx",
      "args": ["-y", "classic-mac-mcp", "--config", "/path/to/fleet.json"]
    }
  }
}

或者，如果你是从源代码安装的：

{
  "mcpServers": {
    "classic-mac": {
      "command": "node",
      "args": ["/path/to/agentbridge/dist/server.js", "--config", "/path/to/agentbridge/config/fleet.json"]
    }
  }
}

协议

AgentBridge 使用面向行的键值文本协议，以适应 Classic Mac 的限制：

• 不使用 JSON — 约 50 行 C 代码即可解析，无需动态内存分配
• 使用 CR 换行符（Classic Mac 原生格式）
• 使用 MacRoman 文本编码（由 MCP 服务转换为 UTF-8）
• 消息最大为 32KB
• 文件名为 C00001.msg（命令）和 R00001.msg（响应）

命令格式

命令是写入 inbox/ 目录的文本文件，文件名为 C{seq}.msg（例如 C00001.msg）。序列号以 5 位数字补零。

BRIDGE 1.0.1
SEQ 00042
CMD list_windows
TS 20260308T153022
---

所有行都是 KEY value 键值对，并以单独一行的 --- 作为结束标记。换行符为 CR（0x0D，Classic Mac 原生格式）。文本编码为 MacRoman（MCP 服务会处理 UTF-8 转换）。多行文本在 TEXT 键之后使用 + 续行。消息最大为 32KB。

响应格式

响应以 R{seq}.msg 文件的形式出现在 outbox/ 目录中，序列号与命令相同。AgentBridge 处理完命令后会删除命令文件；MCP 服务读取响应后会删除响应文件。

BRIDGE 1.0.1
SEQ 00042
STATUS ok
COUNT 2
WINDOW 1|?|Untitled|10,40,400,300|front
WINDOW 2|?||0,0,640,480|back
TS 20260308T153022
---

STATUS 的值为 ok 或 error。发生错误时，ERRCODE 和 ERRMSG 字段会提供详细信息。多值响应（窗口、进程、卷、文件、菜单项）使用重复键（WINDOW、PROCESS、VOLUME、FILEENTRY、MENUBAR、MENUITEM），字段之间以竖线分隔。

心跳

AgentBridge 每隔约 2 秒在其工作目录中写入一个 heartbeat 文件：

BRIDGE 1.0.1
UPTIME 218
TICKS 240498
FRONTAPP Finder
FREEMEM 4096
TS 20260308T173113
---

MCP 服务会监控心跳文件的修改时间，以判断 AgentBridge 是否正在运行。

从源代码构建

git clone https://github.com/SeanFDZ/agentbridge.git
cd agentbridge
npm install
npm run build

需要 Node.js 20+。

AgentBridge 二进制文件可作为预构建下载文件获取，且不提供源代码。

项目结构

agentbridge/
├── src/                            # MCP server (TypeScript, GPLv3)
│   ├── server.ts                   # MCP tool definitions and handlers
│   ├── fleet.ts                    # Fleet registry
│   ├── types.ts                    # Type definitions
│   └── bridge/
│       └── client.ts               # Shared folder I/O client
└── config/
    └── fleet.json                  # Fleet configuration

设计原则

不依赖主机端。 AgentBridge 完全通过 Mac Toolbox 执行操作。它不会使用 SSH、屏幕捕获，也不会在主机操作系统层面注入输入。因此，它在真实硬件和模拟器上的运行方式完全相同。

不修改系统。 AgentBridge 是一个普通应用程序。它不会修改你的 System Folder、安装扩展或更改启动配置。启动它、退出它、删除它，你的 Mac 都不会受到影响。

与传输方式无关。 协议只是在文件夹中的文本文件。该文件夹如何共享（NAS、AFP、SMB、模拟器 extfs、USB 驱动器、信鸽）不属于 AgentBridge 的职责范围。

遵循协作式多任务处理。 AgentBridge 每个周期都会通过 WaitNextEvent() 让出 CPU。其他应用可以正常运行。

无状态命令。 每条命令都是独立完整的。即使 MCP 服务崩溃并重启，Mac 端也无需知晓。

致谢

AgentBridge 1.0.1 Sean Lavigne © 2026 Falling Data Zone, LLC

使用 Wolfgang Thaller 开发的 Retro68 构建。

Falling Data Zone 的其他项目

MacMind — 一个完全用 HyperTalk 实现的单层 Transformer 神经网络，在 Macintosh SE/30 上训练并运行。这证明 1987 年的脚本语言也能实现机器学习。

更多应用请访问 apps.fallingdata.zone。

许可证

本项目包含两个采用不同许可证的组件：

MCP 服务（TypeScript，src/ 目录）——GNU General Public License v3.0——可依据 GPL 条款免费使用、修改和分发。

AgentBridge.app（Classic Mac 应用程序，源代码位于 classic-mac-src/）——修改版 PolyForm Noncommercial 1.0.0。© 2026 Falling Data Zone, LLC。可下载预构建二进制文件。

协议——本 README 中记载的 AgentBridge 协议为开放协议。