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:
HermenixandClaude Opus 5 committed 2026-10-11 11:50:12 +00:00
1 parent 56493721f0
commit e636472106
7 files changed
+290 -85

No files matched your search

+17 -10
View File
@@ -37,7 +37,8 @@
│
┌────────────┴──────────────┐
│ hhstream-mcp │ spawned per client, stdio only
│ 26 tools, one per verb │◀─── an MCP client's JSON-RPC
│ 21 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 8 resources (the state)│
└───────────────────────────┘
```
@@ -64,15 +65,21 @@ piece at all:
And the sixth, which is a *shim* and not a layer:
6. **The MCP server** (`hhstream-mcp`, `docs/CONTRACT-mcp.md`) is the CLI with a
Model Context Protocol surface on it, so an agent calls typed tools instead
of writing command lines. It is drawn above the CLI rather than beside the
broker because that is where it sits: each tool builds the argv list the
CLI's parser takes and runs the CLI's own handler **in the same process**,
and it is the one component here that owns no state at all — not even the
pointer lease, which is an explicit argument on every gesture tool. Add it
to the diagram's list of things that can go wrong and nothing new appears:
every failure it reports is the CLI's or the broker's, carrying their exit
code.
Model Context Protocol surface on it, so an agent reads state by URI and
acts by calling tools instead of writing command lines. It is drawn above
the CLI rather than beside the broker because that is where it sits: every
tool and every resource builds the argv list the CLI's parser takes and runs
the CLI's own handler **in the same process**, and it is the one component
here that owns no state at all — not even the pointer lease, which is an
explicit argument on every gesture tool. Add it to the diagram's list of
things that can go wrong and nothing new appears: every failure it reports
is the CLI's or the broker's, carrying their exit code.
The split between its two halves is *who decides*, not what it costs. A
resource is the host's to include (`hhstream://sessions` is state anyone may
want in context); a tool is the model's to call (`session_kill` is a
decision). That is why `shot` is both — a tool because deciding to look is
an act, and `hhstream://screen` because a frame is also just state.
It is also the only part with a third-party dependency (the `mcp` SDK),
which is why it is a separate derivation (`nix/mcp.nix`) and why