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