mcp-windows-debug

MCP-сервер на TypeScript/Node.js, который подключается к OpenCode через stdio и даёт модели «глаза и руки» на Windows-машине: он читает файлы проекта, делает скриншоты, двигает мышь и нажимает клавиши, а также запускает цикл автодебага против целевого приложения.

Безопасность — главная идея всей конструкции. Отдельный нативный C++ watchdog-процесс устанавливает глобальные низкоуровневые хуки клавиатуры и мыши, чтобы человек всегда мог нажать защищённую кнопку аварийной остановки, даже пока модель инжектит ввод. Node MCP-сервер и watchdog — два независимых процесса, поэтому зависший event loop Node не может заблокировать ваш ввод или молча отбросить слой безопасности. Каждое действие проходит через три шлюза: губернатор (governor), проверка свежести и защита области окна. Подробности — в разделе «Модель безопасности» ниже.

Это v1 только для Windows. Бэкенды для macOS и Linux подключатся позже за теми же интерфейсами провайдеров; пока они не реализованы.

Быстрый старт

git clone https://github.com/wgm66/mcp-windows-debug.git
cd mcp-windows-debug
npm install && npm run build
cd src\watchdog && build.bat   # build the C++ watchdog (MSVC required)
node dist\index.js --validate-config  # verify your OpenCode config

Related MCP server: Desktop Commander MCP Server

Установка

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

• Node.js 20 или новее, плюс npm

• Windows 10 или 11

• Права администратора — нужны только для запуска watchdog (см. ниже)

Установите зависимости и соберите TypeScript:

npm install
npm run build

npm run build запускает tsc и создаёт dist/index.js — точку входа, которую запускает OpenCode.

Далее соберите watchdog. Это консольное Win32-приложение на C++, компилируемое с помощью MSVC, без CMake, MSBuild или MinGW:

cd src\watchdog
build.bat

build.bat требует VS2019 Build Tools (MSVC 14.29) и Windows SDK. Пути к инструментам жёстко прописаны в скрипте, поэтому он ожидает их в стандартных местах установки. Результат — src\watchdog\watchdog.exe, который Node-сервер находит относительно корня проекта во время выполнения.

Watchdog должен запускаться с повышенными правами. Глобальные низкоуровневые хуки отказываются устанавливаться из процесса без повышения прав. Два способа это обеспечить:

1. Запустите OpenCode из терминала с правами администратора, чтобы порождённый watchdog унаследовал повышение прав.

2. Запустите watchdog от администратора самостоятельно перед началом сессии отладки.

Сервер не может сам запросить повышение прав через UAC в этой сборке. Сессия отладки, которая не может достучаться до watchdog с повышенными правами, завершается с ошибкой ELEVATION_REQUIRED, а запуск watchdog без повышения прав выводит ERROR_ACCESS_DENIED и завершается с кодом 1, а не молча ничего не делает.

Конфигурация OpenCode

Добавьте запись windows-debug под ключом mcp в конфиге OpenCode (opencode.json). Обратите внимание: ключ называется mcp, а не mcpServers:

{
  "mcp": {
    "windows-debug": {
      "type": "local",
      "command": ["node", "<abs-path>/dist/index.js"],
      "environment": {}
    }
  }
}

Замените <abs-path> на абсолютный путь к этому проекту, используя прямые слэши, чтобы JSON не требовал экранирования. Например, если проект находится в G:\工程开发\AI全场景图形化调试, команда станет:

"command": ["node", "G:/工程开发/AI全场景图形化调试/dist/index.js"]

command — это массив токенов argv. Карта environment по умолчанию пуста; токен watchdog для каждой сессии генерируется самим сервером и передаётся watchdog через окружение процесса, так что здесь ничего задавать не нужно.

Использование

Сессия отладки имеет фиксированную форму: зарегистрируйте защищённые кнопки аварийной остановки, запустите сессию, дайте модели поработать в цикле автодебага, затем завершите сессию.

Регистрация кнопок аварийной остановки. Сессия не может начаться с нулём защищённых областей. Передайте один или несколько прямоугольников экрана в start_debug_session как regions ({ x, y, w, h, id }, физические пиксели). Инжектируемый ввод, направленный внутрь любой зарегистрированной области, блокируется watchdog. Человеческий ввод всегда проходит, поэтому область — это гарантированная физическая зона аварийной остановки, до которой модель не может дотянуться. Области только добавляются на время жизни сессии; намеренно нет способа удалить или переместить их после запуска.

