`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
3.3 KiB
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):
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
- Set the capability after construction. (recommended)
create_initialization_options()returns the computed capabilities, and the server is handed them byserve()-- so one line inhhstream_mcp.server.servecould setcapabilities.resources.subscribe = Truebeforeserver.run, withsubscribe_resource/unsubscribe_resourcehandlers 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. - Poll on the server's side and notify. Keep
subscribe=False, and have the server itself re-read and sendnotifications/resources/updated. Does not work: a client that was toldsubscribe=Falsehas no reason to have subscribed, so there is nobody to notify. - Upstream it. The hardcoded
Falselooks like an oversight rather than a decision; a patch that derives it from whether asubscribe_resourcehandler was registered would match how every other capability on that method is computed. Slowest, and the right long-term answer. - 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.