feat(mcp)!: state as resources, acts as tools, and --toolsets for the rest
BREAKING: `status`, `session_list`, `session_status`, `session_logs` and
`pointer_state` are no longer tools. They are `hhstream://…` resources. 26
tools became 21, and eight resources appeared beside them.
The reason is the split the protocol itself draws, which the first cut ignored.
A resource is **application**-controlled context: the host decides what to put
in front of the model, and "what is on this machine right now" is the host's
question. A tool is **model**-controlled: an act the model chooses to perform.
Nothing in those five verbs acts. So the line between the halves is *who
decides*, not what a call costs.
hhstream://status text, the units and the frame socket
hhstream://sessions {?all} the broker's own list object
hhstream://pointer the lease holder, buttons and keys
hhstream://containers every container, plus the orphans
hhstream://screen a frame, as an image blob
hhstream://sessions/{id} {?events}
hhstream://sessions/{id}/logs {?lines}
hhstream://outputs/{name} one output's frame, as a blob
What did *not* move is the interesting part. `shot` and `record` stay tools
though neither changes the desktop: capturing is an act at a moment, and an
agent in a loop has to be able to decide to look *now* -- in many clients a
resource is something a person attaches rather than something a model can
fetch. The same frames are readable as `hhstream://screen` and
`hhstream://outputs/{name}` as well, for a host that wants one in context
itself. `session_container` stays a tool for a harder reason: with an id the
CLI runs `container.reconcile`, which writes the record back, so it is not a
read at all. Only the no-id listing is a resource. **A resource read must never
write**, and `resources.py` says so where it would be tempting.
Three consequences worth naming:
* A refusal cannot be content. `ReadResourceResult` has no `isError`, so a CLI
refusal is raised as `-32602` with the same remedy text in `message` and the
same `{ok, exit_code, error, reason, hint, remedy}` in `data`. Returning the
broker's failure object as the *body* would make "no such session" read as a
successful read of a session.
* Arguments become query parameters, and only declared ones are accepted -- for
the reason every tool schema sets `additionalProperties: false`. A parameter
silently ignored is a read that answered a different question.
* A v1 tool name is told where it went: `session_list` comes back with "It is a
RESOURCE now ... read hhstream://sessions instead". "No such tool" alone
reads as a broken server rather than a moved surface.
`--toolsets frames,sessions,pointer,keyboard` lands with it, because 21 flat
tools is the same problem one size smaller. There is **no grouping primitive in
MCP** -- `Tool` carries name, title, description, inputSchema, outputSchema,
icons, annotations, _meta and execution, and nowhere to put a family -- so the
only honest lever is which tools the *server* lists, chosen at launch. An
unknown name is argparse's exit 2, never a silently empty server, and a tool
outside the selection is unreachable rather than merely unlisted. Resources are
deliberately not filtered by it: they are the host's context, not the model's
budget.
`--list-resources` joins `--list-tools`; both are in the package's own
entry-point check, with `--toolsets` beside them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
1 parent
6a40c7e2e4
commit
0a63c9b7fc
6 files changed
+818
-197
No files matched your search
+27
-10
@@ -14,7 +14,7 @@
|
||||
# `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
|
||||
# `shot --output` and `record` are two of the twenty-one 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.
|
||||
@@ -63,19 +63,22 @@ python3.pkgs.buildPythonApplication {
|
||||
# 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.
|
||||
# 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` is the one code path that exercises argument parsing and the
|
||||
# whole table without opening stdio, so it is the honest smoke test.
|
||||
# `--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`
|
||||
@@ -84,9 +87,23 @@ python3.pkgs.buildPythonApplication {
|
||||
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
|
||||
tools=$($out/bin/hhstream-mcp --list-tools)
|
||||
echo "$tools"
|
||||
test "$(echo "$tools" | wc -l)" -eq 21
|
||||
|
||||
resources=$($out/bin/hhstream-mcp --list-resources)
|
||||
echo "$resources"
|
||||
test "$(echo "$resources" | wc -l)" -eq 8
|
||||
|
||||
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 = {
|
||||
|
||||
+9
-8
@@ -917,16 +917,17 @@ in {
|
||||
# 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.
|
||||
# A warning and not an assertion: eighteen of the twenty-one tools and six
|
||||
# of the eight resources 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 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.
|
||||
is off: the MCP server's session, pointer and keyboard tools, and every
|
||||
resource but hhstream://status and hhstream://screen, will fail because
|
||||
the broker is unreachable (exit 5). Only shot, record, run and those two
|
||||
resources will work.
|
||||
'';
|
||||
|
||||
# The broker's state directory and the moved socket directory are two
|
||||
|
||||
Reference in new issue
Block a user