`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
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
# 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.
|