"""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 hhstream_mcp import SERVER_NAME, __version__, invoke, 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(**script): fake = mcp_fake.FakeCli(**script) built = server.build(invoke.Runner(fake)) 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 # 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 # ── 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) 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, "sessions": []} 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", {}) result = run(go) assert not result.isError assert result.structuredContent == reply assert fake.calls == [["session", "list", "--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_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_list", {}) 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_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)