omarchy-mcp

Dale a cualquier LLM compatible con MCP el control total de un escritorio Linux Omarchy.

omarchy-mcp convierte a los agentes de codificación de IA en operadores de escritorio genuinos. A través de un servidor MCP, un agente puede gestionar temas y apariencia, lanzar aplicaciones, tomar capturas de pantalla y grabaciones, controlar audio y red, leer el estado del sistema, manejar ventanas de Hyprland y diseños de mosaico, y orquestar espacios de trabajo multiagente completos: 108 herramientas en 15 módulos.

El proyecto se basa en una regla: una mutación del escritorio no tiene éxito solo porque se ejecutó un comando. Cada acción se confirma contra el estado medido del escritorio (geometría, foco, estado del servicio), para que los agentes puedan actuar de forma autónoma sin fallar silenciosamente.

Estado

Consulta COMMANDS.md para el estado de verificación herramienta por herramienta y ROADMAP.md para los hitos planificados.

Related MCP server: linux-computer-use

Por qué existe esto

Las herramientas de control de escritorio a menudo informan que una acción se envió sin comprobar si funcionó. Esto es particularmente poco fiable en los gestores de ventanas en mosaico, donde el foco, las reglas flotantes, el estado de pantalla completa, las reglas de espacio de trabajo y el ratón pueden cambiar el objetivo.

Este servidor añade el bucle de retroalimentación que faltaba:

• Las mutaciones de ventanas informan del estado medido antes/después y un veredicto claro.

• Los selectores explícitos de dirección y coincidencia reducen los errores relacionados con el foco.

• Una protección de ascendencia de PID evita que el agente cierre su propia ventana anfitriona.

• Las operaciones destructivas del sistema requieren una aceptación explícita en la configuración.

• health_check diagnostica comandos faltantes, instalación de diseño y conectividad de escritorio.

• agent_grid convierte una solicitud completa de espacio de trabajo multiagente en una operación MCP verificada.

Inicio rápido

Requisitos

• Un escritorio Omarchy instalado

• Hyprland con el puente de configuración Lua de Omarchy

• Node.js 20 o más reciente

• npm

Las funciones individuales también pueden usar wtype, nmcli, bluetoothctl, wpctl, grim y wl-copy. health_check informa qué comandos opcionales están disponibles.

Compilación

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

El punto de entrada de MCP es:

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

Instalar el diseño de cuadrícula nativo

Las herramientas de escritorio habituales pueden funcionar sin el diseño personalizado, pero el mosaico de cuadrícula/maestro determinista y agent_grid lo requieren.

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

Asegúrate de que la configuración de Hyprland del usuario lo carga:

require("hypr.layouts")

Luego recarga y comprueba la configuración:

hyprctl reload
hyprctl configerrors

Los archivos de paquete de Omarchy en /usr/share/omarchy deben permanecer intactos; el diseño pertenece a la configuración del usuario en ~/.config/hypr.

Conectar un cliente MCP

Cualquier cliente que admita servidores MCP stdio locales puede lanzar build/index.js.

OpenCode

Añade esto a ~/.config/opencode/opencode.json, reemplazando la ruta con la ruta absoluta del repositorio:

{
  "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"]
    }
  }
}

Reinicia o vuelve a conectar un cliente MCP existente después de reconstruir para que recargue el esquema de herramientas.

Primeros comandos para probar

• "Comprueba si mi Omarchy MCP está sano."

• "Muestra cada ventana con su espacio de trabajo y geometría."

• "Abre una cuadrícula 2x2 de OpenCode en el siguiente espacio de trabajo vacío."

• "Coloca a Claude arriba a la derecha y a Codex abajo a la derecha."

• "Mueve Firefox al espacio de trabajo 4 y confirma dónde terminó."

• "Ajusta esta ventana a la esquina superior izquierda y dime su tamaño final."

• "Enumera las redes Wi-Fi cercanas, pero no te conectes a nada."

Espacios de trabajo de agentes de codificación con un solo comando

agent_grid lanza ventanas TUI independientes de Omarchy, aplica el diseño de cuadrícula nativo, asigna celdas exactas o dispersas y verifica la clase de aplicación, el espacio de trabajo, el estado flotante y la geometría observada de cada ventana.

Para cuatro aplicaciones, pide una cuadrícula 2x2. Una cuadrícula literal 4x4 contiene 16 celdas y lanza 16 aplicaciones cuando está completamente poblada.

Cuadrícula homogénea

Comando:

Abre una cuadrícula 2x2 de OpenCode en este repositorio.

Argumentos equivalentes:

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

Cuadrícula dispersa mixta

Comando:

Abre Claude en la parte superior derecha y Codex en la parte inferior derecha.

Argumentos equivalentes:

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

Los agentes compatibles son OpenCode, Claude, Codex, Gemini, Copilot, Crush, Grok, Oh My Pi (omp) y Pi. Usa dry_run: true para validar un plan completo sin abrir ventanas.

