EZComputerCtrl MCP

English

MCP-сервер для управления графическим интерфейсом рабочего стола Windows, ориентированный на визуальное взаимодействие, который позволяет агентам работать с семантическими объектами, а не с хрупкими экранными координатами.

EZComputerCtrl сначала структурирует текущий рабочий стол в виде исполняемых фактов интерфейса, затем агент верхнего уровня выбирает объекты и действия, а после этого MCP внутри себя выполняет позиционирование, действие и возврат результата.

Текущие возможности

Доступные на данный момент инструменты MCP:

1. see

2. click

3. scroll

4. move_to

5. type_text

6. hotkey

Поддерживаемые способы передачи данных:

1. stdio

2. streamable-http

3. sse

Способ передачи по умолчанию: streamable-http

Related MCP server: umbriel

Установка

git clone https://github.com/JucieOvo/ezcomputerctrl-mcp.git
cd ezcomputerctrl-mcp
pip install -e .

Сопутствующий Skill

В репозиторий встроен универсальный навык (skill) для настройки:

skills/install-ezcomputerctrl-mcp/SKILL.md

Этот навык предназначен для того, чтобы различные клиентские приложения Agent могли быстро выполнить локальную настройку в своих средах, вместо привязки к какому-то одному формату клиента.

Типичный сценарий использования:

1. Откройте клонированный репозиторий в клиентском приложении Agent.

2. Вызовите /install-ezcomputerctrl-mcp или позвольте агенту использовать этот навык.

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

Конфигурация локального запуска

Локальные настройки запуска, зависящие от машины, должны быть записаны в:

.runtime/ezcomputerctrl.env.ps1

Пример файла находится по адресу:

scripts/ezcomputerctrl.env.example.ps1

Скрипт запуска автоматически загружает этот файл перед запуском службы.

Часто используемые переменные окружения:

1. EZCTRL_TRANSPORT

2. EZCTRL_SERVER_HOST

3. EZCTRL_SERVER_PORT

4. EZCTRL_MODEL_NAME

5. EZCTRL_MODEL_BASE_URL

6. EZCTRL_MODEL_API_KEY

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

Рекомендуемый вариант: Qwen3.5/3.6 35B-A3B

Не записывайте здесь вымышленные имена моделей. Всегда используйте реально развернутые:

1. EZCTRL_MODEL_NAME

2. EZCTRL_MODEL_BASE_URL

3. EZCTRL_MODEL_API_KEY

В настоящее время по умолчанию ожидается интерфейс VLM, совместимый с протоколом OpenAI.

Запуск и остановка

Запуск в скрытом фоновом режиме:

cscript //nologo scripts\start_ezcomputerctrl_hidden.vbs

Этот входной скрипт по умолчанию запускает процесс-хранитель (guardian) в скрытом окне.

1. PID процесса-хранителя записывается в .runtime/ezcomputerctrl.guardian.pid.

2. PID текущего рабочего процесса записывается в .runtime/ezcomputerctrl.pid.

3. Пока не выполнен скрипт остановки и текущий сеанс Windows не завершен, процесс-хранитель будет автоматически перезапускать рабочий процесс после его завершения.

Остановка фоновой службы:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\stop_ezcomputerctrl.ps1

Скрипт остановки записывает сигнал остановки, завершает текущий рабочий процесс и очищает файлы PID времени выполнения в .runtime/.

Прямой запуск скрипта:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run_ezcomputerctrl_http.ps1

Прямой запуск в режиме поддержания работы (keep-alive):

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run_ezcomputerctrl_http.ps1 -KeepAlive

Режим однократного запуска выполняет службу MCP только один раз; режим поддержания работы дополнительно поддерживает файл PID процесса-хранителя .runtime/ezcomputerctrl.guardian.pid.

Адрес MCP

При использовании хоста и порта по умолчанию адрес streamable-http выглядит так:

http://127.0.0.1:8765/mcp

Если вы изменили порт локально, замените адрес в соответствии с фактическим портом.

Структура каталогов

.
|-- .runtime/
|-- pyproject.toml
|-- README.md
|-- README_EN.md
|-- scripts/
|   |-- ezcomputerctrl.env.example.ps1
|   |-- run_ezcomputerctrl_http.ps1
|   |-- start_ezcomputerctrl_hidden.vbs
|   `-- stop_ezcomputerctrl.ps1
|-- skills/
|   `-- install-ezcomputerctrl-mcp/
|       `-- SKILL.md
`-- src/
    `-- ezcomputerctrl/

Примечания для Windows

1. Скрипты запуска и остановки в первую очередь совместимы с Windows PowerShell 5.1.

2. Содержимое скриптов по возможности сохраняется в ASCII для уменьшения проблем с кодировкой.

3. Скрытый запуск использует VBScript + PowerShell, чтобы избежать случайного закрытия окна командной строки.

Текущие ограничения

1. Текущая реализация сфокусирована на графическом интерфейсе рабочего стола Windows и не предназначена для управления играми.

2. Текущие возможности зависят от реальной среды рабочего стола и реальной службы VLM.

3. Это уровень управления на основе визуального восприятия, мы не гарантируем нулевую погрешность распознавания в сложных интерфейсах.

4. Текущий набор внешних инструментов остается ограниченным для обеспечения стабильности и управляемости.

5. После запуска этого инструмента, если вы планируете запускать игры с античитом уровня R0 (например, Tencent ACE), существует риск блокировки. Обязательно закройте этот инструмент и перезагрузите компьютер перед входом в соответствующую игру. Автор и сообщество не несут ответственности за любые блокировки игровых аккаунтов, ограничения или другие убытки, возникшие в результате использования данного инструмента.