# checks..vm-mcp -- the MCP server over stdio, in a guest, against a # live broker and a real compositor. # # The same machine the other session checks use (`lib/session-machine.nix`), # plus `services.hyprland-headless-stream.mcp.enable = true` -- which is also # the first thing asserted, because "installing it" is the whole of that # option. Then `hhs-mcp-call` (`lib/mcp_client.py`) spawns `hhstream-mcp` as the # operator account and talks raw JSON-RPC to it: initialize, tools/list, # tools/call. # # WHAT THIS PROVES, AND WHAT IT DOES NOT. # # It proves the *surface*: the handshake completes over a real pipe, all # twenty-six tools are listed, a tool call reaches the broker and comes back # with the broker's own protocol object, an image arrives as image content with # the geometry the module configured, and a refusal arrives as a tool error # carrying the frozen exit code rather than as a success. # # It does not prove the compositor behaviour the other checks own, and it must # not be read as doing so. `vm-pointer` is where a click is shown to land in the # window it was aimed at; `vm-keyboard` is where a typed symbol is shown to be # decoded by a client from the keymap the driver uploaded. Here the victim is # `foot`, which ignores `$HHSTREAM_APP_ID` and so matches no container rule # (README.dev.md, known gap 4) -- so what the pointer and keyboard subtests # below assert is that the lease was granted and the driver accepted the # injection, which is the part the MCP layer is responsible for. # # The client is not the MCP SDK's, deliberately: the SDK on both ends would # agree with itself about a framing neither side had to get right. Same choice # as `tests/assert_stream.py` being a second implementation of the frame # contract, and for the same reason. # # Habits copied from the other session checks: every wait is bounded, each # subtest asserts once, and a failure dumps the compositor's diagnostics and # the broker's journal before it propagates. { testers, hhstream, hhstream-mcp, hhsModule, testTools, hyprland, foot, jq, grim, procps, coreutils, dejavu_fonts, width ? 1280, height ? 720, sessionUser ? "hermes", }: testers.runNixOSTest ( { pkgs, ... }: let tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; }; guest = import ./lib/session-machine.nix { inherit hhsModule hhstream hyprland testTools foot jq procps grim coreutils dejavu_fonts ; sessionTools = tools; }; prelude = import ./lib/session-prelude.nix { inherit hhstream coreutils sessionUser; }; # The client, with a plain python3: it speaks JSON-RPC over a pipe and # imports nothing but the standard library, which is what makes it a second # implementation rather than the SDK talking to itself. client = pkgs.runCommandLocal "hhs-mcp-call" { } '' install -Dm755 ${./lib/mcp_client.py} $out/bin/hhs-mcp-call sed -i '1s|.*|#!${pkgs.python3}/bin/python3|' $out/bin/hhs-mcp-call $out/bin/hhs-mcp-call --help > /dev/null # It must refuse to invent a request rather than printing nothing: a # client that exits 0 having done nothing would make every subtest below # vacuous. if $out/bin/hhs-mcp-call --server ${coreutils}/bin/true; then echo "hhs-mcp-call succeeded against a server that says nothing" >&2 exit 1 fi ''; in { name = "hhstream-vm-mcp"; globalTimeout = 1800; nodes.machine = { imports = [ (guest { inherit width height sessionUser; pointer = true; apps.foot = { exec = "${foot}/bin/foot"; # The broker refuses unlisted arguments and this check passes none: # `foot` with no argv opens a window, which is all the victim has # to do. argsAllow = [ ]; }; }) ]; # The option under test. Installing the package IS the option, so the # first subtest asserts the binary is on PATH and nothing else had to # happen. services.hyprland-headless-stream.mcp = { enable = true; package = hhstream-mcp; }; environment.systemPackages = [ client ]; }; testScript = prelude + '' import base64 import shlex MCP = "${client}/bin/hhs-mcp-call" WIDTH = ${toString width} HEIGHT = ${toString height} def mcp(argv, timeout=180): """`hhs-mcp-call …` as USER, parsed. Fails loudly if it printed no JSON.""" out = machine.succeed(as_user(f"{MCP} {argv}"), timeout=timeout) try: return json.loads(out) except json.JSONDecodeError: raise AssertionError(f"not JSON from `hhs-mcp-call {argv}`: {out!r}") def call(tool, arguments=None, timeout=180): """One tools/call. Returns the CallToolResult as a dict.""" payload = json.dumps(arguments or {}) return mcp(f"{tool} {shlex.quote(payload)}", timeout=timeout) def text_of(result): """The text part of a CallToolResult, which is where the CLI's own output and (on a refusal) the remedy live.""" for block in result.get("content") or []: if block.get("type") == "text": return block["text"] raise AssertionError(f"no text content in {result!r}") def succeeded(tool, arguments=None, timeout=180): """A call that must not be an error, with the reason printed if it is.""" result = call(tool, arguments, timeout=timeout) if result.get("isError"): print(f"----- {tool} returned an error -----") print(text_of(result)) assert not result.get("isError"), f"{tool} failed: {text_of(result)}" return result start_all() bring_up("the compositor and broker") with subtest("the as-user wrapper propagates exit status"): # Every assertion below reads machine.succeed through it, so a # wrapper that swallowed the status would make them all vacuous. machine.succeed(as_user(TRUE), timeout=120) machine.fail(as_user(FALSE), timeout=120) with subtest("mcp.enable put the server on the system PATH"): # The whole of the module option: no unit, no socket, no state dir. path = machine.succeed(as_user("/run/current-system/sw/bin/sh -c 'command -v hhstream-mcp'")).strip() print(f"hhstream-mcp resolves to {path}") assert path.startswith("/run/current-system/sw/bin"), path machine.fail("systemctl is-active hhstream-mcp.service") with subtest("the stdio handshake completes and names this server"): try: handshake = mcp("--initialize") print(json.dumps(handshake, indent=2)[:600]) assert handshake["serverInfo"]["name"] == "hhstream", handshake assert handshake["capabilities"].get("tools") is not None, handshake # The two rules, in the instructions a client is handed once. instructions = handshake["instructions"] assert "`session_touch` is the ONLY" in instructions assert "POINTER lease" in instructions except Exception: dump("the mcp handshake") raise with subtest("tools/list carries every verb, with its annotations"): listed = mcp("--list")["tools"] names = sorted(tool["name"] for tool in listed) print(f"{len(names)} tools: {', '.join(names)}") assert len(names) == 26, names for expected in ( "status", "shot", "record", "run", "session_start", "session_touch", "session_kill", "pointer_acquire", "pointer_click", "keyboard_type", ): assert expected in names, f"{expected} is missing from the listing" by_name = {tool["name"]: tool for tool in listed} assert by_name["session_list"]["annotations"]["readOnlyHint"] is True assert by_name["session_kill"]["annotations"]["destructiveHint"] is True # The rule has to be on the tool, not only in the instructions. assert "session_touch" in by_name["session_list"]["description"] assert "POINTER lease" in by_name["keyboard_type"]["description"] with subtest("a read-only tool reaches the broker and returns its object"): try: result = succeeded("session_list") assert result["structuredContent"]["ok"] is True, result # The text part is the CLI's own `--json` output, unmodified. assert json.loads(text_of(result)) == result["structuredContent"] except Exception: dump("session_list over mcp") raise with subtest("a session started over mcp is the broker's own session"): try: started = succeeded("session_start", {"app": "foot"}, timeout=300) session_id = started["structuredContent"]["id"] print(f"started {session_id}") assert text_of(started).startswith(f"session id: {session_id}") # The broker is the authority on whether that happened, so it # is asked directly rather than through the server under test. listing = cli_json("list --json") assert session_id in [s["id"] for s in listing["sessions"]], listing except Exception: dump("session_start over mcp") raise with subtest("touch is the verb that moves the idle deadline"): try: before = succeeded("session_status", {"id": session_id}) before_expiry = before["structuredContent"]["session"]["expires_in_s"] # `status` must NOT have moved it; `touch` must. after_status = succeeded("session_status", {"id": session_id}) assert ( after_status["structuredContent"]["session"]["expires_in_s"] <= before_expiry ), "reading status reset the idle clock" touched = succeeded("session_touch", {"id": session_id}) assert ( touched["structuredContent"]["session"]["expires_in_s"] >= after_status["structuredContent"]["session"]["expires_in_s"] ), touched except Exception: dump("touch over mcp", session_id) raise with subtest("shot returns image content, sized as the publisher serves it"): # MEASURED, and not what this check first assumed: the frame is # 2560x720 on a guest configured for 1280x720. The publisher's # default capture is `grim -t png -` with no `-o`, which takes the # whole compositor layout -- and with containers on (the module's # default) a session's own output sits beside the main one, so one # session doubles the width. The geometry the module configures is # the geometry of an *output*, which is what the next subtest # captures by name. try: shot = succeeded("shot", timeout=300) kinds = [block["type"] for block in shot["content"]] assert kinds == ["text", "image"], kinds image = shot["content"][1] frame = base64.b64decode(image["data"]) print(f"{image['mimeType']}, {len(frame)} bytes: {text_of(shot)}") assert image["mimeType"] in ("image/png", "image/jpeg") # The media type is read off the bytes, never off the extension # this server asked the CLI for -- so the two must agree. magic = {"image/png": b"\x89PNG", "image/jpeg": b"\xff\xd8\xff"} assert frame.startswith(magic[image["mimeType"]]), frame[:8] reported = shot["structuredContent"] assert reported["height"] == HEIGHT, reported assert reported["width"] >= WIDTH, reported assert reported["bytes"] == len(frame), reported assert len(frame) > 1024, "a frame that small is not a desktop" except Exception: dump("shot over mcp", session_id) raise with subtest("shot of the session's own container is one output, exactly"): # Which is also the only subtest that reads `session_container`, and # the one that joins the two tools an agent uses together: the # output name that verb reports is what `shot` takes as `output`. try: container = succeeded("session_container", {"id": session_id}) output = container["structuredContent"]["container"]["output"] print(f"container output: {output}") assert output == f"hh-{session_id}", container framed = succeeded("shot", {"output": output}, timeout=300) reported = framed["structuredContent"] print(text_of(framed)) assert reported["output"] == output, reported assert (reported["width"], reported["height"]) == (WIDTH, HEIGHT), reported assert framed["content"][1]["type"] == "image" except Exception: dump("shot --output over mcp", session_id) raise with subtest("the pointer lease is granted, used and given back"): try: acquired = succeeded("pointer_acquire", {"id": session_id}) lease = acquired["structuredContent"]["lease_id"] print(f"lease {lease}: {text_of(acquired).splitlines()[0]}") assert text_of(acquired).startswith(f"lease_id: {lease}") # Every gesture takes the lease as an explicit argument: the # server caches nothing, which is what makes a transcript of # tool calls readable. succeeded("pointer_move", {"id": session_id, "lease": lease, "to": [0.5, 0.5]}) succeeded("pointer_click", {"id": session_id, "lease": lease}) succeeded("keyboard_type", {"id": session_id, "lease": lease, "text": "hello"}) typed = succeeded( "keyboard_key", {"id": session_id, "lease": lease, "name": "Return"} ) assert typed["structuredContent"]["ok"] is True, typed released = succeeded("pointer_release", {"id": session_id, "lease": lease}) assert released["structuredContent"]["ok"] is True, released # And the broker agrees that nobody holds it now. assert cli_json("pointer state --json")["holder"] is None except Exception: dump("the pointer lease over mcp", session_id) raise with subtest("a gesture after the release is exit 9 and says to acquire"): # The frozen NO_LEASE code, arriving as a tool error an agent can # act on rather than as a success with a sad message in it. refused = call("pointer_click", {"id": session_id, "lease": lease}) assert refused["isError"] is True, refused assert refused["structuredContent"]["exit_code"] == 9, refused said = text_of(refused) print(said.splitlines()[0]) assert "exit 9 (NO_LEASE)" in said assert "pointer_acquire" in said with subtest("an unknown session is exit 3, not a success"): refused = call("session_status", {"id": "no-such-session"}) assert refused["isError"] is True, refused assert refused["structuredContent"]["exit_code"] == 3, refused assert "session_list" in text_of(refused) with subtest("an argument the schema refuses never reaches the broker"): # No `lease`, so the server's own schema refuses before an argv list # exists. The CLI is not run at all, which is the point. refused = call("keyboard_type", {"id": session_id, "text": "x"}) assert refused["isError"] is True, refused assert "lease" in text_of(refused), refused with subtest("kill over mcp ends the session the broker was tracking"): try: killed = succeeded("session_kill", {"id": session_id}, timeout=300) print(text_of(killed)) assert killed["structuredContent"]["ok"] is True, killed live = [s["id"] for s in cli_json("list --json")["sessions"]] assert session_id not in live, live except Exception: dump("session_kill over mcp", session_id) raise ''; } )