Автоматизация GUI рабочего стола¶

local-shell-mcp умеет наблюдать и управлять нативными настольными приложениями в Linux, Windows и macOS. Публичный интерфейс намеренно остаётся небольшим:

Инструмент	Назначение
`gui_list`	Перечисляет видимые окна приложений и сообщает активный нативный backend и его возможности.
`gui_state`	Наблюдает одно окно. Возвращает краткоживущий `state_id`, элементы доступности, геометрию окна и, при необходимости, нативный снимок MCP.
`gui_action`	Выполняет семантические или координатные действия именно относительно этого наблюдения.

Все три инструмента принимают необязательный machine, поэтому тот же процесс можно применять к подключённому desktop worker.

Сначала наблюдение, затем действие¶

Начните с gui_list, выберите window_id и затем вызовите gui_state. Если возвращённый элемент доступности element_id соответствует нужному контролу, используйте его в первую очередь:

gui_list
  -> gui_state(window_id)
  -> gui_action(window_id, state_id, [{type: "click", element_id: "e17"}])
  -> gui_state(window_id)

Координаты x/y относительно окна используйте только тогда, когда у интерфейса нет полезного элемента доступности, например для canvas или самостоятельно отрисованного контрола. Границы элементов и снимки используют одно и то же пространство логических пикселей относительно окна, включая HiDPI/Retina. Сырые координаты за пределами выбранного окна отклоняются.

state_id истекает через 30 секунд и используется только один раз. Координатные действия также проверяют, что окно после наблюдения не было перемещено или изменено в размере. Если проверка не проходит, снова вызовите gui_state вместо повторного использования старых координат.

Поддерживаются действия click, double_click, right_click, move, scroll, drag, type, key, set_value, focus и wait.

Ручное управление в Native WebUI¶

В Native WebUI есть страница Desktop для прямого управления теми же нативными GUI-backend. Выберите машину и окно, затем взаимодействуйте с изображением окна с помощью клика, двойного клика, правой кнопки, перетаскивания, колеса, клавиатурных сочетаний или текстового поля для IME/CJK.

Этот путь намеренно отделён от семантики модельного state_id. Каждый отображаемый кадр содержит наблюдаемую геометрию окна; каждый запрос человеческого ввода перед инъекцией проверяет, что геометрия всё ещё точно совпадает. Если окно перемещено, изменено в размере или исчезло, действие отклоняется, а WebUI обновляет наблюдение. Сырые координаты остаются ограничены выбранным окном.

Клавиатурные и текстовые действия явно фокусируют выбранное нативное окно перед инъекцией. WebUI использует лёгкий polling снимков вместо VNC/WebRTC-видеопотока; удалённый RPC gui_human_action является внутренней операцией controller-worker и не публикуется моделям как MCP-инструмент.

Нативные backend¶

Платформа	Доступность / семантическое управление	Снимки и сырой ввод
Windows	Microsoft UI Automation	Снимок окна и нативный ввод мыши/клавиатуры Windows
macOS	Accessibility (`AXUIElement`)	`screencapture` выбранного окна и ввод Quartz `CGEvent`
Linux	AT-SPI	Нативный ввод/снимки X11; Wayland использует нативный захват рабочего стола и XDG Desktop Portal RemoteDesktop/ScreenCast

Когда возможно, сначала выполняются семантические действия. Поэтому кнопку с нативным invoke/press можно активировать без угадывания пиксельной координаты. Визуальные координаты остаются fallback для недоступного или самостоятельно отрисованного содержимого.

Настройка платформы¶

Windows¶

Запускайте LSM в той же интерактивной desktop-сессии, где находятся управляемые приложения. Базовая установка local-shell-mcp безопасна для headless-среды и не требует адаптера Windows UI Automation; устанавливайте необязательный extra local-shell-mcp[gui] только когда нужен локальный контроль GUI Windows.

macOS¶

Предоставьте процессу-хосту LSM:

разрешение Accessibility для семантического управления и ввода;
разрешение Screen Recording для снимков экрана.

Базовый пакет не требует PyObjC. Устанавливайте необязательный local-shell-mcp[gui] только для локального GUI-контроля macOS; машинам без GUI-инструментов эти framework не нужны.

Linux¶

Desktop-сессия должна предоставлять AT-SPI. В Debian/Ubuntu необходимые системные binding обычно устанавливаются так:

sudo apt install python3-gi gir1.2-atspi-2.0

Базовый пакет не требует Python-адаптеров X11 или D-Bus. Необязательный local-shell-mcp[gui] устанавливает их для локального GUI. Удалённые workеры определяют активную Linux-сессию до bootstrap GUI-зависимостей: X11 требует только X11-адаптер, Wayland — только D-Bus-адаптер, а headless-worker не устанавливает ни один. На Wayland fallback сырого ввода указателя/клавиатуры использует XDG Desktop Portal RemoteDesktop API, поэтому рабочий стол может один раз показать выбор разрешения/сессии. Поддерживаются portal-реализации KDE и GNOME. Снимки окна используют доступный нативный путь захвата и при необходимости Screenshot portal.

Workеры LSM часто запускаются вне графического login-окружения. Linux-backend восстанавливает DISPLAY, WAYLAND_DISPLAY, XDG_SESSION_TYPE и связанные переменные из пользовательского systemd-окружения, если они не были унаследованы напрямую.

Удалённые рабочие столы¶

GUI-инструменты выполняются на выбранной машине, а не на controller. Удалённый worker должен принадлежать пользователю/сессии, владеющей целевым рабочим столом. GUI-адаптеры загружаются лениво и только для GUI-вызовов: обычный запуск worker и работа shell/files/browser не устанавливают и не импортируют их. В Linux headless-worker сообщает о недоступности GUI до любого GUI pip bootstrap, а графический worker проверяет или устанавливает только адаптер, нужный активной X11/Wayland-сессии.

Снимки, возвращаемые удалённым gui_state, передаются через файловый transfer LSM и предоставляются модели как нативный MCP image content; они не встраиваются в JSON-ответ worker.