Las asignaciones de esquinas con nombre y las asignaciones explícitas de fila/columna persisten cuando el usuario cambia de espacio de trabajo. Las ventanas en mosaico existentes se cuentan antes del lanzamiento y la solicitud se rechaza si excedería la capacidad de la cuadrícula.

Grupos de herramientas

La lista completa y su estado de prueba en vivo se mantienen en COMMANDS.md.

Modelo de seguridad

Sin interpolación de shell

Los comandos se ejecutan con matrices de argumentos a través de execFile o spawn de Node; la entrada del usuario no se concatena en comandos de shell.

Las operaciones destructivas son opcionales

El apagado, el reinicio, la instalación de paquetes, las actualizaciones del sistema y las actualizaciones de configuración están deshabilitados por defecto. Habilítalos con:

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

O establece la anulación a nivel de proceso:

OMARCHY_MCP_ENABLE_DANGEROUS=1 node build/index.js

Usa esta configuración solo para un cliente y una sesión en los que confíes.

Protección de la ventana anfitriona

Las operaciones de cierre de ventanas y otras de alto riesgo resuelven la ascendencia de PID del proceso anfitrión de MCP y se niegan a apuntar a su propia ventana de terminal. Se prefieren las direcciones de ventana explícitas para las mutaciones porque el foco de Hyprland puede seguir al ratón.

Resultados verificados

Las herramientas de mutación de ventanas devuelven estados como confirmed, split_confirmed, opened_but_not_split o not_detected, junto con el estado medido y una pista de recuperación cuando corresponde.

Arquitectura

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

Estructura del código fuente:

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

Los envíos de ventanas de Hyprland usan la API Lua de Omarchy, por ejemplo:

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

El diseño nativo admite modos grid y master además de mensajes en tiempo de ejecución para dimensiones forzadas, ordenación, intercambios, celdas dispersas y estado por espacio de trabajo.

Desarrollo y verificación

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

La prueba de humo es intencionalmente consciente del escritorio. Comprueba el registro de herramientas, el informe de salud, el acceso de solo lectura a Omarchy/Hyprland, la compuerta de operaciones destructivas y una ejecución en seco de agent_grid. Las mutaciones visuales se verifican manualmente en una sesión real de Omarchy y se registran en COMMANDS.md.

Para un ejercicio en vivo de cuadrícula de agentes:

node test/live-agent-grid.mjs

Este comando abre ventanas reales y cambia el espacio de trabajo activo; no forma parte de npm test.

Solución de problemas

La nueva herramienta no aparece

Ejecuta npm run build y luego reinicia o vuelve a conectar el cliente MCP. Los clientes MCP normalmente almacenan en caché la lista de herramientas durante la vida del proceso del servidor.

health_check dice que el diseño de cuadrícula no está completamente instalado

Confirma que ~/.config/hypr/layouts.lua existe, que la configuración de Hyprland del usuario contiene require("hypr.layouts") y que hyprctl configerrors está vacío.

Un comando de ventana seleccionó el objetivo incorrecto

Llama a window_list y luego reintenta con la dirección devuelta en lugar de confiar en la ventana enfocada. Esto evita los cambios de foco de input:follow_mouse.

Una herramienta peligrosa dice que está deshabilitada

Ese es el valor predeterminado seguro. Habilítalo explícitamente solo después de revisar el modelo de seguridad.

Un comando de diseño informa una advertencia de Hyprland

Algunas operaciones nulas del compositor son esperables, por ejemplo, intercambiar una ventana en pantalla completa o intercambiar hacia una celda vacía. El resultado de MCP distingue estas advertencias de las mutaciones confirmadas.

Contribuciones

Las contribuciones son bienvenidas en implementación, verificación en vivo, documentación, pruebas, accesibilidad e ingeniería de lanzamiento. El repositorio proporciona formularios de incidencias estructurados para errores, propuestas de herramientas e informes de verificación, además de una lista de verificación de solicitudes de extracción alineada con el modelo de seguridad del proyecto.

Comienza con CONTRIBUTING.md y luego elige una vía de contribución de ROADMAP.md. Los cambios amplios o de alto riesgo deben comenzar con una incidencia para que el alcance, la evidencia y el comportamiento de recuperación puedan acordarse antes de codificar.

Documentos del proyecto

• COMMANDS.md — registro de implementación y verificación en vivo

• ROADMAP.md — hitos, prioridades y puertas de lanzamiento

• CONTRIBUTING.md — flujo de trabajo de contribución y pruebas

• GOVERNANCE.md — roles, decisiones, revisiones y lanzamientos

• SECURITY.md — informes privados y límites de seguridad

• CODE_OF_CONDUCT.md — estándares de participación comunitaria

• AGENTS.md — contexto técnico para agentes de codificación que trabajan en el repositorio

Licencia

MIT