Запуск сессии. start_debug_session порождает или подключает watchdog, регистрирует каждую область и запускает heartbeat. Оркестратор начинает отслеживать текущее окно переднего плана как цель отладки. Передайте sandbox: 'desktop', чтобы выполнять инжекцию на отдельном приватном Win32-рабочем столе (на основе PostMessage, реальные мышь и клавиатура пользователя не затрагиваются) вместо SendInput (который двигает настоящий курсор). sandbox: 'rdp' зарезервирован, но в v1 не реализован.

Цикл автодебага. Пока сессия активна, оркестратор опрашивает целевое окно на изменения: заголовок, прямоугольник, статус переднего плана и, опционально, diff сигнатуры скриншота. Когда срабатывает триггер, он делает свежий скриншот и предоставляет его как ресурс debug://context. Клиент (OpenCode) опрашивает debug://context, решает, что делать, и вызывает execute_action с этим решением. Оркестратор никогда не принимает решения сам; он только выполняет решения клиента, и только после того, как все шлюзы — губернатор, свежесть и безопасность — пройдены.

Завершение сессии. end_debug_session отправляет SHUTDOWN, убивает watchdog, если тот не отвечает в течение одной секунды, отпускает удерживаемые клавиши-модификаторы и возвращается в состояние IDLE. Если MCP-процесс умирает без чистого завершения, dead-man switch watchdog снимает хуки самостоятельно (см. раздел «Модель безопасности»).

Инструменты

Зарегистрировано десять инструментов.

Четыре инструмента ввода (mouse_click, mouse_move, key_press, type_text) все проходят через шлюз injectGuarded слоя безопасности. Вызов без активной сессии возвращает NO_ACTIVE_SESSION. Вызов, когда курсор или фокус клавиатуры находится вне целевого окна, возвращает WINDOW_SCOPE_VIOLATION.

Ресурсы

Зарегистрировано три ресурса.

Лимиты губернатора

Оркестратор применяет фиксированное ограничение частоты вмешательств:

• кулдаун 5 секунд между действиями

• 6 вмешательств в минуту

• автопауза после 3 подряд неудач

• жёсткий лимит сессии 30 минут, после чего сессия завершается автоматически

Отказы из-за кулдауна, лимита частоты или паузы — это троттлинг, а не ошибки. Только отказ из-за устаревшего состояния или ошибка инжекции засчитываются в паузу после 3 неудач.

Модель безопасности

Что эта конструкция гарантирует, а что нет.

Изоляция двух процессов. Node MCP-сервер и нативный watchdog — отдельные процессы. Зависший event loop Node не может заблокировать хуки или отбросить слой безопасности, потому что watchdog работает на собственном цикле сообщений.

Dead-man switch. Watchdog слушает именованный канал и трактует любой байт как heartbeat. Если heartbeat не приходит более 2 секунд, он вызывает UnhookWindowsHookEx для обоих хуков и корректно завершается. В сочетании с льготным периодом удаления хуки снимаются в течение 3 секунд после смерти MCP, так что упавший или убитый сервер никогда не оставляет ввод заблокированным. Это контракт fail-safe; это не гарантия с точностью до долей секунды.

Ограничение окна. Любая инжекция отклоняется, если нет активной сессии и курсор с фокусом клавиатуры не находятся внутри целевого окна сессии.

Обработка защищённого рабочего стола. Если ОС переключается на защищённый рабочий стол (запрос UAC или экран блокировки), оркестратор ставит на паузу и отказывает в инжекции, не предпринимая ни одной попытки ввода.

Журнал только на добавление. Каждое чтение файла, инжектируемое действие, запрос скриншота и решение о вмешательстве записываются в журнал аудита только на добавление. Содержимое нажатий клавиш и содержимое файлов в него никогда не пишутся.

Чего он НЕ гарантирует. Прочтите эту часть внимательно, потому что это честные остаточные риски.

• Фильтрация инжектируемого ввода — не абсолютная блокировка. Watchdog блокирует ввод с флагами LLKHF_INJECTED / LLMHF_INJECTED, когда пункт назначения попадает внутрь защищённой области. Это останавливает машинно-инжектируемый ввод, то есть то, что производит SendInput. Это не останавливает любой возможный источник ввода. Другой процесс теоретически может синтезировать ввод без флагов другими средствами, и такой ввод пройдёт фильтр. Этот инструмент не претендует на абсолютную физическую блокировку. Относитесь к кнопке аварийной остановки как к сильной страховочной сети с максимальными усилиями, а не как к математической гарантии.

• В худшем случае это примитив удалённого управления. Полная поверхность инструмента — это чтение файлов плюс захват скриншотов плюс инжекция клавиатуры и мыши. Если атакующий или некорректно ведущая себя модель получает над ним контроль, это та возможность, которую они получают. Используйте его на машине и против окон, на которые вы готовы направить эту поверхность.

