From 0a63c9b7fc6830aac0a500abcfe84a73b53a978f Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 11 Oct 2026 11:49:46 +0000 Subject: [PATCH] feat(mcp)!: state as resources, acts as tools, and --toolsets for the rest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE --- nix/mcp.nix | 37 ++- nix/module.nix | 17 +- src/hhstream_mcp/invoke.py | 29 ++- src/hhstream_mcp/resources.py | 436 ++++++++++++++++++++++++++++++++++ src/hhstream_mcp/server.py | 208 ++++++++++++++-- src/hhstream_mcp/tools.py | 288 +++++++++++----------- 6 files changed, 818 insertions(+), 197 deletions(-) create mode 100644 src/hhstream_mcp/resources.py diff --git a/nix/mcp.nix b/nix/mcp.nix index 69a405a..a876b06 100644 --- a/nix/mcp.nix +++ b/nix/mcp.nix @@ -14,7 +14,7 @@ # `buildPythonApplication` output is not. # # `grim` and `ffmpeg` do go on PATH, because the CLI itself spawns them -- -# `shot --output` and `record` are two of the twenty-six tools, and the server +# `shot --output` and `record` are two of the twenty-one tools, and the server # is launched by an MCP client whose PATH is not ours to predict. `--prefix` # and not `--set`, so a deployment that wants its own ahead of these puts them # on PATH and wins. @@ -63,19 +63,22 @@ python3.pkgs.buildPythonApplication { # nix/package.nix, for the same reason. doCheck = false; - # Cheap proof that the tool table builds and the SDK wiring imports: `tools` - # constructs all twenty-six at import time, and `server` is the only module - # that touches `mcp`. A missing SDK, a schema that is not a dict, or a tool - # named twice all fail here rather than at an agent's first call. + # Cheap proof that both tables build and the SDK wiring imports: `tools` and + # `resources` construct every entry at import time, and `server` is the only + # module that touches `mcp`. A missing SDK, a schema that is not a dict, or a + # tool named twice all fail here rather than at an agent's first call. pythonImportsCheck = [ "hhstream_mcp.tools" + "hhstream_mcp.resources" "hhstream_mcp.server" ]; # `pythonImportsCheck` proves the modules load; it does not prove the script # Nix wrapped can run, and the script is what an MCP client spawns. - # `--list-tools` is the one code path that exercises argument parsing and the - # whole table without opening stdio, so it is the honest smoke test. + # `--list-tools` and `--list-resources` are the two code paths that exercise + # argument parsing and both whole tables without opening stdio, so together + # they are the honest smoke test. `--toolsets` is in it because a selection + # that silently served everything would be the failure nobody notices. # # A `postPhases` entry and not `postInstall`, because the script is wrapped in # `fixupPhase`: run any earlier and it has no PYTHONPATH, so `import mcp` @@ -84,9 +87,23 @@ python3.pkgs.buildPythonApplication { postPhases = [ "entryPointCheckPhase" ]; entryPointCheckPhase = '' echo "checking the wrapped entry point..." - listed=$($out/bin/hhstream-mcp --list-tools) - echo "$listed" - test "$(echo "$listed" | wc -l)" -ge 26 + tools=$($out/bin/hhstream-mcp --list-tools) + echo "$tools" + test "$(echo "$tools" | wc -l)" -eq 21 + + resources=$($out/bin/hhstream-mcp --list-resources) + echo "$resources" + test "$(echo "$resources" | wc -l)" -eq 8 + + narrowed=$($out/bin/hhstream-mcp --list-tools --toolsets keyboard | wc -l) + echo "--toolsets keyboard offers $narrowed tools" + test "$narrowed" -eq 4 + + # An unknown toolset must be argparse's exit 2, not a server with no tools. + if $out/bin/hhstream-mcp --list-tools --toolsets nonsense; then + echo "an unknown toolset was accepted" >&2 + exit 1 + fi ''; meta = { diff --git a/nix/module.nix b/nix/module.nix index 89056ec..7a11c8f 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -917,16 +917,17 @@ in { # to declare. environment.systemPackages = lib.mkIf cfg.mcp.enable [ cfg.mcp.package ]; - # A warning and not an assertion: twenty-two of the twenty-six tools need - # the broker, and an agent handed them against a machine where it is off - # gets exit 5 from every one of them -- which is a true answer, badly - # timed. The four frame tools are genuinely useful on their own, so this is - # a thing worth saying rather than a thing worth refusing. + # A warning and not an assertion: eighteen of the twenty-one tools and six + # of the eight resources need the broker, and an agent handed them against + # a machine where it is off gets exit 5 from every one of them -- which is + # a true answer, badly timed. The frame tools are genuinely useful on their + # own, so this is a thing worth saying rather than a thing worth refusing. warnings = lib.optional (cfg.mcp.enable && !cfg.sessions.enable) '' services.hyprland-headless-stream.mcp.enable is on while sessions.enable - is off: the MCP server's session, pointer and keyboard tools will all - fail with exit 5 (the broker is unreachable). Only status, shot, record - and run will work. + is off: the MCP server's session, pointer and keyboard tools, and every + resource but hhstream://status and hhstream://screen, will fail because + the broker is unreachable (exit 5). Only shot, record, run and those two + resources will work. ''; # The broker's state directory and the moved socket directory are two diff --git a/src/hhstream_mcp/invoke.py b/src/hhstream_mcp/invoke.py index c1583f1..9b2b167 100644 --- a/src/hhstream_mcp/invoke.py +++ b/src/hhstream_mcp/invoke.py @@ -15,7 +15,7 @@ the client would see its connection die: the whole process through the setuid ``sg`` wrapper when the frame socket is out of reach. 2. ``cmd_run`` ends in ``os.execvpe`` -- that *is* the verb. ``run`` therefore - forks first; see :meth:`Runner.launch`. + spawns instead; see :meth:`Runner.launch`. So the parser is the CLI's (``cli.build_parser``), the handler is the one argparse selected, and the exit code is that handler's own return value. What @@ -139,20 +139,20 @@ REMEDY: dict[int, str] = { "Fix the arguments; retrying the same call will fail the same way." ), ExitCode.NO_SUCH_SESSION: ( - "No session (or process) by that id. Call `session_list` to see which " - "ids exist; a reaped session is gone and has to be started again." + "No session (or process) by that id. Read `hhstream://sessions` to see " + "which ids exist; a reaped session is gone and has to be started again." ), ExitCode.BAD_STATE: ( "The session exists but is not in a state this verb can act on -- it " "is still starting, or it has already exited, been killed or been " - "reaped. Call `session_status` to see which." + "reaped. Read `hhstream://sessions/` to see which." ), ExitCode.DAEMON_UNREACHABLE: ( "The session broker (`hhstreamd`) could not be reached on its control " "socket. Nothing was done. This is an operator problem, not an " "argument problem: the daemon is down, or $HHSTREAM_SOCKET points " - "somewhere else. Frame tools (`status`, `shot`, `record`, `run`) do " - "not need the broker and may still work." + "somewhere else. The frame tools (`shot`, `record`, `run`) and " + "`hhstream://status` do not need the broker and may still work." ), ExitCode.POLICY: ( "Refused by policy. The application is not on the broker's allowlist, " @@ -162,16 +162,18 @@ REMEDY: dict[int, str] = { ), ExitCode.TIMEOUT: ( "The broker accepted the request and did not finish in time. Whether " - "it took effect is unknown -- read the state back (`session_status`, " - "`session_list`, `pointer_state`) before retrying, and retry with the " - "same `request_id` so a mutation cannot happen twice." + "it took effect is unknown -- read the state back " + "(`hhstream://sessions`, `hhstream://sessions/`, " + "`hhstream://pointer`) before retrying, and retry with the same " + "`request_id` so a mutation cannot happen twice." ), ExitCode.BUSY: ( "Something else holds what this call needs -- for the pointer and " "keyboard verbs, another session holds the one pointer lease, and the " - "refusal names the holder. Nothing was injected. Call `pointer_state` " - "to see who holds it, then wait for them to release it or for its TTL " - "to expire. Do NOT try to take it from them; there is no such verb." + "refusal names the holder. Nothing was injected. Read " + "`hhstream://pointer` to see who holds it, then wait for them to " + "release it or for its TTL to expire. Do NOT try to take it from " + "them; there is no such verb." ), ExitCode.NO_LEASE: ( "This verb needs the pointer lease and this session does not hold one " @@ -191,7 +193,8 @@ REMEDY: dict[int, str] = { GENERIC_FAILURE: ( "The command failed without one of the broker's classified codes. For " "the frame tools this is usually the publisher sending no frame (is the " - "compositor up? call `status`) or `grim`/`ffmpeg` missing from the " + "compositor up? read `hhstream://status`) or `grim`/`ffmpeg` missing " + "from the " "server's PATH. The text below is the CLI's own." ), } diff --git a/src/hhstream_mcp/resources.py b/src/hhstream_mcp/resources.py new file mode 100644 index 0000000..43ce2f9 --- /dev/null +++ b/src/hhstream_mcp/resources.py @@ -0,0 +1,436 @@ +"""The read-only half of the surface: state as resources. Standard library only. + +Every verb of the CLI that only *reads* is addressed by URI here rather than +called as a tool, because that is the split the protocol draws. 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 business. A +tool is **model**-controlled: an act the model chooses to perform, and every one +left in :mod:`hhstream_mcp.tools` either changes something or costs something. + +So the line is not "cheap here, expensive there" -- it is *who decides*. +``hhstream://sessions`` is state a host may always include; ``session_kill`` is +a decision only the model can make. + +Two things this module is careful about: + +* **A resource read must not write.** That rules out ``session container ``, + which looks like a read and is not: with an id the CLI runs + ``container.reconcile`` and brings the record up to the compositor's answer. + Only the no-id form (``container.list``) is here, as ``hhstream://containers``; + the reconciling form stays the ``session_container`` tool. +* **A refusal must not arrive as content.** There is no ``isError`` on a + resource read, so a CLI refusal is *raised* and carries the same remedy + sentence a tool error would have. Returning the broker's failure object as + the body would make "this session does not exist" look like a successful read + of a session. + +Arguments become query parameters, because a resource read takes nothing but a +URI. Only the declared ones are accepted -- an unknown parameter is refused +rather than dropped, for the reason every tool schema sets +``additionalProperties: false``: an argument silently ignored is a read that +answered a different question than the one asked. +""" + +from __future__ import annotations + +import dataclasses +import urllib.parse +from typing import Any, Callable + +from . import media, tools +from .invoke import Outcome, Runner, remedy_for + +#: The scheme every resource here lives under. One, because they are all views +#: of one machine's one desktop. +SCHEME = "hhstream" + +JSON = "application/json" +TEXT = "text/plain" + + +class ReadRefused(Exception): + """The CLI refused, or the URI names nothing. Raised, never returned. + + Carries what a tool error would have carried, so a host that surfaces the + message gives its model the same remedy a tool call would have given it. + """ + + def __init__(self, message: str, detail: dict[str, Any] | None = None) -> None: + super().__init__(message) + self.message = message + self.detail = detail or {} + + +@dataclasses.dataclass(frozen=True) +class Reading: + """What one resource read produced. Text or bytes, never both.""" + + media_type: str + text: str | None = None + blob: bytes | None = None + + +Read = Callable[[Runner, dict[str, str]], Reading] + + +@dataclasses.dataclass(frozen=True) +class Entry: + """One resource, or one family of them. + + ``route`` is the URI after the scheme, as segments: a literal matches + itself, ``{name}`` captures exactly one segment. An entry with a capture is + a *template*; there is no second class for it, because the only thing that + differs is whether ``resources/list`` or ``resources/templates/list`` + mentions it. + """ + + route: tuple[str, ...] + name: str + title: str + description: str + media_type: str + read: Read + #: Query parameters this read accepts, by the name an agent puts in the + #: URI. What each becomes on the command line is :data:`_FLAGS`' business, + #: so that translation lives in one place rather than once per entry. + parameters: tuple[str, ...] = () + + @property + def captures(self) -> tuple[str, ...]: + return tuple(s[1:-1] for s in self.route if s.startswith("{")) + + @property + def is_template(self) -> bool: + return bool(self.captures) + + @property + def uri(self) -> str: + """The concrete URI. Only meaningful for an entry with no captures.""" + + return f"{SCHEME}://" + "/".join(self.route) + + @property + def uri_template(self) -> str: + """RFC 6570, including the query parameters it accepts.""" + + base = f"{SCHEME}://" + "/".join(self.route) + if not self.parameters: + return base + return base + "{?" + ",".join(sorted(self.parameters)) + "}" + + def match(self, segments: tuple[str, ...]) -> dict[str, str] | None: + """The captured values, or ``None`` if this entry is not the one.""" + + if len(segments) != len(self.route): + return None + captured: dict[str, str] = {} + for pattern, value in zip(self.route, segments): + if pattern.startswith("{"): + if not value: + return None + captured[pattern[1:-1]] = value + elif pattern != value: + return None + return captured + + +# ── parsing a URI ────────────────────────────────────────────────────────── + + +def split(uri: str) -> tuple[tuple[str, ...], dict[str, str]]: + """``hhstream://sessions/s-1/logs?lines=5`` -> ``(("sessions","s-1","logs"), {...})``. + + The authority and the path are one route: ``urlsplit`` puts the first + segment in ``netloc`` for a ``scheme://a/b`` URI, which is an artefact of + the form rather than a distinction worth preserving. + """ + + parsed = urllib.parse.urlsplit(uri) + if parsed.scheme != SCHEME: + raise ReadRefused( + f"not a {SCHEME} resource: {uri!r}. Every resource this server " + f"serves is {SCHEME}://… — call resources/list for the set." + ) + joined = parsed.netloc + parsed.path + segments = tuple(s for s in joined.split("/") if s) + if not segments: + raise ReadRefused(f"{uri!r} names no resource; call resources/list") + query: dict[str, str] = {} + for key, value in urllib.parse.parse_qsl(parsed.query, keep_blank_values=True): + if key in query: + raise ReadRefused( + f"{key!r} is given more than once in {uri!r}; each parameter " + "takes one value" + ) + query[key] = value + return segments, query + + +def resolve(uri: str) -> tuple[Entry, dict[str, str]]: + """The entry for ``uri``, with its captures and validated query merged. + + Literal routes are tried before templates, so ``hhstream://sessions`` is the + listing and not a session whose id happens to be absent. + """ + + segments, query = split(uri) + for entry in sorted(ENTRIES, key=lambda e: len(e.captures)): + captured = entry.match(segments) + if captured is None: + continue + unknown = set(query) - set(entry.parameters) + if unknown: + accepted = ", ".join(sorted(entry.parameters)) or "none" + raise ReadRefused( + f"{entry.name} does not accept " + f"{', '.join(repr(u) for u in sorted(unknown))}; it accepts: {accepted}" + ) + return entry, {**captured, **query} + raise ReadRefused( + f"no resource at {uri!r}. Call resources/list for the fixed ones and " + "resources/templates/list for the rest." + ) + + +# ── turning a CLI call into a reading ────────────────────────────────────── + + +def _checked(outcome: Outcome, what: str) -> Outcome: + """The outcome, or a refusal carrying the CLI's own words and the remedy.""" + + if outcome.ok: + return outcome + payload = outcome.payload() or {} + said = (outcome.stderr or outcome.stdout).strip() + raise ReadRefused( + f"could not read {what}: {remedy_for(outcome.returncode)}" + + (f"\n\n{said}" if said else ""), + { + "ok": False, + "exit_code": outcome.returncode, + "error": payload.get("error"), + "reason": payload.get("reason"), + "hint": payload.get("hint"), + "remedy": remedy_for(outcome.returncode), + }, + ) + + +#: Query parameter -> the flag it becomes on the command line. One table, not +#: one entry per resource: the name an agent puts in a URI and the flag the CLI +#: takes are allowed to differ, and a per-entry copy would be a per-entry +#: chance for them to disagree. +_FLAGS = {"all": "all", "events": "events", "lines": "lines"} + +#: Of those, the ones that are switches and not values -- so `?all=true` is +#: `--all` and `?all=false` is no flag at all, rather than `--all=false`, which +#: the CLI would refuse. +_SWITCHES = {"all"} + +_FALSE = {"false", "0", "no", "off", ""} + + +def _flag_for(name: str, value: str) -> list[str]: + flag = _FLAGS[name] + if name in _SWITCHES: + return [] if value.strip().lower() in _FALSE else [f"--{flag}"] + return [tools.flag(flag, value)] + + +def _json_read(verb: list[str], what: str) -> Read: + """A ``--json`` verb's protocol object, verbatim, as the resource's body. + + Verbatim because that object is what the broker actually said, and a + resource that reshaped it would be a second wire format for the same facts. + """ + + def read(runner: Runner, arguments: dict[str, str]) -> Reading: + options = ["--json"] + for name in sorted(arguments): + if name in _FLAGS: + options.extend(_flag_for(name, arguments[name])) + positionals = [arguments["id"]] if "id" in arguments else [] + outcome = _checked(runner.run(tools.argv(verb, options, positionals)), what) + return Reading(media_type=JSON, text=outcome.stdout.strip()) + + return read + + +def _status(runner: Runner, arguments: dict[str, str]) -> Reading: + """``hhstream status``: the one verb with no ``--json``, so it stays text.""" + + outcome = _checked(runner.run(["status"]), "the session's status") + return Reading(media_type=TEXT, text=outcome.stdout.strip()) + + +def _frame(runner: Runner, arguments: dict[str, str]) -> Reading: + """One captured frame as bytes. + + Serves both the whole screen and one named output: ``hhstream://screen`` + captures with no ``--output`` and ``hhstream://outputs/{name}`` captures + with one, which is the same CLI call with one flag more. + + The media type is read off the bytes, never assumed: the publisher serves + `image/jpeg` on some machines and the CLI writes the payload it was given + verbatim, so the entry's declared `mimeType` is a hint and this is the + answer. + """ + + named = arguments.get("name") + what = f"output {named!r}" if named else "the screen" + outcome, frame = tools.capture(runner, named) + _checked(outcome, what) + if frame is None: + raise ReadRefused( + f"hhstream shot reported success but wrote no readable file for {what}" + ) + image = media.sniff(frame) + return Reading( + media_type=image.media_type if image else "application/octet-stream", + blob=frame, + ) + + +# ── the table ────────────────────────────────────────────────────────────── + +#: Appended to the three descriptions whose verb the CLI's own note names. +_NOT_ACTIVITY = ( + " Reading this does NOT reset the session's idle clock -- only the " + "`session_touch` tool does." +) + +ENTRIES: tuple[Entry, ...] = ( + Entry( + route=("status",), + name="status", + title="Is the desktop up", + description=( + "Whether the headless Hyprland session is running and reachable: " + "each unit's state, the frame socket's path and whether this " + "server can read it, the Wayland socket the compositor bound, and " + "one probe frame's size. Read this first when something else " + "fails in a way that smells like the desktop being down. It says " + "nothing about the session broker -- an unreachable broker shows " + "up as exit 5 from a session tool or a failed read of " + "`hhstream://sessions`." + ), + media_type=TEXT, + read=_status, + ), + Entry( + route=("sessions",), + name="sessions", + title="Every tracked session", + description=( + "The broker's list: every session it is tracking, with its state, " + "pid and idle deadline. `?all=true` includes the tombstones of " + "ended ones." + _NOT_ACTIVITY + ), + media_type=JSON, + read=_json_read(["session", "list"], "the session list"), + parameters=("all",), + ), + Entry( + route=("pointer",), + name="pointer", + title="Who holds the pointer", + description=( + "Who holds the one pointer lease, since when, and which buttons " + "and KEYS are held down. This is what to read after a tool " + "returns exit 8 (BUSY): it names the holder. There is one cursor, " + "so there is one of these." + _NOT_ACTIVITY + ), + media_type=JSON, + read=_json_read(["session", "pointer", "state"], "the pointer lease"), + ), + Entry( + route=("containers",), + name="containers", + title="Every container, and the orphans", + description=( + "Each session's output, workspace and mode, plus the `hh-*` " + "outputs no live session claims. The output names here are what " + "`hhstream://outputs/{name}` and the `record` tool take.\n\n" + "This is the LIST, which only reads the record. Asking where a " + "session's window is *now* re-reads the compositor and writes the " + "answer back, so it is the `session_container` tool and not a " + "resource." + _NOT_ACTIVITY + ), + media_type=JSON, + read=_json_read(["session", "container"], "the container list"), + ), + Entry( + route=("screen",), + name="screen", + title="One frame of the screen", + description=( + "The published main output, as an image. This is the whole " + "compositor layout: with containers on, each session's own output " + "sits beside the main one, so the frame is wider than any single " + "output's configured size. For one container alone, read " + "`hhstream://outputs/{name}`." + ), + media_type="image/png", + read=_frame, + ), + Entry( + route=("sessions", "{id}"), + name="session", + title="One session, in detail", + description=( + "One session: its state, pid, container, idle deadline, and the " + "most recent entries from the broker's audit trail. `?events=N` " + "sets how many of those to include. The audit events are where a " + "session that died for a reason its own logs do not show explains " + "itself." + _NOT_ACTIVITY + ), + media_type=JSON, + read=_json_read(["session", "status"], "that session"), + parameters=("events",), + ), + Entry( + route=("sessions", "{id}", "logs"), + name="session-logs", + title="A session's captured output", + description=( + "The tail of the application's own stdout and stderr, as the " + "broker captured it -- the first place to look when an " + "application started and then did nothing. `?lines=N` sets how " + "much to tail.\n\n" + "There is no following here and there cannot be: this SDK does " + "not advertise resource subscriptions, and the CLI's `--follow` " + "polls until interrupted. Read it again instead." + _NOT_ACTIVITY + ), + media_type=JSON, + read=_json_read(["session", "logs"], "that session's logs"), + parameters=("lines",), + ), + Entry( + route=("outputs", "{name}"), + name="output", + title="One output's frame", + description=( + "One output captured in isolation through `grim` -- a session's " + "container is `hh-`, and `hhstream://containers` " + "lists the names. Unlike `hhstream://screen` this is exactly the " + "configured size of that output, which is the coordinate space " + "the pointer tools aim in." + ), + media_type="image/png", + read=_frame, + ), +) + +BY_NAME: dict[str, Entry] = {entry.name: entry for entry in ENTRIES} + +#: The fixed ones, for `resources/list`. +FIXED: tuple[Entry, ...] = tuple(e for e in ENTRIES if not e.is_template) +#: The rest, for `resources/templates/list`. +TEMPLATES: tuple[Entry, ...] = tuple(e for e in ENTRIES if e.is_template) + + +def read(runner: Runner, uri: str) -> Reading: + """Resolve ``uri`` and read it. Raises :class:`ReadRefused`.""" + + entry, arguments = resolve(uri) + return entry.read(runner, arguments) diff --git a/src/hhstream_mcp/server.py b/src/hhstream_mcp/server.py index 93ec36f..12e89e1 100644 --- a/src/hhstream_mcp/server.py +++ b/src/hhstream_mcp/server.py @@ -36,9 +36,12 @@ from typing import Any import anyio import mcp.types as types from mcp.server.lowlevel import NotificationOptions, Server +from mcp.server.lowlevel.helper_types import ReadResourceContents from mcp.server.stdio import stdio_server +from mcp.shared.exceptions import McpError +from pydantic import AnyUrl -from . import SERVER_NAME, __version__, tools +from . import SERVER_NAME, __version__, resources, tools from .invoke import Runner log = logging.getLogger("hhstream.mcp") @@ -51,29 +54,39 @@ INSTRUCTIONS = """\ Drive this machine's headless Hyprland desktop: look at it, put applications on it, and aim its one pointer and keyboard at them. -Each tool is one verb of the `hhstream` CLI and does nothing the CLI would not. -Where to start: `status` says whether the desktop is up; `session_start` puts an -allowlisted application on it and returns a session id; `shot` shows you the -screen; `pointer_acquire` gives you the lease that every pointer and keyboard -tool needs. +Everything here is one verb of the `hhstream` CLI and does nothing the CLI would +not. The surface is split the way the protocol splits it: + +* **Resources are the state.** `hhstream://status` is whether the desktop is up, + `hhstream://sessions` is what is running, `hhstream://sessions/` is one of + them with its recent audit events, `hhstream://sessions//logs` is an + application's own output, `hhstream://pointer` is who holds the input lease, + `hhstream://containers` is each session's output and workspace. Reading any of + them changes nothing. +* **Tools are the acts.** `session_start` puts an allowlisted application on the + screen and returns a session id; `shot` captures the screen now; + `pointer_acquire` gives you the lease every pointer and keyboard tool needs; + `session_kill` ends a session. Two rules this surface will not let you avoid, because they are the two an agent gets wrong: 1. `session_touch` is the ONLY thing that resets a session's idle clock. - Listing, reading status, reading logs, collecting garbage, clicking and - typing all deliberately do NOT. A session being driven is still a session - nobody has said they want kept, and the broker reaps it on schedule. + Reading any resource deliberately does NOT, nor does `session_gc`, nor does + clicking or typing. A session being driven is still a session nobody has said + they want kept, and the broker reaps it on schedule. 2. Every keyboard tool needs the POINTER lease, and holds only while that lease holds. There is no keyboard lease: one compositor seat means one keyboard focus. A held non-modifier key floods the window until you lift it or the lease expires, because the application does the repeating. -Failures come back as tool errors carrying the CLI's own exit code, its +Tool failures come back as tool errors carrying the CLI's own exit code, its machine-readable error name, its reason and what to do next. Exit 8 means -another session holds the pointer lease (`pointer_state` names the holder); exit -9 means you need to acquire one. +another session holds the pointer lease (read `hhstream://pointer` for the +holder); exit 9 means you need to acquire one. A resource read that the CLI +refuses is raised as an error carrying the same remedy, because a resource has +no way to hand back a failure as content. """ @@ -126,7 +139,12 @@ def content_for(result: tools.Result) -> list[types.ContentBlock]: return blocks -def call(runner: Runner, name: str, arguments: dict[str, Any]) -> types.CallToolResult: +def call( + runner: Runner, + name: str, + arguments: dict[str, Any], + available: Any = None, +) -> types.CallToolResult: """Run one tool. A refusal comes back as a tool error, never as a success. ``isError`` rather than a JSON-RPC error, throughout. That is not only a @@ -139,16 +157,35 @@ def call(runner: Runner, name: str, arguments: dict[str, Any]) -> types.CallTool verdict at all: a tool name that does not exist, and this layer's own bug. """ - tool = tools.BY_NAME.get(name) + # The *selected* set, not the whole table: a tool `--toolsets` left out is + # not listed, so calling it must fail rather than work anyway. The SDK only + # validates arguments against what `tools/list` returned, so without this a + # client could reach an unlisted tool by name. + offered = tools.BY_NAME if available is None else available + tool = offered.get(name) if tool is None: + known = ", ".join(sorted(offered)) or "nothing (every toolset is disabled)" + hint = "" + if name in tools.MOVED_TO_RESOURCES: + # The v1 name. Say where it went rather than only that it is gone: + # a caller asking for `session_list` wants the session list, and the + # answer is one `resources/read` away. + hint = ( + f" It is a RESOURCE now, not a tool: read " + f"{tools.MOVED_TO_RESOURCES[name]} instead. Reading state is " + "the host's to offer, not the model's to call -- call " + "resources/list for the whole read-only half of this server." + ) + elif name in tools.BY_NAME: + hint = ( + f" {name!r} exists but this server was started without its " + "toolset, so it is not offered." + ) return types.CallToolResult( content=[ types.TextContent( type="text", - text=( - f"no such tool: {name!r}. This server exposes: " - f"{', '.join(sorted(tools.BY_NAME))}" - ), + text=f"no such tool: {name!r}.{hint} This server exposes: {known}", ) ], structuredContent={"ok": False, "error": "no_such_tool"}, @@ -175,14 +212,86 @@ def call(runner: Runner, name: str, arguments: dict[str, Any]) -> types.CallTool ) -def build(runner: Runner) -> Server: +# ── resources ────────────────────────────────────────────────────────────── + + +def describe_resource(entry: resources.Entry) -> types.Resource: + return types.Resource( + uri=AnyUrl(entry.uri), + name=entry.name, + title=entry.title, + description=entry.description, + mimeType=entry.media_type, + ) + + +def describe_template(entry: resources.Entry) -> types.ResourceTemplate: + return types.ResourceTemplate( + uriTemplate=entry.uri_template, + name=entry.name, + title=entry.title, + description=entry.description, + mimeType=entry.media_type, + ) + + +def resource_listing() -> list[types.Resource]: + return [describe_resource(entry) for entry in resources.FIXED] + + +def template_listing() -> list[types.ResourceTemplate]: + return [describe_template(entry) for entry in resources.TEMPLATES] + + +def read(runner: Runner, uri: str) -> list[ReadResourceContents]: + """One resource read. A refusal is an error, because there is no other way. + + A ``CallToolResult`` can say ``isError``; ``ReadResourceResult`` cannot. So + a URI that names nothing, or a CLI that refused, is raised as a JSON-RPC + error carrying the remedy a tool error would have carried. Handing back the + broker's failure object as the resource's *body* would make "no such + session" read as a successful read of a session. + """ + + try: + reading = resources.read(runner, uri) + except resources.ReadRefused as refused: + raise McpError( + types.ErrorData( + code=types.INVALID_PARAMS, + message=refused.message, + data=refused.detail or None, + ) + ) from refused + body = reading.blob if reading.blob is not None else (reading.text or "") + return [ReadResourceContents(content=body, mime_type=reading.media_type)] + + +def build(runner: Runner, toolsets: Any = None) -> Server: server: Server = Server( SERVER_NAME, version=__version__, instructions=INSTRUCTIONS ) + available = tools.selected(toolsets) + by_name = {tool.name: tool for tool in available} @server.list_tools() async def _list() -> list[types.Tool]: - return listing() + return [describe(tool) for tool in available] + + @server.list_resources() + async def _list_resources() -> list[types.Resource]: + return resource_listing() + + @server.list_resource_templates() + async def _list_templates() -> list[types.ResourceTemplate]: + return template_listing() + + @server.read_resource() + async def _read_resource(uri: AnyUrl) -> list[ReadResourceContents]: + # Off the event loop for the reason a tool call is: this runs the CLI, + # which blocks. `str(uri)` because the route is parsed here, not by + # pydantic -- see `resources.split`. + return await anyio.to_thread.run_sync(lambda: read(runner, str(uri))) # `validate_input` left on: the schemas are the first refusal, and they # refuse before an argv list exists. @@ -193,7 +302,7 @@ def build(runner: Runner) -> Server: # loop stays free to answer a ping and to read the next request. The # calls themselves are serialised inside `Runner.run`, because the CLI # prints to a stdout this process shares. - return await anyio.to_thread.run_sync(lambda: call(runner, name, arguments)) + return await anyio.to_thread.run_sync(lambda: call(runner, name, arguments, by_name)) return server @@ -252,16 +361,45 @@ def build_parser() -> argparse.ArgumentParser: "disagree. Set them in the MCP client's `env` block." ), ) + parser.add_argument( + "--toolsets", + metavar="NAMES", + help="comma-separated families to offer as tools: " + + ", ".join(tools.TOOLSETS) + + ". Omitted, every tool is offered. Resources are NOT filtered by " + "this -- they are the host's context, not the model's tool budget.", + ) parser.add_argument( "--list-tools", action="store_true", - help="print the tool names and exit, without serving. For checking an install.", + help="print the tool names and exit, without serving. Honours " + "--toolsets, so it is also how to see what a selection would offer.", + ) + parser.add_argument( + "--list-resources", + action="store_true", + help="print the resource URIs and templates and exit, without serving.", ) return parser +def chosen_toolsets(raw: str | None) -> list[str] | None: + """``--toolsets`` as a list, or ``None`` for every tool.""" + + if raw is None: + return None + names = [part.strip() for part in raw.split(",") if part.strip()] + if not names: + raise tools.UnknownToolset( + "--toolsets was given no names. Omit the flag for every tool, or " + f"name some of: {', '.join(tools.TOOLSETS)}" + ) + return names + + def main(argv: list[str] | None = None) -> int: - args = build_parser().parse_args(argv) + parser = build_parser() + args = parser.parse_args(argv) # stderr, never stdout: stdout is the transport, and one stray print on it # is a protocol error the client reports as a parse failure. logging.basicConfig( @@ -269,15 +407,33 @@ def main(argv: list[str] | None = None) -> int: stream=sys.stderr, format="%(levelname)s %(name)s: %(message)s", ) + try: + toolsets = chosen_toolsets(args.toolsets) + offered = tools.selected(toolsets) + except tools.UnknownToolset as exc: + # argparse's own exit code for a bad argument, because that is what + # this is: `choices=` cannot express a comma-separated subset. + parser.error(str(exc)) + return int(2) # pragma: no cover -- parser.error exits if args.list_tools: - for tool in tools.TOOLS: + for tool in offered: print(f"{tool.name}\t{tool.title}") return 0 - log.info("serving %d tools over stdio", len(tools.TOOLS)) + if args.list_resources: + for entry in resources.FIXED: + print(f"{entry.uri}\t{entry.title}") + for entry in resources.TEMPLATES: + print(f"{entry.uri_template}\t{entry.title}") + return 0 + log.info( + "serving %d tools and %d resources over stdio", + len(offered), + len(resources.ENTRIES), + ) # The transport is claimed before the event loop starts, so no coroutine can # have written to fd 1 by the time it moves. transport = claim_transport() - anyio.run(serve, build(Runner()), transport) + anyio.run(serve, build(Runner(), toolsets), transport) return 0 diff --git a/src/hhstream_mcp/tools.py b/src/hhstream_mcp/tools.py index 5756fda..1eed94c 100644 --- a/src/hhstream_mcp/tools.py +++ b/src/hhstream_mcp/tools.py @@ -1,4 +1,19 @@ -"""The tool table: one tool per CLI verb. Standard library only. +"""The tool table: one tool per CLI verb that *acts*. Standard library only. + +**What is here and what is not.** A tool is model-controlled: an act the model +chooses to perform. The verbs that only read state are not tools -- they are +resources, addressed by URI in :mod:`hhstream_mcp.resources`, because that is +application-controlled context and "what is on this machine right now" is the +host's business. So ``session_kill`` is here and ``hhstream://sessions`` is +there, and the line between them is *who decides* rather than what it costs. + +``shot`` and ``record`` stay tools even 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*. The same frames are also readable as ``hhstream://screen`` and +``hhstream://outputs/{name}`` for a host that wants to put 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. **Granularity, and why.** One tool per verb rather than one tool per family with an ``action`` enum. Three reasons, in order of weight: @@ -11,14 +26,14 @@ with an ``action`` enum. Three reasons, in order of weight: (after a round trip). 2. The two rules an agent gets wrong have to be *on the tool it gets wrong*. A client shows a tool's own description at the point of use; a family-level - note about the idle clock is not what is read when ``session_list`` is about - to be called for the ninth time. -3. ``readOnlyHint`` is per tool and is a real distinction here: ``session_list`` - reads, ``session_kill`` destroys, and ``session_container`` with an id - reconciles -- which is a write, and is marked as one. + note about the idle clock is not what is read when ``session_touch`` is the + thing being forgotten. +3. ``readOnlyHint`` is per tool and is still a real distinction among what is + left: ``shot`` reads, ``session_kill`` destroys, ``record`` writes a file. -The cost is twenty-six tools in one listing. That is paid back by the names -being the CLI's own: an agent that has read ``hhstream session --help``, or this +The cost is twenty-one tools in one listing, and :data:`TOOLSETS` is the lever +for a client that cannot afford them all. It is paid back by the names being +the CLI's own: an agent that has read ``hhstream session --help``, or this repository's README, already knows what ``session_touch`` is, and a transcript of tool calls can be re-run by hand as a shell session. @@ -57,12 +72,13 @@ from .invoke import GENERIC_FAILURE, Outcome, Runner, remedy_for, temp_name ACTIVITY_NOTE = ( "ACTIVITY: `session_touch` is the ONLY thing that resets a session's idle " - "clock. `session_list`, `session_status`, `session_logs` and `session_gc` " - "do NOT count, and neither does any pointer or keyboard tool -- if polling " - "kept a session alive, an abandoned session would never be reaped. A " - "session being watched or driven is still a session nobody has said they " - "want kept. If you leave an application running, call `session_touch` " - "before its idle timeout expires or the broker will reap it." + "clock. Reading `hhstream://sessions`, `hhstream://sessions/` or its " + "logs does NOT count; neither does `session_gc`, and neither does any " + "pointer or keyboard tool -- if polling kept a session alive, an abandoned " + "session would never be reaped. A session being watched or driven is still " + "a session nobody has said they want kept. If you leave an application " + "running, call `session_touch` before its idle timeout expires or the " + "broker will reap it." ) LEASE_NOTE = ( @@ -262,7 +278,10 @@ def json_verb( SESSION_ID = { "type": "string", - "description": "the session id, as `session_start` printed it or `session_list` reports it", + "description": ( + "the session id, as `session_start` printed it or " + "`hhstream://sessions` reports it" + ), } LEASE = { "type": "string", @@ -314,39 +333,49 @@ def obj(properties: dict[str, Any], required: list[str] | None = None, **extra: # ── frames ───────────────────────────────────────────────────────────────── -def _status(runner: Runner, args: dict[str, Any]) -> Result: - # No `--json`: `hhstream status` has none. It is a human report of the - # units, the socket's reachability and one probe frame, and this passes it - # through as text rather than inventing a shape for it. - return report(runner.run(["status"])) - - -def _shot(runner: Runner, args: dict[str, Any]) -> Result: - """One frame, as MCP image content. +def capture(runner: Runner, output: str | None) -> tuple[Outcome, bytes | None]: + """One frame, as the CLI's outcome and the bytes it wrote. Captured to a temporary file and read back, because that is the CLI's only output shape -- `shot` writes a file and prints its path -- and because a pipe would mean asking the CLI for something it does not offer. The - directory goes away with the call; the bytes are in the reply. + directory goes away with the call; the bytes are the return value. + + Shared with :mod:`hhstream_mcp.resources`, which serves the same frames by + URI: one capture path, so a fix to it cannot reach one caller and miss the + other. ``None`` for the bytes means the CLI claimed success and left no + readable file, which is its own kind of failure and is reported as one. """ with tempfile.TemporaryDirectory(prefix="hhstream-mcp-shot-") as scratch: destination = os.path.join(scratch, "frame.png") - options = [flag("out", destination), *_optional(args, "output")] + options = [flag("out", destination)] + if output: + options.append(flag("output", output)) outcome = runner.run(argv(["shot"], options, [])) if not outcome.ok: - return report(outcome) + return outcome, None try: - frame = pathlib.Path(destination).read_bytes() - except OSError as exc: - return Result( - text=( - f"hhstream shot reported success but wrote no readable file: {exc}\n\n" - f"hhstream said:\n{outcome.stdout.strip()}" - ), - data={"ok": False, "exit_code": 0, "error": "no_artifact"}, - is_error=True, - ) + return outcome, pathlib.Path(destination).read_bytes() + except OSError: + return outcome, None + + +def _shot(runner: Runner, args: dict[str, Any]) -> Result: + """One frame, as MCP image content.""" + + outcome, frame = capture(runner, args.get("output")) + if not outcome.ok: + return report(outcome) + if frame is None: + return Result( + text=( + "hhstream shot reported success but wrote no readable file.\n\n" + f"hhstream said:\n{outcome.stdout.strip()}" + ), + data={"ok": False, "exit_code": 0, "error": "no_artifact"}, + is_error=True, + ) image = media.sniff(frame) where = args.get("output") @@ -500,22 +529,6 @@ def build() -> tuple[Tool, ...]: """The whole surface. A function, so the table is built once per process.""" tools: list[Tool] = [ - Tool( - name="status", - title="Session status", - description=( - "Is the headless Hyprland session up, and can this server reach " - "its frame socket? Reports each unit's state, the socket path " - "and whether it is readable, the Wayland socket the compositor " - "bound, and one probe frame's size and geometry. Start here " - "when any other tool fails in a way that smells like the " - "desktop being down. Human-readable text; this verb has no " - "JSON form." - ), - schema=obj({}), - invoke=_status, - read_only=True, - ), Tool( name="shot", title="Capture one frame", @@ -721,48 +734,6 @@ def _session_tools() -> list[Tool]: summary=_start_summary, ), ), - Tool( - name="session_list", - title="List sessions", - description=( - "Every session the broker is tracking, with its state, pid and " - "idle deadline. `all` includes the tombstones of ended ones.\n\n" - f"{ACTIVITY_NOTE}" - ), - schema=obj( - {"all": {"type": "boolean", "description": "include tombstones of ended sessions"}} - ), - invoke=json_verb(["session", "list"], options=lambda a: _switch(a, "all")), - read_only=True, - ), - Tool( - name="session_status", - title="One session, in detail", - description=( - "One session: its state, pid, container, idle deadline, and the " - "most recent entries from the broker's audit trail. The audit " - "events are the place to look when a session died for a reason " - "its own logs do not show.\n\n" - f"{ACTIVITY_NOTE}" - ), - schema=obj( - { - "id": SESSION_ID, - "events": { - "type": "integer", - "minimum": 0, - "description": "how many recent audit events to include (the CLI's default is 20)", - }, - }, - ["id"], - ), - invoke=json_verb( - ["session", "status"], - options=lambda a: _optional(a, "events"), - positionals=lambda a: [a["id"]], - ), - read_only=True, - ), Tool( name="session_touch", title="Reset the idle clock", @@ -855,37 +826,6 @@ def _session_tools() -> list[Tool]: ], ), ), - Tool( - name="session_logs", - title="A session's captured output", - description=( - "The tail of the application's own stdout and stderr, as the " - "broker captured it. The first place to look when an " - "application started and then did nothing.\n\n" - "There is no follow mode here, deliberately: the CLI's " - "`--follow` polls until interrupted, and a tool call that never " - "returns hangs the client that made it. Call this again " - "instead.\n\n" - f"{ACTIVITY_NOTE}" - ), - schema=obj( - { - "id": SESSION_ID, - "lines": { - "type": "integer", - "minimum": 1, - "description": "how many lines to tail (the CLI's default is 100)", - }, - }, - ["id"], - ), - invoke=json_verb( - ["session", "logs"], - options=lambda a: _optional(a, "lines"), - positionals=lambda a: [a["id"]], - ), - read_only=True, - ), Tool( name="session_container", title="A session's output and workspace", @@ -1134,20 +1074,6 @@ def _pointer_tools() -> list[Tool]: positionals=lambda a: [a["id"]], ), ), - Tool( - name="pointer_state", - title="Who holds the pointer", - description=( - "Who holds the one pointer lease, since when, and which buttons " - "and KEYS are currently held down. This is the tool to call " - "after an exit 8 (BUSY): it names the holder. It takes no " - "session id -- there is one cursor.\n\n" - f"{ACTIVITY_NOTE}" - ), - schema=obj({}), - invoke=json_verb(["session", "pointer", "state"]), - read_only=True, - ), ] @@ -1261,3 +1187,85 @@ def _keyboard_tools() -> list[Tool]: TOOLS: tuple[Tool, ...] = build() BY_NAME: dict[str, Tool] = {tool.name: tool for tool in TOOLS} + + +# ── toolsets ─────────────────────────────────────────────────────────────── + +#: The families ``--toolsets`` selects from, in listing order. +#: +#: Not a protocol feature -- MCP has no notion of a tool group, and the ``Tool`` +#: object has nowhere to put one -- so this is what the ecosystem actually does: +#: the *server* is told which families to list, at launch, by whoever spawns it. +#: It exists because a tool listing is a budget. A client with room for a dozen +#: tools gets a coherent dozen this way instead of an arbitrary truncation, and +#: an agent that will never start an application need not be shown how. +#: +#: Resources are deliberately NOT filtered by it. They are the host's context, +#: not the model's budget, and making ``hhstream://sessions`` conditional on the +#: session *tools* being enabled would couple two decisions that are not the +#: same decision. +TOOLSETS: dict[str, tuple[str, ...]] = { + "frames": ("shot", "record", "run"), + "sessions": ( + "session_start", + "session_touch", + "session_kill", + "session_gc", + "session_adopt", + "session_container", + "session_reconcile", + ), + "pointer": ( + "pointer_acquire", + "pointer_move", + "pointer_click", + "pointer_scroll", + "pointer_down", + "pointer_up", + "pointer_release", + ), + "keyboard": ("keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up"), +} + + +#: Tools that mcp-v1 had and mcp-v2 does not, each pointing at the resource +#: that replaced it. +#: +#: Kept so a refusal can say where the thing went. An agent (or a transcript, +#: or a prompt) that learned the v1 names will ask for these, and "no such +#: tool" alone makes that look like a server that is broken rather than a +#: surface that moved. One sentence here saves a whole loop of guessing. +MOVED_TO_RESOURCES: dict[str, str] = { + "status": "hhstream://status", + "session_list": "hhstream://sessions", + "session_status": "hhstream://sessions/", + "session_logs": "hhstream://sessions//logs", + "pointer_state": "hhstream://pointer", +} + + +class UnknownToolset(ValueError): + """A name ``--toolsets`` does not know. Refused, never ignored.""" + + +def selected(names: Any = None) -> tuple[Tool, ...]: + """The tools in the named families, in the table's own order. + + ``None`` is every tool, which is the default and what an unconfigured + client gets. An unknown name is refused rather than skipped: a server that + quietly served nothing because of a typo would look like a server with no + tools, which is the hardest failure of all to diagnose from the far side of + a pipe. + """ + + if names is None: + return TOOLS + wanted = tuple(dict.fromkeys(names)) + unknown = [name for name in wanted if name not in TOOLSETS] + if unknown: + raise UnknownToolset( + f"no such toolset: {', '.join(repr(u) for u in unknown)}. " + f"Known: {', '.join(TOOLSETS)}" + ) + chosen = {tool for family in wanted for tool in TOOLSETS[family]} + return tuple(tool for tool in TOOLS if tool.name in chosen)