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
+38
-10
@@ -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
|
||||
|
||||
Reference in new issue
Block a user