desktop-hub

Un servidor MCP de fachada compacto para la automatización de escritorio en macOS. Expone solo 10 herramientas escritas a mano (~2,3k tokens de definiciones) y actúa como proxy diferido hacia dos servidores MCP de uso de computadora con todas las funciones: cua-driver (56 herramientas, ~37k tokens) y computer-use-mcp (64 herramientas, ~21k tokens), además del osascript nativo. Conservas toda la superficie de 120 herramientas, pero tu ventana de contexto paga ~2k tokens en lugar de ~58k.

中文说明在下方 · Espejo Gitee 国内镜像 · Funciona con Claude Code y cualquier cliente MCP.

Por qué

Registrar ambos servidores upstream directamente cuesta ~58k tokens de contexto por sesión solo en definiciones de herramientas, mientras que la superficie de uso frecuente es pequeña. Esta fachada mantiene el camino caliente barato y la cola larga alcanzable:

MCP client ──stdio──> desktop-hub (this server, 10 compact tools)
                        ├─ lazy stdio child ──> cua-driver mcp        (background desktop control, no cursor/focus steal)
                        ├─ lazy stdio child ──> computer-use-mcp      (AX tree, find_element, fill_form, Spaces…; spawned on first use)
                        └─ local osascript                            (AppleScript/JXA, true background scripting)

Related MCP server: Computer Use MCP Server

Herramientas

Requisitos previos

• macOS (Apple Silicon o Intel), Node.js 18+ (desarrollado en Node 26).

• cua-driver — el driver de macOS del proyecto trycua/cua (libs/cua-driver). Instálalo con su one-liner oficial, que coloca CuaDriver.app en /Applications y crea el enlace simbólico ~/.local/bin/cua-driver (exactamente la ruta predeterminada de este hub — sin configuración necesaria):

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

  Documentación: https://cua.ai/docs/how-to-guides/driver/install. Probado con cua-driver 0.20.0 (cua-driver --version); si act/verify devuelven errores de herramienta desconocida tras una actualización del driver, ejecuta primero desk_describe server:cua para comparar la superficie de herramientas.

• computer-use-mcp no requiere instalación manual — npx obtiene @zavora-ai/computer-use-mcp@7.0.0 automáticamente en el primer desk_call server:"oss" (acceso de red único; unos segundos de latencia de arranque a partir de entonces — el tiempo de espera del handshake ya está ampliado a 180s). Los usuarios en China continental pueden querer configurar un espejo del registro npm.

Permisos de macOS

• Concede Accesibilidad y Grabación de pantalla (Ajustes del Sistema → Privacidad y seguridad) a CuaDriver.app — ejecuta cua-driver permissions grant para que los diálogos se atribuyan a la identidad de la app (los permisos sobreviven entonces a las actualizaciones). Sin ellos, cada llamada de captura/AX falla con errores opacos.

• Concede los mismos dos a tu terminal / app host de MCP — el backend oss se ejecuta como un proceso hijo node normal del host y hereda su identidad TCC.

• run_script activa el aviso único de Automatización (Apple Events) de macOS por app objetivo en el primer uso.

Instalación y registro

git clone https://github.com/zty552252kevin-code/desktop-hub.git
cd desktop-hub
npm ci        # not `npm install` — the code relies on SDK 1.30.0 internals pinned in the lockfile
claude mcp add desktop-hub -s user -- node "$(pwd)/server.mjs"   # path must be absolute

Espejo para China continental (mantenido en sincronía): git clone https://gitee.com/zty552252kevin/desktop-hub.git

Solo si previamente registraste cua-driver o computer-use-mcp como servidores MCP independientes: desactiva esas entradas (p. ej. disabledMcpServers en ~/.claude.json) para que este hub tome el control. Las instalaciones nuevas se saltan este paso.

Verificación

npm test                        # 20 checks; spawns the real driver and runs osascript on your desktop
DESKTOP_HUB_TEST_OSS=1 npm test # also exercises the oss backend (slow first npx spawn, needs network)

La suite requiere cua-driver instalado con permisos concedidos — los fallos sin ellos son problemas de configuración, no errores del hub.

Variables de entorno

Notas de diseño y trampas (ganadas a pulso)

• Los backends que se bloquean se expulsan automáticamente y se reinician en la siguiente llamada (vía client.onclose — transport.onclose es sobrescrito por el SDK). Backends colgados: la llamada falla con RequestTimeout y el backend se mata y reinicia; la ruta listTools de desk_describe también expulsa. Todas las expulsiones están protegidas por generación para que un onclose tardío de un proceso antiguo nunca pueda eliminar un cliente recién reiniciado (lo que lo dejaría huérfano y perdería todos los element_token).

• La salida del host (EOF de stdin / SIGTERM / SIGINT) propaga el apagado a ambos backends, limitado a 5s — un arranque en frío de npx a mitad de handshake no puede mantener vivo un hub sin host durante la ventana de handshake de 180s; los hijos aún conectándose reciben kill forzado.

• La cancelación del lado del host (p. ej. Esc en Claude Code) aborta de verdad: la señal de aborto se enhebra en el callTool upstream y mata al hijo osascript, de modo que un clic/script en cola nunca llega al escritorio real después de cancelar.

• act: double_click/right_click/set_value/menu requieren pid (requisito duro upstream — element_token solo no basta); doble clic a nivel de escritorio = action:"click" + extra:{count:2}. scope:"desktop" no debe llevar pid/window_id — la fachada los elimina automáticamente. El drag/scroll por píxeles en apps multi-ventana necesita window_id o upstream lo rechaza como ambiguo. El scroll sin objetivo (solo pid) envía teclas de flecha/PageDown al control enfocado — pasa element_token o x,y para hacer scroll con rueda en un punto concreto.

