34 lines
1.4 KiB
Markdown
34 lines
1.4 KiB
Markdown
# hive-screen-mcp
|
|
|
|
A stdio MCP server that exposes screenshot, keyboard, and mouse tools to agents
|
|
running a Weston Wayland compositor (`hyperhive.gui.enable = true`).
|
|
|
|
## When to use it
|
|
|
|
This crate is the bridge for **GUI agents** — agents that drive graphical
|
|
applications (browsers, desktop tools, game UIs) and need to see and interact
|
|
with a Weston Wayland display. If your agent does not have `hyperhive.gui.enable
|
|
= true`, none of these tools will function.
|
|
|
|
## Tools
|
|
|
|
| Tool | Mechanism | Requires |
|
|
|---|---|---|
|
|
| `screenshot` | `grim` → PNG on stdout | `grim` in PATH, `WAYLAND_DISPLAY` |
|
|
| `type_text` | `wtype` (Wayland virtual-keyboard protocol) | `wtype` in PATH |
|
|
| `key_press` | `wtype -k` (XKB keysym syntax) | `wtype` in PATH |
|
|
| `mouse_move` | RFB `PointerEvent` to the neatvnc backend | `HIVE_GUI_VNC_PORT` |
|
|
| `mouse_click` | RFB move → button-down → button-up sequence | `HIVE_GUI_VNC_PORT` |
|
|
|
|
All tools operate in userspace — no `/dev/uinput` or kernel bypass.
|
|
`WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` are injected by the `weston-vnc` NixOS
|
|
module; `HIVE_GUI_VNC_PORT` is set by the harness service (defaults to `5900`).
|
|
|
|
## Shape
|
|
|
|
One binary (`hive-screen-mcp`) launched over stdio. The agent runtime wires it
|
|
as an extra MCP server when `hyperhive.gui.enable = true`. There are no library
|
|
exports — it is a self-contained binary crate.
|
|
|
|
See the crate-root `//!` docs for the full per-tool implementation notes and
|
|
environment variable contract.
|