`docs/CONTRACT-mcp.md` goes to mcp-v2 with a change table at the top, because v1 lasted a day and an agent that learned it deserves to be told what moved rather than to discover it. The new §4 freezes the resource surface: the eight URIs, their bodies, their query parameters, and the five rules the layer keeps (a read never writes; only declared parameters; a literal route beats a template; a frame's media type comes from its bytes; no subscriptions). §6 gains the other half of the error mapping -- for a resource read every exit code arrives as `-32602` with the remedy in `message` and the structured object in `data`, because `ReadResourceResult` has no `isError` to use instead. §2 records what `--toolsets` is and is not: there is no grouping primitive in MCP, the `Tool` object has nowhere to put a family, and tools are a flat list in the specification too -- so the only lever is which tools the server lists, decided by whoever spawns it. README.md leads with the split rather than with a tool count, since that is the thing a reader has to understand before any of the names make sense, and shows the `--toolsets` form for a client with a tight budget. ARCHITECTURE.md's sixth box grows its second half and says why `shot` is on both sides. A second TODO, `mcp-resources-cannot-be-subscribed-to.md`, records the limit that cost the most: `Server.get_capabilities` hardcodes `ResourcesCapability(subscribe=False, …)`, so registering a `subscribe_resource` handler changes nothing and a client is correctly told not to try. Subscriptions would have been the principled answer to the missing `logs --follow` -- it is the one place this design wanted a capability the SDK will not advertise -- so the file names the one-line local override, says what it risks, and recommends upstreaming the real fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
129 lines
5.3 KiB
Markdown
129 lines
5.3 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 behind a [Model Context
|
|
Protocol](https://modelcontextprotocol.io) surface, so an agent can look at this
|
|
desktop, put an application on it, and aim its one pointer and keyboard at that
|
|
application without writing command lines. The interface is frozen in
|
|
`docs/CONTRACT-mcp.md`.
|
|
|
|
It is split the way the protocol splits things:
|
|
|
|
- **Resources are the state** — eight of them, read by URI, and reading one
|
|
changes nothing. `hhstream://status` is whether the desktop is up,
|
|
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
|
|
an application's own output, `hhstream://pointer` is who holds the input
|
|
lease, `hhstream://screen` is a frame of the screen.
|
|
- **Tools are the acts** — twenty-one, one per CLI verb that does something.
|
|
`session_start` puts an application on the screen, `pointer_acquire` takes the
|
|
input lease, `keyboard_type` types, `session_kill` ends a session.
|
|
|
|
A host decides what state to put in front of its model; the model decides what
|
|
to do. That is the whole of the split, and it is why `shot` is still a tool
|
|
(capturing is an act at a moment) while `hhstream://screen` exists beside it.
|
|
|
|
It is a thin wrapper and nothing more: every tool and every resource 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` and `--list-resources` print the two tables and
|
|
exit, which is the quickest way to check an install.
|
|
|
|
If twenty-one tools is more than a client has room for, `--toolsets` narrows
|
|
what is offered to whichever families are wanted — `frames`, `sessions`,
|
|
`pointer`, `keyboard`:
|
|
|
|
```json
|
|
{ "command": "hhstream-mcp", "args": ["--toolsets", "frames,pointer,keyboard"] }
|
|
```
|
|
|
|
Resources are deliberately *not* narrowed by it: they are the host's context,
|
|
not the model's tool budget. Nothing else about the server is configurable — it
|
|
holds no state and 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 surface: the resource URIs, the tool names, their arguments and the 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. |