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

+1
View File
@@ -16,6 +16,7 @@ Each file answers three questions and stops:
| [kill-can-leave-the-app-alive](kill-can-leave-the-app-alive.md) | medium | found by counting windows, not sessions |
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | found the first time the app was run as a unit: a unit's `PATH` has no `grim` |
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
Closed since this folder was written:
@@ -2,9 +2,9 @@
## The issue
`hhstream-mcp` runs the CLI's handlers **in its own process**: a tool builds the
argv list `hhstream.cli`'s parser takes, and `hhstream_mcp.invoke.dispatch` runs
the handler argparse selected. That is the seam the design asks for — one place
`hhstream-mcp` runs the CLI's handlers **in its own process**: a tool or a
resource read builds the argv list `hhstream.cli`'s parser takes, and
`hhstream_mcp.invoke.dispatch` runs the handler argparse selected. That is the seam the design asks for — one place
decides the argv, nothing re-implements a rule — and it costs two things a
subprocess would have given for free. Both are consequences of the same fact, so
they are one item.
@@ -36,11 +36,11 @@ run the server as a member of the group instead.
## Ideas
1. **Leave (1) as it is and make the frame-socket timeout reachable.** *(recommended
for (1))* The honest small fix: let `shot`, `record` and `status` take a
`timeout` argument and emit it as a global flag *before* the verb, which
`hhstream_mcp.tools.argv` cannot express today. That hands the one knob the
CLI already has to the agent, and does not pretend this layer can enforce a
deadline it cannot.
for (1))* The honest small fix: let `shot` and `record` take a `timeout`
argument, and `hhstream://status` and the frame resources a `?timeout=`,
emitted as a global flag *before* the verb — which `hhstream_mcp.tools.argv`
cannot express today. That hands the one knob the CLI already has to the
caller, and does not pretend this layer can enforce a deadline it cannot.
2. **Run each call in a forked child after all.** Restores a killable deadline,
at the cost of a process per tool call and of re-introducing the two `exec`
paths this design avoids. Worth it only if a hang is observed in practice.
@@ -0,0 +1,65 @@
# A resource cannot be followed, because the SDK will not advertise subscriptions
## The issue
`hhstream://sessions/{id}/logs` is the right shape for watching an application:
a URI whose content changes, which is exactly what MCP resource
**subscriptions** are for (`resources/subscribe`, then
`notifications/resources/updated`). An agent waiting for a build to finish, or
for a page to load, would subscribe once instead of reading in a loop.
It is not available. `mcp.server.lowlevel.Server.get_capabilities` computes the
resource capability like this (mcp 1.29.0, `server/lowlevel/server.py`):
```python
if types.ListResourcesRequest in self.request_handlers:
resources_capability = types.ResourcesCapability(
subscribe=False, listChanged=notification_options.resources_changed
)
```
`subscribe=False` is hardcoded. Registering a `@server.subscribe_resource()`
handler does not change it, so a client is told the server cannot be subscribed
to and correctly never tries. The handlers exist on the `Server` class and are
unreachable through the advertised capability.
This is why `docs/CONTRACT-mcp.md` §4 says there is no following, and why the
`session-logs` resource's own description tells the reader to read it again. It
is also the reason the CLI's `session logs --follow` has no equivalent anywhere
in this surface: the tool form would hang the client, and the resource form is
switched off upstream.
## Ideas
1. **Set the capability after construction.** *(recommended)*
`create_initialization_options()` returns the computed capabilities, and the
server is handed them by `serve()` -- so one line in
`hhstream_mcp.server.serve` could set `capabilities.resources.subscribe =
True` before `server.run`, with `subscribe_resource`/`unsubscribe_resource`
handlers behind it. Small, local, and reversible when the SDK grows the
knob. The cost is that it reaches past the SDK's own computation, which is
the kind of thing that breaks on an upgrade without saying so -- so it wants
a unit test asserting the advertised capability, not just the handler.
2. **Poll on the server's side and notify.** Keep `subscribe=False`, and have
the server itself re-read and send `notifications/resources/updated`. Does
not work: a client that was told `subscribe=False` has no reason to have
subscribed, so there is nobody to notify.
3. **Upstream it.** The hardcoded `False` looks like an oversight rather than a
decision; a patch that derives it from whether a `subscribe_resource`
handler was registered would match how every other capability on that method
is computed. Slowest, and the right long-term answer.
4. **Leave it, and say so.** What ships today, in the contract and in the
resource's own description.
## Why it matters
It is the difference between an agent that waits and an agent that polls. Every
read is a CLI call in process, so a loop that reads a session's logs every
second is a `hhstream session logs` every second, serialised against every other
call this server makes -- which is exactly the contention the other TODO in this
folder describes. Subscriptions would remove the loop rather than make it
cheaper.
Medium rather than high because reading again *works*, and because the one
caller who really needs to follow output can run `hhstream session logs
--follow` in a terminal, which is what it is for.