feat(mcp): the hhstream CLI as Model Context Protocol tools

`hhstream_mcp` serves the whole `hhstream` surface -- the four frame verbs, the
ten session verbs, the eight pointer verbs and the four keyboard verbs -- as 26
MCP tools over stdio, so an agent drives this desktop through typed tools
instead of writing command lines.

It is a shim and nothing more. Each tool builds the argv list the CLI's own
parser takes, hands it to the CLI's own handler **in this process**, and maps
what came back. The idle clock, the pointer lease, the allowlist, the exit-code
table and every refusal message stay where they already were.

Four decisions worth stating, each argued at length where it lives:

* **One tool per verb**, not one per family with an `action` enum. The
  arguments do not rhyme, the two rules an agent gets wrong have to be on the
  tool it gets wrong, and `readOnlyHint` is a real per-verb distinction here --
  `session_container` with an id runs `container.reconcile`, so it is not
  marked read-only.
* **In process, not as a subprocess.** `hhstream.cli`'s parser already takes an
  argv list and its handlers already return a code from the frozen table. Two
  of its paths cannot be called here and both end in an `exec` that would
  replace this server: `main`'s `sg` re-exec, and `cmd_run`'s `execvpe`. The
  first is therefore unavailable and said out loud (`access_hint`); the second
  is why `run` goes through `posix_spawn` into its own session.
* **The transport leaves file descriptor 1.** The CLI prints, and `record`
  spawns an `ffmpeg` whose output it does not capture. `claim_transport` takes
  a private duplicate of stdin and stdout at start-up and points fd 1 at the
  log, so a stray write is a log line and never a corrupted JSON-RPC stream.
* **No state, and the lease is an argument.** The CLI caches a lease id between
  invocations because its surface is flagless; this passes `--lease` on every
  call and never reads that cache. A cached lease is a lease an agent cannot
  see.

Refusals come back as tool errors -- never as a success -- carrying the remedy
sentence, the CLI's own `error`/`reason`/`hint`, everything it said, and the
frozen exit code in `structuredContent`. Exits 8 and 9 are held apart by a
test, because an agent that sees 8 must wait and one that sees 9 must acquire.

The root pyproject excludes `hhstream_mcp*` from package discovery: without
that, `packages.hhstream` would ship a module whose first import line fails.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 06:32:23 +00:00
1 parent f3ac9ada27
commit ca5e309e51
8 files changed
+2265

No files matched your search

