desktop-hub

Ein kompakter Fassaden-MCP-Server für macOS-Desktop-Automatisierung. Er stellt nur 10 handgeschriebene Tools bereit (~2,3k Token an Definitionen) und leitet lazy an zwei vollwertige Computer-Use-MCP-Server weiter — cua-driver (56 Tools, ~37k Token) und computer-use-mcp (64 Tools, ~21k Token) — plus natives osascript. Sie behalten die gesamte Oberfläche mit 120 Tools, aber Ihr Kontextfenster zahlt ~2k Token statt ~58k.

中文说明在下方 · Gitee mirror 国内镜像 · Funktioniert mit Claude Code und jedem MCP-Client.

Warum

Das direkte Registrieren beider Upstream-Server kostet ~58k Kontext-Token pro Sitzung nur für Tool-Definitionen, während die hochfrequente Oberfläche klein ist. Diese Fassade hält den heißen Pfad günstig und den langen Schwanz erreichbar:

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

Tools

Voraussetzungen

• macOS (Apple Silicon oder Intel), Node.js 18+ (entwickelt auf Node 26).

• cua-driver — der macOS-Treiber aus dem trycua/cua Projekt (libs/cua-driver). Installieren Sie mit ihrem offiziellen Einzeiler, der CuaDriver.app in /Applications platziert und ~/.local/bin/cua-driver verlinkt (genau der Standardpfad dieses Hubs — keine Konfiguration nötig):

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

  Dokumentation: https://cua.ai/docs/how-to-guides/driver/install. Getestet mit cua-driver 0.20.0 (cua-driver --version); wenn act/verify nach einem Treiber-Upgrade unbekannte Tool-Fehler zurückgeben, führen Sie zuerst desk_describe server:cua aus, um die Tool-Oberfläche zu vergleichen.

• computer-use-mcp benötigt keine manuelle Installation — npx holt @zavora-ai/computer-use-mcp@7.0.0 automatisch beim ersten desk_call server:"oss" (einmaliger Netzwerkzugriff; danach einige Sekunden Spawn-Latenz — das Handshake-Timeout ist bereits auf 180s erweitert). Benutzer in Festlandchina möchten möglicherweise einen npm-Registry-Spiegel konfigurieren.

macOS-Berechtigungen

• Gewähren Sie Bedienungshilfen und Bildschirmaufnahme (Systemeinstellungen → Datenschutz & Sicherheit) für CuaDriver.app — führen Sie cua-driver permissions grant aus, damit die Dialoge der App-Identität zugeordnet werden (die Berechtigungen überleben dann Upgrades). Ohne sie schlägt jeder Screenshot-/AX-Aufruf mit undurchsichtigen Fehlern fehl.

• Gewähren Sie dieselben beiden Ihrer Terminal-/MCP-Host-App — das oss-Backend läuft als einfacher Node-Kindprozess des Hosts und erbt dessen TCC-Identität.

• run_script löst beim ersten Gebrauch die einmalige Automatisierungs-Abfrage (Apple Events) von macOS pro Ziel-App aus.

Installation & Registrierung

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

Festlandchina-Spiegel (synchron gehalten): git clone https://gitee.com/zty552252kevin/desktop-hub.git

Nur wenn Sie zuvor cua-driver oder computer-use-mcp als eigenständige MCP-Server registriert haben: Deaktivieren Sie diese Einträge (z. B. disabledMcpServers in ~/.claude.json), damit dieser Hub übernimmt. Frische Installationen überspringen diesen Schritt.

Verifizieren

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)

Die Suite erfordert cua-driver mit erteilten Berechtigungen — Fehler ohne diese sind Einrichtungsprobleme, keine Hub-Fehler.

Umgebungsvariablen

Designhinweise & Fallstricke (hart erarbeitet)

• Abgestürzte Backends werden automatisch entfernt und beim nächsten Aufruf neu gestartet (über client.onclose — transport.onclose wird vom SDK überschrieben). Hängende Backends: Der Aufruf schlägt mit RequestTimeout fehl und das Backend wird beendet + neu gestartet; auch der listTools-Pfad von desk_describe entfernt. Alle Entfernungen sind generationsgeschützt, sodass ein verspätetes onclose eines alten Prozesses niemals einen frisch neu gestarteten Client löschen kann (was ihn verwaist und jedes element_token stranden würde).

• Host-Exit (stdin EOF / SIGTERM / SIGINT) kaskadiert das Herunterfahren auf beide Backends, begrenzt auf 5s — ein npx-Kaltstart mitten im Handshake kann einen hostlosen Hub nicht für das 180s-Handshake-Fenster am Leben halten; noch verbindende Kinder werden zwangsweise beendet.

• Hostseitige Abbrechung (z. B. Esc in Claude Code) bricht wirklich ab: Das Abbruchsignal wird in das Upstream-callTool eingefädelt und tötet das osascript-Kind, sodass ein in der Warteschlange befindlicher Klick/Skript nach dem Abbrechen nie auf dem echten Desktop landet.

• act: double_click/right_click/set_value/menu erfordern pid (harte Upstream-Anforderung — element_token allein reicht nicht); Desktop-weiter Doppelklick = action:"click" + extra:{count:2}. scope:"desktop" darf kein pid/window_id enthalten — die Fassade entfernt sie automatisch. Pixelpfad-Drag/Scroll bei Multi-Fenster-Apps benötigt window_id, sonst lehnt Upstream als mehrdeutig ab. Zielloses Scrollen (nur pid) sendet Pfeil-/PageDown-Tasten an das fokussierte Steuerelement — übergeben Sie element_token oder x,y, um eine bestimmte Stelle per Rad zu scrollen.

• Koordinatenräume unterscheiden sich zwischen Backends: desktop_screenshot gibt echte Bildschirmpixel zurück (2x auf Retina) — korrekt für cua scope:"desktop"; oss-Zeigerwerkzeuge über desk_call verwenden logische Punkte (1x). Teilen Sie durch den zurückgegebenen Skalierungsfaktor oder nehmen Sie Koordinaten aus desk_call oss screenshot.

• run_script: Die Sprache ist case-insensitiv, unbekannte Werte werden laut abgelehnt; Ausgabe über 1MB/Stream wird abgelassen (das Skript läuft bis zum Ende, Nebenwirkungen bleiben intakt), während der zurückgegebene Text auf 8KB mit einem Hinweis auf verworfene Bytes gekürzt wird; mehrbyteiges CJK wird nie über Pipe-Chunks geteilt.

• SwiftUI-Apps (z. B. Taschenrechner) können unsichtbare Zeichen (U+200E) in Anzeigewerten einbetten — verify's value_equals gibt dann unknown zurück; verwenden Sie stattdessen label_contains oder lesen Sie das window_state-Markdown.

• Adversarial in zwei Multi-Agent-Runden überprüft (21 + 20 Prüfer, 28 bestätigte Fehler behoben — Runde 2 fing zwei Regressionen, die durch Runde-1-Fixes eingeführt wurden). Regressionstests in test/smoke.mjs.

Drittanbieter-Tools

desktop-hub ist eine Fassade, die zwei unabhängig entwickelte Tools als separate MCP-Serverprozesse startet; sie sind nicht in diesem Repo enthalten und werden von Ihnen separat installiert:

• 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" und "Zavora" sind Namen/Marken ihrer jeweiligen Eigentümer, die nominativ zur Identifizierung der Tools verwendet werden; dieses Projekt ist mit keinem von beiden verbunden oder von ihnen unterstützt.

Lizenz

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