Commit Graph
2 Commits
Author SHA1 Message Date
HermenixandClaude Opus 5 0a63c9b7fc feat(mcp)!: state as resources, acts as tools, and --toolsets for the rest
BREAKING: `status`, `session_list`, `session_status`, `session_logs` and
`pointer_state` are no longer tools. They are `hhstream://…` resources. 26
tools became 21, and eight resources appeared beside them.

The reason is the split the protocol itself draws, which the first cut ignored.
A resource is **application**-controlled context: the host decides what to put
in front of the model, and "what is on this machine right now" is the host's
question. A tool is **model**-controlled: an act the model chooses to perform.
Nothing in those five verbs acts. So the line between the halves is *who
decides*, not what a call costs.

    hhstream://status                     text, the units and the frame socket
    hhstream://sessions          {?all}   the broker's own list object
    hhstream://pointer                    the lease holder, buttons and keys
    hhstream://containers                 every container, plus the orphans
    hhstream://screen                     a frame, as an image blob
    hhstream://sessions/{id}     {?events}
    hhstream://sessions/{id}/logs {?lines}
    hhstream://outputs/{name}             one output's frame, as a blob

What did *not* move is the interesting part. `shot` and `record` stay tools
though neither changes the desktop: capturing is an act at a moment, and an
agent in a loop has to be able to decide to look *now* -- in many clients a
resource is something a person attaches rather than something a model can
fetch. The same frames are readable as `hhstream://screen` and
`hhstream://outputs/{name}` as well, for a host that wants one in context
itself. `session_container` stays a tool for a harder reason: with an id the
CLI runs `container.reconcile`, which writes the record back, so it is not a
read at all. Only the no-id listing is a resource. **A resource read must never
write**, and `resources.py` says so where it would be tempting.

Three consequences worth naming:

* A refusal cannot be content. `ReadResourceResult` has no `isError`, so a CLI
  refusal is raised as `-32602` with the same remedy text in `message` and the
  same `{ok, exit_code, error, reason, hint, remedy}` in `data`. Returning the
  broker's failure object as the *body* would make "no such session" read as a
  successful read of a session.
* Arguments become query parameters, and only declared ones are accepted -- for
  the reason every tool schema sets `additionalProperties: false`. A parameter
  silently ignored is a read that answered a different question.
* A v1 tool name is told where it went: `session_list` comes back with "It is a
  RESOURCE now ... read hhstream://sessions instead". "No such tool" alone
  reads as a broken server rather than a moved surface.

`--toolsets frames,sessions,pointer,keyboard` lands with it, because 21 flat
tools is the same problem one size smaller. There is **no grouping primitive in
MCP** -- `Tool` carries name, title, description, inputSchema, outputSchema,
icons, annotations, _meta and execution, and nowhere to put a family -- so the
only honest lever is which tools the *server* lists, chosen at launch. An
unknown name is argparse's exit 2, never a silently empty server, and a tool
outside the selection is unreachable rather than merely unlisted. Resources are
deliberately not filtered by it: they are the host's context, not the model's
budget.

`--list-resources` joins `--list-tools`; both are in the package's own
entry-point check, with `--toolsets` beside them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:49:46 +00:00
HermenixandClaude Opus 5 549c73e8ae feat(nix): hhstream-mcp as its own derivation, and an option to install it
`packages.hhstream-mcp` (`nix/mcp.nix`), separate from `packages.hhstream` and
the separation is the point: the frame socket, the CLI and the broker are
stdlib-only by policy, the MCP SDK is a third-party dependency, and
`packages.hhstream` runs as the compositor's own units. Verified: the hhstream
closure gains no `mcp`, no `pydantic` and no `httpx`, and `hhstream_mcp` is not
in its site-packages.

The join to `hhstream` is a *library* one -- `toPythonModule`, because the
tools call `hhstream.cli`'s handlers in process. `grim` and `ffmpeg` are
prefixed onto the wrapper's PATH, because the CLI spawns them and the server is
launched by an MCP client whose PATH is not ours to predict.

The entry point is smoke-tested with `--list-tools` in a `postPhases` phase,
not `postInstall`: the script is wrapped in `fixupPhase`, so any earlier and
the check runs against a script with no PYTHONPATH and tests the wrong thing.
(`installCheckPhase` is no use either -- `buildPythonPackage` does not include
that phase at all.)

`services.hyprland-headless-stream.mcp.enable` (default false) puts the binary
on the system PATH, which is the whole of the option: the server is stdio and
spawned per client, so there is no unit, no socket and no state directory.
`mcp.package` defaults to this flake's build against `cfg.package`, so the
server and the CLI it runs are one build. A warning, not an assertion, when it
is enabled with `sessions.enable` off: 22 of the 26 tools then answer exit 5,
but the four frame tools are genuinely useful alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 06:32:34 +00:00