docs(mcp): freeze the tool surface, and record what the in-process seam costs
`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
This commit is contained in:
1 parent
fea55eecde
commit
6a40c7e2e4
6 files changed
+473
-11
No files matched your search
@@ -35,9 +35,67 @@ 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` |
|
||||
|
||||
Reference in new issue
Block a user