46 more unit tests, and `vm-mcp` rewritten around the new split (21 subtests, up from 14). `test_mcp_resources.py` is the new file and its subject is what the resource layer actually decides: which entry a URI resolves to, which query parameters it will accept, and the argv each read builds. The cases that matter are the ones a reshuffle would quietly break -- a literal route beating a template (`hhstream://sessions` is the listing, not a session with a blank id), a switch parameter becoming a bare flag or nothing at all (`--all=false` is not something the CLI takes), an undeclared parameter being refused rather than dropped, a frame's media type being sniffed rather than assumed, and a refusal being *raised* instead of returned as the body. One test exists only to stop a future kindness: there must be no resource for the reconciling container read, because that one writes. `test_mcp_server.py` grows the protocol-level half -- both listings, a read that returns JSON, a read that returns a blob, a refused read arriving as `McpError`, and a toolset selection that narrows the tools while leaving the resources alone. The tool and toolset tests move with the surface: the read-only verbs are asserted *absent* by name rather than merely missing, so re-adding one is a failure instead of a silent widening of what mcp-v2 narrowed. In the guest, the subtest the whole surface turns on is now measured rather than described: two reads of `hhstream://sessions/<id>` must NOT move the idle deadline, and `session_touch` must. It also asks for the same container two ways and checks the answers agree, reads one output's frame as a blob and confirms the `shot` tool reports the same geometry, and proves `--toolsets` makes an omitted tool unreachable and not merely unlisted. `checks/lib/mcp_client.py` gains `--resources`, `--read` and `--server-arg`, and exits 3 rather than 2 on a protocol error -- so "the server refused this read" stays distinguishable from "the server did not answer at all", which is the distinction that keeps the refusal subtests from passing for the wrong reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
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.
{
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:
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 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:
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:
{
"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.