diff --git a/flake.nix b/flake.nix index 5a30480..f645fa8 100644 --- a/flake.nix +++ b/flake.nix @@ -15,6 +15,12 @@ in { packages = forAllSystems (pkgs: rec { hhstream = pkgs.callPackage ./nix/package.nix {}; + # The MCP server. Its own derivation, not another entry point on + # `hhstream`: it depends on the `mcp` SDK and `hhstream` is stdlib-only by + # policy (nix/mcp.nix says why at length). `packages.hhstream` therefore + # keeps the closure it had, which is the property `checks.unit` and + # `nix build .#hhstream` are expected to hold. + hhstream-mcp = pkgs.callPackage ./nix/mcp.nix {inherit hhstream;}; default = hhstream; }); @@ -28,7 +34,9 @@ checks = forAllSystems' ({ pkgs, system }: import ./checks { inherit pkgs self system; }); - devShells = forAllSystems (pkgs: { + devShells = forAllSystems (pkgs: let + hhstream = pkgs.callPackage ./nix/package.nix {}; + in { default = pkgs.mkShell { packages = with pkgs; [ python3 @@ -44,7 +52,16 @@ # pywayland and xkbcommon, which `tests/pointer` imports directly -- # `test_keymap.py` compiles a real `us` keymap rather than stubbing # one, because a stub cannot tell you that `é` is unmappable. - (callPackage ./nix/package.nix { }) + hhstream + # The MCP server, so `hhstream-mcp` can be run (and handed to an MCP + # client) straight out of `nix develop`. + (callPackage ./nix/mcp.nix {inherit hhstream;}) + # The SDK itself, because `tests/unit/test_mcp_server.py` imports it + # directly: the tool table is stdlib-only and testable without it, but + # the wiring that turns the table into `mcp.types.Tool` objects is not, + # and a suite that could skip that file would stop noticing a schema + # the SDK rejects. + python3.pkgs.mcp # `websocket-client` drives Chromium over the DevTools protocol, which # is how the demo types into the page and reads the result back. python3.pkgs.websocket-client diff --git a/nix/mcp.nix b/nix/mcp.nix new file mode 100644 index 0000000..69a405a --- /dev/null +++ b/nix/mcp.nix @@ -0,0 +1,97 @@ +# `hhstream-mcp` -- the MCP server, as its own derivation. +# +# Separate from `nix/package.nix` on purpose, and the separation is the point: +# the frame socket, the CLI and the broker are stdlib-only by policy +# (`pyproject.toml`, `docs/CONTRACT-sessions.md` §6 rule 3), the MCP SDK is a +# third-party dependency, and `packages.hhstream` runs as the compositor's own +# units. So the dependency lives here, in a package nothing else imports, and +# `packages.hhstream` keeps the closure it had. +# +# `hhstream` is a *library* dependency here and not a binary one: the tools call +# `hhstream.cli`'s handlers in process (see that module's docstring), so what +# this package needs is the import path. `toPythonModule` is what makes an +# application's site-packages visible to a dependent, which a bare +# `buildPythonApplication` output is not. +# +# `grim` and `ffmpeg` do go on PATH, because the CLI itself spawns them -- +# `shot --output` and `record` are two of the twenty-six tools, and the server +# is launched by an MCP client whose PATH is not ours to predict. `--prefix` +# and not `--set`, so a deployment that wants its own ahead of these puts them +# on PATH and wins. +{ + lib, + python3, + hhstream, + grim, + ffmpeg, + makeWrapper, +}: +python3.pkgs.buildPythonApplication { + pname = "hhstream-mcp"; + version = "0.1.0"; + pyproject = true; + + # The package directory is the project root: its own pyproject.toml lives + # there and maps the package name onto `.`. See the comment in that file for + # why it is not at the repository root. + src = ../src/hhstream_mcp; + + build-system = [ python3.pkgs.setuptools ]; + + dependencies = [ + python3.pkgs.mcp + python3.pkgs.anyio + # An application is not importable by a dependent until this converts it, + # and `hhstream_mcp.invoke` imports `hhstream.cli` directly. + (python3.pkgs.toPythonModule hhstream) + ]; + + nativeBuildInputs = [ makeWrapper ]; + + makeWrapperArgs = [ + "--prefix" + "PATH" + ":" + "${lib.makeBinPath [ + grim + ffmpeg + ]}" + ]; + + # The suite lives in `tests/` at the repository root and runs in the flake's + # `checks.unit`, which is also where `mcp` reaches it. Same choice as + # nix/package.nix, for the same reason. + doCheck = false; + + # Cheap proof that the tool table builds and the SDK wiring imports: `tools` + # constructs all twenty-six at import time, and `server` is the only module + # that touches `mcp`. A missing SDK, a schema that is not a dict, or a tool + # named twice all fail here rather than at an agent's first call. + pythonImportsCheck = [ + "hhstream_mcp.tools" + "hhstream_mcp.server" + ]; + + # `pythonImportsCheck` proves the modules load; it does not prove the script + # Nix wrapped can run, and the script is what an MCP client spawns. + # `--list-tools` is the one code path that exercises argument parsing and the + # whole table without opening stdio, so it is the honest smoke test. + # + # A `postPhases` entry and not `postInstall`, because the script is wrapped in + # `fixupPhase`: run any earlier and it has no PYTHONPATH, so `import mcp` + # fails and the check tests the wrong thing. `installCheckPhase` is no use + # either -- `buildPythonPackage` does not include that phase at all. + postPhases = [ "entryPointCheckPhase" ]; + entryPointCheckPhase = '' + echo "checking the wrapped entry point..." + listed=$($out/bin/hhstream-mcp --list-tools) + echo "$listed" + test "$(echo "$listed" | wc -l)" -ge 26 + ''; + + meta = { + description = "Drive a headless Hyprland session over the Model Context Protocol"; + license = lib.licenses.mit; + mainProgram = "hhstream-mcp"; + }; +} diff --git a/nix/module.nix b/nix/module.nix index 4508f50..89056ec 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -772,6 +772,48 @@ in { ''; }; }; + + # The Model Context Protocol server -- `hhstream-mcp`, the `hhstream` CLI + # as typed tools, so an agent drives this desktop without shelling out. + # + # Its own top-level block rather than one under `sessions`, because it is + # not the broker's: four of its tools (`status`, `shot`, `record`, `run`) + # are frame-socket verbs that work with the broker switched off. It is also + # not a unit. The transport is stdio, one process per client, spawned by + # whichever client wants it -- so "installing" it means exactly putting the + # binary on PATH, and anything that started a daemon here would be + # inventing a second thing to supervise. + mcp = { + enable = lib.mkOption { + type = lib.types.bool; + default = false; + description = '' + Put `hhstream-mcp` on the system PATH, so an MCP client on this + machine can spawn it. + + Off by default, and deliberately not implied by + {option}`sessions.enable`: this is the surface through which a + language model starts applications, clicks and types on this desktop, + and whether that is wanted is a decision, not a consequence of the + broker being up. Installing it starts nothing — the server is stdio + and short-lived, spawned per client — and it grants no access the + `hhstream` CLI does not already grant to whoever runs it. + + The client configures the sockets through the CLI's own environment, + `HHSTREAM_SOCKET` and `HHSTREAM_FRAME_SOCKET`; see the README section + on registering it. + ''; + }; + + package = lib.mkOption { + type = lib.types.package; + description = '' + The MCP server package. Defaults to this flake's `hhstream-mcp`, + built against {option}`package` so the server and the CLI it drives + are the same build. + ''; + }; + }; }; config = lib.mkIf cfg.enable { @@ -863,6 +905,30 @@ in { services.hyprland-headless-stream.package = lib.mkDefault (pkgs.callPackage ./package.nix {}); + # Built against `cfg.package`, so the server and the CLI it runs are one + # build: the tools are argv lists against that CLI's parser, and a server + # paired with a different one would refuse flags for reasons no agent could + # read. `mkDefault` for the same reason as above. + services.hyprland-headless-stream.mcp.package = + lib.mkDefault (pkgs.callPackage ./mcp.nix { hhstream = cfg.package; }); + + # Installing it IS the whole of `mcp.enable`: the server is spawned by a + # client over stdio, so there is no unit, no socket and no state directory + # to declare. + environment.systemPackages = lib.mkIf cfg.mcp.enable [ cfg.mcp.package ]; + + # A warning and not an assertion: twenty-two of the twenty-six tools need + # the broker, and an agent handed them against a machine where it is off + # gets exit 5 from every one of them -- which is a true answer, badly + # timed. The four frame tools are genuinely useful on their own, so this is + # a thing worth saying rather than a thing worth refusing. + warnings = lib.optional (cfg.mcp.enable && !cfg.sessions.enable) '' + services.hyprland-headless-stream.mcp.enable is on while sessions.enable + is off: the MCP server's session, pointer and keyboard tools will all + fail with exit 5 (the broker is unreachable). Only status, shot, record + and run will work. + ''; + # The broker's state directory and the moved socket directory are two # different reasons to write a tmpfiles entry, and this option takes one # definition — so they are merged here rather than assigned twice (which