🍏 macOS Computer Use (MCP Server)

Un servidor Model Context Protocol (MCP) ultrarrápido y nativo que brinda a los LLM y agentes autónomos capacidades completas de inspección visual y automatización de escritorio en macOS sin secuestrar el enfoque de tu ratón físico o teclado.

Construido con un núcleo Swift compilado que aprovecha los CoreGraphics nativos de Apple, Vision OCR (VNRecognizeTextRequest) y el enrutamiento directo de eventos a nivel de proceso (CGEvent.postToPid).

⚡ Características principales

• 🎯 Apple Vision OCR en menos de 30 ms (find_text / click_text): Sin adivinación ciega de coordenadas $(x, y)$. El agente encuentra botones, etiquetas y marcadores de texto por nombre con precisión de píxel usando la aceleración del Apple Neural Engine.

• 🛡️ Ejecución en segundo plano no intrusiva: Desacoplado de los taps de eventos de hardware globales de macOS. Los clics, desplazamientos y pulsaciones de teclas pueden dirigirse directamente a PIDs de aplicaciones específicas mientras sigues trabajando en tu IDE o navegador.

• 👁️ Superposición de cursor virtual (mark_cursor): Las coordenadas objetivo del agente se dibujan visualmente en los fotogramas de la captura de pantalla (anillo objetivo cian + punto de pulso magenta) sin mover tu ratón físico en la pantalla.

• ⚡ Sincronización reactiva de la interfaz de usuario (wait_for_text): Reemplaza los tiempos de espera ciegos de sleep() con un bucle de sondeo OCR de alta velocidad que se resuelve en el instante en que aparecen los menús desplegables de autocompletado dinámicos, modales o cambios de estado.

• 🖼️ Captura de pantalla aislada por ventana: Captura los búferes de la aplicación objetivo limpiamente en segundo plano (screencapture -l <wid> -o -x) sin traer la ventana al frente ni capturar ventanas superpuestas.

🛠️ Herramientas expuestas

🚀 Instalación y configuración

1. Requisitos previos

• macOS 13.0+ (Apple Silicon o Intel)

• Node.js 18+

• Xcode Command Line Tools (para compilar el binario nativo de Swift):

xcode-select --install

2. Clonar y compilar

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

(El script postinstall compila automáticamente native_helper.swift en un binario nativo optimizado).

🔒 Permisos requeridos de macOS

Para permitir la captura de escritorio y la simulación de entrada, concede a tu aplicación anfitriona (Terminal, iTerm2, Antigravity, Cursor o VS Code) permisos en System Settings > Privacidad y seguridad:

1. Grabación de pantalla y audio del sistema: Requerida para screenshot y OCR visual.

2. Accesibilidad: Requerida para mouse_click, type_text y press_key.

🔌 Configuración de MCP

Añade este servidor a la configuración de tu cliente MCP:

Antigravity / Claude Desktop / Cursor / Windsurf

Añádelo a tu mcp_config.json / claude_desktop_config.json:

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

🧪 Probando el Helper nativo de Swift directamente

Puedes probar el binario nativo directamente desde tu terminal:

# 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

📄 Licencia

MIT © John Oba