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
@@ -37,16 +37,31 @@ connects, and keeps running when one disconnects.
|
||||
|
||||
## Driving it from an agent: the MCP server
|
||||
|
||||
`hhstream-mcp` is the `hhstream` CLI as [Model Context
|
||||
Protocol](https://modelcontextprotocol.io) tools, so an agent can look at this
|
||||
`hhstream-mcp` is the `hhstream` CLI behind a [Model Context
|
||||
Protocol](https://modelcontextprotocol.io) surface, so an agent can look at this
|
||||
desktop, put an application on it, and aim its one pointer and keyboard at that
|
||||
application through typed tools instead of a shell. One tool per CLI verb,
|
||||
twenty-six of them; the interface is frozen in `docs/CONTRACT-mcp.md`.
|
||||
application without writing command lines. The interface is frozen in
|
||||
`docs/CONTRACT-mcp.md`.
|
||||
|
||||
It is a thin wrapper and nothing more: every tool builds the argv list the CLI's
|
||||
own parser takes, runs the CLI's own handler, and maps what came back. The idle
|
||||
clock, the pointer lease, the allowlist and the exit-code table all stay where
|
||||
they were.
|
||||
It is split the way the protocol splits things:
|
||||
|
||||
- **Resources are the state** — eight of them, read by URI, and reading one
|
||||
changes nothing. `hhstream://status` is whether the desktop is up,
|
||||
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
|
||||
an application's own output, `hhstream://pointer` is who holds the input
|
||||
lease, `hhstream://screen` is a frame of the screen.
|
||||
- **Tools are the acts** — twenty-one, one per CLI verb that does something.
|
||||
`session_start` puts an application on the screen, `pointer_acquire` takes the
|
||||
input lease, `keyboard_type` types, `session_kill` ends a session.
|
||||
|
||||
A host decides what state to put in front of its model; the model decides what
|
||||
to do. That is the whole of the split, and it is why `shot` is still a tool
|
||||
(capturing is an act at a moment) while `hhstream://screen` exists beside it.
|
||||
|
||||
It is a thin wrapper and nothing more: every tool and every resource builds the
|
||||
argv list the CLI's own parser takes, runs the CLI's own handler, and maps what
|
||||
came back. The idle clock, the pointer lease, the allowlist and the exit-code
|
||||
table all stay where they were.
|
||||
|
||||
Install it with the module — off by default, because it is the surface through
|
||||
which a language model starts processes on this machine:
|
||||
@@ -86,16 +101,27 @@ server cannot recover that for itself the way the CLI does — see
|
||||
answer is `"command": "sg", "args": ["hhstream", "-c", "hhstream-mcp"]` or an
|
||||
account in the group.
|
||||
|
||||
`hhstream-mcp --list-tools` prints the table and exits, which is the quickest
|
||||
way to check an install. Nothing else about the server is configurable: it holds
|
||||
no state, caches no lease, and the pointer lease is an explicit argument on
|
||||
every gesture tool for exactly that reason.
|
||||
`hhstream-mcp --list-tools` and `--list-resources` print the two tables and
|
||||
exit, which is the quickest way to check an install.
|
||||
|
||||
If twenty-one tools is more than a client has room for, `--toolsets` narrows
|
||||
what is offered to whichever families are wanted — `frames`, `sessions`,
|
||||
`pointer`, `keyboard`:
|
||||
|
||||
```json
|
||||
{ "command": "hhstream-mcp", "args": ["--toolsets", "frames,pointer,keyboard"] }
|
||||
```
|
||||
|
||||
Resources are deliberately *not* narrowed by it: they are the host's context,
|
||||
not the model's tool budget. Nothing else about the server is configurable — it
|
||||
holds no state and caches no lease, and the pointer lease is an explicit
|
||||
argument on every gesture tool for exactly that reason.
|
||||
|
||||
| Document | What it is |
|
||||
|---|---|
|
||||
| `docs/CONTRACT.md` | the wire protocol and the module surface — the interface other people build against |
|
||||
| `docs/CONTRACT-sessions.md` | the broker, the containers and the input lease |
|
||||
| `docs/CONTRACT-mcp.md` | the MCP tools: their names, arguments and error mapping |
|
||||
| `docs/CONTRACT-mcp.md` | the MCP surface: the resource URIs, the tool names, their arguments and the error mapping |
|
||||
| `docs/ARCHITECTURE.md` | how the pieces fit: compositor, capture, server, client |
|
||||
| `README.dev.md` | how to build, test and hack on it |
|
||||
| `examples/README.md` | the demo that films the screen: `agent-eyes-demo.py` |
|
||||
|
||||
Reference in new issue
Block a user