macos-ui-mcp

Una herramienta estilo Playwright que permite a Claude inspeccionar y controlar la interfaz de una app nativa de macOS mientras la construyes — sin permiso de Grabación de Pantalla.

En lugar de capturar la pantalla, la app se renderiza a sí misma. Un pequeño paquete Swift solo para depuración (swift-harness/) expone el árbol de vistas de la app y un renderizador PNG en proceso a través de HTTP en localhost; un servidor MCP (src/) convierte eso en herramientas que Claude puede llamar: list_windows, get_ui_tree, screenshot, click, type, wait_for, invoke_action.

Consulta IDEA.md para conocer la justificación del diseño, la comparación de arquitecturas y los objetivos del proyecto.

Claude Code ──MCP(stdio)──> macos-ui-mcp server ──HTTP──> AppMCPHarness (in your app, DEBUG only)

Estructura

Related MCP server: Desktop Pilot MCP

Cómo usarlo

1. Añade el harness a tu app de macOS (solo builds DEBUG)

Consulta swift-harness/README.md. Una línea en tu AppDelegate:

#if DEBUG
AppMCP.start()   // opens http://127.0.0.1:8787
#endif

2. Compila el servidor MCP

npm install
npm run build

3. Regístralo con Claude Code

// .mcp.json
{
  "mcpServers": {
    "macos-ui-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/macos-ui-mcp/dist/index.js"],
      "env": { "MACOS_UI_MCP_HARNESS_URL": "http://127.0.0.1:8787" }
    }
  }
}

Ahora, con tu app ejecutándose en un build de depuración, pide a Claude que llame a get_ui_tree o screenshot — sin aviso de Grabación de Pantalla.

Desarrollo

npm test           # 38 unit tests, no real app needed (mock harness); e2e is skipped
npm run typecheck
npm run dev         # run the server against a live harness

npm run test:e2e    # builds showcase/, launches it, runs the real tools against the
                    # real Swift harness. Needs a logged-in macOS GUI session.

npm run test:e2e es la prueba de los objetivos: verifica que get_ui_tree ve los controles, que screenshot devuelve un PNG real en proceso, y que click / type cambian la interfaz en vivo — sin permiso de Grabación de Pantalla.

Gramática de selectores

Usada por click, type, screenshot, wait_for:

click / type rechazan selectores ambiguos (más de una coincidencia) e informan los ids candidatos.

Estado

• v0.1 — macOS / AppKit. Las 7 herramientas implementadas. 38 pruebas unitarias + una prueba de extremo a extremo de 5 casos que controla la app showcase/ a través del harness Swift real. Verificado: árbol, captura PNG en proceso, toque, establecimiento de texto, hooks de acción — Grabación de Pantalla desactivada.

• Aún no — árbol nativo de SwiftUI (solo introspección de AppKit por ahora), adaptador de Windows, inspección de apps de terceros mediante la API de Accesibilidad.

Licencia

MIT © 2026 Thang Duong