omarchy-mcp

Дайте любому MCP-совместимому LLM полный контроль над Linux-десктопом Omarchy.

omarchy-mcp превращает ИИ-агентов для кодинга в настоящих операторов рабочего стола. Через один MCP-сервер агент может управлять темами и внешним видом, запускать приложения, делать скриншоты и записи, управлять аудио и сетью, читать состояние системы, управлять окнами Hyprland и тайловыми раскладками, а также оркестрировать целые мультиагентные рабочие пространства — 108 инструментов в 15 модулях.

Проект построен на одном правиле: изменение рабочего стола не считается успешным только потому, что команда выполнилась. Каждое действие подтверждается измеренным состоянием рабочего стола — геометрией, фокусом, статусом служб, — чтобы агенты могли действовать автономно без тихих сбоев.

Статус

См. COMMANDS.md для статуса проверки по каждому инструменту и ROADMAP.md для запланированных этапов.

Related MCP server: linux-computer-use

Зачем это существует

Инструменты управления рабочим столом часто сообщают, что действие было отправлено, не проверяя, сработало ли оно. Это особенно ненадёжно для тайловых оконных менеджеров, где фокус, плавающие правила, полноэкранный режим, правила рабочих пространств и мышь могут изменить цель.

Этот сервер добавляет недостающую петлю обратной связи:

• Мутации окон сообщают измеренное состояние до/после и чёткий вердикт.

• Явные селекторы адресов и совпадений уменьшают ошибки, связанные с фокусом.

• Защита по предкам PID предотвращает закрытие агентом собственного окна хоста.

• Деструктивные системные операции требуют явного согласия в конфигурации.

• health_check диагностирует отсутствующие команды, установку раскладки и подключение к рабочему столу.

• agent_grid превращает целый запрос мультиагентного рабочего пространства в одну проверенную MCP-операцию.

Быстрый старт

Требования

• Установленный рабочий стол Omarchy

• Hyprland с мостом конфигурации Lua от Omarchy

• 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

Пакетные файлы Omarchy в /usr/share/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.»

• «Покажи каждое окно с его рабочим пространством и геометрией.»

• «Открой сетку 2x2 OpenCode на следующем пустом рабочем пространстве.»

• «Помести Claude в правый верхний угол, а Codex в правый нижний.»

• «Перемести Firefox на рабочее пространство 4 и подтверди, где он оказался.»

• «Прикрепи это окно к верхнему левому углу и скажи его конечный размер.»

• «Перечисли ближайшие Wi-Fi сети, но ничего не подключай.»

Однокомандные рабочие пространства для агентов кодинга

agent_grid запускает независимые TUI-окна Omarchy, применяет нативную сеточную раскладку, назначает точные или разреженные ячейки и проверяет класс приложения, рабочее пространство, плавающее состояние и наблюдаемую геометрию каждого окна.

Для четырёх приложений запросите сетку 2x2. Буквальная сетка 4x4 содержит 16 ячеек и запускает 16 приложений при полном заполнении.

Однородная сетка

Промпт:

Открой сетку 2x2 OpenCode в этом репозитории.

Эквивалентные аргументы:

{
  "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.

Модель безопасности

Никакой интерполяции в оболочке

Команды выполняются с массивами аргументов через execFile или spawn Node.js; пользовательский ввод не конкатенируется в команды оболочки.

Деструктивные операции — по согласию

Завершение работы, перезагрузка, установка пакетов, системные обновления и обновления конфигурации отключены по умолчанию. Включите их с помощью:

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

Или установите переопределение на уровне процесса:

OMARCHY_MCP_ENABLE_DANGEROUS=1 node build/index.js

Используйте этот параметр только для клиента и сеанса, которым вы доверяете.

Защита окна хоста

Операции закрытия окон и другие высокорисковые операции определяют предков PID процесса MCP-хоста и отказываются нацеливаться на его собственное окно терминала. Для мутаций предпочтительны явные адреса окон, потому что фокус 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 используют Lua API Omarchy, например:

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 отличает эти предупреждения от подтверждённых мутаций.

Вклад

Приветствуются вклады в реализацию, живую проверку, документацию, тестирование, доступность и инженерию релизов. Репозиторий предоставляет структурированные формы вопросов для ошибок, предложений инструментов и отчётов о проверке, а также чек-лист для pull-request, согласованный с моделью безопасности проекта.

Начните с CONTRIBUTING.md, затем выберите направление вклада из ROADMAP.md. Широкие или высокорисковые изменения должны начинаться с issue, чтобы объём, доказательства и поведение при восстановлении были согласованы до написания кода.

Документы проекта

• COMMANDS.md — журнал реализации и живой проверки

• ROADMAP.md — этапы, приоритеты и шлюзы релизов

• CONTRIBUTING.md — рабочий процесс вклада и тестирования

• GOVERNANCE.md — роли, решения, обзоры и релизы

• SECURITY.md — приватные отчёты и границы безопасности

• CODE_OF_CONDUCT.md — стандарты участия сообщества

• AGENTS.md — технический контекст для агентов кодинга, работающих с репозиторием

Лицензия

MIT