mirror of
https://github.com/ksyasuda/dotfiles.git
synced 2026-09-20 05:16:17 -07:00
50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# Hyprland desktop bridge
|
|
|
|
Local stdio MCP server for Hyprland 0.56+, using `grim`, `hyprctl`, `ydotool`,
|
|
`wtype`, and `xdotool`. Registered as `hyprland_desktop` in the Linux Codex config.
|
|
The shared skill is `~/.agents/skills/hyprland-computer-use/SKILL.md`.
|
|
|
|
The server starts on demand as the logged-in user. It has no network listener,
|
|
shell-command tool, or arbitrary file-write tool. It inherits the graphical session
|
|
environment through the MCP config. The agent's normal sandbox remains enabled.
|
|
Focus checks and coordinate validation reduce misdirected input but do not isolate
|
|
apps or prevent desktop-wide keyboard shortcuts. Use one desktop task at a time.
|
|
|
|
The existing user `ydotool.service` owns a mode-0600 socket at
|
|
`$XDG_RUNTIME_DIR/.ydotool_socket`. This machine already grants the active user access
|
|
to `/dev/uinput` through its installed Steam input udev rule. No new root service,
|
|
input-group membership, or system-wide permission rule was added.
|
|
|
|
## Maintenance
|
|
|
|
Inspect input service state with `systemctl --user status ydotool.service`.
|
|
If input stops after system package changes, check `/dev/uinput` and its ACL before
|
|
changing permissions. Stop input injection with `systemctl --user stop ydotool.service`;
|
|
other programs using that shared service will also lose synthetic mouse input.
|
|
To disable this MCP bridge, set `enabled = false` in its Codex config section and
|
|
restart the client.
|
|
|
|
Dependencies are pinned in `requirements.lock`. Recreate the environment with:
|
|
|
|
```sh
|
|
cd ~/.codex/bridges/hyprland-desktop
|
|
uv venv .venv --python 3.13
|
|
uv pip sync --python .venv/bin/python requirements.lock
|
|
```
|
|
|
|
## Verification
|
|
|
|
These commands briefly operate a temporary test window on the live desktop.
|
|
Keep local mouse and keyboard input idle during the run.
|
|
|
|
```sh
|
|
.venv/bin/python test_desktop.py
|
|
.venv/bin/python test_desktop.py --native
|
|
```
|
|
|
|
The first tests XWayland with Tk; the second tests native Wayland with GTK 4.
|
|
They exercise the MCP handshake and tool calls, Unicode text, selection shortcuts,
|
|
clicks, wheel input, dragging, PNG capture, input validation, and the focus guard.
|
|
The latest screenshot is `/tmp/hyprland-desktop-verified.png`.
|
|
Test fixtures require the system Python Tk and PyGObject/GTK packages.
|