Bra1nZ/screenshot-mcp

MCP-сервер, который даёт агенту настоящее окно консоли на рабочем столе
и снимки экрана штатным средством системы.
Ключевая сложность в том, что под Wayland не работают привычные приёмы автоматизации
терминала: xdotool не вводит текст в нативные Wayland-приложения, wmctrl не
существует, а tmux умеет управлять сессией, но не окном на экране. Здесь ввод идёт
прямо в псевдотерминал, поэтому терминал показывает его так же, как ввод с
клавиатуры, — без эмуляции клавиш и без каких-либо следов в интерфейсе.
Возможности:
новое отдельное окно консоли с твоим ~/.bashrc — твой промпт, цвета, алиасы;
ввод команд и чтение вывода с кодом возврата;
интерактивные программы: ввод, Ctrl+C, Ctrl+D, стрелки, история команд;
снимок всего рабочего стола с поднятием окна консоли на передний план;
снимок возвращается агенту прямо в ответе (картинкой), так что он может сам
оценить, что попало в кадр.
## Как это устроено
MCP-сервер (server.py)
│ UNIX-сокет, JSON
core/bridge.py — «насос»: переливает ввод и вывод
│ псевдотерминал (pty)
bash ── запущен прямо в окне терминала, наследует ~/.bashrc
Настоящий bash работает внутри окна терминала и подхватывает пользовательский
.bashrc. Заголовок окна при этом неотличим от обычного ( : bash — Konsole).
Агент пишет байтами прямо в pty. Их обрабатывает tty-драйвер (отражение ввода) и
readline — то есть это буквально тот же путь, что и при наборе с клавиатуры.
Никакой эмуляции клавиш, поэтому в терминале не остаётся следов автоматизации.
Код возврата берётся через хук PROMPTCOMMAND, который пишет маркер в служебный
файл: на экране ничего не появляется.
## Архитектура
Платформенные различия вынесены в бэкенды, ядро от них не зависит:
screenshotmcp/
├── core/ pty-мост, сессия консоли, лаунчер — POSIX, работает везде
├── backends/
│ ├── terminal/ konsole · xterm · gnome-terminal
│ ├── screenshot/ spectacle · x11 · gnome
│ └── focus/ kwin · xdotool · atspi · none
├── config.py определение окружения и пользовательские настройки
└── runtime.py сборка окружения, настроек и бэкендов
Выбор бэкендов автоматический: определяется тип сессии (XDGSESSIONTYPE) и рабочее
окружение (XDGCURRENTDESKTOP). При необходимости его можно задать явно — см.
Настройку.
## Поддерживаемые окружения
| Окружение | Окно терминала | Снимок экрана | Поднятие окна |
| KDE Plasma 6 / Wayland | Konsole | Spectacle | KWin-скриптинг |
| KDE Plasma / X11 | Konsole, xterm | ImageMagick, scrot, maim | xdotool |
| GNOME / Wayland | gnome-terminal | gnome-screenshot | AT-SPI |
| X11 (любой DE) | xterm, gnome-terminal | ImageMagick, scrot, maim | xdotool |
> Что проверено вживую: только вариант KDE Plasma / Wayland — на нём прогнаны
> все тесты. X11- и GNOME-пути написаны по документации используемых утилит
> (scrot, maim, import, xdotool, gnome-screenshot, AT-SPI) и требуют
> проверки на своём железе: терминал и снимок там работают через те же бэкенды
> ядра, но поднятие окна в X11 завязано на xdotool, а в GNOME — на AT-SPI, и
> доступность этих способов зависит от окружения.
## Требования
Python 3.11+ и пакет mcp;
терминал: konsole, xterm или gnome-terminal;
для снимков: spectacle (KDE) либо scrot/maim/import (X11) либо
gnome-screenshot (GNOME);
для поднятия окна: KWin (идёт с Plasma) либо xdotool на X11;