`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.9 KiB
The MCP server cannot abandon a call, and cannot re-join the compositor's group
The issue
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.
1. There is no per-call deadline. A subprocess can be killed; a Python
thread cannot be interrupted. So the only deadlines are the ones that already
exist inside the CLI: hhstream_session.client's 60 s socket timeout, the
broker's own per-verb deadline, and the frame socket's --timeout (10 s by
default, and not currently reachable as a tool argument — it is a global CLI
flag, before the verb, and the argv builders emit the verb first).
Measured consequence: nothing in the current surface is known to hang — every
path either talks to the broker under its 60 s timeout or to the frame socket
under its own — but record with a large seconds, or a grim wedged on a
compositor that has stopped answering, would hold the worker thread until it
returns. The event loop stays responsive (a ping is answered), and the calls
are serialised by design, so the visible symptom is every subsequent tool call
queueing behind one that will not finish.
2. The sg re-exec is unavailable. cli.main recovers from a frame socket
it cannot read by os.execv-ing itself through the setuid sg wrapper to join
the compositor's group. Performing that here would replace the MCP server
mid-session and drop the client's connection, so dispatch deliberately does
not call cli.main and the recovery does not happen. shot and record
instead fail with the CLI's own message plus a sentence naming what the CLI
would have done (hhstream_mcp.invoke.access_hint), and the operator is told to
run the server as a member of the group instead.
Ideas
- Leave (1) as it is and make the frame-socket timeout reachable. (recommended
for (1)) The honest small fix: let
shotandrecordtake atimeoutargument, andhhstream://statusand the frame resources a?timeout=, emitted as a global flag before the verb — whichhhstream_mcp.tools.argvcannot 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. - 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
execpaths this design avoids. Worth it only if a hang is observed in practice. - For (2): a
--sg-groupflag on the server that re-execs itself throughsgonce, before claiming the transport, so the group is joined while there is still no client to drop. (recommended for (2)) It keeps the recovery the CLI has, in the one moment it is safe, and is strictly better than asking every client's configuration to spellsg hhstream -c hhstream-mcp. - For (2): accept it and document only. What ships today. Correct, and the message says what to do — but it makes a working CLI and a failing tool out of the same machine, which is exactly the kind of difference an agent cannot diagnose.
Why it matters
(2) is the one an operator meets first: the CLI works from their shell, the
shot tool does not, and the two differ only in a recovery that is invisible
from either side. The message carries the answer, which is why this is medium
and not high.
(1) is latent. It becomes real the first time a compositor stops answering while an agent is driving it: the agent's next tool call waits behind the stuck one with no way to give up, where a CLI user would have pressed ctrl-C.