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

{quickshell_mcp-2.0.0 → quickshell_mcp-2.2.0}/.gitignore

@@ -20,6 +20,11 @@ result
 result-*
 .direnv/
 
+# Node (used only for local semantic-release debugging)
+node_modules/
+package-lock.json
+package.json
+
 # Editors / OS
 .vscode/
 .idea/

quickshell_mcp-2.2.0/.releaserc.js

@@ -0,0 +1,61 @@
+const notesPattern = (sel) => new RegExp(`^[\\s|*]*(${sel}):\\s*(.*)`, "i");
+
+module.exports = {
+  branches: ["main"],
+  tagFormat: "v${version}",
+  plugins: [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        parserOpts: {
+          headerPattern: "^([\\w.\\-*/]+):\\s?(.*)$",
+          headerCorrespondence: ["scope", "subject"],
+          noteKeywords: ["BREAKING CHANGE", "Semver"],
+          notesPattern,
+        },
+        releaseRules: [
+          { notes: [{ title: "Semver", text: "minor" }], release: "minor" },
+          { notes: [{ title: "Semver", text: "major" }], release: "major" },
+        ],
+      },
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        parserOpts: {
+          headerPattern: "^([\\w.\\-*/]+):\\s?(.*)$",
+          headerCorrespondence: ["scope", "subject"],
+          noteKeywords: null,
+        },
+      },
+    ],
+    [
+      "@google/semantic-release-replace-plugin",
+      {
+        replacements: [
+          {
+            files: ["pyproject.toml"],
+            from: "version = \"[0-9]+\\.[0-9]+\\.[0-9]+[^\"]*\"",
+            to: "version = \"${nextRelease.version}\"",
+            results: [{ file: "pyproject.toml", hasChanged: true }],
+          },
+        ],
+      },
+    ],
+    [
+      "@semantic-release/git",
+      {
+        assets: ["pyproject.toml"],
+        message: "release: v${nextRelease.version} [skip ci]",
+      },
+    ],
+    [
+      "@semantic-release/exec",
+      {
+        prepareCmd:
+          'echo "released=true" >> "$GITHUB_OUTPUT" && echo "version=${nextRelease.version}" >> "$GITHUB_OUTPUT"',
+      },
+    ],
+    "@semantic-release/github",
+  ],
+};

{quickshell_mcp-2.0.0 → quickshell_mcp-2.2.0}/AGENTS.md

@@ -22,8 +22,9 @@ An MCP server that serves live Quickshell documentation from quickshell.org so L
   - `caches.py`: 30-minute in-memory cache per fetch, plus a disk layer that persists built indexes (guide/type/qt) across restarts (30-day default TTL); `QUICKSHELL_DOCS_MCP_DISK_CACHE` env var to disable/redirect
   - `utils.py`: logging, HTTP client, `_fetch_raw` (retry + stats), citation prefix; domain modules call `utils._fetch_raw` by module attribute so tests monkeypatch one seam
   - `versions.py`, `extraction.py`: runtime version discovery; HTML→Markdown with per-source strip rules
