Files
hyprland-headless-stream-pl…/checks/lib/mcp_client.py
T
HermenixandClaude Opus 5 fea55eecde test(mcp): the argv each tool builds, the mapping, and the server in a guest
101 unit tests under `tests/unit/` and one new VM check.

The unit suite's subject is the only thing this layer decides: the argv list.
`mcp_fake.FakeCli` is a recording stand-in put where the CLI goes, so every
test can assert on the exact argv a tool handed over -- the `=` form of each
flag, the `--` before each positional, the omission of a flag the caller did
not give. Three tests drive the **real** entry point against a control socket
that does not exist, which proves the dispatch, the capture and the exit-code
mapping against the CLI's actual parser with no daemon standing up: argparse's
exit 2 for a bad `--button`, exit 5 for the unreachable broker, exit 9 for a
gesture with no lease.

`test_mcp_server.py` imports the MCP SDK unconditionally and runs the server
in process over the SDK's memory transport. It is not allowed to skip: the tool
table is stdlib and tested without the SDK, but whether every schema validates
and every name is one the specification allows is a question only the SDK can
answer, and a file that skipped when it was absent would be green in exactly
the build where that mattered. `checks/unit.nix` therefore puts `mcp` in the
test environment and `hhstream-mcp` on PYTHONPATH beside `hhstream`.

`checks/vm-mcp.nix` boots the session machine with `mcp.enable = true` and
drives the real binary over a real pipe with `checks/lib/mcp_client.py` -- raw
JSON-RPC, deliberately not the SDK's client, for the reason
`tests/assert_stream.py` is a second implementation of the frame contract. It
asserts the handshake, the 26-tool listing with its annotations and its two
rules, a call that reaches the live broker, `shot` as image content, the lease
granted/used/returned against the real driver, and exits 9 and 3 arriving as
tool errors.

The geometry assertion in that check is one it got wrong first time and now
records: the published frame is 2560x720 on a guest configured for 1280x720,
because the publisher's default capture takes the whole compositor layout and a
session's container is a second output beside the main one. `shot` with the
container's own `output` is the one that is exactly 1280x720.

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

176 lines
6.6 KiB
Python
Executable File

#!/usr/bin/env python3
"""``hhs-mcp-call`` -- drive an MCP server over stdio from a shell.
What `checks/vm-mcp.nix` uses to talk to `hhstream-mcp` in the guest, and
deliberately **not** the MCP SDK's own client: the SDK on both ends would agree
with itself about a framing neither side had to get right. This is raw
JSON-RPC, newline-delimited, written against the specification -- the same
choice, and for the same reason, as `tests/assert_stream.py` being a second
implementation of the frame contract.
One server process per invocation, which means every call re-does the
`initialize` handshake. That is a feature here: the handshake is one of the
things under test, and a client that did it once would prove it once.
hhs-mcp-call --initialize the handshake's own result
hhs-mcp-call --list every tool, as JSON
hhs-mcp-call session_list one call, no arguments
hhs-mcp-call session_touch '{"id": "s-1"}' one call, arguments as JSON
Always exits 0 when the server answered, whatever the answer was: a refusal is
a result the test asserts on, not this program's failure. Exit 2 is "the
server did not answer" -- it died, it timed out, or it sent something that is
not JSON-RPC -- which is the one outcome no assertion should be able to mistake
for a reply.
"""
from __future__ import annotations
import argparse
import json
import signal
import subprocess
import sys
from typing import Any
#: The protocol version this client speaks. Named rather than negotiated: a
#: server that answers a different one is a thing the test should see.
PROTOCOL_VERSION = "2025-06-18"
def fail(message: str) -> None:
print(f"hhs-mcp-call: {message}", file=sys.stderr)
raise SystemExit(2)
class Server:
"""One ``hhstream-mcp`` process, spoken to over its stdin and stdout."""
def __init__(self, command: list[str], timeout: int) -> None:
self.timeout = timeout
# stderr is left alone on purpose: the server logs there, and in a
# nixosTest that ends up in the build log beside the assertion that
# failed, which is where it is wanted.
self.process = subprocess.Popen(
command,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
text=True,
bufsize=1,
)
self.next_id = 0
def send(self, message: dict[str, Any]) -> None:
assert self.process.stdin is not None
self.process.stdin.write(json.dumps(message) + "\n")
self.process.stdin.flush()
def read(self) -> dict[str, Any]:
assert self.process.stdout is not None
# An alarm rather than a poll loop: a server that never answers must
# fail the check, not hang the test driver until its global timeout.
signal.alarm(self.timeout)
try:
line = self.process.stdout.readline()
except KeyboardInterrupt: # pragma: no cover -- the alarm handler
fail(f"no answer within {self.timeout}s")
raise
finally:
signal.alarm(0)
if not line:
fail(f"the server closed its stream (exit {self.process.poll()})")
try:
return json.loads(line)
except json.JSONDecodeError:
# The failure a stray `print` on stdout produces, named as such:
# the tools run the CLI in process, and this is what it looks like
# when something it printed reached the transport.
fail(f"not JSON-RPC on the server's stdout: {line!r}")
raise AssertionError("unreachable")
def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
self.next_id += 1
wanted = self.next_id
self.send(
{"jsonrpc": "2.0", "id": wanted, "method": method, "params": params or {}}
)
answer = self.read()
if answer.get("id") != wanted:
fail(f"answer for id {answer.get('id')!r}, expected {wanted}")
if "error" in answer:
fail(f"{method} was refused at the protocol level: {answer['error']}")
return answer["result"]
def initialize(self) -> dict[str, Any]:
result = self.request(
"initialize",
{
"protocolVersion": PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "hhs-mcp-call", "version": "0"},
},
)
self.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
return result
def close(self) -> int:
assert self.process.stdin is not None
self.process.stdin.close()
try:
return self.process.wait(timeout=self.timeout)
except subprocess.TimeoutExpired: # pragma: no cover
self.process.kill()
return -1
def _alarm(signum, frame): # pragma: no cover -- raises into read()
raise KeyboardInterrupt
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="hhs-mcp-call", description=__doc__)
parser.add_argument(
"--server",
default="hhstream-mcp",
help="the MCP server to spawn (default: %(default)s, from PATH)",
)
parser.add_argument("--timeout", type=int, default=120, metavar="SECONDS")
parser.add_argument("--initialize", action="store_true", help="print the handshake result")
parser.add_argument("--list", action="store_true", help="print the tool listing")
parser.add_argument("tool", nargs="?", help="the tool to call")
parser.add_argument("arguments", nargs="?", default="{}", help="its arguments, as JSON")
args = parser.parse_args(argv)
signal.signal(signal.SIGALRM, _alarm)
try:
arguments = json.loads(args.arguments)
except json.JSONDecodeError as exc:
fail(f"arguments are not JSON: {exc}")
return 2
if not isinstance(arguments, dict):
fail("arguments must be a JSON object")
server = Server([args.server], args.timeout)
try:
handshake = server.initialize()
if args.initialize:
print(json.dumps(handshake, indent=2, sort_keys=True))
return 0
if args.list:
print(json.dumps(server.request("tools/list"), indent=2, sort_keys=True))
return 0
if not args.tool:
fail("name a tool, or pass --list or --initialize")
result = server.request(
"tools/call", {"name": args.tool, "arguments": arguments}
)
print(json.dumps(result, indent=2, sort_keys=True))
return 0
finally:
server.close()
if __name__ == "__main__":
raise SystemExit(main())