quickshell-mcp 1.4.1__py3-none-any.whl

quickshell_mcp/__init__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+__all__ = ["main"]

quickshell_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

quickshell_mcp/caches.py

@@ -0,0 +1,96 @@
+"""Caching: a 30-minute in-memory layer for every fetch, plus a disk layer
+that keeps the expensive bulk doc indexes (guide/type/qt) warm across server
+restarts. Raw HTML is never persisted; disk holds only the built indexes."""
+
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import _CACHE_TTL
+
+_log = logging.getLogger(__name__)
+
+_DEFAULT_DISK_TTL_HOURS = 720  # 30 days; published versions are effectively frozen
+
+
+@dataclass
+class _CacheEntry:
+    value: object
+    ts: float = field(default_factory=time.time)
+
+
+_cache: dict[str, _CacheEntry] = {}
+
+
+def _cache_get(key: str):
+    entry = _cache.get(key)
+    if entry and (time.time() - entry.ts) < _CACHE_TTL:
+        return entry.value
+    return None
+
+
+def _cache_set(key: str, value: object):
+    _cache[key] = _CacheEntry(value)
+
+
+def _disk_dir() -> Path | None:
+    """Cache root, or None when disabled via QUICKSHELL_DOCS_MCP_DISK_CACHE.
+    Read per call so tests can redirect it without re-importing."""
+    override = os.environ.get("QUICKSHELL_DOCS_MCP_DISK_CACHE", "").strip()
+    if override.lower() in ("off", "0", "false"):
+        return None
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(xdg) / "quickshell-mcp"
+
+
+def _disk_ttl_seconds() -> float:
+    raw = os.environ.get("QUICKSHELL_DOCS_MCP_DISK_TTL_HOURS", "").strip()
+    try:
+        hours = float(raw) if raw else _DEFAULT_DISK_TTL_HOURS
+    except ValueError:
+        log_warning = logging.getLogger("quickshell-mcp")
+        log_warning.warning("invalid QUICKSHELL_DOCS_MCP_DISK_TTL_HOURS=%r; using default", raw)
+        hours = _DEFAULT_DISK_TTL_HOURS
+    return max(hours, 0.0) * 3600
+
+
+def _disk_path(key: str) -> Path | None:
+    directory = _disk_dir()
+    if directory is None:
+        return None
+    # ':' would be legal on Linux but smells like a Windows portability trap.
+    return directory / (key.replace(":", "_") + ".json")
+
+
+def _disk_get(key: str) -> object | None:
+    path = _disk_path(key)
+    if path is None:
+        return None
+    try:
+        envelope = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    saved_at = envelope.get("saved_at", 0)
+    if not isinstance(saved_at, (int, float)):
+        return None
+    if time.time() - saved_at > _disk_ttl_seconds():
+        return None
+    return envelope.get("value")
+
+
+def _disk_set(key: str, value: object) -> None:
+    path = _disk_path(key)
+    if path is None:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        envelope = {"saved_at": time.time(), "value": value}
+        path.write_text(json.dumps(envelope), encoding="utf-8")
+    except OSError as error:
+        # Disk cache is an optimization only; never fail a request over it.
+        _log.warning("disk cache write failed for %s: %s", key, error)

quickshell_mcp/config.py

@@ -0,0 +1,40 @@
+"""Upstream locations, identities, and tuning constants for every source."""
+
+BASE = "https://quickshell.org"
+QT_DOCS_BASE = "https://doc.qt.io/qt-6"
+EXAMPLES_REPO_WEB = "https://git.outfoxxed.me/quickshell/quickshell-examples"
+EXAMPLES_REPO_API = "https://git.outfoxxed.me/api/v1/repos/quickshell/quickshell-examples"
+
+USER_AGENT = "quickshell-mcp/0.1 (+https://github.com/; contact: local use)"
+
+_CACHE_TTL = 60 * 30  # 30 minutes; long enough to be polite, short enough to track site updates
+
+_RETRY_ATTEMPTS = 3
+
+# Version numbers are vX.Y.Z today but tolerate prerelease suffixes (v0.4.0-rc1)
+# so "latest" doesn't silently lag behind when the site publishes one.
+_VERSION_NUM = r"\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)*"
+
+# doc.qt.io hosts its page body inside <article class="b-sidebar__content...">,
+# so the generic [class*=sidebar] strip rule would delete the actual content.
+_STRIP_SELECTORS = [
+    "nav",
+    "header",
+    "footer",
+    "aside",
+    "script",
+    "style",
+    "[class*=sidebar]",
+    "[class*=toc]",
+    "[class*=search]",
+    "[class*=version-switch]",
+    "[class*=breadcrumb]",
+]
+_QT_STRIP_SELECTORS = ["script", "style"]
+
+IMPLEMENTATION_REPOS: dict[str, dict[str, str]] = {
+    "caelestia": {"owner": "caelestia-dots", "repo": "shell"},
+    # The Quickshell shell lives on the legacy-v4 branch; noctalia's main
+    # branch moved to a C++ compositor project, so the ref is pinned here.
+    "noctalia": {"owner": "noctalia-dev", "repo": "noctalia", "branch": "legacy-v4"},
+}

quickshell_mcp/extraction.py

@@ -0,0 +1,31 @@
+"""HTML -> Markdown extraction, with per-source strip rules."""
+
+import re
+
+from bs4 import BeautifulSoup
+from markdownify import markdownify as html_to_md
+
+from . import utils
+from .config import _QT_STRIP_SELECTORS, _STRIP_SELECTORS
+
+
+def _extract_main_content(html: str, strip: list[str] | None = None) -> str:
+    soup = BeautifulSoup(html, "html.parser")
+
+    for selector in strip if strip is not None else _STRIP_SELECTORS:
+        for tag in soup.select(selector):
+            tag.decompose()
+
+    main = soup.find("main") or soup.find("article") or soup.body or soup
+    markdown = html_to_md(str(main), heading_style="ATX", bullets="-")
+    # Collapse excessive blank lines left over from stripped nav junk.
+    markdown = re.sub(r"\n{3,}", "\n\n", markdown).strip()
+    return markdown
+
+
+def _fetch_page_markdown(url: str) -> str:
+    return _extract_main_content(utils._fetch_raw(url))
+
+
+def _fetch_qt_page_markdown(url: str) -> str:
+    return _extract_main_content(utils._fetch_raw(url), strip=_QT_STRIP_SELECTORS)