docs(#2627): add README for hive-screen-mcp

hive-screen-mcp/Cargo.toml

@@ -2,6 +2,7 @@
 name = "hive-screen-mcp"
 edition.workspace = true
 version.workspace = true
+readme = "README.md"
 
 [lints]
 workspace = true

hive-screen-mcp/README.md

@@ -0,0 +1,34 @@
+# 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.