Files
hyprland-headless-stream-pl…/tests/unit/test_mcp_server.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

531 lines
19 KiB
Python

"""The SDK wiring: the handshake, the listing, and one call of each shape.
This is the file that imports the MCP SDK, and it does so unconditionally. The
tool table is standard library and tested without it
(``test_mcp_tools.py``); what is left is the part only the SDK can judge --
whether every schema validates, whether every name is one the specification
allows, and whether a refusal arrives as a tool error rather than a success. A
file that skipped when the SDK was absent would be green in exactly the build
where that mattered, which is why ``checks/unit.nix`` puts ``mcp`` in the test
environment rather than making it optional.
The server runs in process, over the SDK's in-memory transport. The stdio
transport itself is proved end to end by ``checks/vm-mcp.nix`` and by the
handshake in the pull request description -- a pair of memory streams cannot
tell you that a stray ``print`` has corrupted stdout.
"""
from __future__ import annotations
import json
import os
import anyio
import jsonschema
import mcp.types as types
import mcp_fake
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, resources, server, tools
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
@pytest.fixture
def session():
"""`session(...)` -> (the recording CLI, a connected client session).
The stand-in is scripted per test, exactly as in the table's own tests;
what is added here is a real client on the other end of a real server, so
`initialize` and the two request types are exercised rather than asserted
about.
"""
def _session(toolsets=None, **script):
fake = mcp_fake.FakeCli(**script)
built = server.build(invoke.Runner(fake), toolsets)
return fake, create_connected_server_and_client_session(
built, raise_exceptions=True
)
return _session
def run(coroutine):
return anyio.run(coroutine)
# ── the handshake ──────────────────────────────────────────────────────────
def test_initialize_names_this_server_and_declares_tools(session):
_, connected = session()
async def go():
async with connected as client:
result = await client.initialize()
return result
initialized = run(go)
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
assert "`session_touch` is the ONLY" in initialized.instructions
def test_the_instructions_carry_both_rules():
assert "`session_touch` is the ONLY" in server.INSTRUCTIONS
assert "POINTER lease" in server.INSTRUCTIONS
assert "There is no keyboard lease" in server.INSTRUCTIONS
# And the two lease codes an agent has to tell apart.
assert "Exit 8 means" in server.INSTRUCTIONS
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 ────────────────────────────────────────────────────────────
def test_tools_list_returns_every_tool_with_a_title_and_a_description(session):
_, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.list_tools()
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
assert tool.annotations is not None
assert tool.annotations.openWorldHint is False
def test_every_tool_name_is_one_the_specification_allows():
for tool in tools.TOOLS:
result = validate_tool_name(tool.name)
assert result.is_valid, (tool.name, result.warnings)
# Warnings are not failures to the SDK, but a name that earns one is a
# name that will be mangled by some client.
assert result.warnings == [], (tool.name, result.warnings)
def test_every_input_schema_is_a_schema_the_validator_accepts():
"""The SDK validates every call against these; a bad one fails at call time."""
for tool in tools.TOOLS:
jsonschema.Draft202012Validator.check_schema(tool.schema)
def test_the_read_only_hint_is_set_from_the_verb_and_not_from_the_name():
for tool in tools.TOOLS:
described = server.describe(tool)
assert described.annotations.readOnlyHint == tool.read_only
if tool.read_only:
assert described.annotations.destructiveHint is None
else:
assert described.annotations.destructiveHint is tool.destructive
# ── the schemas, through the validator the server actually uses ────────────
def test_move_requires_exactly_one_of_to_and_by():
schema = tools.BY_NAME["pointer_move"].schema
jsonschema.validate({"id": "s", "lease": "L", "to": [0.5, 0.5]}, schema)
jsonschema.validate({"id": "s", "lease": "L", "by": [0.5, 0.5]}, schema)
for bad in (
{"id": "s", "lease": "L"},
{"id": "s", "lease": "L", "to": [0.5, 0.5], "by": [0.1, 0.1]},
{"id": "s", "lease": "L", "to": [0.5]},
{"id": "s", "lease": "L", "to": [0.5, 0.5, 0.5]},
):
with pytest.raises(jsonschema.ValidationError):
jsonschema.validate(bad, schema)
def test_home_and_ephemeral_home_are_refused_together_by_the_schema():
"""The CLI's mutually exclusive group, moved forward to where it is cheaper."""
schema = tools.BY_NAME["session_start"].schema
jsonschema.validate({"app": "foot"}, schema)
jsonschema.validate({"app": "foot", "home": "/tmp/h"}, schema)
jsonschema.validate({"app": "foot", "ephemeral_home": True}, schema)
with pytest.raises(jsonschema.ValidationError):
jsonschema.validate({"app": "foot", "home": "/tmp/h", "ephemeral_home": True}, schema)
def test_a_gesture_without_a_lease_is_refused_before_the_cli_is_run(session):
"""The lease is required, so the schema refuses and no argv is built."""
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("pointer_click", {"id": "s-1"})
result = run(go)
assert result.isError
assert "lease" in result.content[0].text
# The point of a schema refusal: the CLI was never reached.
assert fake.calls == []
# ── calls ──────────────────────────────────────────────────────────────────
def test_a_successful_call_carries_the_protocol_object_as_structured_content(session):
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_gc", {})
result = run(go)
assert not result.isError
assert result.structuredContent == reply
assert fake.calls == [["session", "gc", "--json"]]
def test_a_refused_call_arrives_as_a_tool_error_an_agent_can_read(session):
reply = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
_, connected = session(
stderr=json.dumps(reply, indent=2), exit_code=int(ExitCode.NO_LEASE)
)
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool(
"pointer_click", {"id": "s-1", "lease": "stale"}
)
result = run(go)
assert result.isError is True
assert result.structuredContent["exit_code"] == int(ExitCode.NO_LEASE)
text = result.content[0].text
assert "exit 9 (NO_LEASE)" in text
assert "pointer_acquire" in text
def test_a_frame_arrives_as_image_content_beside_its_geometry(session):
frame = mcp_fake.png(width=64, height=48)
_, connected = session(write_png=frame, stdout="/tmp/ignored.png\n")
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("shot", {})
result = run(go)
assert not result.isError
kinds = [block.type for block in result.content]
assert kinds == ["text", "image"]
text, image = result.content
assert "64x48 image/png" in text.text
assert image.mimeType == "image/png"
import base64
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."""
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("session_detonate", {})
result = run(go)
assert result.isError is True
assert "no such tool: 'session_detonate'" in result.content[0].text
assert "session_touch" in result.content[0].text
assert fake.calls == []
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_gc", {})
assert result.isError is True
assert result.structuredContent["exit_code"] == invoke.GENERIC_FAILURE
assert "the broker said something odd" in result.content[0].text
def test_the_transport_is_moved_off_the_descriptor_the_cli_prints_to():
"""The one thing an in-process CLI call could break, asserted directly."""
read_fd, write_fd = os.pipe()
saved_out, saved_err = os.dup(1), os.dup(2)
log_read, log_write = os.pipe()
try:
os.dup2(write_fd, 1)
os.dup2(log_write, 2)
_, stdout = server.claim_transport()
# After claiming, this process's own stdout is the log (fd 2), not the
# stream the client reads.
assert os.path.sameopenfile(1, 2)
assert not os.path.sameopenfile(1, stdout.wrapped.fileno())
# ...and stdin cannot eat a request.
assert os.readlink(f"/proc/self/fd/0") == os.devnull
finally:
os.dup2(saved_out, 1)
os.dup2(saved_err, 2)
for fd in (saved_out, saved_err, read_fd, write_fd, log_read, log_write):
try:
os.close(fd)
except OSError:
pass
def test_the_listing_is_what_the_entry_point_prints(capsys):
"""`--list-tools` is the package's own install check; keep it honest."""
assert server.main(["--list-tools"]) == 0
printed = capsys.readouterr().out.splitlines()
assert len(printed) == len(tools.TOOLS)
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"]
assert isinstance(blocks[0], types.TextContent)