agent-sh/computer-use-linux

Linux desktop control over MCP — AT-SPI, GNOME Shell, Wayland portals, ydotool

해결하는 문제

기존 도구들이 종종 macOS 전용이거나 부정확한 픽셀 기반 OCR에 의존하는 한계를 극복하여, AI 에이전트가 라이브 Linux 데스크톱과 상호작용할 수 있도록 합니다. 에이전트가 단순히 특정 좌표를 클릭하는 것이 아니라 의미론적 작업(예: 버튼 이름을 통한 클릭)을 수행할 수 있는 방법을 제공합니다.

작동 방식

이 프로젝트는 Linux 데스크톱 환경과 인터페이스하는 Model Context Protocol (MCP) 서버 역할을 합니다. 제어권을 얻기 위해 다음과 같은 방법을 사용합니다:

Observation (관찰): 액세스성 트리(AT-SPI를 통해)를 읽고, 스크린샷을 찍으며, 컴포지터 인식 백엔드(GNOME, KDE, Hyprland, i3 및 COSMIC)를 사용하여 창 목록을 나열합니다.
Input (입력): Wayland 포털 또는 폴백으로 ydotool을 사용하여 마우스 및 키보드 동작을 구동합니다.
Semantic Selection (의미론적 선택): 액세스성 데이터를 사용하여 에이전트가 역할, 이름 또는 텍스트를 기준으로 요소를 선택할 수 있도록 하며, 필요한 경우 픽셀 좌표로 전환합니다.

대상 사용자

AI 에이전트 개발자: MCP를 통해 Linux 데스크톱을 운영해야 하는 에이전트를 구축하는 모든 개발자.
Linux 사용자: Claude Desktop, Claude Code 또는 Hermes Agent와 같은 도구를 사용하여 데스크톱 자동화를 워크플로우에 통합하려는 사용자.

주요 특징

Wayland 지원: 데스크톱 포털을 사용하는 "Wayland 우선" 방식으로 구축되었습니다.
컴포지터 인식: GNOME, KDE, Hyprland, i3 및 COSMIC을 포함한 여러 윈도우 매니저를 지원합니다.
의미론적 제어: AT-SPI를 통해 이름 및 역할에 따른 UI 요소와의 상호작용을 지원합니다.
진단 도구: 시스템 요구 사항의 문제 해결을 위해 JSON 준비 보고서를 생성하는 doctor 명령어가 포함되어 있습니다.