Merge feat/mcp-server (9708154) into feat/mcp-auth
The base branch moved twelve commits while this work was in flight --
including the per-session live stream and its own contract bump -- so this
integrates rather than leaving a PR nobody can merge. Six files
conflicted; the interesting resolutions are the two that were not
textual.
**The contract is mcp-v3.1, not v2.1.** This branch bumped v2 -> v2.1 for
an additive change; `feat/mcp-server` bumped v2 -> v3 for the live stream,
also additive. Both point releases, both correct, and they cannot both be
the same document. So v3 stands as written and the HTTP transport is the
point release on top of it, by the same rule each of us applied
independently: v2 is still the only major bump, because it is still the
only one that removed anything.
**The counts are no longer literals.** This branch asserted `21 tools` and
`5 resources` in `checks/vm-mcp-http.nix` and `5` in `test_mcp_http.py`;
the stream added two tools and one fixed resource, so the surface is 23
and 6. Rather than re-hardcode numbers that will go stale again, the
check now counts against `--list-tools` and `--list-resources` -- the
server's own table -- and the unit test against `resources.FIXED`. That
is the lesson 9708154 ("count the unnarrowed resources against the
listing, not a literal") had already learned on the other side of this
merge, arrived at twice. A stale number here would have failed in a way
indistinguishable from the HTTP transport dropping tools, which is the
one thing those subtests exist to catch.
The rest were additive on both sides and both halves are kept: the TODO
table, the checks wiring, the README check rows, the architecture diagram
(their 23/10 counts with this branch's two-transport annotation).
`nix/module.nix` needed reconstructing -- git interleaved the bodies of
`hhstream-live` and `hhstream-mcp` because both units land between the
same surrounding lines -- so the live unit is taken verbatim and the MCP
unit placed after it, with this branch's options, tmpfiles entry,
firewall rule, two assertions and two warnings re-applied on top.
One thing deliberately NOT touched: the v3 change table cites `§6` for the
idle-clock exception, but the rule it means is `§8`. That is the other
branch's prose and its author's call, not something to quietly rewrite in
a merge.
Verified after resolution: 394 unit tests pass, and the module evaluates
with both units, the right ExecStart, one firewall port and both
warnings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
This commit is contained in:
commit
f83717ba71
37 files changed
+4241
-101
No files matched your search
+66
-13
@@ -1,4 +1,4 @@
|
||||
# CONTRACT — the MCP server (mcp-v2.1)
|
||||
# CONTRACT — the MCP server (mcp-v3.1)
|
||||
|
||||
This file is the interface of `hhstream-mcp`: the resource URIs, the tool names,
|
||||
the arguments each takes, what comes back, and which of the CLI's exit codes
|
||||
@@ -10,13 +10,17 @@ containers and the input lease).
|
||||
these argument shapes is a consumer like any other, and renaming a tool breaks
|
||||
it exactly as renaming a wire verb would.
|
||||
|
||||
Version: mcp-v2.1 (2026-10-11). v1 was the first freeze and lasted one day;
|
||||
v2 lasted about as long.
|
||||
Version: mcp-v3.1 (2026-10-12). v1 was the first freeze and lasted one day; v2
|
||||
split state out into resources; v3 added the live stream; v3.1 adds a second
|
||||
transport. Only v2 ever broke anything.
|
||||
|
||||
**v2.1 is additive and breaks nothing.** No tool was renamed, no argument
|
||||
changed shape, no resource moved. A client written against v2 over stdio is a
|
||||
client that still works, which is why this is a point release and not v3 — v2
|
||||
was a bump because it *removed* five tools.
|
||||
**v3.1 is additive and breaks nothing.** No tool was renamed, no argument
|
||||
changed shape, no resource moved. A client written against v3 over stdio is a
|
||||
client that still works — which is why this is a point release, the same way v3
|
||||
was additive over v2 and for the same reason. v2 is still the only major bump,
|
||||
because it is the only one that *removed* anything.
|
||||
|
||||
v3.1 changes, all of them the HTTP transport and the credential it needs:
|
||||
|
||||
| § | Change | Why |
|
||||
| --- | --- | --- |
|
||||
@@ -25,6 +29,16 @@ was a bump because it *removed* five tools.
|
||||
| §3 | A token may carry its own `toolsets`, and the **intersection** with the server's `--toolsets` applies. | `--toolsets` is a launch-time flag, and one HTTP process serves many callers: a per-process tool budget stops being a per-caller one the moment the transport is shared. |
|
||||
| §10 | What the HTTP transport's token **is not**: not OAuth 2.1, not RFC 9728, no metadata discovery. | A limit worth stating in the same register as the two the SDK imposes. |
|
||||
|
||||
v3 changes, all of them the per-session live stream
|
||||
(`docs/CONTRACT-sessions.md` §4, v4):
|
||||
|
||||
| § | Change | Why |
|
||||
| --- | --- | --- |
|
||||
| §3 | Tools `session_stream_enable` and `session_stream_disable`. 21 tools became 23. | Switching a stream on is an *act*, and a consequential one: it publishes a desktop on the LAN behind a phrase. Nothing about it is a read. |
|
||||
| §3 | `session_start` gains `stream`, `stream_phrase` and `stream_fps`, and its reply carries the URL. | A stream needs the container output that starting creates, so sequencing start-then-enable in the caller means every caller repeats the ordering and the half-done case. One call, one answer, and the phrase comes back with the session. |
|
||||
| §4 | Resources `hhstream://streams` and `hhstream://sessions/{id}/stream`. 8 resources became 10. | What is being published, and who is watching, is state — so it is read, not called. |
|
||||
| §6 | A connected viewer is the **one exception** to the idle-clock rule. | About once a minute the broker stamps `touch` on any session somebody is watching. It is not a verb and cannot be invoked; it is the broker noticing that a person is looking. |
|
||||
|
||||
**v2 is a breaking change, and the only one: the verbs that merely read are
|
||||
resources now, not tools.**
|
||||
|
||||
@@ -260,7 +274,7 @@ to an argv list.
|
||||
| family | tools |
|
||||
| --- | --- |
|
||||
| `frames` | `shot`, `record`, `run` |
|
||||
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile` |
|
||||
| `sessions` | `session_start`, `session_touch`, `session_kill`, `session_gc`, `session_adopt`, `session_container`, `session_reconcile`, `session_stream_enable`, `session_stream_disable` |
|
||||
| `pointer` | `pointer_acquire`, `pointer_move`, `pointer_click`, `pointer_scroll`, `pointer_down`, `pointer_up`, `pointer_release` |
|
||||
| `keyboard` | `keyboard_type`, `keyboard_key`, `keyboard_down`, `keyboard_up` |
|
||||
|
||||
@@ -294,13 +308,15 @@ running.
|
||||
|
||||
| Tool | Arguments |
|
||||
| --- | --- |
|
||||
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `request_id?` |
|
||||
| `session_start` | `app`, `argv?`, `idle_timeout?`, `wait_ready?`, `home?`, `ephemeral_home?`, `stream?`, `stream_phrase?`, `stream_fps?`, `request_id?` |
|
||||
| `session_touch` | `id` |
|
||||
| `session_kill` | `id`, `grace?`, `signal?`, `request_id?` |
|
||||
| `session_gc` | `request_id?` |
|
||||
| `session_adopt` | `pid`, `app?`, `idle_timeout?`, `request_id?` |
|
||||
| `session_container` | `id` |
|
||||
| `session_reconcile` | `id?`, `request_id?` |
|
||||
| `session_stream_enable` | `id`, `phrase?`, `fps?` |
|
||||
| `session_stream_disable` | `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.
|
||||
@@ -310,6 +326,21 @@ 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_stream_enable` returns the **URL** on the first line of its text part,
|
||||
because that is the whole point of the call: it is what gets handed to a person.
|
||||
It publishes the session's own container output and never the main one — that
|
||||
output carries every other session, and putting it behind one session's phrase
|
||||
is the mistake the broker refuses to make (exit 10 with no container). Re-enabling
|
||||
returns the same URL; a different `phrase` is exit 8, not a silent rotation,
|
||||
because rotating under somebody holding the old URL is the one outcome neither
|
||||
answer can be mistaken for. `session_stream_disable` is marked **destructive**:
|
||||
it forgets the phrase, so anyone holding that URL loses it.
|
||||
|
||||
`session_start` with `stream: true` is one call rather than two, and a stream
|
||||
that cannot be opened **does not fail the start** — the application is on the
|
||||
screen, and killing it over a web page would be the wrong trade. The reply
|
||||
carries `stream_error` whenever `stream` was asked for, `null` when it worked.
|
||||
|
||||
`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.
|
||||
That is also why it is a tool rather than a resource. The no-id listing, which
|
||||
@@ -372,6 +403,13 @@ verb a tool would have, with `--json` where the verb has it.
|
||||
| `hhstream://sessions/{id}` | `application/json` — one session with its recent audit events | `?events=N` |
|
||||
| `hhstream://sessions/{id}/logs` | `application/json` — the application's own captured output | `?lines=N` |
|
||||
| `hhstream://outputs/{name}` | one output captured alone, as an image blob. Exactly that output's configured size, which is the coordinate space the pointer tools aim in. | — |
|
||||
| `hhstream://streams` | `application/json` — every session a stream was enabled on, with its URL, rate and connected viewer count, plus `available` (whether the stream daemon answered) | — |
|
||||
| `hhstream://sessions/{id}/stream` | `application/json` — one session's stream, or `null`. `attached` is separate from `enabled`, and the URL is absent rather than stale when it is false. | — |
|
||||
|
||||
**The URLs in those two bodies contain their phrases**, which are the only thing
|
||||
protecting those streams. Both descriptions say so, because a host that puts
|
||||
`hhstream://streams` into a model's context has put a credential there — and
|
||||
the one place it must never go is anywhere the streamed session can see.
|
||||
|
||||
Rules this surface keeps:
|
||||
|
||||
@@ -489,13 +527,22 @@ in terms of this surface. They are on the individual tools and resources and
|
||||
not only in the server instructions, because a client shows a thing's own
|
||||
description at the point of use:
|
||||
|
||||
1. **`session_touch` is the only thing that resets a session's idle clock.**
|
||||
Reading `hhstream://sessions`, `hhstream://sessions/{id}` or its logs does
|
||||
not, `session_gc` does not, and neither does any pointer or keyboard tool. A
|
||||
1. **`session_touch` is the only thing a *caller* can do that resets a
|
||||
session's idle clock.** Reading `hhstream://sessions`,
|
||||
`hhstream://sessions/{id}` or its logs does not, `session_gc` does not, the
|
||||
stream tools do not, and neither does any pointer or keyboard tool. A
|
||||
session being driven is still a session nobody has said they want kept. The
|
||||
three resources it applies to say so in their own descriptions, because a
|
||||
resources it applies to say so in their own descriptions, because a
|
||||
description is what a host shows beside the thing it describes.
|
||||
|
||||
**The one exception is a connected viewer** (`docs/CONTRACT-sessions.md` §4,
|
||||
v4): about once a minute the broker stamps `touch` on any session somebody
|
||||
is watching through its live stream. It is not a tool and cannot be
|
||||
invoked — it is the broker noticing that a person is looking, which is the
|
||||
one form of "still wanted" that does not come down the control socket. It
|
||||
cannot hold a session open by itself: an enabled stream with no viewer
|
||||
captures nothing and stamps nothing.
|
||||
|
||||
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
|
||||
@@ -516,6 +563,12 @@ 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.
|
||||
|
||||
The stream tools and the two stream resources additionally need
|
||||
`services.hyprland-headless-stream.sessions.stream.enable`, which runs the
|
||||
`hhstream-live` unit and gives the broker the socket it switches streams on
|
||||
over. Without it they answer exit 10 (`stream_unavailable`) — the session is
|
||||
unaffected, which is what that code means.
|
||||
|
||||
`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 stdio server is spawned per client.
|
||||
|
||||
Reference in new issue
Block a user