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.