-  - `sources/`: one logic module per domain capability (`docs`, `qt_docs`, `examples`, `implementations`, `compat`, `migrate`, `validate`, `generate`, `assistant`, `explain_error`, `find_pattern`, `search_all`); no MCP decorators here
-  - `server.py`: FastMCP instance, every `@mcp.tool()` wrapper + docstring (the trigger surface), `main()`, and re-exports of helper names so tests keep addressing `srv.<helper>`
+  - `sources/`: shared-services layer — data-source access, index building, parsing, and low-level analysis (`docs`, `qt_docs`, `examples`, `implementations`, `compat`, `migrate`, `validate`, `generate`, `assistant`, `explain_error`, `find_pattern`, `search_all`); no MCP decorators here and it never imports `capabilities/` (dependencies point down)
+  - `capabilities/`: capability/domain layer between the tools and the sources — one module per capability (`knowledge`, `validation`, `generation`, `migration`, `debugging`, `assistant`), each declaring `CAPABILITY_NAME`/`CAPABILITY_TOOLS`/`CAPABILITY_DEPENDS_ON` and re-exporting the source entry points; `registry.py` aggregates the tool→capability map and a cycle-checked `dependency_order()`. Planned-but-unimplemented capabilities (project, runtime, inspection, testing, performance) are registry entries only — never empty placeholder modules
+  - `server.py`: FastMCP instance, every `@mcp.tool()` wrapper + docstring (the trigger surface), `main()`, and re-exports of helper names so tests keep addressing `srv.<helper>`; tool logic is routed through `capabilities/`
 - `tests/`: offline pytest suite driven by saved snapshots in `tests/fixtures/`. `conftest.py` provides `mock_fetch` (patches `utils._fetch_raw`), `docs_fixture_urls`, `http_404`, and an autouse cache/stats reset.
 - `scripts/smoke_test.py`: end-to-end stdio client; drives the server like a real MCP session against the live sites.
 - `flake.nix` / `Dockerfile` / `.github/workflows/ci.yml`: packaging + CI. `CLAUDE.md` is a symlink to this file.
@@ -118,6 +119,65 @@ Run checks when warranted, not reflexively. If none apply, say so instead of run
 5. **CI pipeline** (`.github/workflows/ci.yml`): flake check → nix build + dist/twine → lint → offline pytest with coverage → Dockerfile validation; live-smoke runs only on manual dispatch. If you add a check locally, wire the equivalent into CI.
 6. **Implementation references are not documentation.** Caelestia/Noctalia/dots-hyprland results carry `kind: real-world implementation` and every tool docstring says the docs win on API disputes. Noctalia's ref is pinned to its `legacy-v4` branch deliberately (its `main` moved to a C++ compositor); a GitHub `truncated: true` tree response is refused rather than silently under-indexed. dots-hyprland's QML root is nested under `dots/.config/quickshell/ii/` and paths are reported relative to it.
 
