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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickshell-mcp
-Version: 2.2.0
+Version: 2.3.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.3.0}/pyproject.toml

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

@@ -25,4 +25,5 @@ CAPABILITY_DEPENDS_ON = (
     "migration",
     "debugging",
     "project",
+    "runtime",
 )

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

@@ -25,7 +25,16 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from . import assistant, debugging, generation, knowledge, migration, project, validation
+from . import (
+    assistant,
+    debugging,
+    generation,
+    knowledge,
+    migration,
+    project,
+    runtime,
+    validation,
+)
 
 __all__ = [
     "ALL_CAPABILITIES",
@@ -72,6 +81,7 @@ _CAPABILITY_MODULES = (
     migration,
     debugging,
     project,
+    runtime,
     assistant,
 )
 
@@ -93,7 +103,7 @@ PLANNED_CAPABILITIES: dict[str, Capability] = {
         status="planned",
         safety_level=_safety_level(name),
     )
-    for name in ("runtime", "inspection", "testing", "performance")
+    for name in ("inspection", "testing", "performance")
 }
 
 ALL_CAPABILITIES: dict[str, Capability] = {**CAPABILITIES, **PLANNED_CAPABILITIES}

quickshell_mcp-2.3.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.3.0}/quickshell_mcp/server.py

@@ -117,6 +117,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 +174,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 +1035,93 @@ 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_stats() -> dict:
     """Report session usage stats for this MCP server: per-tool call counts,

quickshell_mcp-2.3.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,
+        }

quickshell_mcp-2.3.0/quickshell_mcp/sources/runtime_session.py

@@ -0,0 +1,287 @@
+"""Managed Quickshell runtime sessions: launch, track, inspect, and stop
+isolated ``qs`` processes backed by a runtime profile.
+
+Every session is tracked in the global ``_SESSION_REGISTRY`` by a unique
+session id. Lifecycle operations (start/stop/reset) are mutating; status,
+logs, and ping are read-only. The session ring buffer keeps the last
+:data:`_LOG_BUF_SIZE` log lines.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import signal
+import subprocess
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .runtime_profile import _RuntimeProfile
+
+_LOG_BUF_SIZE = 10_000
+_POLL_INTERVAL = 0.1
+_KILL_TIMEOUT = 5.0
+
+_SESSION_REGISTRY: dict[str, _RuntimeSession] = {}
+
+# Status values
+STATUS_STARTING = "starting"
+STATUS_RUNNING = "running"
+STATUS_EXITED = "exited"
+STATUS_KILLED = "killed"
+STATUS_ERROR = "error"
+
+
+def _qs_binary() -> str:
+    """Path to the ``qs`` executable, or raises ``FileNotFoundError``."""
+    path = shutil.which("qs")
+    if path is None:
+        raise FileNotFoundError(
+            "qs binary not found on PATH; install Quickshell to use runtime tools"
+        )
+    return path
+
+
+@dataclass
+class _LogLine:
+    stream: str  # "stdout" | "stderr"
+    line: str
+    ts: float = field(default_factory=time.time)
+
+
+@dataclass
+class _RuntimeSession:
+    session_id: str
+    profile: _RuntimeProfile
+    status: str = STATUS_STARTING
+    pid: int | None = None
+    start_time: float = field(default_factory=time.time)
+    exit_code: int | None = None
+    kind: str = "managed"  # "managed" | "detached"
+    log_buffer: list[_LogLine] = field(default_factory=list)
+    _process: subprocess.Popen | None = None
+
+    def append_log(self, stream: str, line: str) -> None:
+        self.log_buffer.append(_LogLine(stream=stream, line=line))
+        if len(self.log_buffer) > _LOG_BUF_SIZE:
+            self.log_buffer = self.log_buffer[-_LOG_BUF_SIZE:]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "session_id": self.session_id,
+            "status": self.status,
+            "pid": self.pid,
+            "start_time": self.start_time,
+            "uptime": (
+                round(time.time() - self.start_time, 1) if self.status == STATUS_RUNNING else None
+            ),
+            "exit_code": self.exit_code,
+            "kind": self.kind,
+            "profile": {
+                "project_root": self.profile.project_root,
+                "entrypoint": self.profile.entrypoint,
+                "compositor": self.profile.compositor,
+            },
+        }
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle
+# ---------------------------------------------------------------------------
+
+
+def _start_session(profile: _RuntimeProfile) -> _RuntimeSession:
+    """Launch a managed Quickshell session from *profile* and register it.
+
+    Returns a session with status ``running`` on success, or ``error`` if
+    the binary is missing or the process fails to start.
+    """
+    session_id = uuid.uuid4().hex[:12]
+    try:
+        entrypoint = profile.resolved_entrypoint()
+        env = profile.isolated_environment(session_id)
+        binary = _qs_binary()
+        cmd = [binary, "-p", entrypoint, "--no-daemonize"] + profile.arguments
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=env,
+            start_new_session=True,
+            text=True,
+        )
+    except (FileNotFoundError, OSError, subprocess.SubprocessError, ValueError) as exc:
+        session = _RuntimeSession(
+            session_id=session_id,
+            profile=profile,
+            status=STATUS_ERROR,
+            exit_code=-1,
+        )
+        session.append_log("stderr", f"Failed to launch: {exc}")
+        _SESSION_REGISTRY[session_id] = session
+        return session
+
+    session = _RuntimeSession(
+        session_id=session_id,
+        profile=profile,
+        status=STATUS_RUNNING,
+        pid=proc.pid,
+        _process=proc,
+    )
+    _SESSION_REGISTRY[session_id] = session
+    return session
+
+
+def _stop_session(session: _RuntimeSession, timeout: float = _KILL_TIMEOUT) -> None:
+    """Stop a managed session gracefully (SIGTERM → timeout → SIGKILL).
+
+    Handles already-exited and orphaned processes safely.
+    """
+    if session.status in (STATUS_EXITED, STATUS_KILLED, STATUS_ERROR):
+        return
+    pid = session.pid
+    if pid is None:
+        session.status = STATUS_ERROR
+        return
+
+    try:
+        # Send SIGTERM to the whole process group (negative pid).
+        os.killpg(pid, signal.SIGTERM)
+        waited = _wait_with_timeout(pid, timeout)
+        if waited is None:
+            os.killpg(pid, signal.SIGKILL)
+            _wait_with_timeout(pid, 2.0)
+            session.status = STATUS_KILLED
+        else:
+            session.status = STATUS_EXITED
+            session.exit_code = waited
+    except ProcessLookupError:
+        session.status = STATUS_EXITED
+        session.exit_code = 0
+    except PermissionError:
+        session.status = STATUS_ERROR
+
+    _drain_logs(session)
+    session._process = None
+
+
+def _reset_session(session: _RuntimeSession) -> _RuntimeSession:
+    """Stop the existing session and start a fresh one with the same profile.
+
+    A new session id is allocated; the old session is removed from the
+    registry. Stale processes, temp files, and sockets are cleaned up.
+    """
+    _stop_session(session)
+    _cleanup_temp(session)
+    old_id = session.session_id
+    _SESSION_REGISTRY.pop(old_id, None)
+    return _start_session(session.profile)
+
+
+def _status_session(session: _RuntimeSession) -> dict[str, Any]:
+    """Return structured status for a session, refreshing the process state."""
+    _refresh_status(session)
+    return session.to_dict()
+
+
+def _logs(
+    session: _RuntimeSession,
+    *,
+    stream: str | None = None,
+    severity: str | None = None,
+    text: str | None = None,
+    limit: int = 200,
+) -> list[dict[str, Any]]:
+    """Return structured log lines from the session's ring buffer."""
+    lines = list(session.log_buffer)
+    if stream:
+        lines = [line for line in lines if line.stream == stream]
+    if text:
+        text_lower = text.lower()
+        lines = [line for line in lines if text_lower in line.line.lower()]
+    return [{"ts": line.ts, "stream": line.stream, "line": line.line} for line in lines[-limit:]]
+
+
+def _ping(session: _RuntimeSession) -> dict[str, str]:
+    """Lightweight health check. Returns one of:
+
+    * ``process_running`` — the process is alive
+    * ``exited`` — the process has exited
+    * ``unhealthy`` — the session is in an error state
+    """
+    _refresh_status(session)
+    if session.status == STATUS_RUNNING:
+        return {"status": "process_running"}
+    if session.status in (STATUS_EXITED, STATUS_KILLED):
+        return {"status": "exited", "exit_code": str(session.exit_code)}
+    return {"status": "unhealthy", "detail": session.status}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _wait_with_timeout(pid: int, timeout: float) -> int | None:
+    """Wait for *pid* to exit, returning the exit code or None on timeout."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            pid_out, status = os.waitpid(pid, os.WNOHANG)
+            if pid_out == pid:
+                if os.WIFEXITED(status):
+                    return os.WEXITSTATUS(status)
+                if os.WIFSIGNALED(status):
+                    return -os.WTERMSIG(status)
+                return status
+        except ChildProcessError:
+            return None
+        time.sleep(_POLL_INTERVAL)
+    return None
+
+
+def _drain_logs(session: _RuntimeSession) -> None:
+    """Read any remaining stdout/stderr from the finished process."""
+    proc = session._process
+    if proc is None:
+        return
+    for stream_name in ("stdout", "stderr"):
+        handle = getattr(proc, stream_name, None)
+        if handle is None:
+            continue
+        for line in handle.readlines():
+            session.append_log(stream_name, line.rstrip("\n"))
+
+
+def _refresh_status(session: _RuntimeSession) -> None:
+    """Update session status from the actual process state."""
+    if session.status in (STATUS_EXITED, STATUS_KILLED, STATUS_ERROR):
+        return
+    pid = session.pid
+    if pid is None:
+        session.status = STATUS_ERROR
+        return
+    try:
+        os.kill(pid, 0)
+        session.status = STATUS_RUNNING
+    except ProcessLookupError:
+        _drain_logs(session)
+        session.status = STATUS_EXITED
+        session.exit_code = 0
+    except PermissionError:
+        session.status = STATUS_ERROR
+
+
+def _cleanup_temp(session: _RuntimeSession) -> None:
+    """Remove the isolated temp directories for a session."""
+    import tempfile
+
+    for var in ("XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"):
+        env = session.profile.environment.get(var) or ""
+        if env.startswith(tempfile.gettempdir()):
+            with contextlib.suppress(OSError):
+                Path(env).rmdir()  # only removes empty dirs, not recursive

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

@@ -123,6 +123,12 @@ def main() -> int:
         "quickshell_refactor",
         "quickshell_apply_patch",
         "quickshell_style_match",
+        "quickshell_runtime_start",
+        "quickshell_runtime_stop",
+        "quickshell_runtime_reset",
+        "quickshell_runtime_status",
+        "quickshell_runtime_logs",
+        "quickshell_runtime_ping",
     }
     missing = expected - names
     assert not missing, f"missing tools: {missing}"

quickshell_mcp-2.3.0/tests/fixtures/fake_qs.sh

@@ -0,0 +1,10 @@
+#!/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

quickshell_mcp-2.3.0/tests/fixtures/runtime-shell/main.qml

@@ -0,0 +1,48 @@
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+// Minimal managed-runtime fixture shell. Exposes an IpcHandler target
+// "inspector" so runtime tools can introspect and drive the UI over `qs ipc`.
+PanelWindow {
+    id: root
+    width: 200
+    height: 60
+    color: "#1e1e2e"
+
+    property string greeting: "hello"
+    property int counter: 0
+
+    Text {
+        id: label
+        anchors.centerIn: parent
+        text: root.greeting + " #" + root.counter
+        color: "#cdd6f4"
+    }
+
+    IpcHandler {
+        target: "inspector"
+
+        function getProperty(name: string): string {
+            return String(root[name]);
+        }
+
+        function setProperty(name: string, value: string): void {
+            root[name] = value;
+        }
+
+        function getGreeting(): string {
+            return root.greeting;
+        }
+
+        function getCounter(): int {
+            return root.counter;
+        }
+
+        function bumpCounter(): void {
+            root.counter += 1;
+        }
+
+        signal counterChanged(value: int);
+    }
+}

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

@@ -61,6 +61,12 @@ EXPECTED_TOOLS = {
     "quickshell_refactor",
     "quickshell_apply_patch",
     "quickshell_style_match",
+    "quickshell_runtime_start",
+    "quickshell_runtime_stop",
+    "quickshell_runtime_reset",
+    "quickshell_runtime_status",
+    "quickshell_runtime_logs",
+    "quickshell_runtime_ping",
 }
 
 # Tools that report session telemetry / live in server.py, not a domain capability.
@@ -138,7 +144,10 @@ def test_planned_capabilities_are_metadata_only():
 
 def test_implemented_capability_safety_levels():
     for name, cap in registry.CAPABILITIES.items():
-        assert cap.safety_level == "read-only", f"{name} should be read-only"
+        if name in ("runtime", "testing"):
+            assert cap.safety_level == "mutating", f"{name} should be mutating"
+        else:
+            assert cap.safety_level == "read-only", f"{name} should be read-only"
 
 
 def test_planned_capability_safety_levels():