EZComputerCtrl MCP

Englisch

Ein visuell orientierter MCP für die Windows-Desktop-GUI-Steuerung, der es Agenten ermöglicht, semantische Objekte anstelle von fehleranfälligen Bildschirmkoordinaten zu bedienen.

EZComputerCtrl bereitet den aktuellen Desktop zunächst als strukturierte, ausführbare Schnittstellenfakten auf. Anschließend wählt der übergeordnete Agent Objekte und Aktionen aus, woraufhin der MCP intern die Lokalisierung, Ausführung und Rückgabe der Ergebnisse übernimmt.

Aktuelle Funktionen

Derzeit verfügbare MCP-Werkzeuge:

1. see

2. click

3. scroll

4. move_to

5. type_text

6. hotkey

Derzeit unterstützte Übertragungsmethoden:

1. stdio

2. streamable-http

3. sse

Standard-Übertragungsmethode: streamable-http

Related MCP server: umbriel

Installation

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

Zugehörige Skills

Das Repository enthält einen universellen Installations-Skill:

skills/install-ezcomputerctrl-mcp/SKILL.md

Dieser Skill dient dazu, dass verschiedene Agenten-Clients die lokale Konfiguration in ihren jeweiligen Umgebungen schnell abschließen können, anstatt an ein festes Client-Format gebunden zu sein.

Typische Verwendung:

1. Öffnen Sie das geklonte Repository im Agenten-Client.

2. Rufen Sie /install-ezcomputerctrl-mcp auf oder lassen Sie den Agenten diesen Skill verwenden.

3. Lassen Sie den Agenten die Portauswahl, das Schreiben der lokalen Umgebung, den Hintergrundstart und die MCP-Verbindungskonfiguration abschließen.

Lokale Laufzeitkonfiguration

Maschinenspezifische lokale Laufzeitkonfigurationen sollten hier gespeichert werden:

.runtime/ezcomputerctrl.env.ps1

Eine Beispieldatei finden Sie unter:

scripts/ezcomputerctrl.env.example.ps1

Das Startskript lädt diese Datei automatisch, bevor der Dienst gestartet wird.

Gebräuchliche Umgebungsvariablen:

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-Konfiguration

Empfohlener Pfad: Qwen3.5/3.6 35B-A3B

Verwenden Sie hier keine fiktiven Modellnamen. Bitte verwenden Sie immer die tatsächlich bereitgestellten:

1. EZCTRL_MODEL_NAME

2. EZCTRL_MODEL_BASE_URL

3. EZCTRL_MODEL_API_KEY

Derzeit wird standardmäßig eine VLM-Schnittstelle erwartet, die mit dem OpenAI-Protokoll kompatibel ist.

Starten und Stoppen

Im Hintergrund starten (versteckt):

cscript //nologo scripts\start_ezcomputerctrl_hidden.vbs

Dieser Einstiegspunkt startet den Keep-Alive-Daemon standardmäßig in einem versteckten Fenster.

1. Die PID des Daemons wird in .runtime/ezcomputerctrl.guardian.pid geschrieben.

2. Die PID des aktuellen Geschäftsprozesses wird in .runtime/ezcomputerctrl.pid geschrieben.

3. Solange das Stopp-Skript nicht ausgeführt wurde und die aktuelle Windows-Sitzung nicht beendet ist, startet der Daemon den Geschäftsprozess nach dessen Beendigung automatisch neu.

Hintergrunddienst stoppen:

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

Das Stopp-Skript schreibt ein Stopp-Signal, beendet den aktuellen Geschäftsprozess und bereinigt die Laufzeit-PID-Dateien in .runtime/.

Startskript direkt ausführen:

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

Keep-Alive-Modus direkt ausführen:

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

Der Einmal-Startmodus startet den MCP-Dienst nur einmal; der Keep-Alive-Modus verwaltet zusätzlich die Daemon-PID-Datei .runtime/ezcomputerctrl.guardian.pid.

MCP-Adresse

Unter dem Standard-Host und -Port lautet die streamable-http-Adresse:

http://127.0.0.1:8765/mcp

Falls der Port lokal geändert wurde, ersetzen Sie diese Adresse bitte durch den tatsächlichen Port.

Verzeichnisstruktur

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

Hinweise zu Windows

1. Die Start- und Stopp-Skripte sind vorrangig mit Windows PowerShell 5.1 kompatibel.

2. Der Inhalt der Skripte ist weitestgehend auf ASCII optimiert, um Kodierungsprobleme zu minimieren.

3. Der versteckte Start verwendet VBScript + PowerShell, um zu verhindern, dass das Befehlszeilenfenster versehentlich geschlossen wird.

Aktuelle Einschränkungen

1. Die aktuelle Implementierung konzentriert sich auf die Windows-Desktop-GUI und ist nicht für Spielesteuerungsszenarien gedacht.

2. Die aktuellen Fähigkeiten hängen von einer echten Desktop-Umgebung und einem echten VLM-Dienst ab.

3. Dies ist eine visuell gesteuerte Kontrollebene; eine fehlerfreie Erkennung bei komplexen Oberflächen wird nicht garantiert.

4. Die externe Werkzeugoberfläche wird bewusst schlank gehalten, um Stabilität und Kontrollierbarkeit zu priorisieren.

5. Wenn Sie nach dem Start dieses Werkzeugs Spiele mit Anti-Cheat-Systemen der Stufe R0 (z. B. Tencent ACE) ausführen, besteht das Risiko einer Sperrung. Bitte schließen Sie dieses Werkzeug unbedingt und starten Sie den Computer neu, bevor Sie das entsprechende Spiel starten. Der Autor und die Community übernehmen keine Haftung für Spielsperren, Einschränkungen oder andere Verluste, die durch die Nutzung dieses Werkzeugs entstehen.