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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickshell-mcp
-Version: 2.2.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.2.0 → quickshell_mcp-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quickshell-mcp"
-version = "2.2.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.2.0 → quickshell_mcp-2.4.0}/quickshell_mcp/capabilities/assistant.py

@@ -25,4 +25,6 @@ CAPABILITY_DEPENDS_ON = (
     "migration",
     "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.2.0 → quickshell_mcp-2.4.0}/quickshell_mcp/capabilities/registry.py

@@ -25,7 +25,17 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from . import assistant, debugging, generation, knowledge, migration, project, validation
+from . import (
+    assistant,
+    debugging,
+    generation,
+    inspection,
+    knowledge,
+    migration,
+    project,
+    runtime,
+    validation,
+)
 
 __all__ = [
     "ALL_CAPABILITIES",
@@ -58,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",
 }
 
 
@@ -72,6 +85,8 @@ _CAPABILITY_MODULES = (
     migration,
     debugging,
     project,
+    runtime,
+    inspection,
     assistant,
 )
 
@@ -93,7 +108,7 @@ PLANNED_CAPABILITIES: dict[str, Capability] = {
         status="planned",
         safety_level=_safety_level(name),
     )
-    for name in ("runtime", "inspection", "testing", "performance")
+    for name in ("testing", "performance")
 }
 
 ALL_CAPABILITIES: dict[str, Capability] = {**CAPABILITIES, **PLANNED_CAPABILITIES}

quickshell_mcp-2.4.0/quickshell_mcp/capabilities/runtime.py

@@ -0,0 +1,35 @@
+"""The runtime capability: manage isolated Quickshell runtime sessions.
+
+Sessions are launched from explicit runtime profiles with isolated XDG dirs,
+tracked in a registry, and inspectable via status, logs, and ping. The
+capability is mutating: starting, stopping, and resetting sessions alter
+process state and must be explicitly invoked.
+
+Depends on: knowledge, project (runtime tools use project detection and
+documentation for diagnostics).
+"""
+
+from __future__ import annotations
+
+from ..sources.runtime_profile import _RuntimeProfile  # noqa: F401
+from ..sources.runtime_session import (  # noqa: F401
+    _SESSION_REGISTRY,
+    _logs,
+    _ping,
+    _qs_binary,
+    _reset_session,
+    _start_session,
+    _status_session,
+    _stop_session,
+)
+
+CAPABILITY_NAME = "runtime"
+CAPABILITY_TOOLS = (
+    "quickshell_runtime_start",
+    "quickshell_runtime_stop",
+    "quickshell_runtime_reset",
+    "quickshell_runtime_status",
+    "quickshell_runtime_logs",
+    "quickshell_runtime_ping",
+)
+CAPABILITY_DEPENDS_ON = ("knowledge", "project")

