macOS Ghost Control MCP (computer-control-mcp)

面向 macOS 的高性能、无感视觉闭环与 自愈式 SOP（Standard Operating Procedure） 桌面控制 MCP 服务端。支持 Claude Desktop、Cursor、Google Antigravity、Windsurf 等所有兼容 Model Context Protocol (MCP) 的 AI Agent 客户端。

核心特性

1. 1x 逻辑分辨率防遮挡截图与网格对齐（Zero Retina Offset）

   • 底层基于 screencapture -x -o -l <wid> 与 Quartz 窗口帧缓冲，自动将 Retina 2x 物理像素归一化为 1x 逻辑坐标空间，并叠加 100px 辅助网格，彻底解决 macOS 多屏与高分屏点击偏移问题。

2. Codex 风格常驻平滑虚拟光标 + 自动渐隐（Visual Collaborator Cursor）

   • 执行过程中提供带状态胶囊徽章（● AI / ● CLICK / ● TYPE / ● SCROLL / ● KEY）的 NSPanel 点击穿透虚拟指针，以三阶缓动（Cubic Ease-Out）平滑滑行展示 AI 操作轨迹，任务序列结束时自动 0.18s 渐隐消失。

3. 零物理鼠标争抢（Zero Mouse Contention）

   • 支持纯后台 PID 注入与极速 teleport 硬件注入双模式；用户鼠标空闲守卫：区分本驱动合成事件与用户真实事件，用户正在移动/按住鼠标时绝不 warp（等待或抛 UserBusyError）；点击后仅在用户未动鼠标时复位。

   • 虚拟光标采用会话心跳：任务期间常驻（长时间 OCR 等待也不闪隐），任务结束立即渐隐；MCP 进程崩溃 2.5s 内自动隐藏；守护进程带协议版本号，升级后自动替换。

4. 混合感知通用泛化（AX + OCR + 弹层）

   • perception.py：AXUIElement 控件树（Electron 自动开启 AXManualAccessibility，可 AXPress 零鼠标点击）+ RapidOCR（小区域 Retina 物理像素识别）+ kCGWindowLayer>0 弹层窗口感知，统一为窗口相对坐标的 UIElement。

   • 通用定位打分替代应用专属像素硬编码：分组锚点（section）、规避分组（网络搜索/聊天记录）、查询回显联想簇识别、排除输入框自身；fail-safe：最佳候选可疑时拒绝而非误选。

   • select_item 列表选择：keyboard 策略用方向键 + 高亮行帧差分定位，高亮落在目标行才回车（不动鼠标）；click / ax / enter 策略可选。

   • expect 后置条件：text / absent_text / popup / window_size_unchanged，每步证明"生效了"。

5. 闭环自愈 SOP 引擎（sop_engine.py）

   • 快速路径 expect 失败 → recover 重放前置步骤 → alternatives → 其它选择策略 / target 语义重定位 / heal_region → 整个 SOP 跑通后自动写回模板（保留 {{参数}}、版本 +1、changelog + 每步 heal_history、旧版归档 sops/.history/、统计写 sops/.state/）。

   • 不可逆步骤（"idempotent": false，如"回车发送"）绝不自动重试；vacuous 检测防止"动作前条件已成立"造成的假阳性。

Related MCP server: macbot-mcp

目录结构

computer-control-mcp/
├── src/computer_control_mcp/
│   ├── core.py                 # MCP 工具注册入口
│   ├── macos_ghost_driver.py   # Quartz/AppKit 输入注入、截图、鼠标空闲守卫、虚拟光标守护进程
│   ├── perception.py           # AX + OCR + 弹层混合感知、通用定位打分、高亮行检测
│   ├── interaction.py          # 语义动作、expect 后置校验、自愈 run_step
│   ├── sop_engine.py           # SOP 渲染 / 执行 / 自动写回 / 归档 / 统计
│   ├── sop_cli.py              # computer-control-sop 命令行
│   ├── server.py               # MCP 标准 stdio 服务启动入口
│   └── cli.py                  # CLI 命令行入口
├── sops/                       # 可自愈、可热更新的声明式 SOP 剧本库
│   ├── wechat_send_message.json
│   ├── youtube_search_and_play.json
│   └── activity_monitor_top_processes.json
├── skills/macos-computer-use/  # 通用视觉泛化与 SOP 自愈 Agent Skill (适配 Antigravity / Claude)
│   └── SKILL.md
├── .cursor/rules/              # Cursor 专属自动加载规则
│   └── macos-computer-use.mdc
└── scripts/
    └── install_macos.sh        # macOS 一键环境构建与配置脚本

快速开始（macOS 一键安装）

git clone <your-repo-url> computer-control-mcp
cd computer-control-mcp
chmod +x scripts/install_macos.sh
./scripts/install_macos.sh

安装脚本会自动创建 .venv、安装全部依赖、挂载全局 Skill，并在终端输出可直接粘贴到 ~/.cursor/mcp.json 或 claude_desktop_config.json 的配置片段。

系统权限要求

请在 系统设置 -> 隐私与安全性 中为运行客户端（如 Cursor、Terminal、Antigravity 或 Claude）开启：

• 辅助功能（Accessibility）：用于发送 Quartz 键鼠事件。

• 屏幕录制（Screen & System Audio Recording）：用于无遮挡窗口截图与本地 RapidOCR 识别。

核心 MCP 工具一览

SOP 命令行

computer-control-sop list
computer-control-sop run wechat_send_message -p target_contact=文件传输助手 -p message_text=你好
computer-control-sop run wechat_send_message --dry-run -p ...      # 只渲染不执行
computer-control-sop inspect 微信 --region 0 0 420 600            # 打印 AX/OCR 元素

测试

.venv/bin/python -m pytest tests/test_self_healing.py -q   # 离线：定位打分 / 高亮差分 / SOP 写回

License

MIT License