feat(nix): hhstream-mcp as its own derivation, and an option to install it
`packages.hhstream-mcp` (`nix/mcp.nix`), separate from `packages.hhstream` and the separation is the point: the frame socket, the CLI and the broker are stdlib-only by policy, the MCP SDK is a third-party dependency, and `packages.hhstream` runs as the compositor's own units. Verified: the hhstream closure gains no `mcp`, no `pydantic` and no `httpx`, and `hhstream_mcp` is not in its site-packages. The join to `hhstream` is a *library* one -- `toPythonModule`, because the tools call `hhstream.cli`'s handlers in process. `grim` and `ffmpeg` are prefixed onto the wrapper's PATH, because the CLI spawns them and the server is launched by an MCP client whose PATH is not ours to predict. The entry point is smoke-tested with `--list-tools` in a `postPhases` phase, not `postInstall`: the script is wrapped in `fixupPhase`, so any earlier and the check runs against a script with no PYTHONPATH and tests the wrong thing. (`installCheckPhase` is no use either -- `buildPythonPackage` does not include that phase at all.) `services.hyprland-headless-stream.mcp.enable` (default false) puts the binary on the system PATH, which is the whole of the option: the server is stdio and spawned per client, so there is no unit, no socket and no state directory. `mcp.package` defaults to this flake's build against `cfg.package`, so the server and the CLI it runs are one build. A warning, not an assertion, when it is enabled with `sessions.enable` off: 22 of the 26 tools then answer exit 5, but the four frame tools are genuinely useful alone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
1 parent
ca5e309e51
commit
549c73e8ae
3 files changed
+182
-2
No files matched your search
@@ -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
|
||||
|
||||
+97
@@ -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";
|
||||
};
|
||||
}
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user