EZComputerCtrl MCP

Inglés

Un MCP centrado en la visión para el control de GUI de escritorio en Windows, que permite a los agentes operar con objetos semánticos en lugar de coordenadas de pantalla frágiles.

EZComputerCtrl organiza primero el escritorio actual en hechos de interfaz estructurados y ejecutables, luego el agente de nivel superior selecciona los objetos y acciones, y finalmente el MCP completa la localización, ejecución y devolución de resultados internamente.

Capacidades actuales

Herramientas MCP expuestas actualmente:

1. see

2. click

3. scroll

4. move_to

5. type_text

6. hotkey

Modos de transporte soportados actualmente:

1. stdio

2. streamable-http

3. sse

Modo de transporte predeterminado: streamable-http

Related MCP server: umbriel

Instalación

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

Skill complementario

El repositorio incluye un skill de ensamblaje genérico:

skills/install-ezcomputerctrl-mcp/SKILL.md

Este skill se utiliza para que diferentes clientes de Agentes completen rápidamente la configuración local en sus respectivos entornos, en lugar de estar vinculados a un formato de cliente fijo.

Modo de uso típico:

1. Abrir el repositorio clonado en el cliente del Agente.

2. Llamar a /install-ezcomputerctrl-mcp, o permitir que el Agente utilice este skill.

3. Dejar que el Agente complete la selección de puerto, la escritura en el entorno local, el inicio en segundo plano y la configuración de acceso al MCP.

Configuración de ejecución local

La configuración de ejecución local relacionada con la máquina debe escribirse en:

.runtime/ezcomputerctrl.env.ps1

El archivo de ejemplo se encuentra en:

scripts/ezcomputerctrl.env.example.ps1

El script de inicio cargará automáticamente este archivo antes de levantar el servicio.

Variables de entorno comunes:

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

Configuración de VLM

Ruta recomendada: Qwen3.5/3.6 35B-A3B

No escriba nombres de modelos ficticios aquí. Utilice siempre los que estén realmente desplegados:

1. EZCTRL_MODEL_NAME

2. EZCTRL_MODEL_BASE_URL

3. EZCTRL_MODEL_API_KEY

La expectativa predeterminada actual es una interfaz VLM compatible con el protocolo OpenAI.

Inicio y parada

Inicio oculto en segundo plano:

cscript //nologo scripts\start_ezcomputerctrl_hidden.vbs

Esta entrada inicia el proceso demonio de mantenimiento en una ventana oculta de forma predeterminada.

1. El PID del demonio se escribirá en .runtime/ezcomputerctrl.guardian.pid.

2. El PID del proceso de negocio actual se escribirá en .runtime/ezcomputerctrl.pid.

3. Mientras no se ejecute el script de parada y la sesión de Windows actual no haya finalizado, el demonio reiniciará automáticamente el proceso de negocio después de que este se cierre.

Detener el servicio en segundo plano:

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

El script de parada escribirá una señal de parada, finalizará el proceso de negocio actual y limpiará los archivos PID de tiempo de ejecución en .runtime/.

Ejecutar directamente el script de inicio:

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

Ejecutar directamente en modo de mantenimiento:

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

El modo de inicio único solo levantará el servicio MCP una vez; el modo de mantenimiento mantendrá adicionalmente el archivo PID del demonio .runtime/ezcomputerctrl.guardian.pid.

Dirección MCP

En el host y puerto predeterminados, la dirección streamable-http es:

http://127.0.0.1:8765/mcp

Si cambió el puerto localmente, reemplace esta dirección por el puerto real.

Estructura de directorios

.
|-- .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/

Notas sobre Windows

1. Los scripts de inicio y parada son compatibles preferentemente con Windows PowerShell 5.1.

2. El contenido del script intenta mantener la prioridad ASCII para reducir problemas de codificación.

3. El inicio oculto utiliza VBScript + PowerShell para evitar que la ventana de comandos se exponga y sea cerrada accidentalmente.

Limitaciones actuales

1. La implementación actual se centra en la GUI de escritorio de Windows y no está orientada a escenarios de control de juegos.

2. Las capacidades actuales dependen de un entorno de escritorio real y un servicio VLM real.

3. Esta es una capa de control impulsada por visión; no se garantiza una identificación sin errores en interfaces complejas.

4. La superficie de herramientas externas actual se mantiene convergente, priorizando la estabilidad y la controlabilidad.

5. Después de iniciar esta herramienta, si necesita ejecutar juegos con anti-trampas de nivel R0 (como Tencent ACE), existe el riesgo de activar una prohibición. Asegúrese de cerrar esta herramienta y reiniciar su computadora antes de ingresar a los juegos relevantes. El autor y la comunidad no asumen ninguna responsabilidad por prohibiciones de cuentas de juego, restricciones u otras pérdidas derivadas del uso de esta herramienta.