+## ProjectContext (`quickshell_mcp/sources/project.py`)
+
+A reusable internal abstraction for representing a Quickshell project on disk.
+It is **not** a capability or an MCP tool — it is shared infrastructure in the
+`sources/` layer that capabilities consume.
+
+### Consumer pattern
+
+```python
+from ..sources.project import _build_project_context
+
+ctx = _build_project_context("/path/to/shell")
+info = ctx.discover({"qml_files", "imports", "compositor"})
+# info = {"qml_files": [...], "imports": [...], "compositor": ["Hyprland"], ...}
+# ctx.detection_status("compositor") -> "inferred"
+```
+
+### Available fields (all lazy)
+
+| Field | Status | Description |
+|-------|--------|-------------|
+| `qml_files` | detected | Every `*.qml` under the project root |
+| `js_files` | detected | Every `*.js` under the project root |
+| `entrypoints` | detected | QML files whose root object is a window type |
+| `imports` | detected | All QML import statements across every file |
+| `quickshell_modules` | detected / unknown | Imports starting with `Quickshell` |
+| `quickshell_version` | inferred / unknown | Version string from `Quickshell` import versions |
+| `qt_version` | inferred / unknown | Version string from `Qt*` module import versions |
+| `compositor` | inferred / unknown | Quickshell integration namespaces (e.g. `Hyprland`) |
+| `config_paths` | detected | Config files at the project root |
+| `dependencies` | detected | All distinct import modules |
+| `conventions` | inferred | Naming, layout, structure patterns |
+| `components` | detected / unknown | QML files under `components/` or `widgets/` dirs |
+| `services` | detected / inferred / unknown | `Quickshell.Services.*` imports + `*Service`-named objects |
+| `runtime_dependencies` | detected / inferred / unknown | Runtime-hook QML types (Process, IpcHandler, ...) + config keyword hints |
+| `environment` | inferred / unknown | `process.env.*` variables referenced in QML |
+
+### Status semantics
+
+- **detected** — directly observed in the filesystem (file lists, import statements)
+- **inferred** — derived from detected data (version strings, compositor, conventions)
+- **unknown** — no data could be found (no QML files, no version-bearing imports)
+
+### Design rules
+
+- **Never fabricates.** A field without data is `None` / `[]` with status `"unknown"`.
+- **Lazy by default.** `discover({needs})` computes only the requested fields.
+- **Instance-cached.** Repeated `discover()` calls on the same `_ProjectContext` reuse precomputed values.
+- **Shared-cached.** The expensive file-tree scan is cached in the 30-minute in-memory cache keyed by the resolved root path, so a second `_build_project_context` for the same directory skips re-scanning.
+- **No HTTP.** ProjectContext is purely local-filesystem: it walks the tree and parses QML text. Any version resolution against the live site is the caller's responsibility.
+- **Compositor-independent.** The compositor field reports Quickshell integration namespaces (e.g. `Hyprland`) from `Quickshell.<Name>` imports after excluding core namespaces. No compositor-name list is hardcoded.
+
+### Adding a new field
+
+1. Add the field name to `_ALL_FIELDS` in `project.py`.
+2. Add a `_discover_<name>` method that calls `_set(...)` or `_set_inferred(...)`.
+3. Call `_scan()` for the raw file/import data; derive your field from it.
+4. Add a test in `tests/test_project.py`.
+
 ## MCP client configuration
 
 ```json
@@ -150,7 +210,9 @@ Scoped Commits (`<scope>: <description>`). Small diffs, one logical change per c
 > ⚠️ A semantic-release CI runs on every merge to `main`. Every commit defaults to a **patch** release. A new feature/tool must signal a minor bump explicitly — there is no type-prefix heuristic anymore. Forgetting `Semver: minor` on a new tool means no minor release.
 
 - `Semver: minor` — new feature, tool, or user-facing addition
-- `BREAKING CHANGE: <description>` — breaking API/config change
+- `Semver: major` — breaking API/config change (preferred over `BREAKING CHANGE:`)
+
+Both are matched as trailing lines in the commit body, e.g. a final `Semver: minor` line. Matching requires a literal colon after `Semver:`/`BREAKING CHANGE:`, so prose that merely *mentions* "BREAKING CHANGE" or "Semver" never triggers a bump.
 
 Example:
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickshell-mcp
-Version: 2.0.0
+Version: 2.2.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
@@ -417,6 +417,22 @@ Use `refresh=True` to bypass the short-lived cache where supported. The cache lo
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, workflow, and how to submit changes.
 
+### Internal architecture
+
+The server is structured into four layers:
+
+```
+MCP tool (server.py, tool registration + docstrings)
+    ↓
+capabilities/ (domain layer: knowledge, validation, generation, migration, debugging, assistant)
+    ↓
+sources/ (shared services: data-source access, index building, parsing, compatibility)
+    ↓
+config, caches, utils, versions, extraction (infrastructure)
+```
+
+Each capability module declares its tools and its explicit dependencies on other capabilities. The dependency graph is acyclic and verified by `tests/test_capabilities.py`. Planned capabilities (project, runtime, inspection, testing, performance) are documented in the registry; no empty modules are created until features land.
+
 ## Limitations
 
 - Validation is static and heuristic; it complements `qmlls`.

{quickshell_mcp-2.0.0 → quickshell_mcp-2.2.0}/README.md

@@ -380,6 +380,22 @@ Use `refresh=True` to bypass the short-lived cache where supported. The cache lo
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, workflow, and how to submit changes.
 
+### Internal architecture
+
+The server is structured into four layers:
+
+```
+MCP tool (server.py, tool registration + docstrings)
+    ↓
+capabilities/ (domain layer: knowledge, validation, generation, migration, debugging, assistant)
+    ↓
+sources/ (shared services: data-source access, index building, parsing, compatibility)
+    ↓
+config, caches, utils, versions, extraction (infrastructure)
+```
+
+Each capability module declares its tools and its explicit dependencies on other capabilities. The dependency graph is acyclic and verified by `tests/test_capabilities.py`. Planned capabilities (project, runtime, inspection, testing, performance) are documented in the registry; no empty modules are created until features land.
+
 ## Limitations
 
 - Validation is static and heuristic; it complements `qmlls`.

{quickshell_mcp-2.0.0 → quickshell_mcp-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quickshell-mcp"
-version = "2.0.0"
+version = "2.2.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/capabilities/__init__.py

@@ -0,0 +1,36 @@
+"""Capability / domain layer.
+
+Each capability module sits between the MCP tool wrappers in ``server.py``
+and the shared services in ``sources/``.  Capabilities own the tool-to-domain
+mapping, declare explicit inter-capability dependencies, and re-export the
+entry-point helpers that the tool wrappers call.
+
+The dependency graph among implemented capabilities is acyclic:
+
+    knowledge (root)
+        ├── validation
+        ├── debugging
+    validation ──┬── generation
+                 └── migration
+    knowledge, validation, debugging, generation, migration ── assistant
+"""
+
+from . import (
+    assistant,
+    debugging,
+    generation,
+    knowledge,
+    migration,
+    registry,
+    validation,
+)
+
+__all__ = [
+    "assistant",
+    "debugging",
+    "generation",
+    "knowledge",
+    "migration",
+    "registry",
+    "validation",
+]

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/assistant.py

@@ -0,0 +1,28 @@
+"""The assistant capability: orchestrate a plain-language request across every
+other capability.
+
+Depends on: knowledge, validation, generation, migration, debugging.
+"""
+
+from __future__ import annotations
+
+from ..sources.assistant import (  # noqa: F401
+    _classify_intent,
+    _coding_assistant,
+    _detect_compositor,
+    _project_info,
+    _resolve_version_hint,
+    _safe_step,
+)
+from ..sources.project import _build_project_context  # noqa: F401
+
+CAPABILITY_NAME = "assistant"
+CAPABILITY_TOOLS = ("quickshell_coding_assistant",)
+CAPABILITY_DEPENDS_ON = (
+    "knowledge",
+    "validation",
+    "generation",
+    "migration",
+    "debugging",
+    "project",
+)

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/debugging.py

@@ -0,0 +1,16 @@
+"""The debugging capability: explain QML errors and suggest fixes.
+
+Depends on: knowledge (debugging uses the docs and Qt indexes).
+"""
+
+from __future__ import annotations
+
+from ..sources.explain_error import (  # noqa: F401
+    _categorize_error,
+    _explain_error,
+    _extract_type_from_code,
+)
+
+CAPABILITY_NAME = "debugging"
+CAPABILITY_TOOLS = ("quickshell_explain_error",)
+CAPABILITY_DEPENDS_ON = ("knowledge",)

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/generation.py

@@ -0,0 +1,28 @@
+"""The generation capability: produce grounded QML component code.
+
+Depends on: knowledge, validation (generation uses compat, find_pattern,
+search_all, and validate).
+"""
+
+from __future__ import annotations
+
+from ..sources.generate import (  # noqa: F401
+    _build_section,
+    _generate_component,
+    _generate_panel,
+    _generate_service,
+    _interpret_component_query,
+)
+from ..sources.refactor import _apply_patch, _refactor  # noqa: F401
+from ..sources.style_match import _style_match  # noqa: F401
+
+CAPABILITY_NAME = "generation"
+CAPABILITY_TOOLS = (
+    "quickshell_generate_component",
+    "quickshell_generate_service",
+    "quickshell_generate_panel",
+    "quickshell_refactor",
+    "quickshell_apply_patch",
+    "quickshell_style_match",
+)
+CAPABILITY_DEPENDS_ON = ("knowledge", "validation")

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/knowledge.py

@@ -0,0 +1,71 @@
+"""The knowledge capability: read and search Quickshell docs, Qt types,
+official examples, and real-world implementations.
+
+Depends on: (none in the capability layer — pulls directly from shared services).
+"""
+
+from __future__ import annotations
+
+from ..sources.docs import (  # noqa: F401
+    GUIDE_LINK_RE,
+    TYPE_LINK_RE,
+    _build_index,
+    _guide_content_index,
+    _guide_page,
+    _resolve_version,
+    _search_guide_content,
+    _search_type_content,
+    _type_page,
+)
+from ..sources.examples import (  # noqa: F401
+    _example_file,
+    _examples_branch,
+    _examples_known_paths,
+    _examples_listing,
+)
+from ..sources.find_pattern import _find_pattern, _interpret_query  # noqa: F401
+from ..sources.implementations import (  # noqa: F401
+    _GITHUB_API,
+    _IMPL_QUERY_STOPWORDS,
+    _IMPL_TOPICS,
+    _impl_branch,
+    _impl_component,
+    _impl_entry_meta,
+    _impl_file,
+    _impl_repo_config,
+    _impl_topics_for_query,
+    _norm_source,
+    _search_implementations,
+)
+from ..sources.qt_docs import (  # noqa: F401
+    _QT_ANCHOR_RE,
+    _QT_MODULE_LINK_RE,
+    _QT_TYPE_LINK_RE,
+    _VALUE_TYPES_BUCKET,
+    _build_qt_index,
+    _normalize_qt_module,
+    _qt_type_page,
+    _resolve_qt_slug,
+)
+from ..sources.search_all import _search_everything  # noqa: F401
+
+CAPABILITY_NAME = "knowledge"
+CAPABILITY_TOOLS = (
+    "quickshell_list_versions",
+    "quickshell_about",
+    "quickshell_changelog",
+    "quickshell_list_guide_pages",
+    "quickshell_get_guide_page",
+    "quickshell_list_types",
+    "quickshell_get_type",
+    "quickshell_search",
+    "quickshell_search_all",
+    "quickshell_find_pattern",
+    "quickshell_list_qt_types",
+    "quickshell_get_qt_type",
+    "quickshell_list_examples",
+    "quickshell_get_example",
+    "quickshell_search_implementations",
+    "quickshell_get_implementation",
+)
+CAPABILITY_DEPENDS_ON: tuple[str, ...] = ()

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/migration.py

@@ -0,0 +1,19 @@
+"""The migration capability: analyse what code must change between versions.
+
+Depends on: knowledge, validation (migration uses compat, docs, and validate).
+"""
+
+from __future__ import annotations
+
+from ..sources.migrate import (  # noqa: F401
+    _behavioral_scan,
+    _collect_api_refs,
+    _import_diff,
+    _migrate,
+    _migration_plan,
+    _symbol_issue,
+)
+
+CAPABILITY_NAME = "migration"
+CAPABILITY_TOOLS = ("quickshell_migrate",)
+CAPABILITY_DEPENDS_ON = ("knowledge", "validation")

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/project.py

@@ -0,0 +1,45 @@
+"""The project capability: analyze a Quickshell project on disk.
+
+Provides structured project intelligence built on the shared
+``ProjectContext``: an overview, a static relationship map, project-scoped
+search, dependency classification, and config-convention detection. All
+tools are read-only and never modify the project.
+
+Depends on: knowledge (project search reuses the shared search/index
+infrastructure).
+"""
+
+from __future__ import annotations
+
+from ..sources.project import (  # noqa: F401
+    _ALL_FIELDS,
+    _build_project_context,
+    _ProjectContext,
+)
+from ..sources.project_intel import (  # noqa: F401
+    _analyze_project,
+    _config_conventions,
+    _map_project,
+    _project_dependencies,
+    _search_project,
+)
+from ..sources.project_validate import (  # noqa: F401
+    _lint_project,
+    _migrate_project,
+    _project_compatibility,
+    _validate_project,
+)
+
+CAPABILITY_NAME = "project"
+CAPABILITY_TOOLS = (
+    "quickshell_project_analyze",
+    "quickshell_project_map",
+    "quickshell_project_find",
+    "quickshell_project_dependencies",
+    "quickshell_project_config",
+    "quickshell_project_validate",
+    "quickshell_project_lint",
+    "quickshell_project_compatibility",
+    "quickshell_project_migrate",
+)
+CAPABILITY_DEPENDS_ON = ("knowledge", "validation")

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/registry.py

@@ -0,0 +1,167 @@
+"""Capability registry: the boundary map between MCP tools and the domain layer.
+
+Each capability module (``knowledge``, ``validation``, ``generation``,
+``migration``, ``debugging``, ``assistant``) declares which tools it owns and
+which other capabilities it depends on. This module aggregates those
+declarations into a single map plus a cycle-checked topological ordering, so
+server.py and tests can answer "which capability owns this tool?" and prove
+the capability graph is acyclic.
+
+Capabilities that are planned but not implemented yet (runtime, inspection,
+testing, performance) are registered with ``status="planned"`` and no tools.
+No modules are created for them until the features land.
+
+Every capability carries a ``safety_level``:
+
+* **read-only** — analysis only; no state changes, no file writes, no process
+  execution (default for all capabilities today).
+* **mutating** — alters live state (runtime sessions, explicit file writes via
+  ``apply_patch``). Requires explicit invocation.
+* **high-risk** — arbitrary evaluation or destructive filesystem operations.
+  Reserved for future eval/patch capabilities; not yet assigned.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import assistant, debugging, generation, knowledge, migration, project, validation
+
+__all__ = [
+    "ALL_CAPABILITIES",
+    "CAPABILITIES",
+    "Capability",
+    "PLANNED_CAPABILITIES",
+    "SAFETY_LEVELS",
+    "capability_for_tool",
+    "classify_capability",
+    "dependency_order",
+    "safety_level_for_tool",
+]
+
+
+@dataclass(frozen=True)
+class Capability:
+    name: str
+    tools: tuple[str, ...]
+    depends_on: tuple[str, ...]
+    status: str = "implemented"
+    safety_level: str = "read-only"
+
+
+# Mutating capabilities alter live state rather than only reading project/docs.
+# high-risk is not yet assigned to any capability; it is reserved for future
+# evaluation/patch capabilities.
+_MUTATING_CAPABILITIES = ("runtime", "testing")
+
+# Per-tool safety overrides.  A tool listed here overrides its owning
+# capability's default safety level.
+_TOOL_SAFETY_LEVELS: dict[str, str] = {
+    "quickshell_apply_patch": "mutating",
+}
+
+
+def _safety_level(name: str) -> str:
+    return "mutating" if name in _MUTATING_CAPABILITIES else "read-only"
+
+
+_CAPABILITY_MODULES = (
+    knowledge,
+    validation,
+    generation,
+    migration,
+    debugging,
+    project,
+    assistant,
+)
+
+CAPABILITIES: dict[str, Capability] = {
+    mod.CAPABILITY_NAME: Capability(
+        name=mod.CAPABILITY_NAME,
+        tools=mod.CAPABILITY_TOOLS,
+        depends_on=mod.CAPABILITY_DEPENDS_ON,
+        safety_level=_safety_level(mod.CAPABILITY_NAME),
+    )
+    for mod in _CAPABILITY_MODULES
+}
+
+PLANNED_CAPABILITIES: dict[str, Capability] = {
+    name: Capability(
+        name=name,
+        tools=(),
+        depends_on=(),
+        status="planned",
+        safety_level=_safety_level(name),
+    )
+    for name in ("runtime", "inspection", "testing", "performance")
+}
+
+ALL_CAPABILITIES: dict[str, Capability] = {**CAPABILITIES, **PLANNED_CAPABILITIES}
+
+# Convenience dict derived from the authoritative dataclass fields.
+SAFETY_LEVELS: dict[str, str] = {name: cap.safety_level for name, cap in ALL_CAPABILITIES.items()}
+
+# `quickshell_stats` reports session telemetry and lives entirely in server.py;
+# it is not owned by any domain capability.
+_SYSTEM_TOOLS = ("quickshell_stats",)
+
+
+def capability_for_tool(tool: str) -> str | None:
+    """Return the capability that owns *tool*, or None for system tools."""
+    for cap in CAPABILITIES.values():
+        if tool in cap.tools:
+            return cap.name
+    return None
+
+
+def classify_capability(name: str) -> str:
+    """Return the safety level of a registered capability.
+
+    Levels: ``read-only`` (analysis), ``mutating`` (changes live state),
+    ``high-risk`` (arbitrary evaluation or file mutation; not yet assigned).
+    """
+    cap = ALL_CAPABILITIES.get(name)
+    if cap is None:
+        raise ValueError(f"Unknown capability '{name}'")
+    return cap.safety_level
+
+
+def safety_level_for_tool(tool: str) -> str:
+    """Return the safety level of the capability owning *tool*.
+
+    A per-tool override (``_TOOL_SAFETY_LEVELS``) wins; otherwise the level
+    is inherited from the owning capability. System tools (e.g.
+    ``quickshell_stats``) are telemetry and are always classified read-only.
+    """
+    if tool in _TOOL_SAFETY_LEVELS:
+        return _TOOL_SAFETY_LEVELS[tool]
+    cap = capability_for_tool(tool)
+    if cap is not None:
+        return classify_capability(cap)
+    if tool in _SYSTEM_TOOLS:
+        return "read-only"
+    raise ValueError(f"Unknown tool '{tool}'")
+
+
+def dependency_order() -> list[str]:
+    """Topologically order the implemented capabilities (raises on a cycle)."""
+    graph = {name: set(cap.depends_on) for name, cap in CAPABILITIES.items()}
+    for name, deps in graph.items():
+        missing = deps - set(CAPABILITIES)
+        if missing:
+            raise ValueError(f"capability {name!r} depends on unregistered {sorted(missing)!r}")
+    order: list[str] = []
+    resolved: set[str] = set()
+    while len(order) < len(graph):
+        progress = False
+        for name, deps in graph.items():
+            if name in resolved:
+                continue
+            if deps <= resolved:
+                order.append(name)
+                resolved.add(name)
+                progress = True
+        if not progress:
+            cycle = sorted(set(graph) - resolved)
+            raise ValueError(f"circular capability dependency: {cycle}")
+    return order

quickshell_mcp-2.2.0/quickshell_mcp/capabilities/validation.py

@@ -0,0 +1,32 @@
+"""The validation capability: statically validate QML against the docs and
+check version compatibility.
+
+Depends on: knowledge (validation builds on the type/guide indexes).
+"""
+
+from __future__ import annotations
+
+from ..sources.compat import (  # noqa: F401
+    _api_in_version,
+    _changelog_hits,
+    _changelog_sections,
+    _check_compatibility,
+    _compat_at,
+    _compat_from_code,
+    _incorporate_range,
+    _parse_api_ref,
+    _scan_versions,
+)
+from ..sources.validate import (  # noqa: F401
+    _parse_members,
+    _parse_structure,
+    _tokenize,
+    _validate,
+)
+
+CAPABILITY_NAME = "validation"
+CAPABILITY_TOOLS = (
+    "quickshell_validate_qml",
+    "quickshell_check_compatibility",
+)
+CAPABILITY_DEPENDS_ON = ("knowledge",)