desktop-hub

Компактный фасадный MCP-сервер для автоматизации рабочего стола macOS. Он предоставляет всего 10 написанных вручную инструментов (~2,3 тыс. токенов определений) и лениво проксирует запросы к двум полнофункциональным MCP-серверам компьютерного управления — cua-driver (56 инструментов, ~37 тыс. токенов) и computer-use-mcp (64 инструмента, ~21 тыс. токенов) — плюс нативный osascript. Вы сохраняете всю поверхность из 120 инструментов, но ваш контекст платит ~2 тыс. токенов вместо ~58 тыс.

中文说明在下方 · Gitee mirror 国内镜像 · Работает с Claude Code и любым MCP-клиентом.

Зачем

Регистрация обоих вышестоящих серверов напрямую стоит ~58 тыс. токенов контекста за сессию только за определения инструментов, в то время как часто используемая поверхность мала. Этот фасад сохраняет горячий путь дешёвым, а длинный хвост — доступным:

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

Инструменты

Предварительные требования

• macOS (Apple Silicon или Intel), Node.js 18+ (разработано на Node 26).

• cua-driver — драйвер macOS из проекта trycua/cua (libs/cua-driver). Установите с помощью их официальной однострочной команды, которая размещает CuaDriver.app в /Applications и создаёт симлинк ~/.local/bin/cua-driver (именно этот путь по умолчанию использует хаб — настройка не требуется):

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

  Документация: https://cua.ai/docs/how-to-guides/driver/install. Протестировано с cua-driver 0.20.0 (cua-driver --version); если после обновления драйвера act/verify возвращают ошибки неизвестного инструмента, сначала выполните desk_describe server:cua, чтобы сравнить поверхность инструментов.

• computer-use-mcp не требует ручной установки — npx автоматически загрузит @zavora-ai/computer-use-mcp@7.0.0 при первом desk_call server:"oss" (одноразовый доступ к сети; впоследствии несколько секунд задержки запуска — таймаут рукопожатия уже расширен до 180 с). Пользователям в материковом Китае может потребоваться настроить зеркало npm-реестра.

Разрешения macOS

• Предоставьте Специальные возможности и Запись экрана (Системные настройки → Конфиденциальность и безопасность) приложению CuaDriver.app — выполните cua-driver permissions grant, чтобы диалоги привязывались к идентичности приложения (тогда разрешения переживают обновления). Без них каждый вызов снимка экрана/AX завершается ошибкой с непонятным сообщением.

• Предоставьте те же два разрешения вашему терминалу / MCP-хосту — oss-бэкенд работает как обычный дочерний процесс node хоста и наследует его TCC-идентичность.

• run_script при первом использовании вызывает одноразовое системное окно Автоматизации (Apple Events) для каждого целевого приложения.

Установка и регистрация

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

Зеркало для материкового Китая (синхронизируется): git clone https://gitee.com/zty552252kevin/desktop-hub.git

Только если вы ранее регистрировали cua-driver или computer-use-mcp как отдельные MCP-серверы: отключите эти записи (например, disabledMcpServers в ~/.claude.json), чтобы этот хаб взял управление на себя. При новой установке этот шаг пропускается.

Проверка

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)

Набор тестов требует установленного cua-driver с предоставленными разрешениями — сбои без них являются проблемами настройки, а не ошибками хаба.

Переменные окружения

Заметки по дизайну и подводные камни (добытые потом и кровью)

• Упавшие бэкенды автоматически выгружаются и перезапускаются при следующем вызове (через client.onclose — transport.onclose перезаписывается SDK). Зависшие бэкенды: вызов завершается ошибкой RequestTimeout, бэкенд убивается и перезапускается; путь listTools в desk_describe также выполняет выгрузку. Все выгрузки защищены поколениями, чтобы поздний onclose от старого процесса никогда не мог удалить только что перезапущенный клиент (что осиротило бы его и сделало бы недействительными все element_token).

• Выход хоста (EOF stdin / SIGTERM / SIGINT) каскадно завершает оба бэкенда, с ограничением 5 с — холодный запуск npx в середине рукопожатия не может удерживать хаб без хоста в течение 180-секундного окна рукопожатия; всё ещё подключающиеся дочерние процессы принудительно убиваются.

• Отмена на стороне хоста (например, Esc в Claude Code) действительно прерывает операцию: сигнал отмены пробрасывается в вышестоящий callTool и убивает дочерний процесс osascript, поэтому поставленный в очередь клик/скрипт никогда не попадёт на реальный рабочий стол после отмены.

• act: double_click/right_click/set_value/menu требуют pid (жёсткое требование вышестоящего сервера — одного element_token недостаточно); двойной клик в области рабочего стола = action:"click" + extra:{count:2}. scope:"desktop" не должен содержать pid/window_id — фасад удаляет их автоматически. Перетаскивание/прокрутка по пикселям в многоконных приложениях требует window_id, иначе вышестоящий сервер отказывает как в неоднозначном действии. Прокрутка без цели (только pid) отправляет клавиши стрелок/PageDown сфокусированному элементу — передайте element_token или x,y, чтобы прокрутить колёсиком конкретное место.

• Системы координат различаются между бэкендами: desktop_screenshot возвращает настоящие пиксели экрана (2x на Retina) — корректно для cua scope:"desktop"; инструменты указателя oss через desk_call используют логические точки (1x). Разделите на возвращаемый коэффициент масштабирования или берите координаты из desk_call oss screenshot.

• run_script: язык нечувствителен к регистру, неизвестные значения отклоняются с явной ошибкой; вывод свыше 1 МБ/поток дренируется (скрипт выполняется до конца, побочные эффекты сохраняются), а возвращаемое тело обрезается до 8 КБ с пометкой о потерянных байтах; многобайтовый CJK никогда не разбивается между чанками канала.

• Приложения SwiftUI (например, Калькулятор) могут встраивать невидимые символы (U+200E) в отображаемые значения — тогда verify с value_equals возвращает unknown; используйте label_contains или читайте markdown из window_state.

• Подвергнут adversarial-ревью в двух раундах с несколькими агентами (21 + 20 рецензентов, исправлено 28 подтверждённых дефектов — второй раунд выявил две регрессии, внесённые исправлениями первого раунда). Набор регрессионных тестов в test/smoke.mjs.

Сторонние инструменты

desktop-hub — это фасад, который запускает два независимо разработанных инструмента как отдельные процессы MCP-серверов; они не включены в этот репозиторий и устанавливаются вами отдельно:

• 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» и «Zavora» — названия/товарные знаки их соответствующих владельцев, используемые номинативно для идентификации инструментов; этот проект не аффилирован ни с одним из них и не одобрен ими.

Лицензия

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 项确认缺陷（第二轮抓出第一轮两个修复自身引入的回归）。