{quickshell_mcp-2.2.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,
@@ -117,6 +128,17 @@ from .capabilities.project import (  # noqa: F401
     _search_project,
     _validate_project,
 )
+from .capabilities.runtime import (  # noqa: F401
+    _SESSION_REGISTRY,
+    _logs,
+    _ping,
+    _qs_binary,
+    _reset_session,
+    _RuntimeProfile,
+    _start_session,
+    _status_session,
+    _stop_session,
+)
 from .capabilities.validation import (  # noqa: F401
     _api_in_version,
     _changelog_hits,
@@ -163,6 +185,14 @@ from .versions import (  # noqa: F401
 mcp = FastMCP("quickshell-mcp")
 
 
+def _require_session(session_id: str):
+    """Look up a tracked runtime session, raising ValueError if unknown."""
+    session = _SESSION_REGISTRY.get(session_id)
+    if session is None:
+        raise ValueError(f"Unknown runtime session '{session_id}'")
+    return session
+
+
 @mcp.tool()
 def quickshell_list_versions(refresh: bool = False) -> dict:
     """List all Quickshell documentation versions currently published on
@@ -1016,6 +1046,184 @@ def quickshell_project_migrate(project: str, from_version: str, to_version: str)
     return _migrate_project(project, from_version=from_version, to_version=to_version)
 
 
+@mcp.tool()
+def quickshell_runtime_start(
+    project: str,
+    entrypoint: str | None = None,
+    config_dir: str | None = None,
+    environment: dict[str, str] | None = None,
+    compositor: str | None = None,
+    arguments: list[str] | None = None,
+) -> dict:
+    """Start a managed, isolated Quickshell runtime session for a project.
+
+    Launches ``qs`` with isolated XDG directories so it never touches your
+    real desktop session or other quickshell instances. Returns a session id
+    and tracks the process for later status, logs, ping, stop, and reset.
+    This is a mutating operation: it launches a process."""
+    _record_tool("quickshell_runtime_start")
+    profile = _RuntimeProfile(
+        project_root=project,
+        entrypoint=entrypoint,
+        config_dir=config_dir,
+        environment=environment or {},
+        compositor=compositor,
+        arguments=arguments or [],
+    )
+    return _start_session(profile).to_dict()
+
+
+@mcp.tool()
+def quickshell_runtime_stop(session_id: str) -> dict:
+    """Stop a managed runtime session safely (SIGTERM, then SIGKILL on timeout).
+
+    Handles already-exited and orphaned processes; stops only the tracked
+    session's process group, never unrelated user processes. Mutating."""
+    _record_tool("quickshell_runtime_stop")
+    session = _require_session(session_id)
+    _stop_session(session)
+    return session.to_dict()
+
+
+@mcp.tool()
+def quickshell_runtime_reset(session_id: str) -> dict:
+    """Reset a managed runtime session to a clean state.
+
+    Stops the current session, cleans up its isolated temp dirs, and starts a
+    fresh session with the same profile under a new session id. Mutating."""
+    _record_tool("quickshell_runtime_reset")
+    session = _require_session(session_id)
+    fresh = _reset_session(session)
+    return fresh.to_dict()
+
+
+@mcp.tool()
+def quickshell_runtime_status(session_id: str) -> dict:
+    """Return structured status for a runtime session: session id, running
+    state, PID, startup duration, exit code, and profile identity. Read-only."""
+    _record_tool("quickshell_runtime_status")
+    session = _require_session(session_id)
+    return _status_session(session)
+
+
+@mcp.tool()
+def quickshell_runtime_logs(
+    session_id: str,
+    stream: str | None = None,
+    severity: str | None = None,
+    text: str | None = None,
+    limit: int = 200,
+) -> dict:
+    """Return structured logs from a runtime session with optional filtering
+    by stream (stdout/stderr), text, and a bounded limit. Read-only."""
+    _record_tool("quickshell_runtime_logs")
+    session = _require_session(session_id)
+    lines = _logs(session, stream=stream, severity=severity, text=text, limit=limit)
+    return {"session_id": session_id, "logs": lines, "count": len(lines)}
+
+
+@mcp.tool()
+def quickshell_runtime_ping(session_id: str) -> dict:
+    """Lightweight readiness/health check for a runtime session.
+
+    Distinguishes: process_running, exited (with exit code), or unhealthy.
+    Fast, read-only."""
+    _record_tool("quickshell_runtime_ping")
+    session = _require_session(session_id)
+    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/runtime_profile.py

@@ -0,0 +1,81 @@
+"""Runtime profiles: explicit, inspectable launch configuration for managed
+Quickshell runtime sessions.
+
+A profile describes *how* to run a Quickshell project in isolation: the
+project root, entrypoint, config directory, environment overrides, compositor
+or backend, command-line arguments, and optional fixture data. Profiles are
+pure data — nothing here launches processes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class _RuntimeProfile:
+    """Explicit launch configuration for a managed Quickshell session."""
+
+    project_root: str
+    entrypoint: str | None = None
+    config_dir: str | None = None
+    environment: dict[str, str] = field(default_factory=dict)
+    compositor: str | None = None
+    arguments: list[str] = field(default_factory=list)
+    fixture_data: dict[str, str] = field(default_factory=dict)
+
+    def resolved_entrypoint(self) -> str:
+        """The QML entrypoint: the configured one, or the project's detected
+        entrypoint, or ``shell.qml`` / ``main.qml`` under the project root."""
+        if self.entrypoint:
+            return str(Path(self.entrypoint).expanduser().resolve())
+        root = Path(self.project_root).expanduser().resolve()
+        for name in ("shell.qml", "main.qml", "config.qml"):
+            candidate = root / name
+            if candidate.is_file():
+                return str(candidate)
+        raise ValueError(
+            f"No entrypoint found under {root}; pass entrypoint= or add shell.qml/main.qml."
+        )
+
+    def isolated_environment(self, instance_id: str) -> dict[str, str]:
+        """Environment for launching the session: inherited variables plus
+        profile overrides and isolated XDG dirs for the instance."""
+        import os
+        import tempfile
+
+        base = dict(os.environ)
+        base.update(self.environment)
+        prefix = Path(tempfile.gettempdir()) / f"qs-mcp-{instance_id}"
+        # Isolate per-session state so a managed shell never touches the
+        # user's real XDG dirs or other quickshell instances.
+        base.update(
+            {
+                "QUICKSHELL_INSTANCE_ID": instance_id,
+                "XDG_CONFIG_HOME": str(prefix / "config"),
+                "XDG_CACHE_HOME": str(prefix / "cache"),
+                "XDG_DATA_HOME": str(prefix / "data"),
+                "XDG_STATE_HOME": str(prefix / "state"),
+            }
+        )
+        return base
+
+    def to_dict(self) -> dict[str, object]:
+        root = Path(self.project_root).expanduser().resolve()
+        entrypoint: str | None
+        if self.entrypoint or root.is_dir():
+            try:
+                entrypoint = self.resolved_entrypoint()
+            except ValueError:
+                entrypoint = self.entrypoint
+        else:
+            entrypoint = self.entrypoint
+        return {
+            "project_root": self.project_root,
+            "entrypoint": entrypoint,
+            "config_dir": self.config_dir,
+            "compositor": self.compositor,
+            "arguments": self.arguments,
+            "fixture_data": self.fixture_data,
+        }