🍏 macOS Computer Use (MCP Server)

一个超快、原生的 模型上下文协议（MCP） 服务器，为 LLM 和自主智能体提供完整的视觉检查和桌面自动化能力，且 不会劫持你的物理硬件鼠标或键盘焦点。

基于编译的 Swift 核心构建，利用 Apple 原生的 CoreGraphics、Vision OCR（VNRecognizeTextRequest） 以及直接的进程级事件路由（CGEvent.postToPid）。

⚡ 主要亮点

• 🎯 低于 30ms 的 Apple Vision OCR（find_text / click_text）：无需盲猜 $(x, y)$ 坐标。智能体通过名称即可找到按钮、标签和文本占位符，并借助 Apple Neural Engine 加速实现像素级精度。

• 🛡️ 非侵入式后台执行：与全局 macOS 硬件事件监听解耦。点击、滚动和按键可以直接定向到特定应用的 PID，同时你可以继续在 IDE 或浏览器中工作。

• 👁️ 虚拟光标叠加层（mark_cursor）：智能体的目标坐标会被可视地绘制到截图帧上（青色目标环 + 洋红色脉冲点），而不会在屏幕上移动你的物理鼠标。

• ⚡ 响应式 UI 同步（wait_for_text）：用高速 OCR 轮询循环取代盲目的 sleep() 超时，一旦动态自动补全下拉框、模态框或状态变化出现，立即得到解析。

• 🖼️ 窗口隔离截屏：在后台干净地捕获目标应用缓冲区（screencapture -l <wid> -o -x），不会把窗口带到前台，也不会捕获重叠的窗口。

🛠️ 暴露的工具

🚀 安装与设置

1. 前提条件

• macOS 13.0+（Apple Silicon 或 Intel）

• Node.js 18+

• Xcode Command Line Tools（用于编译原生 Swift 二进制文件）：

  xcode-select --install

2. 克隆与构建

git clone https://github.com/johnexzy/macos-computer-use.git
cd macos-computer-use
npm install

（postinstall 脚本会自动将 native_helper.swift 编译为优化的原生二进制文件）。

🔒 必需的 macOS 权限

要允许桌面捕获和输入模拟，请在 系统设置 > 隐私与安全性 中为你的宿主应用（Terminal、iTerm2、Antigravity、Cursor 或 VS Code）授予权限：

1. 屏幕与系统音频录制：screenshot 和视觉 OCR 所必需。

2. 辅助功能：mouse_click、type_text 和 press_key 所必需。

🔌 MCP 配置

将此服务器添加到你的 MCP 客户端配置中：

Antigravity / Claude Desktop / Cursor / Windsurf

添加到你的 mcp_config.json / claude_desktop_config.json 中：

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "node",
      "args": ["/absolute/path/to/macos-computer-use/server.mjs"]
    }
  }
}

🧪 直接测试原生 Swift 辅助程序

你可以直接从终端测试原生二进制文件：

# Display resolution and scaling
./native_helper size

# List active Chrome windows in Z-order
./native_helper list_windows "Google Chrome"

# Find a button or text on screen with Apple Vision OCR in ~30ms
./native_helper find_text "Search" "Google Chrome"

# Reactively wait for dynamic text to appear
./native_helper wait_for_text "quantum" "Google Chrome" nil 5.0

📄 许可证

MIT © John Oba