docs(mcp)!: mcp-v2, and the two limits the SDK imposes on it
`docs/CONTRACT-mcp.md` goes to mcp-v2 with a change table at the top, because v1 lasted a day and an agent that learned it deserves to be told what moved rather than to discover it. The new §4 freezes the resource surface: the eight URIs, their bodies, their query parameters, and the five rules the layer keeps (a read never writes; only declared parameters; a literal route beats a template; a frame's media type comes from its bytes; no subscriptions). §6 gains the other half of the error mapping -- for a resource read every exit code arrives as `-32602` with the remedy in `message` and the structured object in `data`, because `ReadResourceResult` has no `isError` to use instead. §2 records what `--toolsets` is and is not: there is no grouping primitive in MCP, the `Tool` object has nowhere to put a family, and tools are a flat list in the specification too -- so the only lever is which tools the server lists, decided by whoever spawns it. README.md leads with the split rather than with a tool count, since that is the thing a reader has to understand before any of the names make sense, and shows the `--toolsets` form for a client with a tight budget. ARCHITECTURE.md's sixth box grows its second half and says why `shot` is on both sides. A second TODO, `mcp-resources-cannot-be-subscribed-to.md`, records the limit that cost the most: `Server.get_capabilities` hardcodes `ResourcesCapability(subscribe=False, …)`, so registering a `subscribe_resource` handler changes nothing and a client is correctly told not to try. Subscriptions would have been the principled answer to the missing `logs --follow` -- it is the one place this design wanted a capability the SDK will not advertise -- so the file names the one-line local override, says what it risks, and recommends upstreaming the real fix. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
1 parent
56493721f0
commit
e636472106
7 files changed
+290
-85
No files matched your search
+9
-2
@@ -51,7 +51,8 @@ import the SDK:
|
||||
|
||||
```bash
|
||||
nix develop
|
||||
hhstream-mcp --list-tools # the whole surface, 26 lines, no stdio
|
||||
hhstream-mcp --list-tools # the 21 acting verbs
|
||||
hhstream-mcp --list-resources # the 8 read-only URIs
|
||||
```
|
||||
|
||||
## The checks
|
||||
@@ -68,7 +69,7 @@ hhstream-mcp --list-tools # the whole surface, 26 lines, no stdio
|
||||
| `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 |
|
||||
| `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 21 tools and 8 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 |
|
||||
|
||||
All of them at once:
|
||||
|
||||
@@ -122,6 +123,12 @@ 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:
|
||||
`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).
|
||||
|
||||
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
|
||||
deselected, so `checks/lib/check_report.py` parses the JUnit report and refuses
|
||||
|
||||
Reference in new issue
Block a user