• Антивирус и EDR могут его пометить. Глобальные низкоуровневые хуки и инжекция через SendInput — это ровно те техники, которые используют инструменты удалённого доступа и кейлоггеры. Ожидайте ложных срабатываний от продуктов AV/EDR, включая карантин или убийство watchdog посреди сессии. Dead-man switch делает это безопасным (хуки снимаются), но это прервёт сессии. См. «Устранение неполадок».

• Повышение прав расширяет поверхность. Watchdog нужны права администратора для установки глобальных хуков, поэтому сессия работает с повышенным процессом в картине. Не запускайте его на машине, где такая экспозиция неприемлема.

Watchdog никогда не читает и не логирует содержимое нажатий клавиш или кнопок; проверяются только флаг инжекции и пункт назначения курсора. Транспорт — только локальный именованный канал. Нет TCP, нет сетевого слушателя, нет удалённого управления.

Устранение неполадок

Антивирус или EDR помечает watchdog. Добавьте исключение для src\watchdog\watchdog.exe (или каталога проекта) в консоли вашего антивируса/EDR. Надёжное решение — подпись кода: подписанный бинарный файл с гораздо меньшей вероятностью попадёт в карантин. Если watchdog будет убит в середине сеанса, сеанс перейдёт в состояние IDLE, и все инструменты ввода будут отклоняться до нового start_debug_session.

Windows отключает хук (LowLevelHooksTimeout). Процедуры низкоуровневых хуков имеют жёсткий бюджет времени выполнения, управляемый параметром HKCU\Control Panel\Desktop\LowLevelHooksTimeout (по умолчанию 300 мс). Если процедура хука выполняется слишком долго, Windows молча удаляет её. Watchdog поддерживает время выполнения своей процедуры хука значительно ниже 100 мс, так что в обычном использовании это не должно срабатывать. Если вы замечаете пропадание хуков на сильно загруженной машине, проблема в системной нагрузке или вмешательстве другого низкоуровневого хука, а не в этом инструменте.

Клики попадают не в то место в конфигурации с несколькими мониторами или смешанным DPI. Координаты преобразуются между логическими и физическими пикселями с использованием DPI конкретного монитора. В конфигурациях с несколькими мониторами и смешанным DPI есть известное ограничение: при преобразовании из логических в физические координаты логические координаты передаются в вызов, который ожидает физические пиксели. При 96 DPI это безвредно, но на масштабируемых мониторах может давать смещение. Если клик не попадает, сначала сделайте снимок экрана, считайте целевые координаты из него и предпочитайте работать на основном мониторе.

Появляется запрос UAC, или внедрение молча не срабатывает. Watchdog запускается с повышенными правами, поэтому его запуск может вызвать запрос UAC. Если вы отмените его, сеанс завершится с ошибкой ELEVATION_REQUIRED. В этой сборке сервер не может самостоятельно повторно запросить повышение прав, поэтому заранее запустите watchdog от имени администратора перед началом сеанса или запустите OpenCode из терминала с повышенными правами.

ERROR_ACCESS_DENIED при ручном запуске watchdog. Это ожидаемое поведение для оболочки без повышенных прав. Watchdog отказывается запускаться без прав администратора и выводит ERROR_ACCESS_DENIED с кодом возврата 1, так что не происходит молчаливого бездействия. Вместо этого запустите его из PowerShell с повышенными правами.

Запись сеанса

Сеансы можно записывать в виде JSON-транскриптов для последующего воспроизведения. Рекордер подключается к журналу аудита и фиксирует каждый вызов инструмента (имя, аргументы, результат, временная метка) без содержимого нажатий клавиш (минимизация данных). Транскрипты сохраняются в .omo/recordings/session-<id>.json.

# A session transcript can be replayed programmatically:
node -e "const { SessionRecorder } = require('./dist/recording'); SessionRecorder.replay('.omo/recordings/session-xxx.json', async (call) => { console.log(call.toolName, call.args); })"

UIAutomation (API специальных возможностей)

Инструмент inspect_element перечисляет видимые элементы интерфейса с помощью обходчика дерева UIAutomation (паритет с конкурентами terminator-mcp-agent и Windows MCP Inspector). В v1 это заглушка, которая возвращает элементы из шва внедрённых зависимостей; полная COM-интеграция требует нативного N-API аддона (будущая работа). Класс UIAutomationProvider реализует InputProvider, но в v1 выбрасывает UIAutomationError для методов внедрения — используйте пути SendInput или PostMessage для реального внедрения.