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