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:
HermenixandClaude Opus 5 committed 2026-10-11 06:33:07 +00:00
1 parent fea55eecde
commit 6a40c7e2e4
6 files changed
+473 -11

No files matched your search

+38 -10
View File
@@ -7,8 +7,8 @@ decides, and if the document is wrong it gets a version bump, not an edit.
## Prerequisites
- Nix with flakes enabled.
- `/dev/kvm` readable, for the six VM checks. They are `nixosTest`s; without
KVM they still run, just slowly enough that the timeouts below get tight.
- `/dev/kvm` readable, for the VM checks. They are `nixosTest`s; without KVM
they still run, just slowly enough that the timeouts below get tight.
- No GPU. Nothing in the test suite needs one — the compositor runs on
Hyprland's headless backend over software rendering.
@@ -21,21 +21,38 @@ socket outside the build sandbox or the test VM.
nix develop
```
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH
and sets `PYTHONPATH=$PWD/src`, so `import hhstream` picks up the working tree
rather than an installed copy.
Puts `python3`, `pytest`, `hyprland`, `grim`, `ffmpeg`, `jq` and `tmux` on PATH,
plus both packages (`hhstream` and `hhstream-mcp`) and the `mcp` SDK, and sets
`PYTHONPATH=$PWD/src`, so `import hhstream` and `import hhstream_mcp` both pick
up the working tree rather than an installed copy.
## Build
```bash
nix build .#hhstream # the package
ls result/bin # hhstream-server, hhstream-client, hhstream,
# hhstreamd, hhstream-pointer
# hhstreamd, hhstream-pointer, hhstream-live
nix build .#hhstream-mcp # the MCP server, a SEPARATE derivation
ls result/bin # hhstream-mcp
```
Five entry points: the frame server and a reference reader for it, the `hhstream`
front-door CLI (frames, `run`, and the `session` namespace), the session broker,
and the pointer driver.
The first package's entry points: the frame server and a reference reader for
it, the `hhstream` front-door CLI (frames, `run`, and the `session` namespace),
the session broker, the pointer driver and the session-stream web app.
`hhstream-mcp` is its own derivation on purpose. It is the CLI as Model Context
Protocol tools (`docs/CONTRACT-mcp.md`), it depends on the third-party `mcp`
SDK, and `packages.hhstream` is stdlib-only by policy — see the header of
`nix/mcp.nix`. It depends on the `hhstream` package as a *library*: the tools
call `hhstream.cli`'s handlers in process rather than spawning the CLI. The dev
shell has both, plus `python3.pkgs.mcp` so `tests/unit/test_mcp_server.py` can
import the SDK:
```bash
nix develop
hhstream-mcp --list-tools # the whole surface, 26 lines, no stdio
```
## The checks
@@ -51,6 +68,7 @@ and the pointer driver.
| `vm-keyboard` | the **keymap, the focus and a decoded symbol**: the keymap the driver uploads reaching a real compositor, `pointer acquire` leaving the aimed window holding the *keyboard* and not merely the cursor, and `hhs-keyboard-target` decoding `hello` from the keymap it was **forwarded** — so a driver that stopped uploading one arrives as `sym=?` and goes red | yes |
| `vm-keyboard-de` | the same file with `sessions.keyboard.layout = "de"`, because that option reaches the uploaded keymap through exactly one path — `--xkb-layout` on the driver unit — and a single-layout check cannot tell that path from a hardcoded `us`: keysym `y`'s evdev code swaps (21 against 44), the forwarded `symbols=` name with it, and `ü` goes from exit 2 to `udiaeresis` | yes |
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 26 tools are listed with their annotations and their two rules, a call reaches the live broker and returns its own protocol object, `shot` arrives as image content at the configured geometry, the pointer lease is granted/used/returned, and exits 9 and 3 arrive as tool *errors* carrying the frozen code | yes |
All of them at once:
@@ -75,6 +93,7 @@ nix build -L .#checks.x86_64-linux.vm-pointer
nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
nix build -L .#checks.x86_64-linux.vm-mcp
```
`-L` is not optional in practice: without it, Nix hides the build log, and the
@@ -97,7 +116,11 @@ warning.
pytest over `tests/unit/`, run in the build sandbox with `PYTHONPATH` pointing at
what `nix/package.nix` installed (`nix/package.nix` sets `doCheck = false` on
purpose, so this is the only place the suite runs in a build).
purpose, so this is the only place the suite runs in a build). `nix/mcp.nix`'s
output is on that path beside it, and `mcp` is in the test environment, because
`tests/unit/test_mcp_*.py` import `hhstream_mcp` and one of them imports the SDK
— not optionally: a file that skipped when the SDK was absent would be green in
exactly the build where a malformed tool schema mattered.
The check fails if the suite is **empty**, not just if it is red. `pytest` exits
5 on "collected nothing", but it exits 0 when every test was skipped or
@@ -230,6 +253,11 @@ checks/
(layout us) and `vm-keyboard-de` -- because the layout
reaches the keymap only through the driver unit's argv
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw
JSON-RPC client against the live broker
lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately
NOT the MCP SDK's -- the SDK on both ends would agree
with itself about a framing neither side had to get right
lib/test-tools.nix packages the tests/ helpers for the guest
lib/session-tools.nix packages the two guest programs below
lib/session-machine.nix the guest the three session checks share