DarwinRelay

面向 MCP 代理的原生 macOS 执行运行时：shell、PTY、后台 Chrome 以及基于辅助功能的桌面控制。

DarwinRelay 将 MCP 客户端连接到您正在使用的 Mac。它在客户端与 macOS 之间不插入另一个模型循环的情况下，暴露结构化的本机能力：不受限制的 shell/文件系统访问、交互式 PTY、长时间运行的作业、持久化的 Codex 历史记录、受管理的后台 Chrome 工作区，以及通过 Accessibility、ScreenCaptureKit、Vision 和 CoreGraphics 实现的原生桌面控制。

[!CAUTION] DarwinRelay 故意设计得功能强大。它不是沙箱，也不实现文件系统或 shell 命令白名单。连接的客户端可以以运行桥接器的 macOS 用户的有效权限行事。在将其暴露到 localhost 之外之前，请阅读 SECURITY.md。

为什么选择 DarwinRelay

许多 MCP 服务器只暴露一个狭窄的 API。DarwinRelay 被设计为面向开发者和计算机使用工作流的本地执行运行时，在这些工作流中，有用的状态已经存在于 Mac 上：

• Shell 和文件 — 运行命令、检查或修改文件、应用补丁以及管理本地进程。

• 真正的 PTY — 交互式 shell、REPL、SSH、sudo 提示、TUI 和长时间运行的终端程序。

• 原生计算机使用 — 语义化 AX 查询/操作、窗口、对话框、打开/保存面板、键盘/鼠标回退、截图、OCR 和视觉等待。

• 后台浏览器自动化 — 一个专用的 Chrome 扩展拥有的标签页池，可以导航、检查、填写和点击，而不会经常抢占焦点。

• Codex 历史记录 — 读取持久化的 Codex 线程，而无需开始新的模型回合。

• 远程 MCP 传输 — 本地 stdio，或通过您控制的隧道使用附带的经过身份验证的 HTTP/OAuth 前端。

• 故障关闭生命周期 — 显式的完全访问解锁、审计日志、进程回收、单例菜单所有权和可回滚感知的应用更新。

Related MCP server: mcp-server-macos-use

架构

flowchart LR
    A[MCP client] --> B[DarwinRelay bridge]
    B --> C[Shell / filesystem / jobs]
    B --> D[PTY helper]
    B --> E[Codex persisted history]
    B --> F[MacUIHelper]
    F --> G[Accessibility / ScreenCaptureKit / Vision / CGEvent]
    B --> H[Chrome native host]
    H --> I[DarwinRelay Chrome extension]
    I --> J[Background DR tab pool]

原生桌面助手被刻意设计为短生命周期，而不是特权守护进程。菜单应用、MacUIHelper 和虚拟光标使用稳定的代码签名标识符，以便在存在持久签名身份时，macOS TCC 授权能够经受住正常的重新构建。

系统要求

• macOS 13 或更新版本

• Node.js 18 或更新版本（CI 中使用 Node.js 22）

• 用于原生桌面控制和菜单应用的 Xcode Command Line Tools / swiftc

• 原生计算机使用需要辅助功能和屏幕录制权限

• 仅当您需要受管理的 chrome_* 后台工作区时才需要 Google Chrome

• 仅当您远程暴露 HTTP 传输时才需要 cloudflared 或其他 HTTPS 隧道

• 仅当您需要 codex_thread_* 历史记录工具时才需要 Codex CLI

快速开始

克隆仓库并构建菜单应用：

git clone https://github.com/dcierra/darwinrelay.git
cd darwinrelay
npm run check
./menubar/build.sh
open /Applications/DarwinRelay.app

该应用以 DR 的形式出现在 macOS 菜单栏中。授予所需的桌面权限，然后使用 Start 启动您已配置的 HTTP/隧道路径。

对于仅限源代码的本地 MCP 使用，也可以直接运行桥接器。必须明确确认完全访问权限：

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

默认运行时状态位于：

~/Library/Application Support/DarwinRelay
~/Library/Logs/DarwinRelay

使用环境变量（如 DARWINRELAY_DATA_DIR、DARWINRELAY_LOG_DIR、DARWINRELAY_SHELL 和 DARWINRELAY_AUDIT_MODE）来隔离开发/测试实例。

面向 AI 和编码代理

本仓库有意包含面向代理的文档。如果您将仓库交给 Codex、Claude、ChatGPT 或其他编码代理，请首先让它阅读 AGENTS.md。该文件描述了仓库地图、不变量、开发命令、测试预期、签名/浏览器规则和发布约束。

对于操作已安装的 DarwinRelay 运行时而非修改源代码的代理，请使用 docs/AGENT_OPERATIONS.md。它包含完整的工具族地图、首选决策顺序、常见故障状态和安全运行时工作流。docs/ARCHITECTURE.md 描述了组件/数据流和信任边界，以便进行更深入的推理。

原生桌面控制

DarwinRelay 优先使用语义化辅助功能操作，并以视觉/原始输入作为回退。核心能力包括：

• ui_observe、ui_tree、ui_ax_query、ui_ax_at

• 带有陈旧引用检测的指纹化 AX 引用

• ui_action、ui_wait_for、ui_assert

• ui_app_*、ui_window_*、对话框和文件面板

• ScreenCaptureKit 截图和 Vision OCR

• 在 macOS 支持的情况下，后台 PID 定向输入，带有语义验证和有界的前台回退

• ui_sequence 用于确定性的多步原生突发操作

• 一个可点击穿透的虚拟 AI 光标，不会移动物理指针

有关控制模型和限制，请参阅 docs/DESKTOP_CONTROL.md。

后台 Chrome 工作区

