🍏 macOS Computer Use (MCP Server)

Ein ultraschneller nativer Model Context Protocol (MCP)-Server, der LLMs und autonomen Agenten vollständige visuelle Inspektion und Desktop-Automatisierungsfunktionen unter macOS bietet, ohne Ihre physische Hardware-Maus oder den Tastaturfokus zu übernehmen.

Entwickelt mit einem kompilierten Swift-Kern, der Apples native CoreGraphics, Vision OCR (VNRecognizeTextRequest) und direkte Ereignisweiterleitung auf Prozessebene (CGEvent.postToPid) nutzt.

⚡ Hauptmerkmale

• 🎯 Sub-30-ms Apple Vision OCR (find_text / click_text): Kein blindes Raten von $(x, y)$-Koordinaten. Der Agent findet Schaltflächen, Beschriftungen und Textplatzhalter anhand des Namens mit Pixelgenauigkeit mithilfe der Apple Neural Engine-Beschleunigung.

• 🛡️ Nicht-intrusive Hintergrundausführung: Entkoppelt von globalen macOS-Hardware-Ereignis-Taps. Klicks, Scrolls und Tastatureingaben können direkt an bestimmte Anwendungs-PIDs gerichtet werden, während Sie weiterhin in Ihrer IDE oder Ihrem Browser arbeiten.

• 👁️ Virtuelles Cursor-Overlay (mark_cursor): Die Zielkoordinaten des Agenten werden visuell auf Screenshot-Frames gezeichnet (cyanfarbener Zielring + magentafarbener pulsierender Punkt), ohne Ihre physische Maus auf dem Bildschirm zu bewegen.

• ⚡ Reaktive UI-Synchronisierung (wait_for_text): Ersetzt blinde sleep()-Timeouts durch eine Hochgeschwindigkeits-OCR-Abfrageschleife, die auflöst, sobald dynamische Autovervollständigungs-Dropdowns, Modals oder Zustandsänderungen erscheinen.

• 🖼️ Fensterisolierte Bildschirmaufnahme: Erfasst Zielanwendungs-Puffer sauber im Hintergrund (screencapture -l <wid> -o -x), ohne das Fenster in den Vordergrund zu bringen oder überlappende Fenster zu erfassen.

🛠️ Verfügbare Tools

🚀 Installation & Einrichtung

1. Voraussetzungen

• macOS 13.0+ (Apple Silicon oder Intel)

• Node.js 18+

• Xcode Command Line Tools (zum Kompilieren des nativen Swift-Binärs): GXP1

2. Klonen & Erstellen

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

(Das postinstall-Skript kompiliert native_helper.swift automatisch zu einem optimierten nativen Binär.)

🔒 Erforderliche macOS-Berechtigungen

Um Desktop-Erfassung und Eingabesimulation zu ermöglichen, erteilen Sie Ihrer Host-Anwendung (Terminal, iTerm2, Antigravity, Cursor oder VS Code) Berechtigungen unter Systemeinstellungen > Datenschutz & Sicherheit:

1. Bildschirm- & Systemaudioaufnahme: Erforderlich für screenshot und visuelle OCR.

2. Bedienungshilfen: Erforderlich für mouse_click, type_text und press_key.

🔌 MCP-Konfiguration

Fügen Sie diesen Server zu Ihrer MCP-Client-Konfiguration hinzu:

Antigravity / Claude Desktop / Cursor / Windsurf

Fügen Sie Folgendes zu Ihrer mcp_config.json / claude_desktop_config.json hinzu:

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

🧪 Testen des nativen Swift-Helfers direkt

Sie können das native Binär direkt von Ihrem Terminal aus testen:

# 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

📄 Lizenz

MIT © John Oba