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
This commit is contained in:
1 parent
0a63c9b7fc
commit
56493721f0
6 files changed
+893
-112
No files matched your search
@@ -14,9 +14,14 @@ 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 --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
|
||||
@@ -98,7 +103,12 @@ class Server:
|
||||
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']}")
|
||||
# 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]:
|
||||
@@ -134,9 +144,22 @@ def main(argv: list[str] | None = None) -> int:
|
||||
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)
|
||||
@@ -151,7 +174,7 @@ def main(argv: list[str] | None = None) -> int:
|
||||
if not isinstance(arguments, dict):
|
||||
fail("arguments must be a JSON object")
|
||||
|
||||
server = Server([args.server], args.timeout)
|
||||
server = Server([args.server, *args.server_arg], args.timeout)
|
||||
try:
|
||||
handshake = server.initialize()
|
||||
if args.initialize:
|
||||
@@ -160,8 +183,33 @@ def main(argv: list[str] | None = None) -> int:
|
||||
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 or --initialize")
|
||||
fail("name a tool, or pass --list, --resources, --read or --initialize")
|
||||
result = server.request(
|
||||
"tools/call", {"name": args.tool, "arguments": arguments}
|
||||
)
|
||||
|
||||
+205
-43
@@ -10,11 +10,13 @@
|
||||
#
|
||||
# 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 proves the *surface*, both halves of it: the handshake completes over a
|
||||
# real pipe, all twenty-one tools and all eight resources are listed, a tool
|
||||
# call reaches the broker and comes back with the broker's own protocol object,
|
||||
# a resource read reaches it the same way, an image arrives as a blob with the
|
||||
# geometry the module configured, `--toolsets` actually narrows what is
|
||||
# offered, and a refusal arrives as a tool error (or, for a resource, a
|
||||
# protocol 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
|
||||
@@ -148,6 +150,28 @@ testers.runNixOSTest (
|
||||
return mcp(f"{tool} {shlex.quote(payload)}", timeout=timeout)
|
||||
|
||||
|
||||
def read(uri, timeout=180):
|
||||
"""One resources/read that must succeed. Returns its contents list."""
|
||||
|
||||
return mcp(f"--read {shlex.quote(uri)}", timeout=timeout)["contents"]
|
||||
|
||||
|
||||
def read_refused(uri, timeout=180):
|
||||
"""One resources/read that must NOT succeed. Returns the error object.
|
||||
|
||||
A resource read has no `isError`, so a refusal is a protocol error
|
||||
and the client exits 3 for it -- which is deliberately a different
|
||||
status from the 2 it uses for "the server did not answer", so this
|
||||
cannot pass because the server died.
|
||||
"""
|
||||
|
||||
status, out = machine.execute(
|
||||
as_user(f"{MCP} --read {shlex.quote(uri)}"), timeout=timeout
|
||||
)
|
||||
assert status == 3, f"expected a refusal (3) for {uri}, got {status}: {out}"
|
||||
return json.loads(out)["error"]
|
||||
|
||||
|
||||
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."""
|
||||
@@ -199,34 +223,75 @@ testers.runNixOSTest (
|
||||
dump("the mcp handshake")
|
||||
raise
|
||||
|
||||
with subtest("tools/list carries every verb, with its annotations"):
|
||||
with subtest("tools/list carries every acting 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
|
||||
assert len(names) == 21, names
|
||||
for expected in (
|
||||
"status", "shot", "record", "run",
|
||||
"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"
|
||||
# The read-only verbs are resources now and must not be here.
|
||||
for moved in ("status", "session_list", "session_status",
|
||||
"session_logs", "pointer_state"):
|
||||
assert moved not in names, f"{moved} is a resource, not a tool"
|
||||
by_name = {tool["name"]: tool for tool in listed}
|
||||
assert by_name["session_list"]["annotations"]["readOnlyHint"] is True
|
||||
assert by_name["shot"]["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"]
|
||||
# The rules have to be on the tool, not only in the instructions.
|
||||
assert "session_touch" in by_name["session_gc"]["description"]
|
||||
assert "POINTER lease" in by_name["keyboard_type"]["description"]
|
||||
|
||||
with subtest("a read-only tool reaches the broker and returns its object"):
|
||||
with subtest("resources/list and the templates carry the read-only half"):
|
||||
both = mcp("--resources")
|
||||
uris = sorted(r["uri"] for r in both["resources"])
|
||||
templates = sorted(t["uriTemplate"] for t in both["resourceTemplates"])
|
||||
print(f"resources: {', '.join(uris)}")
|
||||
print(f"templates: {', '.join(templates)}")
|
||||
assert uris == [
|
||||
"hhstream://containers",
|
||||
"hhstream://pointer",
|
||||
"hhstream://screen",
|
||||
"hhstream://sessions",
|
||||
"hhstream://status",
|
||||
], uris
|
||||
assert templates == [
|
||||
"hhstream://outputs/{name}",
|
||||
"hhstream://sessions/{id}/logs{?lines}",
|
||||
"hhstream://sessions/{id}{?events}",
|
||||
], templates
|
||||
by_uri = {r["uri"]: r for r in both["resources"]}
|
||||
assert by_uri["hhstream://status"]["mimeType"] == "text/plain"
|
||||
assert by_uri["hhstream://sessions"]["mimeType"] == "application/json"
|
||||
# The idle-clock rule is on the reads it applies to.
|
||||
assert "does NOT reset" in by_uri["hhstream://sessions"]["description"]
|
||||
|
||||
with subtest("a resource read 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"]
|
||||
contents = read("hhstream://sessions")
|
||||
assert len(contents) == 1, contents
|
||||
assert contents[0]["mimeType"] == "application/json"
|
||||
# The body is the CLI's own `--json` output, unmodified.
|
||||
listing = json.loads(contents[0]["text"])
|
||||
assert listing["ok"] is True, listing
|
||||
assert "sessions" in listing, listing
|
||||
except Exception:
|
||||
dump("session_list over mcp")
|
||||
dump("reading hhstream://sessions")
|
||||
raise
|
||||
|
||||
with subtest("the status resource answers without the broker's help"):
|
||||
# It reads the compositor's units and the frame socket, not the
|
||||
# control socket -- which is why it is the thing to read first.
|
||||
contents = read("hhstream://status")
|
||||
assert contents[0]["mimeType"] == "text/plain"
|
||||
report = contents[0]["text"]
|
||||
print(report)
|
||||
assert "hyprland-headless.service" in report
|
||||
assert "frame:" in report
|
||||
|
||||
with subtest("a session started over mcp is the broker's own session"):
|
||||
try:
|
||||
started = succeeded("session_start", {"app": "foot"}, timeout=300)
|
||||
@@ -241,23 +306,38 @@ testers.runNixOSTest (
|
||||
dump("session_start over mcp")
|
||||
raise
|
||||
|
||||
with subtest("touch is the verb that moves the idle deadline"):
|
||||
with subtest("reading a session does not reset its clock; touching it does"):
|
||||
# The rule the whole surface repeats, measured rather than asserted
|
||||
# about: two reads of the resource, then the tool, and the deadline
|
||||
# has to move only for the tool.
|
||||
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"
|
||||
def expires_in():
|
||||
body = json.loads(read(f"hhstream://sessions/{session_id}")[0]["text"])
|
||||
return body["session"]["expires_in_s"]
|
||||
|
||||
first = expires_in()
|
||||
second = expires_in()
|
||||
assert second <= first, (
|
||||
f"reading hhstream://sessions/{session_id} reset the idle "
|
||||
f"clock: {first} -> {second}"
|
||||
)
|
||||
touched = succeeded("session_touch", {"id": session_id})
|
||||
assert (
|
||||
touched["structuredContent"]["session"]["expires_in_s"]
|
||||
>= after_status["structuredContent"]["session"]["expires_in_s"]
|
||||
touched["structuredContent"]["session"]["expires_in_s"] >= second
|
||||
), touched
|
||||
except Exception:
|
||||
dump("touch over mcp", session_id)
|
||||
dump("the idle clock over mcp", session_id)
|
||||
raise
|
||||
|
||||
with subtest("a session's logs read through its template, with a query"):
|
||||
try:
|
||||
contents = read(f"hhstream://sessions/{session_id}/logs?lines=5")
|
||||
body = json.loads(contents[0]["text"])
|
||||
assert body["ok"] is True, body
|
||||
assert "lines" in body, body
|
||||
print(f"{len(body['lines'])} line(s) of {session_id}'s own output")
|
||||
except Exception:
|
||||
dump("reading a session's logs", session_id)
|
||||
raise
|
||||
|
||||
with subtest("shot returns image content, sized as the publisher serves it"):
|
||||
@@ -290,24 +370,50 @@ testers.runNixOSTest (
|
||||
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`.
|
||||
with subtest("the container is listed as a resource and reconciled as a tool"):
|
||||
# The pair that has to stay split: the LIST only reads the record,
|
||||
# so it is a resource; asking where the window is *now* re-reads the
|
||||
# compositor and writes the answer back, so it is a tool. Both are
|
||||
# asked here, and they have to agree about the output's name.
|
||||
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
|
||||
listed = json.loads(read("hhstream://containers")[0]["text"])
|
||||
assert listed["ok"] is True, listed
|
||||
from_resource = [
|
||||
c["output"] for c in (listed.get("containers") or [])
|
||||
]
|
||||
print(f"containers resource reports: {from_resource}")
|
||||
assert f"hh-{session_id}" in from_resource, listed
|
||||
|
||||
reconciled = succeeded("session_container", {"id": session_id})
|
||||
output = reconciled["structuredContent"]["container"]["output"]
|
||||
assert output == f"hh-{session_id}", reconciled
|
||||
except Exception:
|
||||
dump("the container, both ways", session_id)
|
||||
raise
|
||||
|
||||
with subtest("one output's frame reads as a blob, at exactly its own size"):
|
||||
# The resource that is an image, and the one place the configured
|
||||
# geometry is the geometry: `hhstream://screen` is the whole layout.
|
||||
try:
|
||||
output = f"hh-{session_id}"
|
||||
contents = read(f"hhstream://outputs/{output}", timeout=300)
|
||||
assert len(contents) == 1, contents
|
||||
blob = contents[0]
|
||||
assert blob["mimeType"] in ("image/png", "image/jpeg"), blob
|
||||
assert "text" not in blob, "an image must not arrive as text"
|
||||
frame = base64.b64decode(blob["blob"])
|
||||
print(f"{output}: {blob['mimeType']}, {len(frame)} bytes")
|
||||
assert frame[:4] in (b"\x89PNG", b"\xff\xd8\xff\xe0")
|
||||
assert len(frame) > 1024, "a frame that small is not a desktop"
|
||||
|
||||
# And the tool agrees about the size, which is what makes the
|
||||
# pointer's normalised coordinates meaningful.
|
||||
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)
|
||||
dump("reading an output's frame", session_id)
|
||||
raise
|
||||
|
||||
with subtest("the pointer lease is granted, used and given back"):
|
||||
@@ -347,11 +453,29 @@ testers.runNixOSTest (
|
||||
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"})
|
||||
with subtest("an unknown session is exit 3 from a tool, not a success"):
|
||||
refused = call("session_touch", {"id": "no-such-session"})
|
||||
assert refused["isError"] is True, refused
|
||||
assert refused["structuredContent"]["exit_code"] == 3, refused
|
||||
assert "session_list" in text_of(refused)
|
||||
assert "hhstream://sessions" in text_of(refused)
|
||||
|
||||
with subtest("a refused read is a protocol error carrying the same remedy"):
|
||||
# A resources/read has no `isError`, so this is the one place the
|
||||
# refusal has to travel as an error -- with the exit code intact,
|
||||
# or an agent cannot tell "no such session" from "broker down".
|
||||
error = read_refused("hhstream://sessions/no-such-session")
|
||||
print(error["message"].splitlines()[0])
|
||||
assert error["data"]["exit_code"] == 3, error
|
||||
assert error["data"]["error"] == "no_such_session", error
|
||||
assert "exit 3 (NO_SUCH_SESSION)" in error["message"]
|
||||
|
||||
with subtest("a uri this server does not serve is refused without running anything"):
|
||||
error = read_refused("hhstream://nonsense")
|
||||
assert "no resource at" in error["message"], error
|
||||
# And an undeclared query parameter, which the routing refuses for
|
||||
# the reason every tool schema sets additionalProperties: false.
|
||||
error = read_refused("hhstream://pointer?id=x")
|
||||
assert "accepts: none" in error["message"], error
|
||||
|
||||
with subtest("an argument the schema refuses never reaches the broker"):
|
||||
# No `lease`, so the server's own schema refuses before an argv list
|
||||
@@ -360,6 +484,44 @@ testers.runNixOSTest (
|
||||
assert refused["isError"] is True, refused
|
||||
assert "lease" in text_of(refused), refused
|
||||
|
||||
with subtest("--toolsets narrows the tools and leaves the resources alone"):
|
||||
# The flag exists because a tool listing is a budget. What it must
|
||||
# not do is take the host's context away with it.
|
||||
narrowed = json.loads(
|
||||
machine.succeed(
|
||||
as_user(f"{MCP} --server-arg=--toolsets=keyboard --list"),
|
||||
timeout=180,
|
||||
)
|
||||
)["tools"]
|
||||
names = sorted(tool["name"] for tool in narrowed)
|
||||
print(f"--toolsets keyboard offers: {', '.join(names)}")
|
||||
assert names == [
|
||||
"keyboard_down", "keyboard_key", "keyboard_type", "keyboard_up",
|
||||
], names
|
||||
|
||||
still_there = json.loads(
|
||||
machine.succeed(
|
||||
as_user(f"{MCP} --server-arg=--toolsets=keyboard --resources"),
|
||||
timeout=180,
|
||||
)
|
||||
)
|
||||
assert len(still_there["resources"]) == 5, still_there
|
||||
assert len(still_there["resourceTemplates"]) == 3, still_there
|
||||
|
||||
# And a tool outside the selection must be unreachable, not merely
|
||||
# unlisted, or the flag is cosmetic.
|
||||
refused = json.loads(
|
||||
machine.succeed(
|
||||
as_user(
|
||||
f"{MCP} --server-arg=--toolsets=keyboard session_kill "
|
||||
+ shlex.quote(json.dumps({"id": session_id}))
|
||||
),
|
||||
timeout=180,
|
||||
)
|
||||
)
|
||||
assert refused["isError"] is True, refused
|
||||
assert "without its toolset" 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)
|
||||
|
||||
@@ -252,7 +252,7 @@ def test_the_lease_codes_say_the_two_different_things_an_agent_must_do():
|
||||
busy = invoke.remedy_for(int(ExitCode.BUSY))
|
||||
none_held = invoke.remedy_for(int(ExitCode.NO_LEASE))
|
||||
|
||||
assert "pointer_state" in busy and "wait" in busy
|
||||
assert "hhstream://pointer" in busy and "wait" in busy
|
||||
assert "pointer_acquire" in none_held
|
||||
# "acquire one" must not be the advice for BUSY: that is the one confusion
|
||||
# the two codes exist to prevent.
|
||||
|
||||
@@ -0,0 +1,303 @@
|
||||
"""The resource table: which URI runs which CLI call, and what comes back.
|
||||
|
||||
Same subject as ``test_mcp_tools.py`` and the same stand-in: what this layer
|
||||
decides is the argv list, and here also the *routing* -- which entry a URI
|
||||
resolves to, and which query parameters it will accept. Nothing here imports
|
||||
the MCP SDK; the protocol wiring is ``test_mcp_server.py``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
|
||||
import mcp_fake
|
||||
import pytest
|
||||
from hhstreamd.protocol import ExitCode
|
||||
from hhstream_mcp import invoke, resources, tools
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _isolated(monkeypatch, tmp_path):
|
||||
mcp_fake.isolate(monkeypatch, tmp_path)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def read():
|
||||
"""`read("hhstream://sessions")` -> (Reading, [argv, ...])."""
|
||||
|
||||
def _read(uri, **script):
|
||||
fake = mcp_fake.FakeCli(**script)
|
||||
reading = resources.read(invoke.Runner(fake), uri)
|
||||
return reading, fake.calls
|
||||
|
||||
return _read
|
||||
|
||||
|
||||
# ── the table ──────────────────────────────────────────────────────────────
|
||||
|
||||
#: Every resource `docs/CONTRACT-mcp.md` §4 freezes, written out rather than
|
||||
#: derived, for the reason the tool list is.
|
||||
EXPECTED_FIXED = {
|
||||
"hhstream://status",
|
||||
"hhstream://sessions",
|
||||
"hhstream://pointer",
|
||||
"hhstream://containers",
|
||||
"hhstream://screen",
|
||||
}
|
||||
EXPECTED_TEMPLATES = {
|
||||
"hhstream://sessions/{id}{?events}",
|
||||
"hhstream://sessions/{id}/logs{?lines}",
|
||||
"hhstream://outputs/{name}",
|
||||
}
|
||||
|
||||
|
||||
def test_the_whole_surface_is_there_and_nothing_else_is():
|
||||
assert {entry.uri for entry in resources.FIXED} == EXPECTED_FIXED
|
||||
assert {entry.uri_template for entry in resources.TEMPLATES} == EXPECTED_TEMPLATES
|
||||
assert len(resources.ENTRIES) == len(EXPECTED_FIXED) + len(EXPECTED_TEMPLATES)
|
||||
|
||||
|
||||
def test_every_entry_has_a_unique_name_and_a_description():
|
||||
names = [entry.name for entry in resources.ENTRIES]
|
||||
assert len(names) == len(set(names))
|
||||
for entry in resources.ENTRIES:
|
||||
assert entry.title, entry.name
|
||||
assert len(entry.description) > 40, entry.name
|
||||
assert entry.media_type
|
||||
|
||||
|
||||
def test_a_template_is_exactly_an_entry_with_a_capture():
|
||||
for entry in resources.FIXED:
|
||||
assert entry.captures == ()
|
||||
for entry in resources.TEMPLATES:
|
||||
assert entry.captures
|
||||
|
||||
|
||||
def test_the_three_reads_the_activity_rule_names_say_so_themselves():
|
||||
"""The rule has to be where it is read, and these are read, not called."""
|
||||
|
||||
for name in ("sessions", "session", "session-logs", "pointer", "containers"):
|
||||
description = resources.BY_NAME[name].description
|
||||
assert "does NOT reset" in description, name
|
||||
assert "`session_touch`" in description, name
|
||||
|
||||
|
||||
# ── routing ────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_literal_route_beats_a_template_that_would_also_match():
|
||||
"""`hhstream://sessions` is the listing, not a session with a blank id."""
|
||||
|
||||
entry, arguments = resources.resolve("hhstream://sessions")
|
||||
assert entry.name == "sessions"
|
||||
assert arguments == {}
|
||||
|
||||
|
||||
def test_a_capture_becomes_the_argument_the_cli_takes(read):
|
||||
_, calls = read("hhstream://sessions/foot-abc", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "status", "--json", "--", "foot-abc"]]
|
||||
|
||||
|
||||
def test_a_deeper_route_is_its_own_entry(read):
|
||||
_, calls = read("hhstream://sessions/foot-abc/logs", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "logs", "--json", "--", "foot-abc"]]
|
||||
|
||||
|
||||
def test_each_fixed_resource_runs_the_verb_it_names(read):
|
||||
cases = {
|
||||
"hhstream://status": ["status"],
|
||||
"hhstream://sessions": ["session", "list", "--json"],
|
||||
"hhstream://pointer": ["session", "pointer", "state", "--json"],
|
||||
"hhstream://containers": ["session", "container", "--json"],
|
||||
}
|
||||
for uri, argv in cases.items():
|
||||
_, calls = read(uri, stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [argv], uri
|
||||
|
||||
|
||||
def test_the_status_resource_is_text_because_the_verb_has_no_json(read):
|
||||
reading, calls = read("hhstream://status", stdout="services:\n up\n")
|
||||
assert calls == [["status"]]
|
||||
assert reading.media_type == "text/plain"
|
||||
assert reading.text == "services:\n up"
|
||||
assert reading.blob is None
|
||||
|
||||
|
||||
def test_a_json_resource_passes_the_protocol_object_through_unchanged(read):
|
||||
reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]}
|
||||
reading, _ = read("hhstream://sessions", stdout=json.dumps(reply, indent=2))
|
||||
|
||||
assert reading.media_type == "application/json"
|
||||
assert json.loads(reading.text) == reply
|
||||
|
||||
|
||||
def test_a_scheme_this_server_does_not_serve_is_refused(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("file:///etc/passwd")
|
||||
assert "not a hhstream resource" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_uri_that_names_nothing_is_refused_and_points_at_the_listing(read):
|
||||
for uri in ("hhstream://nonsense", "hhstream://sessions/a/b/c", "hhstream://"):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(uri)
|
||||
assert "resources/list" in str(caught.value) or "names no resource" in str(
|
||||
caught.value
|
||||
)
|
||||
|
||||
|
||||
def test_nothing_was_run_for_a_uri_that_did_not_resolve(monkeypatch, tmp_path):
|
||||
"""The routing refuses before the CLI is reached, as a schema would."""
|
||||
|
||||
fake = mcp_fake.FakeCli()
|
||||
with pytest.raises(resources.ReadRefused):
|
||||
resources.read(invoke.Runner(fake), "hhstream://nonsense")
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
# ── query parameters ───────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_declared_parameter_becomes_the_flag_the_cli_takes(read):
|
||||
_, calls = read(
|
||||
"hhstream://sessions/foot-abc/logs?lines=250", stdout=mcp_fake.reply(ok=True)
|
||||
)
|
||||
assert calls == [["session", "logs", "--json", "--lines=250", "--", "foot-abc"]]
|
||||
|
||||
_, calls = read(
|
||||
"hhstream://sessions/foot-abc?events=5", stdout=mcp_fake.reply(ok=True)
|
||||
)
|
||||
assert calls == [["session", "status", "--json", "--events=5", "--", "foot-abc"]]
|
||||
|
||||
|
||||
def test_a_switch_parameter_is_a_bare_flag_or_nothing(read):
|
||||
"""`--all=false` is not a thing the CLI takes, so false must omit it."""
|
||||
|
||||
_, calls = read("hhstream://sessions?all=true", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "list", "--json", "--all"]]
|
||||
|
||||
for falsey in ("false", "0", "no", "off", ""):
|
||||
_, calls = read(f"hhstream://sessions?all={falsey}", stdout=mcp_fake.reply(ok=True))
|
||||
assert calls == [["session", "list", "--json"]], falsey
|
||||
|
||||
|
||||
def test_an_undeclared_parameter_is_refused_rather_than_dropped(read):
|
||||
"""A parameter silently ignored is a read that answered another question."""
|
||||
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://sessions?lines=5")
|
||||
assert "'lines'" in str(caught.value)
|
||||
assert "all" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_resource_with_no_parameters_says_so_when_given_one(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://pointer?id=s-1")
|
||||
assert "accepts: none" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_parameter_given_twice_is_refused(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://sessions/s-1/logs?lines=1&lines=2")
|
||||
assert "more than once" in str(caught.value)
|
||||
|
||||
|
||||
def test_the_template_advertises_the_parameters_it_accepts():
|
||||
"""So a client can construct a URI without guessing."""
|
||||
|
||||
logs = resources.BY_NAME["session-logs"]
|
||||
assert logs.uri_template == "hhstream://sessions/{id}/logs{?lines}"
|
||||
assert logs.parameters == ("lines",)
|
||||
|
||||
|
||||
# ── refusals ───────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_cli_refusal_is_raised_and_never_returned_as_the_body(read):
|
||||
"""A resource has no `isError`; returning the failure object would lie."""
|
||||
|
||||
reply = {"ok": False, "error": "no_such_session", "reason": "no session 'nope'"}
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(
|
||||
"hhstream://sessions/nope",
|
||||
stderr=mcp_fake.reply(**reply),
|
||||
exit_code=int(ExitCode.NO_SUCH_SESSION),
|
||||
)
|
||||
refused = caught.value
|
||||
assert "exit 3 (NO_SUCH_SESSION)" in refused.message
|
||||
assert "no session 'nope'" in refused.message
|
||||
# And the structured detail carries what a tool error would have carried.
|
||||
assert refused.detail["exit_code"] == int(ExitCode.NO_SUCH_SESSION)
|
||||
assert refused.detail["error"] == "no_such_session"
|
||||
assert "hhstream://sessions" in refused.detail["remedy"]
|
||||
|
||||
|
||||
def test_an_unreachable_broker_is_refused_with_the_operator_s_remedy(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(
|
||||
"hhstream://sessions",
|
||||
stderr=mcp_fake.reply(ok=False, error="daemon_unreachable", reason="no socket"),
|
||||
exit_code=int(ExitCode.DAEMON_UNREACHABLE),
|
||||
)
|
||||
assert "HHSTREAM_SOCKET" in caught.value.message
|
||||
|
||||
|
||||
# ── frames ─────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_the_screen_resource_is_the_frame_bytes_with_its_real_media_type(read):
|
||||
frame = mcp_fake.png(width=320, height=180)
|
||||
reading, calls = read("hhstream://screen", write_png=frame)
|
||||
|
||||
assert calls[0][0] == "shot"
|
||||
assert calls[0][1].startswith("--out=")
|
||||
assert len(calls[0]) == 2, "the screen takes no --output"
|
||||
assert reading.blob == frame
|
||||
assert reading.text is None
|
||||
assert reading.media_type == "image/png"
|
||||
|
||||
|
||||
def test_an_output_resource_captures_that_output_alone(read):
|
||||
frame = mcp_fake.png()
|
||||
reading, calls = read("hhstream://outputs/hh-foot-abc", write_png=frame)
|
||||
|
||||
assert "--output=hh-foot-abc" in calls[0]
|
||||
assert reading.blob == frame
|
||||
|
||||
|
||||
def test_a_frame_s_media_type_is_sniffed_and_not_assumed(read):
|
||||
"""The entry declares image/png; a JPEG publisher must still be told truly."""
|
||||
|
||||
assert resources.BY_NAME["screen"].media_type == "image/png"
|
||||
reading, _ = read("hhstream://screen", write_png=mcp_fake.jpeg())
|
||||
assert reading.media_type == "image/jpeg"
|
||||
|
||||
|
||||
def test_a_capture_that_wrote_no_file_is_refused_rather_than_empty(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read("hhstream://screen")
|
||||
assert "no readable file" in str(caught.value)
|
||||
|
||||
|
||||
def test_a_refused_capture_carries_the_cli_s_own_words(read):
|
||||
with pytest.raises(resources.ReadRefused) as caught:
|
||||
read(
|
||||
"hhstream://outputs/hh-gone",
|
||||
stderr="hhstream: could not capture output 'hh-gone': unknown output\n",
|
||||
exit_code=1,
|
||||
)
|
||||
assert "unknown output" in str(caught.value)
|
||||
assert "hh-gone" in str(caught.value)
|
||||
|
||||
|
||||
# ── the one read that must not be a resource ───────────────────────────────
|
||||
|
||||
|
||||
def test_there_is_no_resource_for_the_reconciling_container_read():
|
||||
"""`session container <id>` writes. Only the no-id list is a resource."""
|
||||
|
||||
assert "hhstream://containers" in EXPECTED_FIXED
|
||||
for entry in resources.ENTRIES:
|
||||
assert entry.route[:1] != ("containers",) or entry.captures == ()
|
||||
# ...and the writing form is still reachable, as a tool.
|
||||
assert "session_container" in tools.BY_NAME
|
||||
@@ -28,8 +28,9 @@ import pytest
|
||||
from hhstreamd.protocol import ExitCode
|
||||
from mcp.shared.memory import create_connected_server_and_client_session
|
||||
from mcp.shared.tool_name_validation import validate_tool_name
|
||||
from pydantic import AnyUrl
|
||||
|
||||
from hhstream_mcp import SERVER_NAME, __version__, invoke, server, tools
|
||||
from hhstream_mcp import SERVER_NAME, __version__, invoke, resources, server, tools
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
@@ -47,9 +48,9 @@ def session():
|
||||
about.
|
||||
"""
|
||||
|
||||
def _session(**script):
|
||||
def _session(toolsets=None, **script):
|
||||
fake = mcp_fake.FakeCli(**script)
|
||||
built = server.build(invoke.Runner(fake))
|
||||
built = server.build(invoke.Runner(fake), toolsets)
|
||||
return fake, create_connected_server_and_client_session(
|
||||
built, raise_exceptions=True
|
||||
)
|
||||
@@ -76,6 +77,9 @@ def test_initialize_names_this_server_and_declares_tools(session):
|
||||
assert initialized.serverInfo.name == SERVER_NAME
|
||||
assert initialized.serverInfo.version == __version__
|
||||
assert initialized.capabilities.tools is not None
|
||||
# Resources are half the surface now, so the capability has to be declared
|
||||
# or a host will never ask for them.
|
||||
assert initialized.capabilities.resources is not None
|
||||
# The instructions are where the two rules are said once for the whole
|
||||
# surface; a client that shows them must be given them.
|
||||
assert initialized.instructions
|
||||
@@ -91,6 +95,15 @@ def test_the_instructions_carry_both_rules():
|
||||
assert "9 means you need to acquire one" in server.INSTRUCTIONS
|
||||
|
||||
|
||||
def test_the_instructions_explain_the_split_they_cannot_be_read_without():
|
||||
"""An agent that does not know state is a resource will look for a tool."""
|
||||
|
||||
assert "Resources are the state" in server.INSTRUCTIONS
|
||||
assert "Tools are the acts" in server.INSTRUCTIONS
|
||||
for uri in ("hhstream://status", "hhstream://sessions", "hhstream://pointer"):
|
||||
assert uri in server.INSTRUCTIONS
|
||||
|
||||
|
||||
# ── the listing ────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@@ -104,6 +117,7 @@ def test_tools_list_returns_every_tool_with_a_title_and_a_description(session):
|
||||
|
||||
listed = run(go).tools
|
||||
assert {tool.name for tool in listed} == set(tools.BY_NAME)
|
||||
assert len(listed) == 21
|
||||
for tool in listed:
|
||||
assert tool.title, tool.name
|
||||
assert tool.description and len(tool.description) > 40, tool.name
|
||||
@@ -186,18 +200,18 @@ def test_a_gesture_without_a_lease_is_refused_before_the_cli_is_run(session):
|
||||
|
||||
|
||||
def test_a_successful_call_carries_the_protocol_object_as_structured_content(session):
|
||||
reply = {"ok": True, "sessions": []}
|
||||
reply = {"ok": True, "pruned": 0}
|
||||
fake, connected = session(stdout=json.dumps(reply, indent=2))
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("session_list", {})
|
||||
return await client.call_tool("session_gc", {})
|
||||
|
||||
result = run(go)
|
||||
assert not result.isError
|
||||
assert result.structuredContent == reply
|
||||
assert fake.calls == [["session", "list", "--json"]]
|
||||
assert fake.calls == [["session", "gc", "--json"]]
|
||||
|
||||
|
||||
def test_a_refused_call_arrives_as_a_tool_error_an_agent_can_read(session):
|
||||
@@ -243,6 +257,24 @@ def test_a_frame_arrives_as_image_content_beside_its_geometry(session):
|
||||
assert base64.b64decode(image.data) == frame
|
||||
|
||||
|
||||
def test_a_v1_tool_name_is_told_which_resource_replaced_it(session):
|
||||
"""`no such tool` alone reads as a broken server rather than a moved surface."""
|
||||
|
||||
fake, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("session_list", {})
|
||||
|
||||
result = run(go)
|
||||
assert result.isError is True
|
||||
text = result.content[0].text
|
||||
assert "It is a RESOURCE now" in text
|
||||
assert "hhstream://sessions" in text
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
def test_a_tool_that_does_not_exist_names_the_ones_that_do(session):
|
||||
"""And is an error. The SDK turns a raised McpError into this shape anyway."""
|
||||
|
||||
@@ -264,7 +296,7 @@ def test_a_handler_that_raises_is_reported_to_the_agent_and_not_only_logged():
|
||||
"""A CLI process would have died with a traceback and status 1; so does this."""
|
||||
|
||||
fake = mcp_fake.FakeCli(raises=RuntimeError("the broker said something odd"))
|
||||
result = server.call(invoke.Runner(fake), "session_list", {})
|
||||
result = server.call(invoke.Runner(fake), "session_gc", {})
|
||||
|
||||
assert result.isError is True
|
||||
assert result.structuredContent["exit_code"] == invoke.GENERIC_FAILURE
|
||||
@@ -306,6 +338,192 @@ def test_the_listing_is_what_the_entry_point_prints(capsys):
|
||||
assert printed[0].split("\t")[0] == tools.TOOLS[0].name
|
||||
|
||||
|
||||
def test_the_entry_point_lists_resources_too(capsys):
|
||||
assert server.main(["--list-resources"]) == 0
|
||||
printed = capsys.readouterr().out.splitlines()
|
||||
assert len(printed) == len(resources.ENTRIES)
|
||||
assert printed[0].split("\t")[0] == "hhstream://status"
|
||||
|
||||
|
||||
def test_the_entry_point_s_listing_honours_a_toolset_selection(capsys):
|
||||
assert server.main(["--list-tools", "--toolsets", "keyboard"]) == 0
|
||||
printed = capsys.readouterr().out.splitlines()
|
||||
assert [line.split("\t")[0] for line in printed] == list(
|
||||
tools.TOOLSETS["keyboard"]
|
||||
)
|
||||
|
||||
|
||||
def test_an_unknown_toolset_on_the_command_line_is_argparse_s_exit_two(capsys):
|
||||
with pytest.raises(SystemExit) as caught:
|
||||
server.main(["--list-tools", "--toolsets", "mouse"])
|
||||
assert caught.value.code == 2
|
||||
assert "no such toolset" in capsys.readouterr().err
|
||||
|
||||
|
||||
def test_an_empty_toolset_list_is_refused_rather_than_read_as_all(capsys):
|
||||
"""`--toolsets ""` is a mistake, and serving everything would hide it."""
|
||||
|
||||
with pytest.raises(SystemExit) as caught:
|
||||
server.main(["--list-tools", "--toolsets", " , "])
|
||||
assert caught.value.code == 2
|
||||
|
||||
|
||||
# ── resources, over the protocol ───────────────────────────────────────────
|
||||
|
||||
|
||||
def test_resources_list_returns_the_fixed_ones_with_their_descriptions(session):
|
||||
_, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.list_resources()
|
||||
|
||||
listed = run(go).resources
|
||||
assert {str(r.uri) for r in listed} == {e.uri for e in resources.FIXED}
|
||||
for resource in listed:
|
||||
assert resource.title and resource.description and resource.mimeType
|
||||
|
||||
|
||||
def test_resource_templates_are_listed_separately_with_their_parameters(session):
|
||||
_, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.list_resource_templates()
|
||||
|
||||
listed = run(go).resourceTemplates
|
||||
assert {t.uriTemplate for t in listed} == {e.uri_template for e in resources.TEMPLATES}
|
||||
logs = next(t for t in listed if t.uriTemplate.endswith("/logs{?lines}"))
|
||||
assert logs.name == "session-logs"
|
||||
|
||||
|
||||
def test_reading_a_json_resource_returns_the_broker_s_object(session):
|
||||
reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]}
|
||||
fake, connected = session(stdout=json.dumps(reply, indent=2))
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.read_resource(AnyUrl("hhstream://sessions"))
|
||||
|
||||
result = run(go)
|
||||
assert len(result.contents) == 1
|
||||
content = result.contents[0]
|
||||
assert content.mimeType == "application/json"
|
||||
assert json.loads(content.text) == reply
|
||||
assert fake.calls == [["session", "list", "--json"]]
|
||||
|
||||
|
||||
def test_reading_a_template_passes_the_capture_and_the_query_through(session):
|
||||
fake, connected = session(stdout=mcp_fake.reply(ok=True, lines=[]))
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.read_resource(
|
||||
AnyUrl("hhstream://sessions/foot-abc/logs?lines=7")
|
||||
)
|
||||
|
||||
run(go)
|
||||
assert fake.calls == [
|
||||
["session", "logs", "--json", "--lines=7", "--", "foot-abc"]
|
||||
]
|
||||
|
||||
|
||||
def test_reading_a_frame_resource_returns_a_blob_not_text(session):
|
||||
frame = mcp_fake.png(width=48, height=24)
|
||||
_, connected = session(write_png=frame)
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.read_resource(AnyUrl("hhstream://screen"))
|
||||
|
||||
content = run(go).contents[0]
|
||||
assert isinstance(content, types.BlobResourceContents)
|
||||
assert content.mimeType == "image/png"
|
||||
|
||||
import base64
|
||||
|
||||
assert base64.b64decode(content.blob) == frame
|
||||
|
||||
|
||||
def test_a_refused_read_is_a_protocol_error_carrying_the_remedy(session):
|
||||
"""A resource read has no `isError`, so the refusal has to be an error."""
|
||||
|
||||
from mcp.shared.exceptions import McpError
|
||||
|
||||
fake, connected = session(
|
||||
stderr=mcp_fake.reply(ok=False, error="no_such_session", reason="no session 'nope'"),
|
||||
exit_code=int(ExitCode.NO_SUCH_SESSION),
|
||||
)
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
with pytest.raises(McpError) as caught:
|
||||
await client.read_resource(AnyUrl("hhstream://sessions/nope"))
|
||||
return caught.value
|
||||
|
||||
error = run(go)
|
||||
assert "exit 3 (NO_SUCH_SESSION)" in str(error)
|
||||
assert "no session 'nope'" in str(error)
|
||||
|
||||
|
||||
def test_a_uri_that_names_no_resource_is_a_protocol_error(session):
|
||||
from mcp.shared.exceptions import McpError
|
||||
|
||||
fake, connected = session()
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
with pytest.raises(McpError) as caught:
|
||||
await client.read_resource(AnyUrl("hhstream://nonsense"))
|
||||
return caught.value
|
||||
|
||||
error = run(go)
|
||||
assert "no resource at" in str(error)
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
# ── toolsets, over the protocol ────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_toolset_selection_narrows_the_listing_but_not_the_resources(session):
|
||||
_, connected = session(toolsets=["keyboard"])
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.list_tools(), await client.list_resources()
|
||||
|
||||
listed, resource_list = run(go)
|
||||
assert [t.name for t in listed.tools] == list(tools.TOOLSETS["keyboard"])
|
||||
# Resources are the host's context, not the model's tool budget.
|
||||
assert len(resource_list.resources) == len(resources.FIXED)
|
||||
|
||||
|
||||
def test_a_tool_outside_the_selection_cannot_be_called_by_name(session):
|
||||
"""Unlisted must mean unreachable, or the selection is cosmetic."""
|
||||
|
||||
fake, connected = session(toolsets=["keyboard"])
|
||||
|
||||
async def go():
|
||||
async with connected as client:
|
||||
await client.initialize()
|
||||
return await client.call_tool("session_kill", {"id": "s-1"})
|
||||
|
||||
result = run(go)
|
||||
assert result.isError is True
|
||||
text = result.content[0].text
|
||||
assert "session_kill" in text
|
||||
assert "without its toolset" in text
|
||||
assert fake.calls == []
|
||||
|
||||
|
||||
def test_content_for_a_text_only_result_has_no_image_block():
|
||||
blocks = server.content_for(tools.Result(text="hello"))
|
||||
assert [block.type for block in blocks] == ["text"]
|
||||
|
||||
+107
-57
@@ -42,26 +42,56 @@ def call():
|
||||
|
||||
# ── the surface is all there ───────────────────────────────────────────────
|
||||
|
||||
#: Every tool `docs/CONTRACT-mcp.md` §3 freezes, which is every verb of the CLI.
|
||||
#: Written out rather than derived from the table, because a list derived from
|
||||
#: the thing it checks cannot notice a missing entry.
|
||||
#: Every tool `docs/CONTRACT-mcp.md` §3 freezes. Written out rather than derived
|
||||
#: from the table, because a list derived from the thing it checks cannot
|
||||
#: notice a missing entry.
|
||||
EXPECTED = {
|
||||
# frames
|
||||
"status", "shot", "record", "run",
|
||||
# lifecycle
|
||||
"session_start", "session_list", "session_status", "session_touch",
|
||||
"session_kill", "session_gc", "session_adopt", "session_logs",
|
||||
"session_container", "session_reconcile",
|
||||
# frames -- capturing is an act at a moment, so these stay tools
|
||||
"shot", "record", "run",
|
||||
# lifecycle. The read-only verbs are resources; see MOVED_TO_RESOURCES.
|
||||
"session_start", "session_touch", "session_kill", "session_gc",
|
||||
"session_adopt", "session_container", "session_reconcile",
|
||||
# pointer
|
||||
"pointer_acquire", "pointer_move", "pointer_click", "pointer_scroll",
|
||||
"pointer_down", "pointer_up", "pointer_release", "pointer_state",
|
||||
"pointer_down", "pointer_up", "pointer_release",
|
||||
# keyboard
|
||||
"keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up",
|
||||
}
|
||||
|
||||
#: Verbs that are resources now and must NOT come back as tools. Named, not
|
||||
#: merely absent, so re-adding one is a failure rather than a silent widening
|
||||
#: of the surface mcp-v2 narrowed.
|
||||
MOVED_TO_RESOURCES = {
|
||||
"status",
|
||||
"session_list",
|
||||
"session_status",
|
||||
"session_logs",
|
||||
"pointer_state",
|
||||
}
|
||||
|
||||
def test_every_cli_verb_has_a_tool_and_nothing_else_does():
|
||||
|
||||
def test_the_acting_verbs_are_tools_and_nothing_else_is():
|
||||
assert set(tools.BY_NAME) == EXPECTED
|
||||
assert len(tools.TOOLS) == 21
|
||||
|
||||
|
||||
def test_the_read_only_verbs_are_not_tools():
|
||||
"""They are `hhstream://…` resources: the host's context, not the model's acts."""
|
||||
|
||||
assert MOVED_TO_RESOURCES.isdisjoint(set(tools.BY_NAME))
|
||||
# ...and the table that says where each one went covers exactly those five,
|
||||
# so a caller holding a v1 name can be told rather than just refused.
|
||||
assert set(tools.MOVED_TO_RESOURCES) == MOVED_TO_RESOURCES
|
||||
for uri in tools.MOVED_TO_RESOURCES.values():
|
||||
assert uri.startswith("hhstream://")
|
||||
|
||||
|
||||
def test_session_container_stayed_a_tool_because_it_writes():
|
||||
"""With an id the CLI runs `container.reconcile`, so it is not a read."""
|
||||
|
||||
assert "session_container" in tools.BY_NAME
|
||||
assert not tools.BY_NAME["session_container"].read_only
|
||||
assert "write" in tools.BY_NAME["session_container"].description
|
||||
|
||||
|
||||
def test_the_table_is_ordered_and_has_no_duplicate_names():
|
||||
@@ -71,18 +101,10 @@ def test_the_table_is_ordered_and_has_no_duplicate_names():
|
||||
|
||||
|
||||
def test_only_the_verbs_that_read_are_marked_read_only():
|
||||
"""`session_container` with an id reconciles, which is a write."""
|
||||
"""One left, now that the rest of the reads are resources."""
|
||||
|
||||
read_only = {tool.name for tool in tools.TOOLS if tool.read_only}
|
||||
assert read_only == {
|
||||
"status",
|
||||
"shot",
|
||||
"session_list",
|
||||
"session_status",
|
||||
"session_logs",
|
||||
"pointer_state",
|
||||
}
|
||||
assert not tools.BY_NAME["session_container"].read_only
|
||||
assert read_only == {"shot"}
|
||||
# `record` writes a file, so it is not read-only either.
|
||||
assert not tools.BY_NAME["record"].read_only
|
||||
assert tools.BY_NAME["session_kill"].destructive
|
||||
@@ -91,12 +113,9 @@ def test_only_the_verbs_that_read_are_marked_read_only():
|
||||
|
||||
# ── the two rules an agent gets wrong ──────────────────────────────────────
|
||||
|
||||
#: The verbs the CLI's own note names as NOT counting as activity. Taken from
|
||||
#: the rule, so a tool that stopped carrying the warning is a failure here.
|
||||
#: The tools the CLI's own note names as NOT counting as activity. The others
|
||||
#: it names are resources now, and `test_mcp_resources.py` holds those.
|
||||
NON_ACTIVITY = {
|
||||
"session_list",
|
||||
"session_status",
|
||||
"session_logs",
|
||||
"session_gc",
|
||||
"session_container",
|
||||
"session_reconcile",
|
||||
@@ -115,6 +134,9 @@ GESTURES = {
|
||||
"keyboard_up",
|
||||
}
|
||||
|
||||
#: The four families `--toolsets` selects from.
|
||||
FAMILIES = ("frames", "sessions", "pointer", "keyboard")
|
||||
|
||||
|
||||
def test_the_idle_clock_rule_is_on_every_tool_that_does_not_reset_it():
|
||||
for name in NON_ACTIVITY | GESTURES | {"session_start", "session_touch", "pointer_acquire"}:
|
||||
@@ -124,9 +146,12 @@ def test_the_idle_clock_rule_is_on_every_tool_that_does_not_reset_it():
|
||||
|
||||
def test_the_idle_clock_rule_names_touch_as_the_only_mark_of_activity():
|
||||
assert "`session_touch` is the ONLY thing" in tools.ACTIVITY_NOTE
|
||||
for verb in ("session_list", "session_status", "session_logs", "session_gc"):
|
||||
assert verb in tools.ACTIVITY_NOTE
|
||||
assert "do NOT count" in tools.ACTIVITY_NOTE
|
||||
# It has to name the *resources* now, because that is where reading moved:
|
||||
# an agent told "listing does not count" cannot act on it if the thing it
|
||||
# is listing with is no longer called `session_list`.
|
||||
for named in ("hhstream://sessions", "session_gc", "pointer or keyboard tool"):
|
||||
assert named in tools.ACTIVITY_NOTE
|
||||
assert "does NOT count" in tools.ACTIVITY_NOTE
|
||||
|
||||
|
||||
def test_the_cli_still_owns_the_rule_this_wording_restates():
|
||||
@@ -170,6 +195,48 @@ def test_the_lease_is_a_required_argument_on_every_gesture_and_is_never_cached()
|
||||
assert "lease" not in tools.BY_NAME["pointer_acquire"].schema.get("required", [])
|
||||
|
||||
|
||||
# ── toolsets ───────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_every_tool_is_in_exactly_one_toolset():
|
||||
"""Or `--toolsets` would be able to hide a tool nobody could ask for."""
|
||||
|
||||
assert tuple(tools.TOOLSETS) == FAMILIES
|
||||
seen: list[str] = []
|
||||
for family in FAMILIES:
|
||||
seen.extend(tools.TOOLSETS[family])
|
||||
assert len(seen) == len(set(seen)), "a tool is in two toolsets"
|
||||
assert set(seen) == set(tools.BY_NAME), "a tool is in no toolset"
|
||||
|
||||
|
||||
def test_no_toolset_named_is_every_tool():
|
||||
"""The default, and what an unconfigured client gets."""
|
||||
|
||||
assert tools.selected(None) == tools.TOOLS
|
||||
|
||||
|
||||
def test_a_selection_keeps_the_table_s_own_order():
|
||||
"""So a listing does not reshuffle because of how the flag was written."""
|
||||
|
||||
chosen = [tool.name for tool in tools.selected(["keyboard", "frames"])]
|
||||
assert chosen == ["shot", "record", "run", "keyboard_type", "keyboard_key",
|
||||
"keyboard_down", "keyboard_up"]
|
||||
|
||||
|
||||
def test_a_repeated_family_is_not_a_repeated_tool():
|
||||
assert tools.selected(["frames", "frames"]) == tools.selected(["frames"])
|
||||
|
||||
|
||||
def test_an_unknown_family_is_refused_and_names_the_known_ones():
|
||||
"""Not skipped: a typo that served nothing would look like an empty server."""
|
||||
|
||||
with pytest.raises(tools.UnknownToolset) as caught:
|
||||
tools.selected(["frames", "mouse"])
|
||||
assert "'mouse'" in str(caught.value)
|
||||
for family in FAMILIES:
|
||||
assert family in str(caught.value)
|
||||
|
||||
|
||||
def test_every_schema_refuses_an_argument_this_server_would_drop():
|
||||
for tool in tools.TOOLS:
|
||||
assert tool.schema["additionalProperties"] is False, tool.name
|
||||
@@ -187,12 +254,12 @@ def test_a_session_verb_is_run_with_json_and_its_id_after_a_separator(call):
|
||||
def test_omitted_arguments_become_no_flag_at_all(call):
|
||||
"""A flag left off is the broker's own default; this layer must not supply one."""
|
||||
|
||||
_, calls = call("session_list", {})
|
||||
assert calls == [["session", "list", "--json"]]
|
||||
_, calls = call("session_list", {"all": True})
|
||||
assert calls == [["session", "list", "--json", "--all"]]
|
||||
_, calls = call("session_list", {"all": False})
|
||||
assert calls == [["session", "list", "--json"]]
|
||||
_, calls = call("session_gc", {})
|
||||
assert calls == [["session", "gc", "--json"]]
|
||||
_, calls = call("session_gc", {"request_id": "r-1"})
|
||||
assert calls == [["session", "gc", "--json", "--request-id=r-1"]]
|
||||
_, calls = call("session_reconcile", {})
|
||||
assert calls == [["session", "reconcile", "--json"]]
|
||||
|
||||
|
||||
def test_start_passes_the_application_argv_after_one_separator(call):
|
||||
@@ -259,12 +326,6 @@ def test_a_negative_scroll_amount_stays_one_token(call):
|
||||
]
|
||||
|
||||
|
||||
def test_pointer_state_takes_no_session_because_there_is_one_cursor(call):
|
||||
_, calls = call("pointer_state", {})
|
||||
assert calls == [["session", "pointer", "state", "--json"]]
|
||||
assert tools.BY_NAME["pointer_state"].schema["properties"] == {}
|
||||
|
||||
|
||||
def test_a_typed_string_is_one_positional_after_the_separator(call):
|
||||
text = "--not-a-flag\nsecond line\twith a tab"
|
||||
_, calls = call("keyboard_type", {"id": "s-1", "lease": "L", "text": text})
|
||||
@@ -288,23 +349,12 @@ def test_container_with_no_id_lists_and_with_an_id_reconciles(call):
|
||||
assert calls == [["session", "container", "--json", "--", "s-1"]]
|
||||
|
||||
|
||||
def test_logs_has_no_follow_because_a_tool_call_must_return(call):
|
||||
assert "follow" not in tools.BY_NAME["session_logs"].schema["properties"]
|
||||
_, calls = call("session_logs", {"id": "s-1", "lines": 5})
|
||||
assert calls == [["session", "logs", "--json", "--lines=5", "--", "s-1"]]
|
||||
|
||||
|
||||
def test_status_is_not_run_with_json_because_the_verb_has_none(call):
|
||||
_, calls = call("status", {}, stdout="services:\n")
|
||||
assert calls == [["status"]]
|
||||
|
||||
|
||||
# ── what each tool makes of the answer ─────────────────────────────────────
|
||||
|
||||
|
||||
def test_a_successful_session_verb_passes_the_protocol_object_through(call):
|
||||
reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]}
|
||||
result, _ = call("session_list", {}, stdout=json.dumps(reply, indent=2))
|
||||
reply = {"ok": True, "pruned": 2, "sessions": [{"id": "s-1"}]}
|
||||
result, _ = call("session_gc", {}, stdout=json.dumps(reply, indent=2))
|
||||
|
||||
assert not result.is_error
|
||||
assert result.data == reply
|
||||
@@ -366,7 +416,7 @@ def test_the_contended_lease_case_names_the_holder_and_does_not_say_acquire(call
|
||||
|
||||
assert result.is_error
|
||||
assert result.text.startswith("exit 8 (BUSY)")
|
||||
assert "pointer_state" in result.text
|
||||
assert "hhstream://pointer" in result.text
|
||||
assert "s-other" in result.text
|
||||
|
||||
|
||||
@@ -387,7 +437,7 @@ def test_a_usage_refusal_from_argparse_itself_is_still_an_error(call):
|
||||
|
||||
def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call):
|
||||
result, _ = call(
|
||||
"session_list",
|
||||
"session_gc",
|
||||
{},
|
||||
stderr="error: cannot reach the hhstream session daemon at /run/hhstream/control.sock\n",
|
||||
exit_code=int(ExitCode.DAEMON_UNREACHABLE),
|
||||
@@ -395,7 +445,7 @@ def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call):
|
||||
|
||||
assert result.is_error
|
||||
assert "HHSTREAM_SOCKET" in result.text
|
||||
assert "Frame tools" in result.text
|
||||
assert "frame tools" in result.text
|
||||
|
||||
|
||||
# ── shot and record ────────────────────────────────────────────────────────
|
||||
|
||||
Reference in new issue
Block a user