`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
14 KiB
CONTRACT — the MCP server (mcp-v1)
This file is the interface of hhstream-mcp: the tool names, the arguments each
takes, what comes back, and which of the CLI's exit codes arrives as which kind
of MCP error. It is the sibling of docs/CONTRACT.md (the frame socket's wire
format) and docs/CONTRACT-sessions.md (the broker, the containers and the
input lease).
Immutable without a version bump. An agent that has learned these names and these argument shapes is a consumer like any other, and renaming a tool breaks it exactly as renaming a wire verb would.
Version: mcp-v1 (2026-10-11).
0. What this is, and what it is not
It is a shim. Each tool builds the argv list the hhstream CLI's own parser
takes, hands it to the CLI's own handler in this process, and maps what came
back. Nothing in it decides anything:
| Rule | Whose it is |
|---|---|
the idle clock, and that only touch resets it |
the broker |
| the pointer lease: who holds it, its TTL, what it lifts | the broker |
| the allowlist, and which arguments an app may be given | the broker's policy |
| the exit-code table | docs/CONTRACT-sessions.md §4 |
the refusal messages (reason, hint) |
the CLI and the broker |
| coordinate normalisation, the scroll bound, the type cap | the broker and the driver |
What this layer owns is the argv list, the mapping of a result to MCP content, and one sentence of remedy per exit code — the "what to do next" that the CLI says to a human in the words of a command line and an agent needs in the words of tools.
In process, not as a subprocess: hhstream.cli is importable Python whose
parser already takes an argv list and whose handlers already return a code from
the frozen table. Two of its paths cannot be called here, and both are
documented in hhstream_mcp.invoke: cli.main's sg re-exec, and cmd_run's
execvpe. Consequences of the first are in §5.
1. Transport
stdio, and only stdio. One process per client, spawned by the client; no port, no daemon, no socket of its own. There is already a daemon in this system and it owns all the state.
The protocol is not on file descriptor 1 once the server is running: the
tools run the CLI in process, the CLI prints, and record spawns an ffmpeg
whose output the CLI does not capture. The server takes a private duplicate of
stdin and stdout at start-up, then points fd 1 at its log and fd 0 at
/dev/null. A stray write is therefore a log line and never a corrupted
stream.
2. Configuration
There is no --socket flag. The sockets are the CLI's own environment, read by
the CLI:
| Variable | What it names | Default |
|---|---|---|
HHSTREAM_SOCKET |
the broker's control socket | /run/hhstream/control.sock |
HHSTREAM_FRAME_SOCKET |
the published frame socket | /run/hypr-stream/stream.sock |
Set them in the MCP client's env block. One place to configure them is one
place for them to be wrong.
The server's own command line is two flags: --list-tools, which prints the
table and exits (the package's install check uses it), and nothing else that
affects behaviour. $HHSTREAM_MCP_LOG sets the log level on stderr.
3. The tool surface
One tool per CLI verb, named after it, with _ where the CLI has a space.
Twenty-six tools. The rationale — and the alternative that was rejected, one
tool per family with an action enum — is in hhstream_mcp.tools' docstring.
Every schema sets additionalProperties: false, so an argument this server
would not pass through is refused by the schema rather than dropped on the way
to an argv list.
Frames
| Tool | Arguments | Returns |
|---|---|---|
status |
— | the CLI's own text report: both units, the socket's reachability, one probe frame. This verb has no JSON form, so neither does the tool. |
shot |
output? |
image content (PNG or JPEG, by the bytes' own magic) plus text naming the geometry, the media type and the byte count |
record |
seconds?, out?, output?, fps?, work_dir?, keep? |
the artefact's path and the measured rate — never the video |
run |
argv, settle_s? |
the application's pid, and that it is unmanaged |
shot captures to a temporary file and reads it back, because that is the CLI's
only output shape. The media type comes from the bytes and not from the
extension: the publisher serves image/jpeg on some machines and hhstream shot writes the payload it was given verbatim.
record hands back a path because an mp4 of a 720p desktop is megabytes and a
tool reply is a message in a model's context. The rate is the one the capture
measured, read off the CLI's own line.
run is spawned with posix_spawn into its own session and not waited for.
settle_s (default 1.5) is how long the server watches it before reporting the
pid: a launch that fails — no Wayland socket, no such executable — fails inside
that window and comes back as an error, one that survives it comes back as
running.
Session lifecycle
| Tool | Arguments |
|---|---|
session_start |
app, argv?, idle_timeout?, wait_ready?, home?, ephemeral_home?, request_id? |
session_list |
all? |
session_status |
id, events? |
session_touch |
id |
session_kill |
id, grace?, signal?, request_id? |
session_gc |
request_id? |
session_adopt |
pid, app?, idle_timeout?, request_id? |
session_logs |
id, lines? |
session_container |
id? |
session_reconcile |
id?, request_id? |
Every one of these runs with --json, so what comes back is the broker's own
protocol object: in the text part verbatim, and in structuredContent parsed.
The human rendering is a table for a terminal; scraping it would be inventing a
second wire format.
home and ephemeral_home are mutually exclusive, and the schema says so —
the CLI's argparse group, moved forward to where the refusal is free.
session_container is not marked read-only, and that is not an oversight:
with an id the CLI runs container.reconcile, which writes the record back.
With no id it lists.
Input — the pointer lease is an argument, never a cache
| Tool | Arguments |
|---|---|
pointer_acquire |
id, ttl?, no_restore? |
pointer_move |
id, lease, exactly one of to / by (each [x, y]) |
pointer_click |
id, lease, button? |
pointer_scroll |
id, lease, axis?, amount? |
pointer_down |
id, lease, button? |
pointer_up |
id, lease, button? |
pointer_release |
id, lease |
pointer_state |
— |
keyboard_type |
id, lease, text |
keyboard_key |
id, lease, name |
keyboard_down |
id, lease, name |
keyboard_up |
id, lease, name |
lease is required on every gesture. The CLI caches the lease id between
invocations (hhstream_session.lease) because its surface is flagless and it is
one process per verb; this server passes --lease explicitly on every call and
so never reads that cache. The reason is worth stating in full: a cached lease
is a lease an agent cannot see, and the failure it
produces — a gesture that went to a lease the agent did not know it held — is
not one a transcript can explain.
pointer_acquire's reply puts lease_id on the first line of the text part,
because that is what the next call needs.
pointer_state takes no session id. There is one cursor.
Durations (ttl, idle_timeout, wait_ready, grace) are strings in the
CLI's own vocabulary: 30s, 5m, 3h, 2d, or a bare number of seconds.
They are passed through untouched, so the parsing and the refusal are the CLI's.
Flag form
Every option value is passed as one --name=value token, and a literal --
precedes every positional. Not a style choice: --by -0.1,0.5 and a text
beginning with a dash are both values argparse reads as option strings, and one
uniform rule is one fewer thing to get wrong per flag.
4. What is deliberately absent
| Not exposed | Why |
|---|---|
session logs --follow |
it polls until interrupted, and a tool call that never returns hangs the client that made it. Call session_logs again. |
session start --no-container |
the CLI's flag exists in order to refuse: the broker's start verb carries no such field (docs/CONTRACT-sessions.md §4), so the CLI exits 2 and names the disagreement. A tool argument whose only possible outcome is a refusal is a trap. |
hhstream --frame-socket / session --socket |
§2: the environment configures them, in one place. |
| a per-call timeout | §5. |
session keyboard with no verb |
it prints help and exits 2. There is nothing for a tool to do with that. |
5. Error mapping
Every refusal the CLI produces comes back as a tool error —
CallToolResult with isError: true — carrying:
- the remedy sentence, first, naming the code:
exit 9 (NO_LEASE): …; - the CLI's own
error,reasonandhintwhen it printed a protocol object; - everything it said, verbatim, under
hhstream said:; structuredContentwithok: false,exit_code,remedy, and the protocol object's own fields.
isError and not a JSON-RPC error, throughout. A JSON-RPC error reaches the
client's log; "another session holds the lease" is something the calling agent
has to read and act on. (The SDK's call_tool handler also converts anything
raised into isError, so this is the only channel there is in practice.)
| Exit | Name | Arrives as | The remedy an agent is given |
|---|---|---|---|
| 0 | OK | a result | — |
| 1 | not in the frozen table | tool error | the frame verbs' own failure: no frame published, or grim/ffmpeg missing from the server's PATH. Also what an uncaught exception in a handler becomes, with its traceback — which is what a CLI process would have done. |
| 2 | USAGE | tool error | fix the arguments; a retry fails identically |
| 3 | NO_SUCH_SESSION | tool error | session_list to see which ids exist |
| 4 | BAD_STATE | tool error | session_status to see which state |
| 5 | DAEMON_UNREACHABLE | tool error | an operator problem; the four frame tools may still work |
| 7 | TIMEOUT | tool error | read the state back, then retry with the same request_id |
| 6 | POLICY | tool error | a configuration decision; no retry changes it |
| 8 | BUSY | tool error | pointer_state names the holder; wait. Never "acquire one" |
| 9 | NO_LEASE | tool error | pointer_acquire, then pass the new lease_id |
| 10 | COMPOSITOR | tool error | the session is not lost; it is degraded |
8 and 9 must never read alike, and a unit test holds them apart: an agent that sees 8 must wait, one that sees 9 must acquire.
Two failures are not the CLI's verdict and are reported in the same channel anyway, because the agent holding the tool is the one who has to say so:
- a tool name that does not exist — the reply names the ones that do;
- an argument the schema rejects — the SDK refuses before an argv list exists, so the CLI is never reached.
The sg re-exec is not available here. hhstream recovers from an
unreadable frame socket by re-executing itself through the setuid sg wrapper
to join the compositor's group. That is an exec, and performing it would
replace this server and drop the client's connection. So a frame verb that
cannot reach the socket fails with the CLI's own message plus a sentence saying
what the CLI would have done and how to avoid needing it: run the server as a
member of that group (sg hhstream -c hhstream-mcp in the client's spawn
command, or add the account to the group). The hint is added only when the
condition is actually true, asked of the CLI's own predicate, and only for the
verbs it could be true of.
There is no per-call timeout. In process there is nothing to kill: a thread
cannot be interrupted. The deadlines are therefore the ones that already exist
— the session client's 60 s socket timeout, the broker's per-verb deadline, and
the frame socket's own --timeout — and a call that outlives all of them
outlives this server too. A subprocess design could have killed it; that is the
one thing given up by calling the CLI in process.
6. Concurrency
Tool calls are serialised. The CLI prints to a process-global sys.stdout,
so two concurrent calls would interleave their output into each other's reply.
One lock around the whole call is the honest fix, and costs nothing a caller
would notice: the broker already serialises every mutation, and the CLI was one
process per verb anyway. The event loop stays free, so a ping is answered
while a record runs.
7. The two rules, which every relevant tool repeats
These are hhstream_session.ACTIVITY_NOTE and KEYBOARD_LEASE_NOTE restated
in terms of tools. They are on the individual tools and not only in the server
instructions, because a client shows a tool's own description at the point of
use:
-
session_touchis the only thing that resets a session's idle clock.session_list,session_status,session_logsandsession_gcdo not, and neither does any pointer or keyboard tool. A session being driven is still a session nobody has said they want kept. -
Every keyboard tool needs the pointer lease, and holds only while it holds. There is no keyboard lease: one compositor seat means one keyboard focus. A held non-modifier key floods the window until it is lifted or the lease expires, because the application does the repeating — measured at 25 a second after 600 ms — and this server cannot rate-limit what it does not generate.
tests/unit/test_mcp_tools.py asserts both notes are present on every tool
they apply to, and holds the CLI's own constants as a tripwire against drift.
8. Packaging
packages.hhstream-mcp (nix/mcp.nix), a separate derivation from
packages.hhstream because mcp is a third-party dependency and the frame
socket, the CLI and the broker are stdlib-only by policy. packages.hhstream
must not grow that dependency; the root pyproject.toml excludes
hhstream_mcp* from its package discovery so it cannot acquire it by accident.
services.hyprland-headless-stream.mcp.enable (default false) puts the
binary on the system PATH. That is the whole of the option: there is no unit, no
socket and no state directory, because the server is spawned per client over
stdio.