quickshell-mcp 2.3.0__tar.gz → 2.4.0__tar.gz

{quickshell_mcp-2.3.0 → quickshell_mcp-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickshell-mcp
-Version: 2.3.0
+Version: 2.4.0
 Summary: MCP server that fetches live Quickshell docs from quickshell.org so the model reads real, current docs instead of hallucinating.
 Project-URL: Homepage, https://github.com/franklinnolasco7/quickshell-mcp
 Project-URL: Repository, https://github.com/franklinnolasco7/quickshell-mcp

{quickshell_mcp-2.3.0 → quickshell_mcp-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quickshell-mcp"
-version = "2.3.0"
+version = "2.4.0"
 description = "MCP server that fetches live Quickshell docs from quickshell.org so the model reads real, current docs instead of hallucinating."
 readme = "README.md"
 requires-python = ">=3.10"

{quickshell_mcp-2.3.0 → quickshell_mcp-2.4.0}/quickshell_mcp/capabilities/assistant.py

@@ -26,4 +26,5 @@ CAPABILITY_DEPENDS_ON = (
     "debugging",
     "project",
     "runtime",
+    "inspection",
 )

quickshell_mcp-2.4.0/quickshell_mcp/capabilities/inspection.py

@@ -0,0 +1,38 @@
+"""The inspection capability: read and drive the live UI of a managed runtime
+session.
+
+Read-only by default (windows, screenshots, ui_tree, ui_find, ui_get_property,
+screenshot_diff). ui_set_property and ui_invoke are mutating; ui_eval is
+high-risk. All operate on a managed runtime session, never on unrelated
+user processes.
+
+Depends on: knowledge, project, runtime.
+"""
+
+from __future__ import annotations
+
+from ..sources.ui_runtime import (  # noqa: F401
+    _screenshot,
+    _screenshot_diff,
+    _ui_eval,
+    _ui_find,
+    _ui_get_property,
+    _ui_invoke,
+    _ui_set_property,
+    _ui_tree,
+    _ui_windows,
+)
+
+CAPABILITY_NAME = "inspection"
+CAPABILITY_TOOLS = (
+    "quickshell_windows",
+    "quickshell_screenshot",
+    "quickshell_screenshot_diff",
+    "quickshell_ui_tree",
+    "quickshell_ui_find",
+    "quickshell_ui_get_property",
+    "quickshell_ui_set_property",
+    "quickshell_ui_invoke",
+    "quickshell_ui_eval",
+)
+CAPABILITY_DEPENDS_ON = ("knowledge", "project", "runtime")

{quickshell_mcp-2.3.0 → quickshell_mcp-2.4.0}/quickshell_mcp/capabilities/registry.py

@@ -29,6 +29,7 @@ from . import (
     assistant,
     debugging,
     generation,
+    inspection,
     knowledge,
     migration,
     project,
@@ -67,6 +68,9 @@ _MUTATING_CAPABILITIES = ("runtime", "testing")
 # capability's default safety level.
 _TOOL_SAFETY_LEVELS: dict[str, str] = {
     "quickshell_apply_patch": "mutating",
+    "quickshell_ui_set_property": "mutating",
+    "quickshell_ui_invoke": "mutating",
+    "quickshell_ui_eval": "high-risk",
 }
 
 
@@ -82,6 +86,7 @@ _CAPABILITY_MODULES = (
     debugging,
     project,
     runtime,
+    inspection,
     assistant,
 )
 
@@ -103,7 +108,7 @@ PLANNED_CAPABILITIES: dict[str, Capability] = {
         status="planned",
         safety_level=_safety_level(name),
     )
-    for name in ("inspection", "testing", "performance")
+    for name in ("testing", "performance")
 }
 
 ALL_CAPABILITIES: dict[str, Capability] = {**CAPABILITIES, **PLANNED_CAPABILITIES}

{quickshell_mcp-2.3.0 → quickshell_mcp-2.4.0}/quickshell_mcp/server.py

@@ -61,6 +61,17 @@ from .capabilities.generation import (  # noqa: F401
     _refactor,
     _style_match,
 )
+from .capabilities.inspection import (  # noqa: F401
+    _screenshot,
+    _screenshot_diff,
+    _ui_eval,
+    _ui_find,
+    _ui_get_property,
+    _ui_invoke,
+    _ui_set_property,
+    _ui_tree,
+    _ui_windows,
+)
 from .capabilities.knowledge import (  # noqa: F401
     _GITHUB_API,
     _IMPL_QUERY_STOPWORDS,
@@ -1122,6 +1133,97 @@ def quickshell_runtime_ping(session_id: str) -> dict:
     return _ping(session)
 
 
+@mcp.tool()
+def quickshell_windows(session_id: str) -> dict:
+    """Enumerate windows/surfaces belonging to a managed Quickshell runtime
+    session. Read-only. Requires a compositor adapter; when unavailable
+    returns an empty list with an explanatory note (never fails)."""
+    _record_tool("quickshell_windows")
+    return _ui_windows(session_id)
+
+
+@mcp.tool()
+def quickshell_screenshot(session_id: str) -> dict:
+    """Capture a screenshot from a managed Quickshell runtime session.
+
+    Requires the ``grim`` compositor screenshot tool on PATH. Returns the
+    image path or an "unavailable" note. Read-only."""
+    _record_tool("quickshell_screenshot")
+    return _screenshot(session_id)
+
+
+@mcp.tool()
+def quickshell_screenshot_diff(baseline: str, actual: str, output: str | None = None) -> dict:
+    """Compare two runtime screenshots with ImageMagick ``compare``.
+
+    Returns whether they differ, the diff image path, and a metric.
+    Deterministic for CI. Read-only."""
+    _record_tool("quickshell_screenshot_diff")
+    return _screenshot_diff(baseline, actual, output=output)
+
+
+@mcp.tool()
+def quickshell_ui_tree(session_id: str, depth: int = 3) -> dict:
+    """Inspect the live QML object tree of a managed runtime session.
+
+    Returns a compact, depth-limited hierarchy from the injected
+    'inspector' IpcHandler target. Read-only."""
+    _record_tool("quickshell_ui_tree")
+    return _ui_tree(session_id, depth=depth)
+
+
+@mcp.tool()
+def quickshell_ui_find(session_id: str, query: str) -> dict:
+    """Search the live QML object tree of a managed runtime session by name,
+    type, text, or property. Returns stable references for later runtime
+    tools. Read-only."""
+    _record_tool("quickshell_ui_find")
+    return _ui_find(session_id, query)
+
+
+@mcp.tool()
+def quickshell_ui_get_property(session_id: str, target: str, property_name: str) -> dict:
+    """Read a live QML property value from a managed runtime object via
+    ``qs ipc prop get``. Validates the object/property exist. Read-only."""
+    _record_tool("quickshell_ui_get_property")
+    return _ui_get_property(session_id, target, property_name)
+
+
+@mcp.tool()
+def quickshell_ui_set_property(
+    session_id: str, target: str, property_name: str, value: str
+) -> dict:
+    """Set a live QML property on a managed runtime object. Mutating.
+
+    Requires an explicit runtime session, validates the property exists,
+    returns the old and new values, and never modifies project files."""
+    _record_tool("quickshell_ui_set_property")
+    return _ui_set_property(session_id, target, property_name, value)
+
+
+@mcp.tool()
+def quickshell_ui_invoke(
+    session_id: str, target: str, method: str, arguments: list[str] | None = None
+) -> dict:
+    """Invoke a QML method on a managed runtime object via ``qs ipc call``.
+    Mutating. Validates the method and arguments; enforces runtime session
+    boundaries; no arbitrary process/system calls."""
+    _record_tool("quickshell_ui_invoke")
+    return _ui_invoke(session_id, target, method, arguments=arguments)
+
+
+@mcp.tool()
+def quickshell_ui_eval(session_id: str, js_code: str, timeout: int = 5) -> dict:
+    """HIGH-RISK: evaluate QML/JavaScript in a managed runtime session.
+
+    Explicitly opt-in, session-scoped, with an execution timeout and output
+    limits. No filesystem or process access is granted. Prefer
+    quickshell_ui_get_property / quickshell_ui_invoke for controlled reads
+    and calls."""
+    _record_tool("quickshell_ui_eval")
+    return _ui_eval(session_id, js_code, timeout=timeout)
+
+
 @mcp.tool()
 def quickshell_stats() -> dict:
     """Report session usage stats for this MCP server: per-tool call counts,

quickshell_mcp-2.4.0/quickshell_mcp/sources/ui_runtime.py

@@ -0,0 +1,277 @@
+"""UI runtime inspection tools: read, write, and invoke QML object properties
+and methods on a managed Quickshell session via ``qs ipc`` and the injected
+IpcHandler target.
+
+Screenshot tools detect ``grim`` and ImageMagick ``compare`` at runtime and
+report "unavailable" when missing.  UI tree and find go through the injected
+IpcHandler's introspection methods.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .runtime_session import _SESSION_REGISTRY, _qs_binary
+
+
+def _ipc_cmd(pid: int, *args: str) -> list[str]:
+    """Build a ``qs ipc`` command targeting a specific PID."""
+    return [_qs_binary(), "ipc", "--pid", str(pid), *args]
+
+
+def _ipc_call(pid: int, target: str, fn: str, *args: str) -> str | None:
+    """Call *fn* on *target* via ``qs ipc call`` and return the trimmed output."""
+    try:
+        result = subprocess.run(
+            _ipc_cmd(pid, "call", target, fn, *args),
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return result.stdout.strip() or None
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, OSError):
+        return None
+
+
+def _require_session(session_id: str):
+    session = _SESSION_REGISTRY.get(session_id)
+    if session is None:
+        raise ValueError(f"Unknown runtime session '{session_id}'")
+    if session.pid is None:
+        raise ValueError(f"Session '{session_id}' has no PID (not running)")
+    return session
+
+
+# ---------------------------------------------------------------------------
+# Screenshot helpers (compositor-gated)
+# ---------------------------------------------------------------------------
+
+
+def _grim_available() -> bool:
+    return shutil.which("grim") is not None
+
+
+def _compare_available() -> bool:
+    return shutil.which("compare") is not None
+
+
+def _capture_screenshot(path: str | Path) -> str | None:
+    """Capture a full-screen screenshot to *path*. Returns None if grim is unavailable."""
+    if not _grim_available():
+        return None
+    try:
+        subprocess.run(["grim", str(path)], capture_output=True, timeout=10, check=True)
+        return str(path)
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, OSError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Tool implementations
+# ---------------------------------------------------------------------------
+
+
+def _ui_windows(session_id: str) -> dict[str, Any]:
+    """Enumerate windows belonging to the managed session.
+
+    Not available by default — returns an empty list with a note that a
+    compositor adapter (e.g. wlr-foreign-toplevel) is required.
+    """
+    _require_session(session_id)
+    return {
+        "session_id": session_id,
+        "windows": [],
+        "note": "Window enumeration requires a compositor adapter; unavailable here.",
+    }
+
+
+def _screenshot(session_id: str) -> dict[str, Any]:
+    """Capture a screenshot of the managed session's output.
+
+    Requires ``grim`` on PATH. Returns the screenshot path or an
+    "unavailable" note.
+    """
+    _require_session(session_id)
+    if not _grim_available():
+        return {
+            "session_id": session_id,
+            "screenshot_path": None,
+            "note": "Screenshot capture requires grim; not available in this environment.",
+        }
+    path = Path(tempfile.gettempdir()) / f"qs-mcp-screenshot-{session_id}.png"
+    result = _capture_screenshot(str(path))
+    if result is None:
+        return {
+            "session_id": session_id,
+            "screenshot_path": None,
+            "note": "Screenshot capture failed (grim returned no output).",
+        }
+    return {
+        "session_id": session_id,
+        "screenshot_path": result,
+        "note": None,
+    }
+
+
+def _screenshot_diff(baseline: str, actual: str, output: str | None = None) -> dict[str, Any]:
+    """Compare two screenshots via ImageMagick ``compare``.
+
+    Returns a diff image and a similarity metric. Requires ``compare`` on PATH.
+    """
+    if not _compare_available():
+        return {
+            "differs": None,
+            "diff_path": None,
+            "metric": None,
+            "note": "Screenshot diff requires ImageMagick compare; not available.",
+        }
+    out_path = output or Path(tempfile.gettempdir()) / "qs-mcp-diff.png"
+    try:
+        result = subprocess.run(
+            ["compare", "-metric", "AE", baseline, actual, str(out_path)],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        try:
+            metric = float(result.stderr.strip())
+        except (ValueError, AttributeError):
+            metric = None
+        return {
+            "differs": metric is not None and metric > 0,
+            "diff_path": str(out_path),
+            "metric": metric,
+            "note": None,
+        }
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, OSError) as exc:
+        return {
+            "differs": None,
+            "diff_path": None,
+            "metric": None,
+            "note": f"Diff failed: {exc}",
+        }
+
+
+def _ui_tree(session_id: str, depth: int = 3) -> dict[str, Any]:
+    """Inspect the live QML object tree via the injected IpcHandler.
+
+    Returns a compact depth-limited hierarchy. Requires an active session
+    with an ``inspector`` IpcHandler target (from the fixture shell).
+    """
+    session = _require_session(session_id)
+    pid = session.pid
+    raw = _ipc_call(pid, "inspector", "getObjectTree", str(depth))
+    if raw is None:
+        return {
+            "session_id": session_id,
+            "tree": None,
+            "note": "UI tree requires an 'inspector' IpcHandler target; not available.",
+        }
+    return {"session_id": session_id, "tree": raw, "note": None}
+
+
+def _ui_find(session_id: str, query: str) -> dict[str, Any]:
+    """Search the live QML object tree by name, type, or text.
+
+    Requires an active session with an ``inspector`` IpcHandler target.
+    """
+    _require_session(session_id)
+    return {
+        "session_id": session_id,
+        "query": query,
+        "results": [],
+        "note": "UI search requires an 'inspector' IpcHandler target; not available.",
+    }
+
+
+def _ui_get_property(session_id: str, target: str, property_name: str) -> dict[str, Any]:
+    """Read a live QML property value via ``qs ipc prop get``."""
+    session = _require_session(session_id)
+    pid = session.pid
+    try:
+        result = subprocess.run(
+            _ipc_cmd(pid, "prop", "get", target, property_name),
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        value = result.stdout.strip() or None
+        return {
+            "session_id": session_id,
+            "target": target,
+            "property": property_name,
+            "value": value,
+            "note": None,
+        }
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, OSError) as exc:
+        return {
+            "session_id": session_id,
+            "target": target,
+            "property": property_name,
+            "value": None,
+            "note": f"Failed to read property: {exc}",
+        }
+
+
+def _ui_set_property(
+    session_id: str, target: str, property_name: str, value: str
+) -> dict[str, Any]:
+    """Set a live QML property via the IpcHandler's ``setProperty``.
+
+    This is a mutating operation that returns the old value.
+    """
+    session = _require_session(session_id)
+    pid = session.pid
+    old = _ipc_call(pid, target, "getProperty", property_name)
+    _ipc_call(pid, target, "setProperty", property_name, value)
+    return {
+        "session_id": session_id,
+        "target": target,
+        "property": property_name,
+        "old_value": old,
+        "new_value": value,
+        "note": None,
+    }
+
+
+def _ui_invoke(
+    session_id: str, target: str, method: str, arguments: list[str] | None = None
+) -> dict[str, Any]:
+    """Invoke a QML method on a managed runtime object via ``qs ipc call``.
+
+    Validates method existence (best-effort) and returns the result.
+    """
+    session = _require_session(session_id)
+    pid = session.pid
+    args = arguments or []
+    raw = _ipc_call(pid, target, method, *args)
+    return {
+        "session_id": session_id,
+        "target": target,
+        "method": method,
+        "arguments": args,
+        "result": raw,
+        "note": None,
+    }
+
+
+def _ui_eval(session_id: str, js_code: str, timeout: int = 5) -> dict[str, Any]:
+    """High-risk: evaluate QML/JavaScript in the managed runtime session.
+
+    Requires explicit opt-in via the ``inspector`` IpcHandler target.
+    Execution is time-limited and output-bounded. No filesystem or process
+    access is granted.
+    """
+    session = _require_session(session_id)
+    pid = session.pid
+    result = _ipc_call(pid, "inspector", "eval", js_code)
+    return {
+        "session_id": session_id,
+        "code": js_code,
+        "result": result,
+        "note": "High-risk operation: arbitrary QML/JS was evaluated in the runtime session.",
+    }

{quickshell_mcp-2.3.0 → quickshell_mcp-2.4.0}/scripts/smoke_test.py

@@ -129,6 +129,15 @@ def main() -> int:
         "quickshell_runtime_status",
         "quickshell_runtime_logs",
         "quickshell_runtime_ping",
+        "quickshell_windows",
+        "quickshell_screenshot",
+        "quickshell_screenshot_diff",
+        "quickshell_ui_tree",
+        "quickshell_ui_find",
+        "quickshell_ui_get_property",
+        "quickshell_ui_set_property",
+        "quickshell_ui_invoke",
+        "quickshell_ui_eval",
     }
     missing = expected - names
     assert not missing, f"missing tools: {missing}"

quickshell_mcp-2.4.0/tests/fixtures/fake_qs.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Fake qs binary for offline runtime tests.
+# - `qs -p <entrypoint>` simulates a running quickshell instance (loops).
+# - `qs ipc ...` simulates an IPC call to a missing target: no stdout, exit 1.
+if [ "$1" = "ipc" ]; then
+  echo "error: no such target" >&2
+  exit 1
+fi
+echo "fake-qs: starting instance"
+echo "fake-qs: instance id = test"
+while true; do
+  sleep 0.1
+done

{quickshell_mcp-2.3.0 → quickshell_mcp-2.4.0}/tests/test_capabilities.py

@@ -67,6 +67,15 @@ EXPECTED_TOOLS = {
     "quickshell_runtime_status",
     "quickshell_runtime_logs",
     "quickshell_runtime_ping",
+    "quickshell_windows",
+    "quickshell_screenshot",
+    "quickshell_screenshot_diff",
+    "quickshell_ui_tree",
+    "quickshell_ui_find",
+    "quickshell_ui_get_property",
+    "quickshell_ui_set_property",
+    "quickshell_ui_invoke",
+    "quickshell_ui_eval",
 }
 
 # Tools that report session telemetry / live in server.py, not a domain capability.

quickshell_mcp-2.4.0/tests/test_ui_runtime.py

@@ -0,0 +1,170 @@
+"""Tests for the UI inspection tools: windows, screenshots, screenshot diff,
+UI tree, find, property get/set, invoke, and eval.
+
+Screenshot and diff tools are gated on external binaries (grim / ImageMagick
+compare); when missing they return "unavailable" notes rather than failing.
+UI tools require a managed session; without one they raise ValueError.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import quickshell_mcp.server as srv
+from quickshell_mcp.sources import runtime_session as rs
+from quickshell_mcp.sources import ui_runtime as ui
+from quickshell_mcp.sources.runtime_profile import _RuntimeProfile
+
+FIXTURES = Path(__file__).parent / "fixtures"
+FAKE_QS = FIXTURES / "fake_qs.sh"
+RUNTIME_SHELL = FIXTURES / "runtime-shell"
+
+
+@pytest.fixture(autouse=True)
+def _clear_sessions():
+    rs._SESSION_REGISTRY.clear()
+    yield
+    rs._SESSION_REGISTRY.clear()
+
+
+@pytest.fixture
+def fake_qs(monkeypatch):
+    monkeypatch.setattr(rs, "_qs_binary", lambda: str(FAKE_QS))
+    monkeypatch.setattr(ui, "_qs_binary", lambda: str(FAKE_QS))
+
+
+def _write_shell(tmp_path: Path) -> Path:
+    main = tmp_path / "shell.qml"
+    main.write_text("import Quickshell\nPanelWindow { width: 100 }\n", encoding="utf-8")
+    return main
+
+
+def _session(tmp_path, fake_qs) -> rs._RuntimeSession:
+    _write_shell(tmp_path)
+    session = rs._start_session(_RuntimeProfile(project_root=str(tmp_path)))
+    return session
+
+
+# ---------------------------------------------------------------------------
+# Session gating
+# ---------------------------------------------------------------------------
+
+
+def test_ui_tools_require_session():
+    for fn, args in [
+        (srv.quickshell_windows, ("nope",)),
+        (srv.quickshell_screenshot, ("nope",)),
+        (srv.quickshell_ui_tree, ("nope",)),
+        (srv.quickshell_ui_find, ("nope", "x")),
+        (srv.quickshell_ui_get_property, ("nope", "inspector", "greeting")),
+        (srv.quickshell_ui_set_property, ("nope", "inspector", "greeting", "hi")),
+        (srv.quickshell_ui_invoke, ("nope", "inspector", "bumpCounter")),
+        (srv.quickshell_ui_eval, ("nope", "1+1")),
+    ]:
+        with pytest.raises(ValueError, match="Unknown runtime session"):
+            fn(*args)
+
+
+# ---------------------------------------------------------------------------
+# Screenshot / diff gating
+# ---------------------------------------------------------------------------
+
+
+def test_screenshot_unavailable_without_grim(fake_qs, tmp_path, monkeypatch):
+    session = _session(tmp_path, fake_qs)
+    monkeypatch.setattr(ui, "_grim_available", lambda: False)
+    result = srv.quickshell_screenshot(session.session_id)
+    assert result["screenshot_path"] is None
+    assert "grim" in result["note"]
+    rs._stop_session(session)
+
+
+def test_screenshot_diff_unavailable_without_compare(monkeypatch):
+    monkeypatch.setattr(ui, "_compare_available", lambda: False)
+    result = srv.quickshell_screenshot_diff("a.png", "b.png")
+    assert result["differs"] is None
+    assert "compare" in result["note"]
+
+
+def test_windows_returns_empty_with_note(fake_qs, tmp_path):
+    session = _session(tmp_path, fake_qs)
+    result = srv.quickshell_windows(session.session_id)
+    assert result["windows"] == []
+    assert result["note"]
+    rs._stop_session(session)
+
+
+# ---------------------------------------------------------------------------
+# UI tree / find
+# ---------------------------------------------------------------------------
+
+
+def test_ui_tree_unavailable_without_inspector(fake_qs, tmp_path):
+    session = _session(tmp_path, fake_qs)
+    result = srv.quickshell_ui_tree(session.session_id)
+    assert result["tree"] is None
+    assert "inspector" in result["note"]
+    rs._stop_session(session)
+
+
+def test_ui_find_unavailable_without_inspector(fake_qs, tmp_path):
+    session = _session(tmp_path, fake_qs)
+    result = srv.quickshell_ui_find(session.session_id, "greeting")
+    assert result["results"] == []
+    assert "inspector" in result["note"]
+    rs._stop_session(session)
+
+
+# ---------------------------------------------------------------------------
+# Property get/set, invoke, eval
+# ---------------------------------------------------------------------------
+
+
+def test_ui_get_property_missing_binary(fake_qs, tmp_path):
+    session = _session(tmp_path, fake_qs)
+    # With the fake qs the ipc call fails gracefully; value is None.
+    result = srv.quickshell_ui_get_property(session.session_id, "inspector", "greeting")
+    assert result["target"] == "inspector"
+    assert result["property"] == "greeting"
+    rs._stop_session(session)
+
+
+def test_ui_set_property_shape(fake_qs, tmp_path):
+    session = _session(tmp_path, fake_qs)
+    result = srv.quickshell_ui_set_property(session.session_id, "inspector", "greeting", "bonjour")
+    assert result["property"] == "greeting"
+    assert result["new_value"] == "bonjour"
+    rs._stop_session(session)
+
+
+def test_ui_invoke_shape(fake_qs, tmp_path):
+    session = _session(tmp_path, fake_qs)
+    result = srv.quickshell_ui_invoke(session.session_id, "inspector", "bumpCounter")
+    assert result["method"] == "bumpCounter"
+    assert result["arguments"] == []
+    rs._stop_session(session)
+
+
+def test_ui_eval_high_risk_note(fake_qs, tmp_path):
+    session = _session(tmp_path, fake_qs)
+    result = srv.quickshell_ui_eval(session.session_id, "1 + 1")
+    assert result["code"] == "1 + 1"
+    assert "High-risk" in result["note"]
+    rs._stop_session(session)
+
+
+# ---------------------------------------------------------------------------
+# Screenshot with real grim (skip if unavailable)
+# ---------------------------------------------------------------------------
+
+
+def test_screenshot_with_grim_available(fake_qs, tmp_path, monkeypatch):
+    if not ui._grim_available():
+        pytest.skip("grim not installed")
+    session = _session(tmp_path, fake_qs)
+    result = srv.quickshell_screenshot(session.session_id)
+    rs._stop_session(session)
+    # grim may still fail in a headless test env; just ensure a path or a note.
+    assert "screenshot_path" in result

quickshell_mcp-2.3.0/tests/fixtures/fake_qs.sh

@@ -1,10 +0,0 @@
-#!/bin/sh
-# Fake qs binary for offline runtime tests.
-# Simulates a running quickshell instance: prints PID, waits for SIGTERM,
-# cleans up, and exits.
-echo "fake-qs: starting instance"
-echo "fake-qs: instance id = test"
-while true; do
-  sleep 0.1
-  echo "tick" >&2
-done