`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
284 lines
14 KiB
Markdown
284 lines
14 KiB
Markdown
# 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`, `reason` and `hint` when it printed a protocol object;
|
|
- everything it said, verbatim, under `hhstream said:`;
|
|
- `structuredContent` with `ok: 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:
|
|
|
|
1. **`session_touch` is the only thing that resets a session's idle clock.**
|
|
`session_list`, `session_status`, `session_logs` and `session_gc` do not, and
|
|
neither does any pointer or keyboard tool. A session being driven is still a
|
|
session nobody has said they want kept.
|
|
|
|
2. **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.
|