DarwinRelay 使用未打包的 Chrome 扩展以及 Native Messaging。公共扩展标识是稳定的；预期的扩展 ID 是：

pfhahlehpahegefejooendokpkklgmgd

安装程序默认创建或重用一个名为 DarwinRelay 的已退出登录的本地 Chrome 配置文件。这会将代理的浏览状态与日常 Google 配置文件分开：

# Recommended/default: dedicated local profile named DarwinRelay
./scripts/install-background-chrome.sh

# Explicit alternatives only when you want them
./scripts/install-background-chrome.sh --profile 'Some Existing Profile'
./scripts/install-background-chrome.sh --use-current-profile

默认配置文件的创建不会删除或修改其他配置文件中的浏览数据。如果 DarwinRelay 配置文件尚不存在，请在运行安装程序前退出 Chrome 一次，这样 Chrome 就无法同时重写其 Local State；配置文件存在后，正常的重新安装可以在 Chrome 打开时运行。卸载 DarwinRelay 会故意保留该配置文件，因为浏览器配置文件内容是用户数据。

然后，仅在所选配置文件中，打开 chrome://extensions，启用开发者模式，选择 Load unpacked，并选择此仓库的 chrome-extension/ 目录。您可以向安装程序传递 --open 以完成此一次性设置步骤。

该扩展拥有一个名为 DR 的 Chrome 原生标签页组。常规的 chrome_open 调用会租用预先创建的空闲标签页，而不是创建任意的前台标签页。chrome_close 会将工作区标签页返回到池中。

浏览器安全模型

默认采用宽松审批。通过配置的 chrome_* 工作区进行的常规 HTTP/HTTPS 工作不需要按站点的终端授权。在菜单应用中启用 Strict approvals 会恢复范围限定的 URL 授权和一次性应用范围的原生变更审批。

通过 shell/AppleScript/JXA 直接自动化 Chrome 仍会被桥接器阻止，因此常规 Web 工作保持在受管理的后台路径上。当浏览器/操作系统安全表面确实需要时，单独的原生 ui_* 表面仍可以与前台 Chrome UI 交互。

在 DARWINRELAY_ADVANCED_BROWSER=1 后面存在一个可选的原始 Browser Harness/CDP 适配器。它默认禁用，并在 Strict approvals 下故障关闭，因为任意 CDP 无法被合理地缩减到 URL 范围。

HTTP / OAuth 传输

mcp-http.mjs 绑定到回环地址，并支持带有静态 bearer 令牌以及远程 MCP 客户端使用的 OAuth 2.1 流程的 MCP HTTP 传输。Cloudflare 等隧道可以通过 HTTPS 发布回环服务。

一个最小的本地前端如下所示：

mkdir -p "$HOME/Library/Application Support/DarwinRelay"
openssl rand -hex 32 > "$HOME/Library/Application Support/DarwinRelay/http-token"
chmod 600 "$HOME/Library/Application Support/DarwinRelay/http-token"

export DARWINRELAY_HTTP_TOKEN_FILE="$HOME/Library/Application Support/DarwinRelay/http-token"
node mcp-http.mjs

在阅读 SECURITY.md 中的远程访问威胁模型之前，不要暴露 HTTP 端点。此前端接受的凭据最终将决定是否以您的桌面用户身份执行本地代码。

本仓库还保留了从原始项目继承的 OpenAI Secure MCP Tunnel 安装程序，供喜欢该传输方式的用户使用。请参阅 DEPLOY.md。

开发

npm run check
npm run test:core
npm run test:desktop
npm run test:lifecycle
# or all groups
npm test

公共 CI 有意暴露单独的检查，而不是一个不透明的 test 作业：

• 静态检查 — 语法/原生构建验证和全历史 gitleaks 扫描

• 核心与协议测试 — MCP、HTTP/OAuth、PTY、联合、浏览器和对抗性测试

• 桌面控制测试 — 确定性桌面协议测试以及原生 fixture 编译

• 安装与生命周期测试 — 安装程序、自动启动、单例所有权、回滚和卸载行为

真正的可变 AppKit E2E 需要已登录且具有 TCC 权限的 Mac，因此在一次性的 GitHub 托管 GUI 会话中不被视为可靠。维护者可以在本地运行它：

DARWINRELAY_RUN_NATIVE_DESKTOP_E2E=1 node tests/desktop-control-native.mjs

在打开拉取请求之前，请参阅 CONTRIBUTING.md。

安全

重要的边界很简单：DarwinRelay 拥有运行它的 macOS 账户的权限。 解锁文件、Strict approvals、审计元数据、OAuth、后台浏览器路由和进程回收等安全功能可减少意外或远程滥用；它们不会将任意 shell 访问变成沙箱。

安全报告应使用 GitHub 的私有漏洞报告，而不是公开 issue。请参阅 SECURITY.md。

项目渊源

DarwinRelay 由独立维护，并且已与 Alexander Rådahl Benz 的 Mac Developer Bridge 产生了显著分歧。继承的上游历史被有意保留，原始 MIT 版权声明仍保留在 LICENSE 中。有关确切的渊源和署名政策，请参阅 UPSTREAM.md。

公共的 dcierra/darwinrelay 仓库是规范的开发源。之前的私有仓库仅作为临时的旧版生产/回滚渊源保留，直到已安装的 0.5.x 运行时迁移完成；它不是第二个活跃的开发分支。有关提交历史映射和未来工作流，请参阅 docs/DEVELOPMENT_MODEL.md。

DarwinRelay 与 OpenAI、Apple、Google、Cloudflare 或上游维护者无关联，也未获得其认可。

许可证

MIT。请参阅 LICENSE 和 UPSTREAM.md。