#!/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())