• Los espacios de coordenadas difieren entre backends: desktop_screenshot devuelve píxeles reales de pantalla (2x en Retina) — correcto para cua scope:"desktop"; las herramientas de puntero oss vía desk_call usan puntos lógicos (1x). Divide por el factor de escala devuelto, o toma las coordenadas de desk_call oss screenshot.

• run_script: el idioma no distingue mayúsculas y los valores desconocidos se rechazan con un error claro; la salida por encima de 1MB/stream se drena (el script se ejecuta hasta el final, los efectos secundarios intactos) mientras que el cuerpo devuelto se recorta a 8KB con una nota de bytes descartados; el CJK multibyte nunca se divide entre fragmentos de pipe.

• Las apps SwiftUI (p. ej. Calculadora) pueden incrustar caracteres invisibles (U+200E) en los valores mostrados — value_equals de verify devuelve entonces unknown; usa label_contains o lee el markdown de window_state en su lugar.

• Revisado de forma adversaria en dos rondas multi-agente (21 + 20 revisores, 28 defectos confirmados corregidos — la ronda 2 detectó dos regresiones introducidas por las correcciones de la ronda 1). Suite de regresión en test/smoke.mjs.

Herramientas de terceros

desktop-hub es una fachada que lanza dos herramientas desarrolladas de forma independiente como procesos de servidor MCP separados; no están incluidas en este repositorio y las instalas tú por separado:

• cua-driver (CuaDriver.app, com.trycua.driver) — MIT, © Cua AI, Inc. — https://github.com/trycua/cua

• @zavora-ai/computer-use-mcp — MIT, © Zavora Technologies Ltd. — https://github.com/zavora-ai/computer-use-mcp

"cua", "CuaDriver" y "Zavora" son nombres/marcas de sus respectivos propietarios, usados de forma nominativa para identificar las herramientas; este proyecto no está afiliado ni respaldado por ninguno de ellos.

Licencia

MIT

中文说明

macOS 桌面自动化的精简聚合 MCP 服务器：用 ~2.3k token 的 10 个工具定义，替代 cua-driver（56 工具 ~37k token）+ computer-use-mcp（64 工具 ~21k token）合计 ~58k token 的上下文占用，120 个底层工具一个不少（长尾经 desk_call 直达、schema 用 desk_describe 按需取）。

安装

前置：macOS、Node 18+、cua-driver（用 trycua/cua 官方一键脚本装，见上方英文 Prerequisites，装完默认路径即本 hub 默认路径）；oss 后端无需手装，首次 desk_call server:"oss" 时 npx 自动拉取 @zavora-ai/computer-use-mcp@7.0.0（首次需联网，大陆用户建议配 npm 镜像）。

git clone https://github.com/zty552252kevin-code/desktop-hub.git
cd desktop-hub
npm ci
claude mcp add desktop-hub -s user -- node "$(pwd)/server.mjs"   # 必须绝对路径

国内镜像（同步更新，免翻墙）：git clone https://gitee.com/zty552252kevin/desktop-hub.git

权限：给 CuaDriver.app 授予「辅助功能」+「屏幕录制」（推荐 cua-driver permissions grant 让弹窗归属到 App 身份，升级不掉权限）；oss 后端跟随宿主终端的 TCC 身份，终端也要授同样两项；run_script 首次对每个目标 App 会弹一次「自动化」授权。

此前如果单独注册过 cua/oss 两个 MCP 服务器，把它们 disable 掉由本 hub 接管；全新安装跳过这步。

验证：npm test（20 项检查，会真实驱动桌面；DESKTOP_HUB_TEST_OSS=1 含 oss 后端）。环境变量见上方英文表格。

坑（血泪换来的）

• 后端崩溃自动清理、下次调用重生（依赖 client.onclose，transport.onclose 会被 SDK 覆写）；假死后端该次调用报 RequestTimeout 并杀掉重生，desk_describe 的 listTools 超时同样驱逐。所有驱逐带代际守卫：旧进程迟到的 onclose 不会误删刚重生的新 client（否则孤儿化新后端 + element_token 全部失效）。

• 宿主退出级联关停两个后端、限时 5s 强退，握手中的子进程也会被补刀（否则 npx 冷启动握手期能把无宿主 hub 拖 180s）。

• 宿主取消（Esc）真正中止：信号贯通到上游 callTool 和 osascript 子进程，取消后排队的点击/脚本不会再落到真桌面。

• act：double_click/right_click/set_value/menu 必须带 pid（上游硬性要求）；scope:"desktop" 禁止携带 pid/window_id（facade 自动剔除）；多窗口应用的像素 drag/scroll 必须带 window_id；无目标 scroll 走键击路径（发给焦点控件），要滚指定区域必须给 element_token 或 x,y。

• 坐标系不同：desktop_screenshot 是 Retina 真像素（2x），cua desktop-scope 用它；oss 指针工具用逻辑坐标（1x），要除以 scale factor 或从 desk_call oss screenshot 取坐标。

• run_script：language 大小写不敏感、未知值明确报错；输出超 1MB 不杀脚本（继续排水跑完、副作用完整），回传剪裁到 8KB 并标注丢弃量；中文跨管道块不出乱码。

• SwiftUI 应用显示值可能带 U+200E 隐形字符，verify 的 value_equals 会 unknown，改用 label_contains。

• 经两轮多 agent 对抗评审（21+20 个审查员）累计修复 28 项确认缺陷（第二轮抓出第一轮两个修复自身引入的回归）。