+9
View File
@@ -34,6 +34,15 @@ hhstream-live = "hhstream_live.__main__:main"
[tool.setuptools.packages.find]
where = ["src"]
# `hhstream_mcp` lives under src/ beside the others -- so the dev shell's
# PYTHONPATH reaches it and the tests import it the same way they import
# everything else -- but it is a *different distribution*
# (src/hhstream_mcp/pyproject.toml, built by nix/mcp.nix) because it depends on
# the MCP SDK. Without this exclusion `find` would sweep it into this wheel,
# and `packages.hhstream` would ship a module whose first import line fails:
# the dependency policy above would be intact and the package would still be
# broken.
exclude = ["hhstream_mcp*"]
# The phrase generator reads this at runtime, so it has to be *installed*, not
# just present in the checkout: a wheel (and the Nix build) that dropped it
+43
View File
@@ -0,0 +1,43 @@
"""``hhstream-mcp`` -- the ``hhstream`` CLI, as Model Context Protocol tools.
A **shim**, and deliberately the thinnest one that can be honest: every tool
builds the argv list the CLI's own parser takes, hands it to the CLI's own
handler *in this process*, and maps what came back. No behavioural rule lives
here. The idle clock, the pointer lease, the container policy, the allowlist,
the exit-code table and the refusal messages are all the CLI's and the broker's,
and this package's one job is to not get between an agent and them.
In process, and not as a subprocess: ``hhstream.cli`` is importable Python, its
``main`` already takes an argv list and returns an exit code from the frozen
table, and spawning a Python interpreter per tool call to re-parse arguments
this process just built would be paying for an isolation nobody asked for. The
seam that matters is the *argv list* -- the thing this layer actually decides --
and that is identical either way. :mod:`hhstream_mcp.invoke` says which two of
the CLI's paths cannot be called in process, and what is done about them.
Why a separate distribution from ``hhstream`` rather than one more entry point
in ``pyproject.toml``: the frame socket, the CLI and the broker are stdlib-only
by policy (``pyproject.toml``, ``docs/CONTRACT-sessions.md`` §6 rule 3), and the
MCP SDK is a third-party dependency. Growing ``packages.hhstream`` an ``mcp``
dependency to serve a shim would put that dependency on the compositor's own
units. So the code lives beside the others under ``src/`` -- the dev shell's
``PYTHONPATH`` reaches it for free -- and ``nix/mcp.nix`` builds it as its own
derivation, with its own pyproject, that *depends on* the ``hhstream`` package.
The interface is frozen in ``docs/CONTRACT-mcp.md``: the tool names, their
arguments, and which exit code arrives as which MCP error. The modules split
along the one line that matters for testing -- :mod:`hhstream_mcp.invoke`,
:mod:`hhstream_mcp.media` and :mod:`hhstream_mcp.tools` are standard library
only, so the argv each tool builds, the parsing of what the CLI printed and the
error mapping are all testable without the SDK and without a live socket. Only
:mod:`hhstream_mcp.server` imports ``mcp``.
"""
from __future__ import annotations
__version__ = "0.1.0"
#: What the server calls itself in the ``initialize`` handshake. The same name
#: an MCP client configuration block is expected to use for it, so a log line
#: and a config entry can be matched up by eye.
SERVER_NAME = "hhstream"
+8
View File
@@ -0,0 +1,8 @@
"""``python -m hhstream_mcp`` — the same entry point as the ``hhstream-mcp`` script."""
from __future__ import annotations
from .server import main
if __name__ == "__main__":
raise SystemExit(main())
+496
View File
@@ -0,0 +1,496 @@
"""Run the CLI's own functions, in this process. Standard library only.
No subprocess. A tool builds the same argv list the CLI's parser takes, this
module hands it to ``hhstream.cli``'s parser, runs the handler argparse
selected, and reports what that handler printed and returned. The behavioural
rules stay exactly where they were -- the idle clock, the lease, the exit-code
table, the allowlist and every refusal message are the CLI's and the broker's --
and what is saved is a process spawn per tool call and a ``PATH`` to get wrong.
**Why not ``hhstream.cli.main``.** Two of its paths end in an ``exec``, and in
a CLI that is correct while here it would replace the MCP server mid-session and
the client would see its connection die:
1. ``main`` calls ``ensure_access`` before the four frame verbs, which re-execs
the whole process through the setuid ``sg`` wrapper when the frame socket is
out of reach.
2. ``cmd_run`` ends in ``os.execvpe`` -- that *is* the verb. ``run`` therefore
forks first; see :meth:`Runner.launch`.
So the parser is the CLI's (``cli.build_parser``), the handler is the one
argparse selected, and the exit code is that handler's own return value. What
this module adds is the dispatch line between them, the capture, and the remedy
sentence per exit code.
**The one capability lost with the ``sg`` re-exec**, stated plainly because it
is a real difference from running the CLI: a process that cannot read the frame
socket does not recover here. ``shot`` and ``record`` fail with the CLI's own
message plus a hint, where the CLI would have rejoined the group and succeeded.
The remedy is to give the server the group in the first place -- see the README
section on registering it.
**Serialised.** The CLI prints to process-global ``sys.stdout``, so two
concurrent calls would interleave their output into each other's reply. One
lock around the whole call is the honest fix, and costs nothing a caller would
notice: the broker already serialises every mutation, and the CLI was one
process per verb anyway.
"""
from __future__ import annotations
import contextlib
import dataclasses
import io
import json
import os
import shutil
import sys
import tempfile
import threading
import time
import traceback
from typing import Any, Callable, Iterator
from hhstream import cli
from hhstreamd.protocol import ExitCode
#: Exit 1 is not in the frozen table: it is what the *frame* verbs return when
#: the publisher sent no frame or a tool they need is missing, and what this
#: module reports for an exception no handler caught.
GENERIC_FAILURE = 1
#: The three frame verbs' handlers, by the name the CLI's parser gives them.
#: `run` is deliberately absent -- it is the one that execs -- and the session
#: namespace needs no entry, because argparse sets `func` for it.
FRAME_VERBS: dict[str, Callable[[Any], int]] = {
"status": cli.cmd_status,
"shot": cli.cmd_shot,
"record": cli.cmd_record,
}
#: One CLI call at a time. See the module docstring.
_ONE_AT_A_TIME = threading.Lock()
@dataclasses.dataclass(frozen=True)
class Outcome:
"""One completed CLI call, exactly as it ended."""
argv: list[str]
returncode: int
stdout: str
stderr: str
@property
def ok(self) -> bool:
return self.returncode == 0
def payload(self) -> dict[str, Any] | None:
"""The protocol object a ``--json`` verb printed, wherever it printed it.
stdout on success and **stderr on failure** -- that is the CLI's own
split (``hhstream_session._finish``), not a guess: an error always goes
to stderr whatever the output mode, because that is what an agent
branches on. Both streams are searched in both cases anyway, because a
verb that grows a warning on the happy path should not take the parsing
with it.
"""
for text in (self.stdout, self.stderr):
found = first_json_object(text)
if found is not None:
return found
return None
def first_json_object(text: str) -> dict[str, Any] | None:
"""The first JSON *object* in ``text``, or ``None``.
A scan rather than ``json.loads`` on the whole stream: ``session start``
prints the bare id above its object, and a verb that one day prints a line
above one should not stop being parseable.
"""
decoder = json.JSONDecoder()
index = text.find("{")
while index != -1:
try:
value, _ = decoder.raw_decode(text, index)
except ValueError:
index = text.find("{", index + 1)
continue
if isinstance(value, dict):
return value
index = text.find("{", index + 1)
return None
# ── what each exit code means to an agent ──────────────────────────────────
#: The sentence a calling agent needs after a refusal: not what went wrong --
#: the CLI's own ``reason`` says that better than any table could -- but what to
#: do about it. Keyed by the frozen exit codes of
#: ``docs/CONTRACT-sessions.md`` §4, so a new code is a missing key here and
#: not a silently generic message.
REMEDY: dict[int, str] = {
ExitCode.USAGE: (
"The call was rejected before anything happened: an argument is "
"missing, malformed, or names something this build does not support. "
"Fix the arguments; retrying the same call will fail the same way."
),
ExitCode.NO_SUCH_SESSION: (
"No session (or process) by that id. Call `session_list` to see which "
"ids exist; a reaped session is gone and has to be started again."
),
ExitCode.BAD_STATE: (
"The session exists but is not in a state this verb can act on -- it "
"is still starting, or it has already exited, been killed or been "
"reaped. Call `session_status` to see which."
),
ExitCode.DAEMON_UNREACHABLE: (
"The session broker (`hhstreamd`) could not be reached on its control "
"socket. Nothing was done. This is an operator problem, not an "
"argument problem: the daemon is down, or $HHSTREAM_SOCKET points "
"somewhere else. Frame tools (`status`, `shot`, `record`, `run`) do "
"not need the broker and may still work."
),
ExitCode.POLICY: (
"Refused by policy. The application is not on the broker's allowlist, "
"or an argument is not one the allowlist permits, or a budget (session "
"cap, workspace band) is full. No retry will change it; this is a "
"configuration decision."
),
ExitCode.TIMEOUT: (
"The broker accepted the request and did not finish in time. Whether "
"it took effect is unknown -- read the state back (`session_status`, "
"`session_list`, `pointer_state`) before retrying, and retry with the "
"same `request_id` so a mutation cannot happen twice."
),
ExitCode.BUSY: (
"Something else holds what this call needs -- for the pointer and "
"keyboard verbs, another session holds the one pointer lease, and the "
"refusal names the holder. Nothing was injected. Call `pointer_state` "
"to see who holds it, then wait for them to release it or for its TTL "
"to expire. Do NOT try to take it from them; there is no such verb."
),
ExitCode.NO_LEASE: (
"This verb needs the pointer lease and this session does not hold one "
"(never acquired, already released, or expired -- an idle lease is "
"force-released by the broker). Call `pointer_acquire` for this "
"session and pass the `lease_id` it returns as `lease` on every "
"pointer and keyboard call. A lease id that was refused is dead; "
"acquire a new one rather than retrying with it."
),
ExitCode.COMPOSITOR: (
"The compositor or the input driver failed. **The session itself is "
"not lost** -- it keeps running in degraded mode -- so do not treat "
"this as a dead session. The compositor may be down, the container may "
"be gone, or the driver refused the request (an unmappable character, "
"a keysym this layout does not have)."
),
GENERIC_FAILURE: (
"The command failed without one of the broker's classified codes. For "
"the frame tools this is usually the publisher sending no frame (is the "
"compositor up? call `status`) or `grim`/`ffmpeg` missing from the "
"server's PATH. The text below is the CLI's own."
),
}
def remedy_for(returncode: int) -> str:
try:
name = ExitCode(returncode).name
except ValueError:
name = "UNCLASSIFIED"
advice = REMEDY.get(
returncode,
"The CLI exited with a code this server does not know. Treat it as a "
"failure and read the output below; do not assume anything happened.",
)
return f"exit {returncode} ({name}): {advice}"
# ── capture ────────────────────────────────────────────────────────────────
@contextlib.contextmanager
def captured() -> Iterator[tuple[io.StringIO, io.StringIO]]:
"""Redirect the CLI's ``print``s into a pair of buffers.
Python-level only, and that is enough **because the protocol is not on file
descriptor 1 any more**: :func:`hhstream_mcp.server.claim_transport` takes a
private duplicate of stdout at start-up and points fd 1 at the log. So a
stray write from a grandchild (``ffmpeg``, which the CLI does not capture)
lands in the server's log rather than in the client's stream, and this
context manager only has to collect what the handler itself printed.
"""
out, err = io.StringIO(), io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
yield out, err
def dispatch(argv: list[str]) -> int:
"""Parse ``argv`` with the CLI's own parser and run the handler it selects.
The CLI's ``main`` minus its two ``exec`` paths; see the module docstring.
"""
parser = cli.build_parser()
args = parser.parse_args(argv)
if args.command is None:
parser.print_help(sys.stderr)
return int(ExitCode.USAGE)
handler = FRAME_VERBS.get(args.command)
if handler is not None:
return int(handler(args))
# The session namespace: argparse already chose the handler when it parsed.
return int(getattr(args, "func")(args))
def access_hint(argv: list[str]) -> str:
"""The sentence the ``sg`` re-exec would otherwise have made unnecessary.
Added to a failure only when the diagnosis is actually true, and only for
the verbs it could be true of. The predicate is the CLI's own, asked about
the CLI's own resolved socket path; the verb list is the one ``cli.main``
guards, because the frame socket has nothing to do with why a session verb
failed and an explanation that does not apply is worse than none.
"""
try:
# Inside the capture, because an argv argparse refuses makes it print
# usage -- and this runs *after* the call, so that print would reach
# the log rather than the reply, saying the same thing twice in the
# wrong place.
with captured():
args = cli.build_parser().parse_args(argv)
if args.command not in FRAME_VERBS and args.command != "run":
return ""
socket_path = getattr(args, "frame_socket", None)
if socket_path and not cli.have_access(socket_path):
return (
f"\n\nThis process cannot read {socket_path}. The hhstream CLI "
"would have re-joined the compositor's group through the "
"setuid 'sg' wrapper at this point; this server cannot, "
"because that is an exec which would replace it and drop the "
"client's connection. Run it as a member of that group "
"instead -- `sg hhstream -c hhstream-mcp` in the client's "
"spawn command, or add the account to the group."
)
except SystemExit:
# A parse that fails here fails identically in the call itself, and
# that failure is the one worth reporting.
return ""
return ""
# ── the runner ─────────────────────────────────────────────────────────────
@dataclasses.dataclass(frozen=True)
class Spawned:
"""A process that was started and deliberately not waited for."""
argv: list[str]
pid: int
exited: bool
stdout: str
stderr: str
class Runner:
"""Calls the CLI. Holds the entry point and nothing else.
No lease, no session id, no last reply. The server is a shim
(``docs/CONTRACT-mcp.md`` §3), and the moment it remembers a lease an agent
can no longer see which lease its call used.
``entry`` exists so the tests can put a recorder where the CLI goes: what
this layer decides is the argv list, and a test that cannot see the argv
list is testing nothing. There is no second production value for it.
"""
def __init__(self, entry: Callable[[list[str]], int] | None = None) -> None:
self.entry = entry or dispatch
def run(self, argv: list[str]) -> Outcome:
"""One call, start to finish. Never raises for a CLI failure."""
with _ONE_AT_A_TIME:
with captured() as (out, err):
try:
code = int(self.entry(list(argv)))
except SystemExit as exc:
# argparse's own refusals, and the handlers' `sys.exit` for
# an unreachable compositor or a grim that is not there.
code = _exit_status(exc)
except BaseException: # noqa: BLE001 -- a CLI process would
# have died here with a traceback on stderr and status 1;
# reproducing that is more honest than letting it reach the
# protocol as a transport error.
traceback.print_exc(file=sys.stderr)
code = GENERIC_FAILURE
stdout, stderr = out.getvalue(), err.getvalue()
if code != 0:
stderr += access_hint(list(argv))
return Outcome(argv=list(argv), returncode=code, stdout=stdout, stderr=stderr)
def launch(self, command: list[str], *, settle: float) -> Spawned:
"""``run``: put an application on the screen and do not wait for it.
``cli.cmd_run`` is two lines -- the environment a Wayland client needs,
then ``os.execvpe`` -- and the second of them is why it cannot be
called here: it would turn this server into the application. So the
environment comes from the CLI's own
:func:`hhstream.cli.env_for_session` and the exec is done by
``posix_spawn``:
* ``posix_spawn`` and not ``fork`` because this runs on a worker thread.
A ``fork`` from a threaded process can inherit a lock another thread
was holding, and Python warns about exactly that; ``posix_spawn``
leaves no Python running between the clone and the exec.
* ``setsid`` puts the application in its own session, so a client that
kills this server's process group does not take the desktop with it.
That, plus not waiting, is what "launch and forget" means.
* The executable is resolved *here*, so "no such command" is a refusal
an agent can read rather than a child exiting 127 into a log.
* A reaper thread waits on the pid, so a long-lived application that
eventually exits does not sit in this process's table as a zombie.
"""
# The frame socket the CLI would have resolved -- its flag default, or
# $HHSTREAM_FRAME_SOCKET -- read out of its own parser rather than
# re-derived, because `run` takes the compositor's runtime directory
# from it and a second opinion about that path is a second bug.
frame_socket = cli.build_parser().parse_args(["status"]).frame_socket
runtime_dir = os.path.dirname(frame_socket)
try:
environment = dict(os.environ)
environment.update(cli.env_for_session(runtime_dir))
except SystemExit as exc:
# `env_for_session` refuses with `sys.exit(message)` when the
# compositor has bound no Wayland socket. The message is the CLI's
# own and is handed on verbatim.
return Spawned(
argv=command, pid=0, exited=True, stdout="", stderr=str(exc.code)
)
resolved = shutil.which(command[0], path=environment.get("PATH"))
if resolved is None:
return Spawned(
argv=command,
pid=0,
exited=True,
stdout="",
stderr=f"hhstream-mcp: no executable {command[0]!r} on PATH",
)
return _spawn_detached(resolved, command, environment, settle)
def _exit_status(exc: SystemExit) -> int:
"""``SystemExit`` as a status. A message is status 1, as in a real process."""
if exc.code is None:
return 0
if isinstance(exc.code, int):
return exc.code
return GENERIC_FAILURE
def _spawn_detached(
resolved: str, command: list[str], environment: dict[str, str], settle: float
) -> Spawned:
"""Start the application in its own session and report its pid."""
with tempfile.TemporaryDirectory(prefix="hhstream-mcp-run-") as scratch:
capture = os.path.join(scratch, "output")
# Its stdin must not be the protocol stream, and its first complaint is
# worth handing back to the agent rather than mixing into the server's
# log -- so both of its output descriptors go to one file, which this
# directory takes away afterwards. An application that keeps writing
# writes to a deleted inode and leaves nothing behind.
file_actions = [
(os.POSIX_SPAWN_OPEN, 0, os.devnull, os.O_RDONLY, 0o666),
(
os.POSIX_SPAWN_OPEN,
1,
capture,
os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
0o600,
),
(os.POSIX_SPAWN_DUP2, 1, 2),
]
pid = os.posix_spawn(
resolved, command, environment, file_actions=file_actions, setsid=True
)
exited = _watch(pid, settle)
if not exited:
_reap_later(pid)
try:
with open(capture, encoding="utf-8", errors="replace") as fh:
said = fh.read()
except OSError: # pragma: no cover -- the spawn created it
said = ""
return Spawned(
argv=command,
pid=pid,
exited=exited,
stdout="" if exited else said,
stderr=said if exited else "",
)
#: How often to look at a launched process while the settle window runs.
_WATCH_INTERVAL_S = 0.05
def _watch(pid: int, settle: float) -> bool:
"""``True`` if the process is gone before ``settle`` seconds are up.
``waitpid`` with ``WNOHANG``, so an application that fails at once is both
detected and reaped here.
"""
deadline = time.monotonic() + max(0.0, settle)
while True:
try:
reaped, _ = os.waitpid(pid, os.WNOHANG)
except ChildProcessError: # pragma: no cover -- already reaped
return True
if reaped == pid:
return True
if time.monotonic() >= deadline:
return False
time.sleep(_WATCH_INTERVAL_S)
def _reap_later(pid: int) -> None:
"""Wait on a surviving application, on a thread that does nothing else.
Without this the application sits in this process's table as a zombie from
the moment it exits until the server does. A thread blocked in ``waitpid``
is the cheapest way to not have that, and a daemon one so it never delays
shutdown.
"""
def wait() -> None:
try:
os.waitpid(pid, 0)
except (ChildProcessError, OSError): # pragma: no cover
pass
threading.Thread(target=wait, name=f"hhstream-mcp-reap-{pid}", daemon=True).start()
def temp_name(prefix: str, suffix: str) -> str:
"""A unique filename for an artefact, in the system temporary directory.
Used for ``record``'s default destination, which is the one artefact a tool
hands back by *path*: it has to outlive the call, so it cannot live in a
directory this process cleans up.
"""
directory = os.path.join(tempfile.gettempdir(), "hhstream-mcp")
os.makedirs(directory, exist_ok=True)
stamp = time.strftime("%Y%m%d-%H%M%S")
return os.path.join(directory, f"{prefix}-{stamp}-{os.getpid()}{suffix}")
+115
View File
@@ -0,0 +1,115 @@
"""Read back what ``shot`` and ``record`` produced. Standard library only.
Two small readers, and both are deliberately readers rather than deciders.
``shot`` writes a file and prints its path; ``record`` writes an mp4 and prints
the path with the rate it measured. The geometry and the rate are facts those
artefacts already carry, and an agent that gets a picture without its
dimensions has to guess at the coordinate space it is about to aim the pointer
in -- so they are parsed out and put in the text part of the reply.
Nothing here re-derives anything the CLI decided. The frame rate is the CLI's
own measured number, read off its output; the dimensions come from the image's
header, not from the configured output size, because the configured size is
what the compositor was *asked* for.
"""
from __future__ import annotations
import dataclasses
import re
import struct
PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
JPEG_MAGIC = b"\xff\xd8"
#: The SOFn markers that carry a JPEG's dimensions. Everything except DHT
#: (c4), DAC (cc) and the RSTn range (d0-d7), which share the 0xffc_ block.
_JPEG_SOF = {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
@dataclasses.dataclass(frozen=True)
class Image:
media_type: str
width: int
height: int
size: int
def sniff(data: bytes) -> Image | None:
"""The media type and pixel size of one captured frame, or ``None``.
By magic bytes and not by the extension this server asked for. The frame
socket publishes whatever format the module configured -- ``image/png`` by
default, ``image/jpeg`` on the deployment machine -- and ``hhstream shot``
writes the payload it was given to the ``--out`` path verbatim, so a file
called ``.png`` holds a JPEG whenever the publisher is serving one. An
agent told the wrong media type gets an image its client cannot decode.
"""
if data.startswith(PNG_MAGIC):
return _png(data)
if data.startswith(JPEG_MAGIC):
return _jpeg(data)
return None
def _png(data: bytes) -> Image | None:
# IHDR is required to be the first chunk: 8 bytes of signature, a 4-byte
# length, the type, then width and height.
if len(data) < 24 or data[12:16] != b"IHDR":
return None
width, height = struct.unpack(">II", data[16:24])
return Image("image/png", width, height, len(data))
def _jpeg(data: bytes) -> Image | None:
index = 2
end = len(data)
while index + 3 < end:
if data[index] != 0xFF:
index += 1
continue
marker = data[index + 1]
if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
index += 2
continue
if marker == 0xD9 or marker == 0xDA: # end of image, or start of scan
return None
(length,) = struct.unpack(">H", data[index + 2 : index + 4])
if marker in _JPEG_SOF:
if index + 9 > end:
return None
height, width = struct.unpack(">HH", data[index + 5 : index + 9])
return Image("image/jpeg", width, height, len(data))
index += 2 + length
return None
#: What ``hhstream record`` prints on success, which is the only place the
#: *measured* rate exists: a software-rendered compositor tops out well under
#: the advertised fps, so the encoded rate is the one it counted, and an agent
#: reading the mp4 later cannot recover how long the capture actually took.
RECORD_LINE = re.compile(
r"^(?P<path>.+?) \((?P<frames>\d+) frames in (?P<seconds>[\d.]+)s -> (?P<fps>\d+) fps\)\s*$",
re.MULTILINE,
)
@dataclasses.dataclass(frozen=True)
class Recording:
path: str
frames: int
seconds: float
fps: int
def recording(stdout: str) -> Recording | None:
match = RECORD_LINE.search(stdout)
if match is None:
return None
return Recording(
path=match["path"],
frames=int(match["frames"]),
seconds=float(match["seconds"]),
fps=int(match["fps"]),
)
+46
View File
@@ -0,0 +1,46 @@
# The second distribution in this repository, and the only one with a
# third-party runtime dependency.
#
# It sits *inside* the package directory rather than at the repository root
# because the root `pyproject.toml` is `hhstream`'s and a project has one. The
# alternatives were worse: a second source tree would duplicate nothing but a
# directory level, and adding `hhstream-mcp` to the root project would put the
# `mcp` dependency on the compositor's own units -- which is the one thing
# `docs/CONTRACT-sessions.md` §6 rule 3 and the root pyproject's own comment
# forbid. The root project excludes `hhstream_mcp*` from its package discovery
# for the same reason; see the note there.
#
# `package-dir` maps the package name onto this directory, so the layout stays
# `src/hhstream_mcp/` -- which is what puts it on the dev shell's
# `PYTHONPATH=$PWD/src` beside every other package here, with no second path to
# set and no second place for a test to import from.
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "hhstream-mcp"
version = "0.1.0"
description = "Drive a headless Hyprland session over the Model Context Protocol"
requires-python = ">=3.11"
# `mcp` is the official Python SDK and the whole reason this is a separate
# distribution. `anyio` is declared rather than taken for granted through the
# SDK: `server.py` calls `anyio.run` and `anyio.to_thread` directly, and a
# dependency used by name belongs in the metadata.
#
# `hhstream` is NOT listed, and it is not optional either: this package imports
# `hhstream.cli`, `hhstreamd.protocol` and `hhstream_session` and does not work
# without them. It is absent because `hhstream` is not a wheel anyone installs
# from an index -- it is this repository's other derivation, and `nix/mcp.nix`
# is where the two are joined. A dependency naming a version nobody can
# resolve would be worse than the comment you are reading.
dependencies = ["mcp>=1.9", "anyio>=4"]
[project.scripts]
# Stdio only. One process per client, spawned by the client; no port, no daemon.
hhstream-mcp = "hhstream_mcp.server:main"
[tool.setuptools]
packages = ["hhstream_mcp"]
package-dir = { "hhstream_mcp" = "." }
+285
View File
@@ -0,0 +1,285 @@
"""The MCP wiring. The only module here that imports the SDK.
Transport is **stdio** and nothing else: one process per client, spawned by the
client, no port and no daemon. There is already a daemon in this system
(`hhstreamd`) and it owns all the state; a second long-lived process in front of
it would be a second place for a lease to be remembered.
The low-level :class:`mcp.server.Server` rather than FastMCP, for two reasons.
The schemas here are written by hand -- ``pointer_move``'s exclusive ``to``/``by``
pair, ``additionalProperties: false`` on every tool -- and deriving them from
Python type hints would mean writing the signatures that happen to produce them.
And ``shot`` returns image content beside its text, which is a content list, not
a return value.
**The transport does not stay on file descriptor 1**, and that is load-bearing
rather than tidy: the tools run the CLI's handlers *in this process*
(:mod:`hhstream_mcp.invoke`), those handlers ``print``, and ``record`` spawns an
``ffmpeg`` whose output the CLI does not capture. Any one of those writing on
fd 1 would put a line of prose in the middle of a JSON-RPC stream, which a
client reports as a parse failure with no hint of where it came from. So
:func:`claim_transport` takes a private duplicate of stdin and stdout before
anything else runs and then points fd 1 at the log and fd 0 at ``/dev/null``.
After that the protocol is on descriptors nothing else in the process knows
about, and a stray write is a log line.
"""
from __future__ import annotations
import argparse
import io
import logging
import os
import sys
from typing import Any
import anyio
import mcp.types as types
from mcp.server.lowlevel import NotificationOptions, Server
from mcp.server.stdio import stdio_server
from . import SERVER_NAME, __version__, tools
from .invoke import Runner
log = logging.getLogger("hhstream.mcp")
#: Shown by a client that surfaces server instructions, and the one place the
#: whole surface can be introduced at once. The two rules are repeated on the
#: individual tools, because a per-tool description is what a client shows at
#: the point of use.
INSTRUCTIONS = """\
Drive this machine's headless Hyprland desktop: look at it, put applications on
it, and aim its one pointer and keyboard at them.
Each tool is one verb of the `hhstream` CLI and does nothing the CLI would not.
Where to start: `status` says whether the desktop is up; `session_start` puts an
allowlisted application on it and returns a session id; `shot` shows you the
screen; `pointer_acquire` gives you the lease that every pointer and keyboard
tool needs.
Two rules this surface will not let you avoid, because they are the two an agent
gets wrong:
1. `session_touch` is the ONLY thing that resets a session's idle clock.
Listing, reading status, reading logs, collecting garbage, clicking and
typing all deliberately do NOT. A session being driven is still a session
nobody has said they want kept, and the broker reaps it on schedule.
2. Every keyboard tool needs the POINTER lease, and holds only while that lease
holds. There is no keyboard lease: one compositor seat means one keyboard
focus. A held non-modifier key floods the window until you lift it or the
lease expires, because the application does the repeating.
Failures come back as tool errors carrying the CLI's own exit code, its
machine-readable error name, its reason and what to do next. Exit 8 means
another session holds the pointer lease (`pointer_state` names the holder); exit
9 means you need to acquire one.
"""
def annotations_for(tool: tools.Tool) -> types.ToolAnnotations:
"""Hints, and only honest ones.
``readOnlyHint`` is set from the verb's own behaviour, which is why
``session_container`` does not get it: with a session id that verb runs
``container.reconcile`` and writes the record back. ``openWorldHint`` is
false throughout -- the world here is one desktop on one machine.
"""
return types.ToolAnnotations(
title=tool.title,
readOnlyHint=tool.read_only,
# Meaningful only when `readOnlyHint` is false, and then stated rather
# than left out: the spec's default for it is *true*, so omitting it
# would mark `session_touch` and `record` as possibly destructive.
destructiveHint=None if tool.read_only else tool.destructive,
openWorldHint=False,
)
def describe(tool: tools.Tool) -> types.Tool:
return types.Tool(
name=tool.name,
title=tool.title,
description=tool.description,
inputSchema=tool.schema,
annotations=annotations_for(tool),
)
def listing() -> list[types.Tool]:
return [describe(tool) for tool in tools.TOOLS]
def content_for(result: tools.Result) -> list[types.ContentBlock]:
blocks: list[types.ContentBlock] = [types.TextContent(type="text", text=result.text)]
if result.image is not None and result.media_type:
import base64
blocks.append(
types.ImageContent(
type="image",
data=base64.b64encode(result.image).decode("ascii"),
mimeType=result.media_type,
)
)
return blocks
def call(runner: Runner, name: str, arguments: dict[str, Any]) -> types.CallToolResult:
"""Run one tool. A refusal comes back as a tool error, never as a success.
``isError`` rather than a JSON-RPC error, throughout. That is not only a
preference: the SDK's own ``call_tool`` handler catches whatever this raises
and turns it into an ``isError`` result anyway, and for the CLI's refusals
it is the right channel regardless -- "another session holds the lease" is
something the calling agent has to read and act on, and a JSON-RPC error
reaches the client's log rather than the agent. So the error text is
written for the agent, including for the two cases that are not the CLI's
verdict at all: a tool name that does not exist, and this layer's own bug.
"""
tool = tools.BY_NAME.get(name)
if tool is None:
return types.CallToolResult(
content=[
types.TextContent(
type="text",
text=(
f"no such tool: {name!r}. This server exposes: "
f"{', '.join(sorted(tools.BY_NAME))}"
),
)
],
structuredContent={"ok": False, "error": "no_such_tool"},
isError=True,
)
try:
result = tool.invoke(runner, arguments)
except (OSError, ValueError, KeyError) as exc:
# `Runner.run` already turns a handler's own exception into exit 1 with
# its traceback, so what reaches here is this layer's own fault -- a
# schema and an argv builder that disagree about a field name. Reported
# to the agent rather than only logged, because an agent that is told
# nothing retries forever.
log.exception("tool %s failed", name)
result = tools.Result(
text=f"the {name} tool failed before the CLI was called: {exc!r}",
data={"ok": False, "error": "tool_failed"},
is_error=True,
)
return types.CallToolResult(
content=content_for(result),
structuredContent=result.data,
isError=result.is_error,
)
def build(runner: Runner) -> Server:
server: Server = Server(
SERVER_NAME, version=__version__, instructions=INSTRUCTIONS
)
@server.list_tools()
async def _list() -> list[types.Tool]:
return listing()
# `validate_input` left on: the schemas are the first refusal, and they
# refuse before an argv list exists.
@server.call_tool()
async def _call(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
# The CLI call is blocking and can take seconds (`record`, a `start`
# with a readiness budget), so it goes to a worker thread: the event
# loop stays free to answer a ping and to read the next request. The
# calls themselves are serialised inside `Runner.run`, because the CLI
# prints to a stdout this process shares.
return await anyio.to_thread.run_sync(lambda: call(runner, name, arguments))
return server
def claim_transport() -> tuple[Any, Any]:
"""Take stdin and stdout for the protocol, then make fd 0 and 1 harmless.
Returns the pair of streams to hand to ``stdio_server``. After this call
the process's own ``sys.stdout`` writes to the log beside ``sys.stderr``,
and nothing that reads stdin can eat a request: both are the right answer
for a server whose tools run a CLI in-process.
"""
stdin = anyio.wrap_file(
io.TextIOWrapper(os.fdopen(os.dup(0), "rb"), encoding="utf-8", errors="replace")
)
stdout = anyio.wrap_file(
io.TextIOWrapper(os.fdopen(os.dup(1), "wb"), encoding="utf-8")
)
sys.stdout.flush()
# The literal descriptor 2, not `sys.stderr.fileno()`: what is wanted is
# "whatever the log is at the file-descriptor level", so that a grandchild
# which never heard of `sys` writes there too.
os.dup2(2, 1)
null = os.open(os.devnull, os.O_RDONLY)
try:
os.dup2(null, 0)
finally:
os.close(null)
return stdin, stdout
async def serve(server: Server, transport: tuple[Any, Any] | None = None) -> None:
stdin, stdout = transport if transport is not None else claim_transport()
async with stdio_server(stdin, stdout) as (read_stream, write_stream):
await server.run(
read_stream,
write_stream,
server.create_initialization_options(NotificationOptions()),
)
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="hhstream-mcp",
description=(
"Serve the hhstream CLI as Model Context Protocol tools over stdio. "
"Spawned by an MCP client; it speaks JSON-RPC on stdin/stdout and "
"logs to stderr."
),
epilog=(
"There is no --socket flag here, deliberately: the sockets are the "
"CLI's own environment -- $HHSTREAM_FRAME_SOCKET for the frame "
"socket and $HHSTREAM_SOCKET for the broker's control socket -- and "
"a second place to configure them is a second place for them to "
"disagree. Set them in the MCP client's `env` block."
),
)
parser.add_argument(
"--list-tools",
action="store_true",
help="print the tool names and exit, without serving. For checking an install.",
)
return parser
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
# stderr, never stdout: stdout is the transport, and one stray print on it
# is a protocol error the client reports as a parse failure.
logging.basicConfig(
level=os.environ.get("HHSTREAM_MCP_LOG", "WARNING").upper(),
stream=sys.stderr,
format="%(levelname)s %(name)s: %(message)s",
)
if args.list_tools:
for tool in tools.TOOLS:
print(f"{tool.name}\t{tool.title}")
return 0
log.info("serving %d tools over stdio", len(tools.TOOLS))
# The transport is claimed before the event loop starts, so no coroutine can
# have written to fd 1 by the time it moves.
transport = claim_transport()
anyio.run(serve, build(Runner()), transport)
return 0
if __name__ == "__main__": # pragma: no cover
raise SystemExit(main())
File diff suppressed because it is too large. Load diff