`docs/CONTRACT-mcp.md` (mcp-v1) is the new interface, written the way this repository writes interfaces: the tool names, the arguments each takes, the flag form, what is deliberately absent and why, and a row per exit code saying what it arrives as and what an agent should do about it. An agent that has learned these names is a consumer like any other, so renaming one needs a version bump. README.md gains the section an operator reads: the `mcp.enable` option, the `mcpServers` block to register it with, why both environment variables are shown at their defaults, and what to do when `shot` cannot read the frame socket. README.dev.md gains the `nix build .#hhstream-mcp` half of the build section, the `vm-mcp` row, the new files in the layout, and the reason `mcp` is in the unit check's environment. ARCHITECTURE.md gains the sixth box, drawn above the CLI rather than beside the broker, because that is where it sits. `docs/TODO/mcp-in-process-has-no-call-deadline.md` records the two things the in-process seam costs, rather than leaving them to be rediscovered. A thread cannot be interrupted, so there is no per-call deadline and a wedged call queues every later one behind it; and `cli.main`'s `sg` re-exec is an `exec` this server cannot perform, so a frame verb that cannot read the socket fails where the CLI would have recovered. The second is the one an operator meets first -- the CLI works from their shell and the tool does not -- which is why the failure says what the CLI would have done and how to not need it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
# hyprland-headless-stream-plugin
|
|
|
|
A Nix flake that runs a **headless Hyprland session** and publishes its frames on
|
|
a **persistent Unix socket**, so any process that can open a socket can see the
|
|
screen without owning a display.
|
|
|
|
Two parts:
|
|
|
|
- **NixOS module** — `services.hyprland-headless-stream`: starts Hyprland with
|
|
no physical monitor, and a small frame server beside it.
|
|
- **Package** — `hhstream` — the frame server (publishes frames) and its client
|
|
(reads them). Pure Python standard library.
|
|
|
|
```nix
|
|
{
|
|
inputs.hhstream.url = "git+https://<host>/git/<owner>/hyprland-headless-stream-plugin.git";
|
|
|
|
# in your host config
|
|
imports = [ inputs.hhstream.nixosModules.default ];
|
|
services.hyprland-headless-stream = {
|
|
enable = true;
|
|
# Optional: the default is one 1280x720@30 rule with an empty name, which
|
|
# is Hyprland's wildcard and applies to whatever outputs the GPU has.
|
|
outputs = [ { width = 1920; height = 1080; refresh = 60; } ];
|
|
};
|
|
}
|
|
```
|
|
|
|
Then any consumer:
|
|
|
|
```bash
|
|
hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
|
|
```
|
|
|
|
The socket is a plain file descriptor: the server serves every client that
|
|
connects, and keeps running when one disconnects.
|
|
|
|
## Driving it from an agent: the MCP server
|
|
|
|
`hhstream-mcp` is the `hhstream` CLI as [Model Context
|
|
Protocol](https://modelcontextprotocol.io) tools, so an agent can look at this
|
|
desktop, put an application on it, and aim its one pointer and keyboard at that
|
|
application through typed tools instead of a shell. One tool per CLI verb,
|
|
twenty-six of them; the interface is frozen in `docs/CONTRACT-mcp.md`.
|
|
|
|
It is a thin wrapper and nothing more: every tool builds the argv list the CLI's
|
|
own parser takes, runs the CLI's own handler, and maps what came back. The idle
|
|
clock, the pointer lease, the allowlist and the exit-code table all stay where
|
|
they were.
|
|
|
|
Install it with the module — off by default, because it is the surface through
|
|
which a language model starts processes on this machine:
|
|
|
|
```nix
|
|
services.hyprland-headless-stream = {
|
|
enable = true;
|
|
sessions.enable = true; # the session, pointer and keyboard tools need the broker
|
|
mcp.enable = true; # puts `hhstream-mcp` on the system PATH
|
|
};
|
|
```
|
|
|
|
Then register it with a client. The transport is **stdio** — one process per
|
|
client, spawned by the client, no port and no daemon — so the whole
|
|
configuration is a command and an environment:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"hhstream": {
|
|
"command": "hhstream-mcp",
|
|
"env": {
|
|
"HHSTREAM_SOCKET": "/run/hhstream/control.sock",
|
|
"HHSTREAM_FRAME_SOCKET": "/run/hypr-stream/stream.sock"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Both variables are the CLI's own and both are shown at their defaults, so they
|
|
can be left out unless this machine moved a socket. The account the client runs
|
|
as needs what the CLI needs: membership of the compositor's group (`hhstream`)
|
|
to read the frame socket, and of the broker's to reach the control socket. The
|
|
server cannot recover that for itself the way the CLI does — see
|
|
`docs/CONTRACT-mcp.md` §5 — so if `shot` reports it cannot read the socket, the
|
|
answer is `"command": "sg", "args": ["hhstream", "-c", "hhstream-mcp"]` or an
|
|
account in the group.
|
|
|
|
`hhstream-mcp --list-tools` prints the table and exits, which is the quickest
|
|
way to check an install. Nothing else about the server is configurable: it holds
|
|
no state, caches no lease, and the pointer lease is an explicit argument on
|
|
every gesture tool for exactly that reason.
|
|
|
|
| Document | What it is |
|
|
|---|---|
|
|
| `docs/CONTRACT.md` | the wire protocol and the module surface — the interface other people build against |
|
|
| `docs/CONTRACT-sessions.md` | the broker, the containers and the input lease |
|
|
| `docs/CONTRACT-mcp.md` | the MCP tools: their names, arguments and error mapping |
|
|
| `docs/ARCHITECTURE.md` | how the pieces fit: compositor, capture, server, client |
|
|
| `README.dev.md` | how to build, test and hack on it |
|
|
| `examples/README.md` | the demo that films the screen: `agent-eyes-demo.py` |
|
|
|
|
Status: work in progress — the module and the test suite are being built. |