Files
hyprland-headless-stream-pl…/nix/mcp.nix
T
HermenixandClaude Opus 5 549c73e8ae 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
2026-10-11 06:32:34 +00:00

98 lines
3.6 KiB
Nix

# `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";
};
}