docs(mcp)!: mcp-v4, a second transport, and what its token is not
The contract said "stdio, and only stdio" and now describes two transports, so it gets a version -- **v4**, because v3 (the live stream) was published to main while this branch was in review. Nothing here breaks: no tool renamed, no argument reshaped, no resource moved, so a client written against v2 over stdio still works unchanged. v2 is the only bump that took something away, and it took away five tools; v3 and v4 are additive. §1 is rewritten around the asymmetry rather than around the feature, because the asymmetry is the part that is easy to get wrong later: stdio is unauthenticated **on purpose** and that is now written down with its argument, so the next reader does not "fix" it. A stdio client spawns the server, so it has already passed a filesystem permission check and holds the broker's 0660 control socket either way -- unix permissions are the gate, exactly as `mcp.enable`'s own option text has always said. A port is the first time the caller passed neither, which is the entire reason the token exists. §2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`: that directory is 0700 owned by the broker's user and holds the audit trail), the `serve --http` flags, and the `token` verbs with the three decisions behind them -- digests not tokens, wall-clock expiry where every broker deadline is BOOTTIME, and a flock because two processes write the table. §3 records that a token's toolsets intersect the server's and cannot widen them. §10 is new and is the part worth having: **what this is not.** Not OAuth 2.1, not RFC 9728, no metadata discovery -- so a client that can only *discover* an authorization server will not connect, and one that lets you set a header will. And a token narrows tools but not resources, so a `frames` token can still read `hhstream://sessions`. Both are now TODO files with their own evidence and recommended routes, beside the two limits the SDK imposes: * `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about interoperability rather than exposure. Nothing is weaker than it claims; what is missing is the part that lets a client somebody else configured connect without a human pasting a header. It records that `ssh host hhstream-mcp` is genuinely the better answer for one operator with one machine, because that is what this competes with. * `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all until a second token is minted for someone else, at which point the restriction is narrower than it reads. README gains the HTTP section with the three things to know before enabling it (the unit's refusal and self-heal, no TLS, not OAuth); README.dev gains the token commands in the dev-shell walkthrough and the new check's row; ARCHITECTURE gains the two transports in its diagram and the reason the shim has a state directory while owning no state about the desktop. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
This commit is contained in:
1 parent
7eb9afdfa3
commit
10176356b6
8 files changed
+504
-31
No files matched your search
+28
-3
@@ -51,10 +51,21 @@ import the SDK:
|
||||
|
||||
```bash
|
||||
nix develop
|
||||
hhstream-mcp --list-tools # the 21 acting verbs
|
||||
hhstream-mcp --list-tools # the 23 acting verbs
|
||||
hhstream-mcp --list-resources # the 10 read-only URIs
|
||||
|
||||
# the HTTP transport, which is the only part that needs a credential
|
||||
export HHSTREAM_MCP_STATE_DIR=$PWD/.mcp-state
|
||||
hhstream-mcp token mint --label dev # the token, once, on stdout
|
||||
hhstream-mcp serve --http # 127.0.0.1:9989/mcp
|
||||
```
|
||||
|
||||
stdio is unauthenticated on purpose and the HTTP transport is not: a stdio
|
||||
client spawns the server and so already holds the broker's socket, while a port
|
||||
is reachable by someone who passed no permission check. `docs/CONTRACT-mcp.md`
|
||||
§1 has the argument; `token mint` prints the secret once and the table on disk
|
||||
keeps only its digest.
|
||||
|
||||
## The checks
|
||||
|
||||
| Check | What it proves | Needs a VM |
|
||||
@@ -72,6 +83,8 @@ hhstream-mcp --list-resources # the 10 read-only URIs
|
||||
| `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 23 tools and 10 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
|
||||
|
||||
| `vm-mcp-http` | the **HTTP transport, its token and its unit**: the unit refusing to start while the authorization table is empty *and* saying so in the journal, then coming up by itself within one retry interval of the first `token mint` with no `systemctl start` — the half that nothing in Python can test; the state directory `0700` and owned by the account that mints tokens, the table `0600` and holding no token; the port on loopback only and **not** in the firewall; an unauthenticated and a wrong-token request both `401` with an empty body and no echo; a good token completing the handshake, reading a resource and calling a tool against the live broker; two tokens served by **one process** with different tool budgets; and a revocation taking effect on the next request with no restart | yes |
|
||||
|
||||
All of them at once:
|
||||
|
||||
```bash
|
||||
@@ -96,6 +109,7 @@ 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
|
||||
nix build -L .#checks.x86_64-linux.vm-mcp-http
|
||||
nix build -L .#checks.x86_64-linux.vm-stream
|
||||
```
|
||||
|
||||
@@ -125,11 +139,15 @@ output is on that path beside it, and `mcp` is in the test environment, because
|
||||
— 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 MCP suite is four files, split along what each can be tested without:
|
||||
The MCP suite is six files, split along what each can be tested without:
|
||||
`test_mcp_invoke.py` (the in-process CLI call and the exit-code mapping),
|
||||
`test_mcp_tools.py` (the argv each tool builds, and the toolsets),
|
||||
`test_mcp_resources.py` (URI routing, query parameters, and that a read never
|
||||
writes) and `test_mcp_server.py` (the SDK wiring, over its memory transport).
|
||||
writes), `test_mcp_authorizations.py` (the token store and the `token` verbs --
|
||||
standard library, no SDK), `test_mcp_server.py` (the SDK wiring, over its
|
||||
memory transport, plus the command line now that it has subcommands) and
|
||||
`test_mcp_http.py` (the bearer check and the per-token toolsets, over a real
|
||||
ASGI stack).
|
||||
|
||||
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
|
||||
@@ -264,11 +282,18 @@ checks/
|
||||
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
|
||||
vm-mcp-http.nix nixosTest, the HTTP transport: the unit's refusal while
|
||||
no token exists and its self-heal after the first mint,
|
||||
the 0700 state dir, the refusals, and two tokens with
|
||||
different tool budgets served by one process
|
||||
vm-stream.nix nixosTest, `session stream enable` and a real HTTP
|
||||
viewer reading MJPEG from inside the guest
|
||||
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/mcp_http_client.py the same choice over HTTP: hhs-mcp-http, urllib only,
|
||||
with a distinct exit status for an HTTP refusal so a
|
||||
401 cannot be mistaken for a server that died
|
||||
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