From 7176ce63221209a648895461a6b9b48009eba35a Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Thu, 23 Jul 2026 12:38:38 +0200
Subject: [PATCH] docs(#2627): add README for hive-screen-mcp

---
 hive-screen-mcp/Cargo.toml |  1 +
 hive-screen-mcp/README.md  | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 hive-screen-mcp/README.md

diff --git a/hive-screen-mcp/Cargo.toml b/hive-screen-mcp/Cargo.toml
index 60239418..7ac02ad9 100644
--- a/hive-screen-mcp/Cargo.toml
+++ b/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
diff --git a/hive-screen-mcp/README.md b/hive-screen-mcp/README.md
new file mode 100644
index 00000000..4056fbed
--- /dev/null
+++ b/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.