git clone https://github.com/franklinnolasco7/quickshell-mcp
cd quickshell-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

nix run github:franklinnolasco7/quickshell-mcp

docker build -t quickshell-mcp .
docker run --rm -i quickshell-mcp     # speaks MCP over stdio

Static validation

quickshell_validate_qml checks QML against the same Quickshell and Qt documentation indexes the other tools use. It catches:

• Unknown Quickshell and Qt types
• Unknown properties, methods, and signals
• Missing imports
• Obvious type mismatches
• APIs unavailable in the requested Quickshell version

quickshell_validate_qml complements qmlls; it does not replace it. Dynamic JavaScript and local component resolution are outside its scope.

{"source": "PanelWindow { foo: 123 }", "version": "latest", "filename": "panel.qml"}

Version compatibility

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).

It 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.

{"api": "PanelWindow.exclusiveZone", "version": "v0.2.0"}
{"api": "Quickshell.shellRoot", "version": "v0.3.1"}
{"code": "PanelWindow { exclusiveZone: 1 }", "version": "v0.1.0"}

The 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.

Migrating between versions

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).

It 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).

The tool analyzes and recommends; it never rewrites code or files.

{
  "code": "Quickshell { shellRoot: \"/tmp\" }\nPanelWindow { exclusiveZone: 1 }",
  "from_version": "v0.1.0",
  "to_version": "v0.3.1"
}

The report includes the overall verdict (compatible, changes_required, uncertain), the per-issue findings, and an ordered migration plan.

Component generation

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".

{"description": "volume OSD", "version": "latest", "compositor": "hyprland"}

The 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.

The result includes the generated QML plus:

• dependencies: imports, required Quickshell types, and Qt types
• verified_surface: the documented properties/methods/signals of every type the component uses, so you can rewrite the QML against verified members
• integration: compositor and external-service requirements (Hyprland socket, PipeWire, a notification daemon, ...)
• verification: per-API compatibility verdicts and an overall verified/unverified flag
• validation: the diagnostics from the static validator
• references: documentation, official examples, and real-world implementations to compare against
• assumptions: the conservative choices made (default palette, unrecognized compositor, requested windows that were not embedded)

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.