`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
68 lines
3.9 KiB
Markdown
68 lines
3.9 KiB
Markdown
# 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
|
|
|
|
1. **Leave (1) as it is and make the frame-socket timeout reachable.** *(recommended
|
|
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.
|
|
3. **For (2): a `--sg-group` flag on the server** that re-execs itself through
|
|
`sg` *once, 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 spell `sg hhstream -c
|
|
hhstream-mcp`.
|
|
4. **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.
|