omarchy-mcp

MCP 호환 LLM에게 Omarchy Linux 데스크톱의 완전한 제어 권한을 부여합니다.

omarchy-mcp는 AI 코딩 에이전트를 진정한 데스크톱 운영자로 전환합니다. 하나의 MCP 서버를 통해 에이전트는 테마와 외관 관리, 앱 실행, 스크린샷 및 녹화, 오디오와 네트워크 제어, 시스템 상태 읽기, Hyprland 창 및 타일링 레이아웃 구동, 다중 에이전트 워크스페이스 전체 오케스트레이션까지 수행할 수 있습니다 — 15개 모듈에 걸쳐 108개의 도구를 제공합니다.

이 프로젝트는 하나의 원칙을 중심으로 구축되었습니다: 데스크톱 변경은 단지 명령이 실행되었다는 이유만으로 성공한 것이 아닙니다. 모든 작업은 측정된 데스크톱 상태(기하학, 포커스, 서비스 상태)를 기준으로 확인되므로, 에이전트는 조용히 실패하지 않고 자율적으로 작동할 수 있습니다.

상태

도구별 검증 상태는 COMMANDS.md를, 계획된 마일스톤은 ROADMAP.md를 참조하세요.

Related MCP server: linux-computer-use

존재 이유

데스크톱 제어 도구는 종종 작업이 실제로 성공했는지 확인하지 않고 명령이 전달되었다고만 보고합니다. 특히 타일링 윈도우 매니저에서는 포커스, 플로팅 규칙, 전체화면 상태, 워크스페이스 규칙, 마우스 위치에 따라 대상이 달라질 수 있기 때문에 이는 특히 신뢰할 수 없습니다.

이 서버는 누락된 피드백 루프를 추가합니다:

• 창 변경 작업은 측정된 전후 상태와 명확한 판정을 보고합니다.

• 명시적 주소 및 매치 선택자를 통해 포커스 관련 오류를 줄입니다.

• PID 조상 가드가 에이전트가 자신의 호스트 창을 닫는 것을 방지합니다.

• 파괴적 시스템 작업은 명시적 구성 동의(opt-in)가 필요합니다.

• health_check는 누락된 명령, 레이아웃 설치, 데스크톱 연결을 진단합니다.

• agent_grid는 다중 에이전트 워크스페이스 요청 전체를 하나의 검증된 MCP 작업으로 변환합니다.

빠른 시작

요구 사항

• 설치된 Omarchy 데스크톱

• Omarchy의 Lua 구성 브리지를 갖춘 Hyprland

• Node.js 20 이상

• npm

개별 기능은 wtype, nmcli, bluetoothctl, wpctl, grim, wl-copy를 사용할 수도 있습니다. health_check는 어떤 선택적 명령이 사용 가능한지 보고합니다.

빌드

git clone https://github.com/hlsitechio/Omarchy-MCP.git
cd Omarchy-MCP
npm ci
npm run build
npm test

MCP 진입점은 다음과 같습니다:

node /absolute/path/to/Omarchy-MCP/build/index.js

네이티브 그리드 레이아웃 설치

일반 데스크톱 도구는 사용자 정의 레이아웃 없이도 실행할 수 있지만, 결정적 그리드/마스터 타일링과 agent_grid에는 필요합니다.

install -Dm644 hypr/layouts.lua ~/.config/hypr/layouts.lua

사용자 Hyprland 구성이 이를 로드하는지 확인하세요:

require("hypr.layouts")

그런 다음 다시 로드하고 구성을 확인하세요:

hyprctl reload
hyprctl configerrors

/usr/share/omarchy 아래의 Omarchy 패키지 파일은 그대로 두어야 합니다. 레이아웃은 ~/.config/hypr 아래의 사용자 구성에 속합니다.

MCP 클라이언트 연결

로컬 stdio MCP 서버를 지원하는 모든 클라이언트는 build/index.js를 실행할 수 있습니다.

OpenCode

경로를 저장소의 절대 경로로 바꿔서 ~/.config/opencode/opencode.json에 다음을 추가하세요:

