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
224 lines
8.5 KiB
Python
Executable File
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())
|