EZComputerCtrl MCP

English

Windows 데스크톱 GUI 제어를 위한 시각 중심의 MCP로, 에이전트가 불안정한 화면 좌표 대신 의미론적 객체를 조작할 수 있게 합니다.

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: OmniFlow

설치

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

제공되는 Skill

저장소에는 범용 설치 skill이 내장되어 있습니다:

skills/install-ezcomputerctrl-mcp/SKILL.md

이 skill은 다양한 에이전트 클라이언트가 특정 클라이언트 형식에 종속되지 않고 각자의 환경에서 로컬 구성을 빠르게 완료할 수 있도록 합니다.

일반적인 사용 방법:

1. 에이전트 클라이언트에서 복제된 저장소를 엽니다.

2. /install-ezcomputerctrl-mcp를 호출하거나 에이전트가 해당 skill을 사용하도록 합니다.

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

현재 기본적으로 OpenAI 프로토콜과 호환되는 VLM 인터페이스를 예상합니다.

시작 및 중지

백그라운드 숨김 시작:

cscript //nologo scripts\start_ezcomputerctrl_hidden.vbs

이 진입점은 기본적으로 숨겨진 창에서 실행되는 유지 관리 데몬 프로세스를 시작합니다.

1. 데몬 프로세스 PID는 .runtime/ezcomputerctrl.guardian.pid에 기록됩니다.

2. 현재 비즈니스 프로세스 PID는 .runtime/ezcomputerctrl.pid에 기록됩니다.

3. 중지 스크립트를 실행하지 않고 현재 Windows 세션이 종료되지 않은 경우, 데몬 프로세스는 비즈니스 프로세스가 종료된 후 자동으로 다시 시작합니다.

백그라운드 서비스 중지:

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

중지 스크립트는 중지 신호를 기록하고, 현재 비즈니스 프로세스를 종료하며, .runtime/ 내의 런타임 PID 파일을 정리합니다.

시작 스크립트 직접 실행:

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

유지 관리 모드 직접 실행:

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

단일 시작 모드는 MCP 서비스를 한 번만 실행하며, 유지 관리 모드는 .runtime/ezcomputerctrl.guardian.pid 데몬 프로세스 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 데스크톱 GUI에 초점을 맞추고 있으며 게임 제어 시나리오는 지원하지 않습니다.

2. 현재 기능은 실제 데스크톱 환경과 실제 VLM 서비스에 의존합니다.

3. 이는 시각 기반 제어 계층이며 복잡한 인터페이스에서 0% 오류 인식을 보장하지 않습니다.

4. 현재 외부 도구 인터페이스는 안정성과 제어 가능성을 우선시하여 간결하게 유지됩니다.

5. 본 도구 실행 후 R0급 안티 치트(예: 텐센트 ACE)가 포함된 게임을 실행할 경우, 차단 위험이 발생할 수 있습니다. 관련 게임에 접속하기 전에 반드시 본 도구를 종료하고 컴퓨터를 재부팅하십시오. 작성자와 커뮤니티는 본 도구 사용으로 인해 발생하는 게임 계정 차단, 제한 또는 기타 손실에 대해 어떠한 책임도 지지 않습니다.