{
  "mcp": {
    "omarchy": {
      "type": "local",
      "command": [
        "node",
        "/absolute/path/to/Omarchy-MCP/build/index.js"
      ],
      "enabled": true
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "omarchy": {
      "command": "node",
      "args": ["/absolute/path/to/Omarchy-MCP/build/index.js"]
    }
  }
}

다시 빌드한 후 기존 MCP 클라이언트를 재시작하거나 다시 연결하여 도구 스키마를 다시 로드하세요.

시도해 볼 첫 프롬프트

• "내 Omarchy MCP가 정상인지 확인해 줘."

• "모든 창을 워크스페이스와 기하학과 함께 보여 줘."

• "다음 빈 워크스페이스에 OpenCode 2x2 그리드를 열어 줘."

• "Claude를 오른쪽 위에, Codex를 오른쪽 아래에 배치해 줘."

• "Firefox를 워크스페이스 4로 이동하고 어디에 도착했는지 확인해 줘."

• "이 창을 왼쪽 위에 스냅하고 최종 크기를 알려 줘."

• "주변 Wi-Fi 네트워크를 나열하되, 아무것도 연결하지 마."

원커맨드 코딩 에이전트 워크스페이스

agent_grid는 독립적인 Omarchy TUI 창을 실행하고, 네이티브 그리드 레이아웃을 적용하며, 정확하거나 희소한 셀을 할당하고, 각 창의 애플리케이션 클래스, 워크스페이스, 플로팅 상태, 관찰된 기하학을 검증합니다.

네 개의 애플리케이션에는 2x2 그리드를 요청하세요. 문자 그대로의 4x4 그리드는 16개의 셀을 포함하며 완전히 채워지면 16개의 애플리케이션을 실행합니다.

동종 그리드

프롬프트:

이 저장소에 OpenCode 2x2 그리드를 열어 줘.

동등한 인자:

{
  "agent": "opencode",
  "cols": 2,
  "rows": 2,
  "workspace": "next_empty",
  "cwd": "/path/to/project"
}

혼합 희소 그리드

프롬프트:

Claude를 오른쪽 위에, Codex를 오른쪽 아래에 열어 줘.

동등한 인자:

{
  "cols": 2,
  "rows": 2,
  "placements": [
    { "agent": "claude", "position": "top_right" },
    { "agent": "codex", "position": "bottom_right" }
  ]
}

지원되는 에이전트는 OpenCode, Claude, Codex, Gemini, Copilot, Crush, Grok, Oh My Pi(omp), Pi입니다. 창을 열지 않고 완전한 계획을 검증하려면 dry_run: true를 사용하세요.

명명된 모서리 할당과 명시적 행/열 할당은 사용자가 워크스페이스를 변경해도 유지됩니다. 기존 타일링 창은 실행 전에 계산되며, 그리드 용량을 초과하면 요청이 거부됩니다.

도구 그룹

전체 목록과 실시간 테스트 상태는 COMMANDS.md에 유지됩니다.

안전 모델

셸 보간 없음

명령은 Node의 execFile 또는 spawn을 통해 인자 배열로 실행됩니다. 사용자 입력은 셸 명령에 연결되지 않습니다.

파괴적 작업은 동의 필요

종료, 재부팅, 패키지 설치, 시스템 업데이트, 구성 새로고침은 기본적으로 비활성화되어 있습니다. 다음으로 활성화하세요:

mkdir -p ~/.config/omarchy-mcp
printf '%s\n' '{"enableDangerous": true}' > ~/.config/omarchy-mcp/config.json

또는 프로세스 수준 재정의를 설정하세요:

OMARCHY_MCP_ENABLE_DANGEROUS=1 node build/index.js

이 설정은 신뢰하는 클라이언트와 세션에서만 사용하세요.

호스트 창 보호

창 닫기 및 기타 고위험 작업은 MCP 호스트 프로세스의 PID 조상을 확인하고 자신의 터미널 창을 대상으로 삼는 것을 거부합니다. Hyprland 포커스는 마우스를 따라갈 수 있으므로 변경 작업에는 명시적 창 주소가 선호됩니다.

검증된 결과

창 변경 도구는 confirmed, split_confirmed, opened_but_not_split, not_detected와 같은 상태를 측정된 상태 및 적절한 복구 힌트와 함께 반환합니다.

아키텍처

MCP client
    │  JSON-RPC over stdio
    ▼
MCP tool + Zod input validation
    │
    ├── Omarchy CLI ───────────── themes, capture, power, applications
    ├── Hyprland Lua dispatcher ─ windows, workspaces, native layout
    └── System CLIs ───────────── nmcli, bluetoothctl, wpctl, upower
    │
    ▼
State reread + geometry/verdict engine
    │
    ▼
Structured MCP result with STATUS, evidence, and HINT

소스 구조:

src/index.ts              server and tool registration
src/exec.ts               shell-free process execution
src/hypr.ts               desktop introspection and verification helpers
src/result.ts             consistent MCP success/error results
src/config.ts             safety configuration
src/tools/                 tool domains
hypr/layouts.lua          native deterministic grid/master layout
test/                      automated and manual live tests

Hyprland 창 디스패치는 Omarchy Lua API를 사용합니다. 예:

hl.dsp.window.resize({ window = "address:0x...", x = 900, y = 700, relative = false })

네이티브 레이아웃은 grid 및 master 모드와 강제 크기, 순서, 교체, 희소 셀, 워크스페이스별 상태를 위한 런타임 메시지를 지원합니다.

개발 및 검증

npm run build      # TypeScript compilation
npm test           # compilation + deterministic planner tests
npm run smoke      # live local MCP/Omarchy smoke test

스모크 테스트는 의도적으로 데스크톱을 인식합니다. 도구 등록, 상태 보고서, 읽기 전용 Omarchy/Hyprland 접근, 파괴적 작업 게이트, agent_grid 드라이 런을 확인합니다. 시각적 변경은 실제 Omarchy 세션에서 수동으로 검증되며 COMMANDS.md에 기록됩니다.

실시간 에이전트 그리드 연습:

node test/live-agent-grid.mjs

이 명령은 실제 창을 열고 활성 워크스페이스를 변경합니다. npm test의 일부가 아닙니다.

문제 해결

새 도구가 나타나지 않음

npm run build를 실행한 다음 MCP 클라이언트를 재시작하거나 다시 연결하세요. MCP 클라이언트는 일반적으로 서버 프로세스 수명 동안 도구 목록을 캐시합니다.

health_check가 그리드 레이아웃이 완전히 설치되지 않았다고 보고함

~/.config/hypr/layouts.lua가 존재하는지, 사용자 Hyprland 구성에 require("hypr.layouts")가 포함되어 있는지, hyprctl configerrors가 비어 있는지 확인하세요.

창 명령이 잘못된 대상을 선택함

window_list를 호출한 다음 포커스된 창에 의존하는 대신 반환된 주소로 다시 시도하세요. 이렇게 하면 input:follow_mouse 포커스 변경을 피할 수 있습니다.

위험한 도구가 비활성화되었다고 표시됨

그것이 안전한 기본값입니다. 안전 모델을 검토한 후에만 명시적으로 활성화하세요.

레이아웃 명령이 Hyprland 경고를 보고함

일부 컴포지터 no-op은 예상됩니다 — 예를 들어 전체화면 창 교체 또는 빈 셀 방향으로의 교체가 있습니다. MCP 결과는 이러한 경고를 확인된 변경과 구분합니다.

기여

구현, 실시간 검증, 문서화, 테스트, 접근성, 릴리스 엔지니어링 전반에 걸쳐 기여를 환영합니다. 저장소는 버그, 도구 제안, 검증 보고서를 위한 구조화된 이슈 양식과 프로젝트 안전 모델에 맞춘 풀 리퀘스트 체크리스트를 제공합니다.

CONTRIBUTING.md로 시작한 다음 ROADMAP.md에서 기여 트랙을 선택하세요. 광범위하거나 고위험 변경은 코딩 전에 범위, 증거, 복구 동작을 합의할 수 있도록 이슈로 시작해야 합니다.

프로젝트 문서

• COMMANDS.md — 구현 및 실시간 검증 원장

• ROADMAP.md — 마일스톤, 우선순위, 릴리스 게이트

• CONTRIBUTING.md — 기여 및 테스트 워크플로

• GOVERNANCE.md — 역할, 의사결정, 검토, 릴리스

• SECURITY.md — 비공개 보고 및 보안 경계

• CODE_OF_CONDUCT.md — 커뮤니티 참여 기준

• AGENTS.md — 저장소에서 작업하는 코딩 에이전트를 위한 기술 컨텍스트

라이선스

MIT