Files
hyprland-headless-stream-pl…/nix/mcp.nix
T
HermenixandClaude Opus 5 5f5726c02e feat(mcp): the stream, as two tools and two resources
The split mcp-v2 froze, applied to the stream: switching one on is an act, so
it is a tool; what is being published is state, so it is a resource. 23 tools
and 10 resources.

Tools: `session_stream_enable` (returns the URL, takes an optional `phrase` and
`fps`), `session_stream_disable`, and `session_start` gains `stream`,
`stream_phrase` and `stream_fps` -- the last because a stream needs the
container output that starting creates, so one call is the shape an agent
actually wants.

Resources: `hhstream://streams` (every stream, with `available` so "no streams"
is not confused with "no daemon") and `hhstream://sessions/{id}/stream`.

What the descriptions carry is the part that matters here, because an agent
reads them and nothing else:

* **CREDENTIAL.** The phrase in the URL is the stream's only protection. The
  resource descriptions say outright not to put the URL where a session's own
  screen can see it -- an agent that pastes it into the browser it is driving
  has published the desktop.
* **ACTIVITY.** The stream tools do *not* reset the idle clock, but a connected
  viewer does, which is the first exception to that rule this surface has had
  to state. `session_touch` is still the only thing an agent can do about it.
* `session_start`'s summary prints `stream url:` beside the id, and a stream
  that could not be opened is reported loudly as `stream: NOT enabled -- …`,
  because the call succeeded and an agent must not read that as a stream.

`nix/mcp.nix` counts the new surface in `entryPointCheckPhase` (23 and 10),
which is the only place those numbers are asserted against the *wrapped* binary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 22:48:45 +00:00

115 lines
4.2 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-three 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 both tables build and the SDK wiring imports: `tools` and
# `resources` construct every entry 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.resources"
"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` and `--list-resources` are the two code paths that exercise
# argument parsing and both whole tables without opening stdio, so together
# they are the honest smoke test. `--toolsets` is in it because a selection
# that silently served everything would be the failure nobody notices.
#
# 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..."
tools=$($out/bin/hhstream-mcp --list-tools)
echo "$tools"
test "$(echo "$tools" | wc -l)" -eq 23
resources=$($out/bin/hhstream-mcp --list-resources)
echo "$resources"
test "$(echo "$resources" | wc -l)" -eq 10
narrowed=$($out/bin/hhstream-mcp --list-tools --toolsets keyboard | wc -l)
echo "--toolsets keyboard offers $narrowed tools"
test "$narrowed" -eq 4
# An unknown toolset must be argparse's exit 2, not a server with no tools.
if $out/bin/hhstream-mcp --list-tools --toolsets nonsense; then
echo "an unknown toolset was accepted" >&2
exit 1
fi
'';
meta = {
description = "Drive a headless Hyprland session over the Model Context Protocol";
license = lib.licenses.mit;
mainProgram = "hhstream-mcp";
};
}