{
"markdown": "\n\n# quickshell-mcp\n\n**An MCP server that connects AI coding agents to live Quickshell, QML, and Qt documentation.**\n\n[](LICENSE)\n[](https://pypi.org/project/quickshell-mcp/)\n[](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.franklinnolasco7%2Fquickshell-mcp/versions/latest)\n[](https://github.com/franklinnolasco7/quickshell-mcp/blob/main/pyproject.toml)\n[](https://codecov.io/gh/franklinnolasco7/quickshell-mcp)\n[](https://github.com/franklinnolasco7/quickshell-mcp/actions/workflows/ci.yml)\n\n---\n\nSearch APIs, discover implementation patterns, explain errors, validate QML, inspect a project, run tests, and profile a live shell **before** your agent writes or runs code.\n\n## Why\n\nQuickshell changes quickly, and AI coding agents can generate QML from outdated or incomplete training data. `quickshell-mcp` lets agents verify APIs against current documentation, find existing implementation patterns, validate generated QML, and inspect or test a project instead of guessing from memory.\n\n> [!IMPORTANT]\n> When sources disagree, official documentation always takes precedence.\n\n## Table of Contents\n\n- [Quick start](#quick-start)\n- [What it provides](#what-it-provides)\n- [External tools](#external-tools)\n- [Knowledge sources](#knowledge-sources)\n- [Configure](#configure)\n- [Tools](#tools)\n- [Typical workflow](#typical-workflow)\n- [Advanced usage](#advanced-usage)\n- [Source priority](#source-priority)\n- [Caching](#caching)\n- [References](#references)\n- [Limitations](#limitations)\n- [License](#license)\n\n## Quick start\n\n```bash\npip install quickshell-mcp # or: uvx quickshell-mcp\n```\n\nThen point your MCP client at it (see [Configure](#configure) below).\n\nAlso installable via the [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.franklinnolasco7%2Fquickshell-mcp/versions/latest).\n\n\nInstall from source
\n\n```bash\ngit clone https://github.com/franklinnolasco7/quickshell-mcp\ncd quickshell-mcp\npython3 -m venv .venv && source .venv/bin/activate\npip install -e .\n```\n \n\n\nInstall with Nix
\n\n```bash\nnix run github:franklinnolasco7/quickshell-mcp\n```\n \n\n\nInstall with Docker
\n\n```bash\ndocker build -t quickshell-mcp .\ndocker run --rm -i quickshell-mcp # speaks MCP over stdio\n```\n \n\n## What it provides\n\n| | |\n|---|---|\n| **Quickshell docs** | Version-aware type references, guides, and changelogs |\n| **Qt/QML docs** | QtQuick, Controls, Layouts, and other base types |\n| **Official examples** | Working Quickshell example configurations |\n| **Real-world implementations** | Searchable Caelestia, Noctalia, and dots-hyprland patterns |\n| **Error explanations** | Grounded diagnosis of QML and Quickshell errors |\n| **QML validation** | Static checks for types, properties, signals, imports, and version compatibility |\n| **Version compatibility** | Whether an API or QML snippet works on a specific Quickshell release |\n| **Migration** | Analyze what a QML config must change to keep working after an upgrade |\n| **Component generation** | Minimal, source-grounded QML components from a plain-language description |\n| **Project intelligence** | Analyze, map, search, and classify a project on disk |\n| **Project validation** | Validate, lint, check compatibility, and migrate a whole project per file |\n| **Runtime sessions** | Start and inspect isolated `qs` processes, opt-in and mutating |\n| **Visual and UI inspection** | Windows, screenshots, UI tree, properties, and snapshots |\n| **Runtime testing** | Machine-readable test steps, suites, and assertions against a live session |\n| **Performance profiling** | Bounded sampling plus static component, binding, and timer analysis |\n| **Desktop adapters** | Read-only Hyprland, PipeWire, D-Bus, and system inspection |\n| **Knowledge 2.0** | Version diffs, API graphs, best practices, pattern comparison, provenance |\n| **Intelligence** | Project memory, architecture recommendations, regression detection, task plans |\n| **Agent orchestration** | Build, debug, migrate, test, and optimize a feature end to end |\n| **Coding assistant** | One plain-language request routed through the right tools, returning a structured, source-grounded result |\n| **CI entrypoints** | Headless validation, screenshot, runtime-test, compat, and migration scripts |\n\n## External tools\n\nMost tools need nothing beyond the `quickshell-mcp` package. The ones that inspect a real desktop detect their dependency at runtime and report it as unavailable when missing, instead of failing. This applies to runtime sessions, UI inspection, and the desktop adapters.\n\n| Dependency | Used by |\n|---|---|\n| `qs` (Quickshell binary) | Runtime sessions, UI inspection, testing, `qs ipc` |\n| `grim` | Screenshots |\n| ImageMagick (`compare`, `identify`) | Screenshot diff, visual checks |\n| `hyprctl`, `pw-cli`, `busctl` | Desktop adapters (each optional, degrades gracefully) |\n\nThe headless CI shell (`nix develop .#ci`) packages `quickshell`, `weston`, `grim`, and `imagemagick` for running runtime-test and screenshot jobs without a desktop.\n\n## Knowledge sources\n\nSix sources back the server: Quickshell docs, Qt/QML docs, official Quickshell examples, and three real-world shells (Caelestia, Noctalia, dots-hyprland). The shells are practical reference material, not authoritative API definitions. See [Source priority](#source-priority) for how conflicts resolve.\n\n## Configure\n\n**opencode** (`opencode.json`):\n\n```json\n{\n \"mcp\": {\n \"quickshell\": {\n \"type\": \"local\",\n \"command\": [\"/absolute/path/to/quickshell-mcp/.venv/bin/quickshell-mcp\"],\n \"enabled\": true\n }\n }\n}\n```\n\n**Claude Desktop**: same JSON under `claude_desktop_config.json`, wrapped in `mcpServers`.\n\nFor HTTP transport, set `QUICKSHELL_DOCS_MCP_TRANSPORT=http` (plus optional `HOST`/`PORT`).\n\n> [!TIP]\n> Set `QUICKSHELL_DOCS_MCP_LOG=DEBUG` for verbose request logging on stderr.\n>\n> The `QUICKSHELL_DOCS_MCP_*` environment variable prefix is retained for backwards compatibility with earlier releases.\n\n## Tools\n\nFor the full per-tool list, grouped by capability with mutating and high-risk tools flagged, see [docs/TOOLS.md](docs/TOOLS.md).\n\n## Typical workflow\n\n```mermaid\nflowchart TD\n A[Search] --> B[Find implementation pattern]\n B --> C[Verify API]\n C --> D[Write QML]\n D --> E[Validate]\n E -->|errors| F[Fix errors]\n F --> E\n E -->|clean| G[Done]\n\n classDef discover fill:#cdeaff,stroke:#1c6dd0,stroke-width:1px,color:#0b3661\n classDef build fill:#ffe3c2,stroke:#d8871b,stroke-width:1px,color:#5c3a05\n classDef check fill:#c9f2d8,stroke:#1f9e5c,stroke-width:1px,color:#0b3d24\n classDef fix fill:#ffd1d1,stroke:#d13b3b,stroke-width:1px,color:#5c0b0b\n classDef done fill:#e3d6ff,stroke:#7b3ff0,stroke-width:2px,color:#2f1466\n\n class A,B,C discover\n class D build\n class E check\n class F fix\n class G done\n```\n\n### Example\n\nInstead of asking an AI agent to guess how to create a workspace indicator in Quickshell, the agent can search for the API, find existing implementations, verify the requested version, generate the QML, and validate it before running it:\n\n```mermaid\nflowchart LR\n A[quickshell_search_all] --> B[quickshell_find_pattern]\n B --> C[quickshell_list_versions /
quickshell_get_type]\n C --> D[quickshell_generate_component]\n D --> E[quickshell_validate_qml]\n E --> F[quickshell_explain_error]\n\n classDef tool fill:#cdeaff,stroke:#1c6dd0,stroke-width:1px,color:#0b3661\n classDef action fill:#ffe3c2,stroke:#d8871b,stroke-width:1px,color:#5c3a05\n classDef debug fill:#ffd1d1,stroke:#d13b3b,stroke-width:1px,color:#5c0b0b\n\n class A,B,C tool\n class D,E action\n class F debug\n```\n\n## Advanced usage\n\n\nStatic validation, version compatibility, migration, component generation, and the coding assistant: catch bad QML, verify API support per release, plan upgrades, generate components, or route a whole development task through the assistant
\n\n### Static validation\n\n`quickshell_validate_qml` checks QML against the same Quickshell and Qt documentation indexes the other tools use. It catches:\n\n- Unknown Quickshell and Qt types\n- Unknown properties, methods, and signals\n- Missing imports\n- Obvious type mismatches\n- APIs unavailable in the requested Quickshell version\n\n> `quickshell_validate_qml` complements `qmlls`; it does not replace it. Dynamic JavaScript and local component resolution are outside its scope.\n\n```json\n{\"source\": \"PanelWindow { foo: 123 }\", \"version\": \"latest\", \"filename\": \"panel.qml\"}\n```\n\n### Version compatibility\n\n`quickshell_check_compatibility` checks whether a Quickshell API, QML property/method/signal, type, or whole snippet works on a specific release. Pass one of `api`, `type`, or `code`; choose the release with `version` (or use `from_version`/`to_version` for a range).\n\nIt does not judge from the latest docs page alone. It cross-references the requested version's type index and pages plus the changelog, and returns `uncertain` when the evidence is not enough. Qt/QML types (Rectangle, Item, ...) show as `compatible` with `origin: \"qt\"`, because your Qt version sets their availability, not the Quickshell one.\n\n```json\n{\"api\": \"PanelWindow.exclusiveZone\", \"version\": \"v0.2.0\"}\n{\"api\": \"Quickshell.shellRoot\", \"version\": \"v0.3.1\"}\n{\"code\": \"PanelWindow { exclusiveZone: 1 }\", \"version\": \"v0.1.0\"}\n```\n\nThe result includes the verdict, the version evidence (earliest/latest known), any rename or change with a likely replacement, the matching changelog entry, and cited documentation URLs.\n\n### Migrating between versions\n\n`quickshell_migrate` analyzes what a QML config must change to keep working when upgrading from one Quickshell version to another. Pass the QML source (or a single `api`/`type`), plus `from_version` and `to_version` (both required, ordered oldest to newest).\n\nIt reports every removed, renamed, deprecated, or changed API with severity, location, the old and new API, why it must change, a suggested migration, confidence, and a cited source. It also scans the breaking-change changelog entries between the versions that mention the referenced symbols, so a rename that landed at an intermediate release is reported with the version it landed in. Findings are classified `definite` (backed by the docs or changelog), `likely` (documented but low-impact, e.g. deprecation), or `manual_review` (evidence suggests a change but the exact migration is not provable).\n\nThe tool analyzes and recommends; it never rewrites code or files.\n\n```json\n{\n \"code\": \"Quickshell { shellRoot: \\\"/tmp\\\" }\\nPanelWindow { exclusiveZone: 1 }\",\n \"from_version\": \"v0.1.0\",\n \"to_version\": \"v0.3.1\"\n}\n```\n\nThe report includes the overall verdict (`compatible`, `changes_required`, `uncertain`), the per-issue findings, and an ordered migration plan.\n\n### Component generation\n\n`quickshell_generate_component` turns a plain-language description into a minimal QML component, e.g. \"Create a Hyprland workspace indicator\", \"animated volume OSD\", \"top bar with workspaces, clock and system tray\", \"popup control center\", or \"notification popup\".\n\n```json\n{\"description\": \"volume OSD\", \"version\": \"latest\", \"compositor\": \"hyprland\"}\n```\n\nThe generator searches for the request (using the same search and pattern tools as the rest), builds a small component from the section templates, then checks every Quickshell type and property/method it references against the requested version with `quickshell_check_compatibility` and runs the assembled QML through `quickshell_validate_qml`. An API that cannot be verified is shown in the result, not silently emitted, so the output never passes off an unverified API as valid.\n\nThe result includes the generated QML plus:\n\n- `dependencies`: imports, required Quickshell types, and Qt types\n- `verified_surface`: the documented properties/methods/signals of every type the component uses, so you can rewrite the QML against verified members\n- `integration`: compositor and external-service requirements (Hyprland socket, PipeWire, a notification daemon, ...)\n- `verification`: per-API compatibility verdicts and an overall `verified`/`unverified` flag\n- `validation`: the diagnostics from the static validator\n- `references`: documentation, official examples, and real-world implementations to compare against\n- `assumptions`: the conservative choices made (default palette, unrecognized compositor, requested windows that were not embedded)\n\n`compositor=\"hyprland\"` generates Hyprland-specific types; any other value is noted and generates no compositor-specific code. A request that matches no template still returns `verified_surface` plus `references`, so you can compose the component yourself. Each generated file contains one top-level window: if a request mentions several windows (such as a bar and a notification popup), the primary one is generated and the rest are listed under `assumptions` instead of being nested. The tool writes nothing to disk.\n\n### Coding assistant\n\n`quickshell_coding_assistant` is an orchestration layer over the other tools, for tasks that span several of them. Give it one plain-language development request and it runs a fixed pipeline of stages: search, verify, generate, validate, migrate, research (provenance), and optionally execute. Each stage activates only the tools the request needs. The result is structured and source-grounded, with sections for understanding, relevant APIs, recommended approach, implementation references, compatibility, validation, remaining issues, sources, provenance, and a terminal `grounded_result`.\n\n```json\n{\"request\": \"Build a Hyprland workspace bar\"}\n{\"request\": \"Why is this PanelWindow failing?\", \"code\": \"PanelWindow { foo: 1 }\"}\n{\"request\": \"Migrate this shell from v0.2 to v0.3\", \"from_version\": \"v0.2.0\", \"to_version\": \"v0.3.1\"}\n{\"request\": \"Find an implementation of a volume OSD and adapt the pattern\"}\n```\n\nRequests map to five intents, each running the relevant pipeline stages:\n\n- **build** (\"build/add/make a ...\") delegates the search and verify stages to `quickshell_generate_component`, which runs them internally, and its validated QML becomes `grounded_result`.\n- **debug** (\"why is X failing?\", \"fix this error\") runs search (`quickshell_explain_error`) and verify (relevant type page + compatibility), then validate (`quickshell_validate_qml`); `grounded_result` is the diagnosis and fix.\n- **migrate** (\"migrate/upgrade from vX to vY\") runs search (breaking-change changelog when no code is given), validate against the target version, and migrate (`quickshell_migrate`); `grounded_result` is the ordered migration plan.\n- **pattern** (\"find an implementation ... and adapt it\") runs search (`quickshell_find_pattern`, with a short excerpt of the top implementation) and verify (compatibility of the hinted APIs); `grounded_result` is the excerpt plus verified APIs.\n- **research** (\"what is X?\", \"how do I ...?\") runs search (all sources) and verify (top type and guide pages + compatibility); `grounded_result` lists the resolved types and guides.\n\nExecution is off by default: the assistant never modifies files. To let it apply an explicit, validated edit set, pass `permitted_execution=True` together with `edits=[...]` (same shape as `quickshell_apply_patch`) and a `project=` path. Non-permitted requests record an execution step and continue read-only.\n\nVersion and compositor come from the request text (`0.2`, `hyprland`) or from the `version`/`compositor`/`from_version`/`to_version` parameters. Loose version hints resolve at runtime against the published list. Each step runs in isolation, so a failing source shows up in `errors` instead of failing the whole request. The result carries an `orchestration` trace of the tools used and a deduplicated `sources` list. The `basis` tags on approach steps and the `verified` flag on API entries separate verified facts (from the official docs) from recommendations.\n\n**When to use it:** multi-step development requests, or when you do not yet know which single tool fits. For a single, focused lookup (one type page, one error message, one version check) call the specific tool directly; it is cheaper and gives the raw answer.\n\n \n\n\nProject, runtime, inspection, testing, performance, and agents: work on a real project on disk and a live shell
\n\n### Project analysis\n\n`quickshell_project_analyze`, `quickshell_project_map`, and `quickshell_project_find` read a project on disk without executing anything. Analysis marks unknown values explicitly, the map distinguishes confirmed from inferred edges (and reports cycles), and find searches project files with location and context. `quickshell_project_dependencies` classifies imports as required, optional, detected, or missing.\n\n```json\n{\"project\": \"/path/to/shell\"}\n```\n\n`quickshell_project_validate`, `quickshell_project_lint`, `quickshell_project_compatibility`, and `quickshell_project_migrate` run the same engines used by the single-file tools across every QML file, grouped by file and severity. Lint uses an extensible rule table; compatibility never overclaims runtime incompatibility; migrate produces machine-readable proposed edits and never writes.\n\n### Runtime sessions\n\nRuntime tools launch real `qs` processes in isolated XDG directories so a managed shell never touches your desktop session. They are opt-in and mutating, and require `qs` on PATH.\n\n```json\n{\"project\": \"/path/to/shell\", \"entrypoint\": \"main.qml\"}\n```\n\n`quickshell_runtime_start` returns a session id; `quickshell_runtime_status`, `quickshell_runtime_logs`, and `quickshell_runtime_ping` inspect it; `quickshell_runtime_stop` and `quickshell_runtime_reset` manage the lifecycle. Profiles are named and versioned via the ecosystem `quickshell_profile_*` tools and can be reused by start.\n\n### Visual and UI inspection\n\n`quickshell_windows`, `quickshell_ui_tree`, and `quickshell_ui_find` inspect a running session. Screenshots need `grim` and a compositor; UI introspection needs an `inspector` IpcHandler target in the shell. `quickshell_ui_set_property` and `quickshell_ui_invoke` mutate the session through IPC and return the old/new state; `quickshell_ui_eval` is high-risk (explicit opt-in, time-limited, output-bounded) and never touches the filesystem.\n\n### Testing\n\n`quickshell_test` runs a machine-readable test (steps then assertions, screenshot on failure); `quickshell_test_suite` runs several tests in isolation; `quickshell_assert`, `quickshell_test_macro`, and `quickshell_test_record` build up steps; `quickshell_test_report` summarizes a suite.\n\n```json\n{\"session_id\": \"abc123\", \"tests\": [{\"name\": \"bar shows\", \"assertions\": [{\"type\": \"visible\", \"target\": \"bar\"}]}]}\n```\n\n### Performance\n\n`quickshell_profile` samples a session's CPU/memory over a bounded window. `quickshell_profile_component`, `quickshell_profile_bindings`, `quickshell_profile_timers`, and `quickshell_profile_object_tree` analyze a project statically. `quickshell_performance_diagnose` correlates the evidence into hypotheses with confidence, and never attributes cost without evidence.\n\n### Agents\n\n`quickshell_build_feature`, `quickshell_debug`, `quickshell_migrate_project`, `quickshell_test_feature`, `quickshell_optimize`, and `quickshell_engineer` each run an explicit staged plan over the lower-level tools. Every stage is isolated, so one failure never sinks the plan. `quickshell_engineer` composes the whole loop (build, test, debug, optimize, verify) and returns every stage's result plus a flattened plan.\n\n \n\n## Source priority\n\nWhen sources disagree, in order of authority:\n\n1. Official Quickshell documentation\n2. Official Qt documentation\n3. Official Quickshell examples\n4. Real-world implementations\n\nReal-world implementations are practical references, not authoritative API definitions.\n\n## Caching\n\nDocumentation indexes are cached locally under `~/.cache/quickshell-mcp`.\n\n| Cache type | TTL |\n|---|---|\n| Fetched pages (in-memory/disk) | 30 minutes |\n| Bulk documentation indexes (disk) | 30 days |\n\nUse `refresh=True` to bypass the short-lived cache where supported. The cache location and disk TTL can be configured with the existing `QUICKSHELL_DOCS_MCP_*` environment variables.\n\n## References\n\n| Source | URL | What it provides |\n|---|---|---|\n| Quickshell docs | https://quickshell.org | Type references, usage guide, changelog |\n| Qt docs | https://doc.qt.io/qt-6 | QtQuick base types (Rectangle, RowLayout, etc.) |\n| Quickshell examples | https://git.outfoxxed.me/quickshell/quickshell-examples | Official example configs |\n| Caelestia shell | https://github.com/caelestia-dots/shell | Real-world implementation references |\n| Noctalia shell | https://github.com/noctalia-dev/noctalia (legacy-v4) | Real-world implementation references |\n| dots-hyprland | https://github.com/end-4/dots-hyprland | Real-world implementation references (the \"ii\" shell) |\n\n## Development\n\nSee [AGENTS.md](AGENTS.md) for the internal architecture (the four-layer capability/source stack, the CI script list, and coding/commit conventions) and [CONTRIBUTING.md](CONTRIBUTING.md) for setup and workflow.\n\n## Limitations\n\n- Validation is static and heuristic; it complements `qmlls`.\n- Dynamic JavaScript and local component resolution are limited.\n- Official examples may target different Quickshell versions.\n- Deep documentation searches can be slower on a cold cache.\n- Real-world implementations are references and may contain outdated patterns.\n- Runtime and inspection tools are opt-in and need `qs` on PATH; screenshots also need a compositor, and UI introspection needs an `inspector` IpcHandler target.\n\n## License\n\n[MIT](LICENSE)",
"bytes": 22373,
"sha": "8eee8655b581cc2ae7312e10b739b4c330b9164896f675eae20094ed3ff5fbdf",
"repo_slug": "franklinnolasco7/quickshell-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_franklinnolasco7_quickshell_mc_70ca00e8/readme"
}