# 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.