🍏 macOS Computer Use (MCP Server)

Сверхбыстрый нативный Model Context Protocol (MCP)-сервер, который предоставляет LLM и автономным агентам полную визуальную инспекцию и возможности автоматизации рабочего стола в macOS без перехвата вашей физической мыши или фокуса клавиатуры.

Создан на основе скомпилированного ядра Swift с использованием нативных CoreGraphics, Vision OCR (VNRecognizeTextRequest) от Apple и прямой маршрутизации событий на уровне процессов (CGEvent.postToPid).

⚡ Ключевые особенности

• 🎯 Apple Vision OCR со временем менее 30 мс (find_text / click_text): Никаких слепых угадываний координат $(x, y)$. Агент находит кнопки, надписи и текстовые плейсхолдеры по имени с попиксельной точностью благодаря ускорению Apple Neural Engine.

• 🛡️ Ненавязчивое фоновое выполнение: Отвязан от глобальных перехватчиков аппаратных событий macOS. Клики, прокрутка и нажатия клавиш могут направляться напрямую в конкретные PID приложений, пока вы продолжаете работать в своей IDE или браузере.

• 👁️ Оверлей виртуального курсора (mark_cursor): Целевые координаты агента визуально отображаются на кадрах скриншота (голубое целевое кольцо + пульсирующая пурпурная точка) без перемещения вашей физической мыши на экране.

• ⚡ Реактивная синхронизация интерфейса (wait_for_text): Заменяет слепые таймауты sleep() высокоскоростным циклом опроса OCR, который срабатывает сразу, как только появляются динамические выпадающие списки автодополнения, модальные окна или изменения состояния.

• 🖼️ Захват экрана с изоляцией окна: Аккуратно захватывает буферы целевого приложения в фоне (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