Files
hyprland-headless-stream-pl…/checks/lib/mcp_client.py
T
HermenixandClaude Opus 5 56493721f0 test(mcp): the resource routing, the toolsets, and the guest check for both
46 more unit tests, and `vm-mcp` rewritten around the new split (21 subtests,
up from 14).

`test_mcp_resources.py` is the new file and its subject is what the resource
layer actually decides: which entry a URI resolves to, which query parameters
it will accept, and the argv each read builds. The cases that matter are the
ones a reshuffle would quietly break -- a literal route beating a template
(`hhstream://sessions` is the listing, not a session with a blank id), a
switch parameter becoming a bare flag or nothing at all (`--all=false` is not
something the CLI takes), an undeclared parameter being refused rather than
dropped, a frame's media type being sniffed rather than assumed, and a refusal
being *raised* instead of returned as the body.

One test exists only to stop a future kindness: there must be no resource for
the reconciling container read, because that one writes.

`test_mcp_server.py` grows the protocol-level half -- both listings, a read
that returns JSON, a read that returns a blob, a refused read arriving as
`McpError`, and a toolset selection that narrows the tools while leaving the
resources alone. The tool and toolset tests move with the surface: the
read-only verbs are asserted *absent* by name rather than merely missing, so
re-adding one is a failure instead of a silent widening of what mcp-v2
narrowed.

In the guest, the subtest the whole surface turns on is now measured rather
than described: two reads of `hhstream://sessions/<id>` must NOT move the idle
deadline, and `session_touch` must. It also asks for the same container two
ways and checks the answers agree, reads one output's frame as a blob and
confirms the `shot` tool reports the same geometry, and proves `--toolsets`
makes an omitted tool unreachable and not merely unlisted.

`checks/lib/mcp_client.py` gains `--resources`, `--read` and `--server-arg`,
and exits 3 rather than 2 on a protocol error -- so "the server refused this
read" stays distinguishable from "the server did not answer at all", which is
the distinction that keeps the refusal subtests from passing for the wrong
reason.

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

224 lines
8.5 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 --resources every resource and template
hhs-mcp-call --read hhstream://sessions one resources/read
hhs-mcp-call session_gc one call, no arguments
hhs-mcp-call session_touch '{"id": "s-1"}' one call, arguments as JSON
``--server-arg`` is passed through to the server, which is how a check drives
``--toolsets`` without a second program.
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:
# Printed as the result and exited 3, not `fail`ed: a resource read
# has no `isError`, so a refusal arrives here -- and the checks
# assert on *which* refusal. Exit 3 keeps it distinguishable from
# exit 2, which is "the server did not answer at all".
print(json.dumps({"error": answer["error"]}, indent=2, sort_keys=True))
raise SystemExit(3)
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(
"--server-arg",
action="append",
default=[],
metavar="ARG",
help="an argument for the server itself; repeatable",
)
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(
"--resources",
action="store_true",
help="print the resource listing and the templates, as one object",
)
parser.add_argument("--read", metavar="URI", help="read one resource")
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.server_arg], 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 args.resources:
# Both listings as one object, because they are two halves of one
# question and a check that asked twice would pay two handshakes.
print(
json.dumps(
{
"resources": server.request("resources/list")["resources"],
"resourceTemplates": server.request(
"resources/templates/list"
)["resourceTemplates"],
},
indent=2,
sort_keys=True,
)
)
return 0
if args.read:
print(
json.dumps(
server.request("resources/read", {"uri": args.read}),
indent=2,
sort_keys=True,
)
)
return 0
if not args.tool:
fail("name a tool, or pass --list, --resources, --read 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())