# Quickshell MCP (pypi · quickshell-mcp)

Source-grounded Quickshell, QML, and Qt documentation, examples, and real-world implementations.

- Trust score: 60/100 (medium)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-09-21

## Components

- pypi · `quickshell-mcp`: 60/100 (this document), [markdown](https://verifymcp.io/servers/franklinnolasco7-quickshell-mcp/quickshell-mcp.md), [page](https://verifymcp.io/servers/franklinnolasco7-quickshell-mcp/quickshell-mcp)

## Channel facts

- Registry: `pypi`
- Package: `quickshell-mcp`
- Version: `2.17.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-09-21.

- **Supply Chain Security**: 50/100
  - Malware scan not yet available for this package.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised native-build step with no shell scripting around it.
  - 0 of 33 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 32/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: the license (MIT License) isn't a recognized OSI-approved license.
  - Actively maintained (last published 21 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 71/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 10693 tokens (~104/item across 102 items; 102 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 83/100
  - Stability observed for 25 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 71/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
  - Structured output schemas are declared (7% of tools); any adoption earns full credit.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 2 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "quickshell_ui_eval" implies "eval" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 102 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the Quickshell MCP server?

Quickshell MCP runs locally as a PyPI package, launched with uvx quickshell-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add franklinnolasco7-quickshell-mcp -- uvx quickshell-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "franklinnolasco7-quickshell-mcp": {
      "command": "uvx",
      "args": [
        "quickshell-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "franklinnolasco7-quickshell-mcp": {
      "command": "uvx",
      "args": [
        "quickshell-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add franklinnolasco7-quickshell-mcp -- uvx quickshell-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "franklinnolasco7-quickshell-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "quickshell-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add franklinnolasco7-quickshell-mcp --command uvx --arg quickshell-mcp
```

### Hermes

```yaml
mcp_servers:
  franklinnolasco7-quickshell-mcp:
    command: "uvx"
    args: ["quickshell-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "franklinnolasco7-quickshell-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "quickshell-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add franklinnolasco7-quickshell-mcp -t stdio -c uvx -a quickshell-mcp
```

### Other

```json
{
  "mcpServers": {
    "franklinnolasco7-quickshell-mcp": {
      "command": "uvx",
      "args": [
        "quickshell-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-09-21 (score 60, 0)

- [functional regression] Security disclosure: fail → unverified

### 2026-09-20 (score 60, +1)

No change was recorded against any check on this day. Stability & Change Management went from 77 to 80. That category is still filling its 30-day observation window: 23 days of observed history at the previous scan, 24 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-18 (score 59, +1)

No change was recorded against any check on this day. Stability & Change Management went from 70 to 73. That category is still filling its 30-day observation window: 21 days of observed history at the previous scan, 22 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-16 (score 58, +1)

No change was recorded against any check on this day. Stability & Change Management went from 63 to 67. That category is still filling its 30-day observation window: 19 days of observed history at the previous scan, 20 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-14 (score 57, +1)

No change was recorded against any check on this day. Stability & Change Management went from 57 to 60. That category is still filling its 30-day observation window: 17 days of observed history at the previous scan, 18 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-12 (score 56, +1)

No change was recorded against any check on this day. Stability & Change Management went from 50 to 53. That category is still filling its 30-day observation window: 15 days of observed history at the previous scan, 16 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-10 (score 55, +1)

No change was recorded against any check on this day. Stability & Change Management went from 43 to 47. That category is still filling its 30-day observation window: 13 days of observed history at the previous scan, 14 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-07 (score 54, −14)

- [security regression] Malware scan: pass → unverified

## MCP tools (102)

### `quickshell_list_versions` (~67 tokens)

List all Quickshell documentation versions currently published on
quickshell.org, newest first, and report which one is latest.
Use this before fetching a page if you're unsure which version to use.
Set refresh=True to bypass the in-process cache.

Input parameters:

- `refresh` (boolean)

### `quickshell_about` (~53 tokens)

Fetch the Quickshell 'About' page (https://quickshell.org/about/) as
Markdown. Use this for high-level questions like what Quickshell is,
who maintains it, and how it's licensed.

Output parameters:

- `result` (string)

### `quickshell_changelog` (~45 tokens)

Fetch the Quickshell changelog (https://quickshell.org/changelog/) as
Markdown. Use this to answer 'what's new / what changed' questions.

Output parameters:

- `result` (string)

### `quickshell_list_guide_pages` (~77 tokens)

List the Usage Guide pages available for a given doc version
(e.g. install-setup, introduction, size-position, qml-language,
advanced, faq). Defaults to the latest version if none given.
Set refresh=True to bypass the in-process cache.

Input parameters:

- `refresh` (boolean)
- `version` (string)

### `quickshell_get_guide_page` (~73 tokens)

Fetch one Usage Guide page as Markdown, e.g. slug='introduction' or
slug='qml-language'. Call quickshell_list_guide_pages first if you don't
know the exact slug. Defaults to the latest doc version.

Input parameters:

- `slug` (string, required)
- `version` (string)

Output parameters:

- `result` (string)

### `quickshell_list_types` (~100 tokens)

List Quickshell QML types, optionally filtered to one namespace
(e.g. 'Quickshell.Hyprland', 'Quickshell.Io', 'Quickshell.Services.Pipewire').
Call with no namespace to see every namespace and its types.
Defaults to the latest doc version.
Set refresh=True to bypass the in-process cache.

Input parameters:

- `namespace`
- `refresh` (boolean)
- `version` (string)

### `quickshell_get_type` (~110 tokens)

Fetch the documentation page for one QML type as Markdown, e.g.
type_name='PanelWindow', namespace='Quickshell', or
type_name='HyprlandMonitor', namespace='Quickshell.Hyprland'.
Call quickshell_list_types first if you're unsure of the exact
namespace or type name (they are case-sensitive). Defaults to the
latest doc version.

Input parameters:

- `namespace` (string)
- `type_name` (string, required)
- `version` (string)

Output parameters:

- `result` (string)

### `quickshell_search` (~483 tokens)

Search Quickshell type names, namespaces, and guide page slugs for a
substring match (case-insensitive). ALWAYS call this before writing any
QML that references a Quickshell type or property from memory; never
guess property/type names, verify them here first.

Use this whenever a request mentions a desktop-shell feature and you
don't already know the exact Quickshell type name, e.g.:
\- "battery" / "power" / "upower"       -> search 'battery' or 'power' (UPower, UPowerDevice)
\- "volume" / "audio" / "mixer"         -> search 'audio' or 'volume' (Pipewire, PwNode)
\- "tray" / "system tray"               -> search 'tray' (SystemTray, SystemTrayItem)
\- "workspaces" / "monitor"             -> search 'monitor' or 'workspace'
  (HyprlandMonitor, HyprlandWorkspace, I3Monitor)
\- "notifications"                      -> search 'notification'
  (Notification, NotificationServer)
\- "network" / "wifi"                   -> search 'wifi' or 'network' (WifiDevice, Network)
\- "bluetooth"                          -> search 'bluetooth' (Bluetooth, BluetoothDevice)
\- "clock" / "date" / "time"            -> search 'clock' (SystemClock)

For concept/how-to questions where the answer is prose rather than a
type name ("where is IPC documented?", "how do anchors work?"), pass
include_content=True; this also full-text-searches the guide-page
bodies. Pass include_type_pages=True to also deep-search the ~200 type
reference pages for property/method/signal text (slower: first call
fetches every type page once, then it's cached).

Returns matches with enough info to call quickshell_get_type or
quickshell_get_guide_page directly. Namespace and type matches are
reported separately so a namespace hit doesn't flood the results with
all of its types. Defaults to the latest doc version.
Set refresh=True to bypass the in-process cache.

Input parameters:

- `include_content` (boolean)
- `include_type_pages` (boolean)
- `query` (string, required)
- `refresh` (boolean)
- `version` (string)

### `quickshell_search_all` (~315 tokens)

Search ALL sources at once with one natural-language query: Quickshell
docs (type names, guide pages), Qt/QML types on doc.qt.io, official
example configs, and real-world implementations (Caelestia, Noctalia, and
end-4's dots-hyprland).
Results come back grouped by source, most relevant group first; every
entry carries a relevance score, a why-it-matched reason, and a URL or
repo path.

Use this when you don't know which specialized tool fits ("how do I make
a workspace bar?", "create a volume OSD") or as a first pass before
drilling in. API-shaped queries ("PanelWindow", "exclusive zones") rank
exact type matches first; feature requests rank working implementations
first.

This is breadth over depth: follow up with quickshell_get_type /
quickshell_get_guide_page / quickshell_get_qt_type / quickshell_get_example /
quickshell_get_implementation for full content. include_content=True also
full-text-searches guide-page bodies (slower on first call, then cached).
limit_per_source caps entries per source (default 4, max 10). version pins
a Quickshell release ('latest' resolves at runtime); refresh=True bypasses
the cache.

Input parameters:

- `include_content` (boolean)
- `limit_per_source` (integer)
- `query` (string, required)
- `refresh` (boolean)
- `version` (string)

### `quickshell_find_pattern` (~290 tokens)

Find real implementations of a FEATURE you want to build, described in
plain words instead of exact type names: 'Hyprland workspace indicator',
'macOS-style control center', 'volume OSD', 'system tray', 'animated
popup', 'floating notification', 'top bar with workspaces', 'launcher
like Spotlight', 'power menu'. Searches Caelestia, Noctalia, and end-4's
dots-hyprland (real-world shells) plus the official examples repo,
interprets aliases ('Spotlight' means launcher, 'hud' means OSD), and
returns a small ranked set where every entry carries source project, file
path, why it matched, and the Quickshell APIs that pattern typically
needs. When several projects solve the same pattern they are grouped so
you can compare approaches.

For API/type lookups by name use quickshell_search or
quickshell_search_all instead; for browsing one repo use
quickshell_search_implementations. Read matched files via
quickshell_get_implementation / quickshell_get_example. limit caps total
implementations (default 5, max 10); version pins a Quickshell release;
refresh=True bypasses the cache.

Input parameters:

- `limit` (integer)
- `query` (string, required)
- `refresh` (boolean)
- `version` (string)

### `quickshell_list_qt_types` (~155 tokens)

List QML types documented on doc.qt.io for QtQuick and its sibling
modules (Controls, Layouts, Effects, Shapes, ...), discovered from the
QtQuick module page. Use this for Qt base types like Rectangle, Text,
MouseArea, Timer, or RowLayout that Quickshell configs import but the
Quickshell docs don't describe themselves. For Quickshell-specific types
use quickshell_list_types instead. qt_version pins a minor (e.g. '6.8',
'6.7') instead of the newest release.
Set refresh=True to bypass the in-process cache.

Input parameters:

- `module`
- `qt_version` (string)
- `refresh` (boolean)

### `quickshell_get_qt_type` (~159 tokens)

Fetch one Qt type's reference page from doc.qt.io as Markdown, e.g.
Rectangle, Text, MouseArea, Timer, Item, RowLayout, or a value type like
color or vector3d. Use this when a Quickshell config imports QtQuick /
QtQuick.Controls / QtQuick.Layouts types and you need their properties,
signals, or syntax. Pass module (e.g. 'qtquick', 'qtquick-controls') to
disambiguate names that exist in several modules. qt_version pins a
minor (e.g. '6.8') to match your installed Qt instead of the newest.

Input parameters:

- `module`
- `name` (string, required)
- `qt_version` (string)

Output parameters:

- `result` (string)

### `quickshell_list_examples` (~79 tokens)

List files and folders in the official Quickshell examples repo
(real-world sample shell/bar/widget configs written by the Quickshell
authors). Call with no path to list the root, then drill into a folder
using its path. Pair with quickshell_get_example to read a file's
contents.

Input parameters:

- `path` (string)

### `quickshell_get_example` (~61 tokens)

Read one file from the official Quickshell examples repo verbatim
(QML configs, READMEs). Get valid paths from quickshell_list_examples.
Prefer these maintained examples over writing a shell config from
memory.

Input parameters:

- `path` (string, required)

Output parameters:

- `result` (string)

### `quickshell_search_implementations` (~257 tokens)

Search real-world Quickshell shells (Caelestia, Noctalia, and
end-4's dots-hyprland) for implementations: 'find a bar implementation',
'find a control center example', 'find Quickshell IPC usage', 'find
multi-monitor implementation', 'find workspace widget', 'find
notification/OSD/launcher implementation', 'find lock screen', 'find
wallpaper handling', 'find Quickshell animations', 'find service
patterns', 'find reusable QML components', 'find Hyprland/Niri
integration', 'find volume/audio implementation', 'find wifi/network
implementation', 'find bluetooth', 'find brightness', 'find battery
implementation', 'find media controls'.
Restrict to one shell with source='caelestia', source='noctalia', or
source='dots-hyprland'; to compare approaches, call once per shell.
These are practical references, NOT API docs: verify API surface with
quickshell_search/quickshell_get_type. Get file contents via
quickshell_get_implementation.

Input parameters:

- `limit` (integer)
- `query` (string, required)
- `source` (string)

### `quickshell_get_implementation` (~137 tokens)

Read a QML file from the Caelestia, Noctalia, or dots-hyprland shells
(get paths from quickshell_search_implementations). Pass find='osd' /
find='workspace' / find='ipc' etc. to jump to the most relevant section
instead of pulling the whole large file. This is a real-world
implementation reference, NOT official documentation: when it disagrees
with quickshell.org or doc.qt.io, trust the docs.

Input parameters:

- `find`
- `max_chars` (integer)
- `path` (string, required)
- `source` (string, required)

Output parameters:

- `result` (string)

### `quickshell_explain_error` (~212 tokens)

Explain a Quickshell/QML error and suggest a fix, grounded in the
actual documentation. Pass the error message; optionally include QML code,
the filename, line number, component/type name, or Quickshell version for
a more precise diagnosis.

The tool verifies reported properties, methods, and signals against the
Quickshell and Qt type indexes before suggesting fixes, so it never
recommends APIs that don't exist.

Use this when you encounter errors like:
\- "Cannot assign to non-existent property"
\- "Type 'X' is not accessible"
\- "X is not a function"
\- "Cannot connect to non-existent signal"
\- "module 'X' is not installed"
\- "Invalid assignment"
\- "Could not find or load the component"
\- binding errors or type mismatches

Input parameters:

- `code`
- `component`
- `error` (string, required)
- `filename`
- `line_number`
- `version` (string)

### `quickshell_check_compatibility` (~329 tokens)

Check whether a Quickshell API, QML property/method/signal, type, or
code snippet is compatible with a specific Quickshell version. Use this
before targeting an older release, e.g. 'is PanelWindow.exclusiveZone
available in v0.2.0?', 'which version introduced SomeType?', 'does this
QML config work on v0.3.0?', 'was Quickshell.shellRoot renamed?'.

Pass exactly one of:
\- api: a dotted path like 'PanelWindow.exclusiveZone',
  'Quickshell.Hyprland.HyprlandMonitor', or 'HyprlandWorkspace.activate()'
\- type: a bare type name like 'PanelWindow'
\- code: a QML snippet; every referenced type and property is checked

version pins the Quickshell release (default 'latest', resolved at
runtime). to_version overrides version as the target; from_version adds a
lower-bound so the result reports compatibility across the whole range.

The verdict is one of 'compatible' / 'incompatible' / 'uncertain', backed
by per-version documentation and changelog evidence (never a guess from
the latest page alone). Qt/QML types (Rectangle, Item, ...) are reported
as compatible with origin 'qt': their availability is governed by your Qt
version, not the Quickshell one.

Input parameters:

- `api`
- `code`
- `from_version`
- `to_version`
- `type`
- `version` (string)

### `quickshell_migrate` (~326 tokens)

Migrate Quickshell/QML code from one Quickshell version to another:
'migrate this config from v0.2.0 to v0.3.0', 'what do I need to change
to upgrade to the latest Quickshell?', 'is my config still valid after
the upgrade?'. Analyzes the code (or a single API/type) against both
versions and reports every removed, renamed, deprecated, or changed API,
plus breaking changes from the changelog, each with severity, location,
the old API, the replacement, why it must change, a suggested migration,
confidence, and a cited source.

Pass exactly one of:
\- code: the QML source to migrate
\- api: a dotted path like 'Quickshell.shellRoot' or
  'PanelWindow.exclusiveZone'
\- type: a bare type name like 'LegacyThing'

Both from_version and to_version are required. The scan covers only
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, not as a vague
'sometime between'. Findings are classified definite / likely /
manual_review: only changes backed by the docs or changelog are
definite. This tool analyzes and recommends; it never rewrites code
or modifies files.

Input parameters:

- `api`
- `code`
- `filename`
- `from_version` (string, required)
- `to_version` (string, required)
- `type`

### `quickshell_validate_qml` (~282 tokens)

Statically validate Quickshell/QML source before you run it: unknown
types, unknown properties, unknown signals, missing imports, obvious type
mismatches, and APIs not available in the requested Quickshell version.

Pass the QML source; optionally pin a Quickshell version (defaults to the
latest) and give a filename so a root type matching the file stem is
treated as a local component instead of an unknown type.

The check is a lightweight heuristic that complements qmlls, not a
replacement: it validates types/properties/signals against the Quickshell
and Qt docs, skips JavaScript bodies, and reports things it cannot resolve
as info diagnostics rather than errors. Returns structured diagnostics
with line/column, severity, confidence, and a docs source URL for each
finding.

Use this while writing a config (e.g. after noticing 'Cannot assign to
non-existent property' in your logs) to catch typos early:
\- unknown type or namespace
\- property/signal/method not documented on a type
\- invalid assignment to a scalar-typed property
\- missing 'import Quickshell.X' for a used namespace
\- type not present in the requested Quickshell version

Input parameters:

- `filename`
- `source` (string, required)
- `version` (string)

### `quickshell_generate_component` (~486 tokens)

Generate a minimal, source-grounded Quickshell QML component from a
plain-language description, e.g. 'Create a Hyprland workspace indicator',
'animated volume OSD', 'top bar with workspaces, clock and system tray',
'popup control center', or 'notification popup'.

The generator researches the request, assembles a small component from
curated templates, and BEFORE returning it verifies every Quickshell type
and property/method it references against the requested version (via the
compatibility machinery) and runs the static validator on the assembled
QML. Any API that cannot be verified is surfaced rather than silently
emitted, so the result never claims an API is valid without checking.

The result also includes a 'verified_surface': the documented
properties/methods/signals of every type the component uses, so you can
freely rewrite the QML against verified members. When no curated template
matches the request, the result carries that verified surface plus
supporting references instead of a component, so you can compose the
component yourself from grounded building blocks. Only one top-level
window is generated; additional requested windows are reported in
'assumptions' rather than embedded.

Inputs:
\- description: what to build, in plain words
\- version: Quickshell release to target (default 'latest', resolved at runtime)
\- compositor: e.g. 'hyprland' to use compositor-specific types
\- style: optional style/behavior hints (surfaced in 'assumptions')
\- context: optional existing project context (surfaced, never read)
\- filename: suggested filename; derived from the description by default

The result includes the generated QML, the imports/types it needs, any
compositor or external-service dependency, per-API verification evidence,
validation diagnostics, supporting references, and the assumptions made.
Official documentation always wins over examples and real-world
implementations when they disagree. This tool writes nothing to disk.

Pass project= a path to the pr…

Input parameters:

- `compositor`
- `context`
- `description` (string, required)
- `filename`
- `project`
- `style`
- `version` (string)

### `quickshell_generate_service` (~112 tokens)

Generate a generic, architecture-neutral Quickshell service
abstraction for a common application concern. The first version returns a
verified service skeleton with declared imports and a placeholder service
object you can extend; it is deliberately generic rather than a giant
library of service templates. No nonexistent Quickshell APIs are emitted.
Pass project= to align the target version and compositor with the project.

Input parameters:

- `compositor`
- `description` (string, required)
- `project`
- `version` (string)

### `quickshell_generate_panel` (~108 tokens)

Generate high-level panel scaffolding for a bar, OSD, launcher,
dashboard, control center, or notification panel. This is scaffolding,
not a full design generator: it reuses the component generator and
project style detection, and outputs minimal, valid, extendable QML.
Pass project= to align version, compositor, and conventions with the
project.

Input parameters:

- `compositor`
- `description` (string, required)
- `project`
- `version` (string)

### `quickshell_refactor` (~93 tokens)

Propose a safe refactoring (rename component, property, or reference)
across a Quickshell project: rename an identifier everywhere it appears
as a whole token. Returns structured edits plus a unified diff. Never
writes files — apply the edits with quickshell_apply_patch when you are
ready.

Input parameters:

- `new` (string, required)
- `old` (string, required)
- `project` (string, required)

### `quickshell_apply_patch` (~135 tokens)

Apply a previously generated edit set to a Quickshell project, but only
when explicitly requested. This is a mutating operation.

Validates that every edit path stays inside the authorized project root,
the patch is well-formed, not stale (optionally by expected file hashes),
and would not silently overwrite conflicting edits. Only whole-token
occurrences are replaced, and a target must be unique or the patch is
rejected. Reports every changed file. Nothing outside the project root is
ever touched.

Input parameters:

- `edits` (array, required)
- `expected_base_hashes`
- `project` (string, required)

### `quickshell_style_match` (~82 tokens)

Analyze an existing Quickshell project and infer reusable UI
conventions: colors, corner radius, font sizes, spacing, animation
durations, component structure, and naming patterns. Returns
evidence-backed findings (values actually present and their frequency),
never design opinions. Generation tools can consume this style
representation later.

Input parameters:

- `project` (string, required)

### `quickshell_coding_assistant` (~500 tokens)

High-level Quickshell development assistant for AI coding agents.

Give it one plain-language development request and it routes the work
through the other tools, returning a structured, source-grounded result:
\- build: 'build a Hyprland workspace bar', 'add an animated volume popup'
\- debug: 'why is this PanelWindow failing?', 'fix this QML error' (pass
  error= and/or code=)
\- migrate: 'migrate this shell from v0.2 to v0.3' (from_version/to_version
  pin the range)
\- adapt a pattern: 'find an implementation of this feature and adapt it'
\- research: 'how should I structure this component?', 'what is PanelWindow?'

The assistant picks the minimal set of lower-level tools needed (search,
pattern lookup, type/guide pages, compatibility, migration, generation,
validation), runs each step in isolation so a failing source never sinks
the whole answer, deduplicates searches, reuses the shared cache, and
never modifies files. version pins the Quickshell release. Results clearly
separate verified facts (official docs) from recommendations, and every
claim carries a source URL. For a single, focused lookup call the specific
tool directly instead.

Pass project= a path to the Quickshell project root to ground the answer
in that project: the assistant infers its Quickshell version and
compositor from the project's QML imports and uses them as defaults, and
returns a 'project' section describing what was detected (version,
compositor, QML files, each marked detected/inferred/unknown). An invalid
path is reported in that section instead of failing the request.

Execution is off by default: the assistant never modifies files. To let
it apply an explicit, validated edit set to the project, 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.

Input parameters:

- `code`
- `compositor`
- `context`
- `edits`
- `error`
- `filename`
- `from_version`
- `permitted_execution` (boolean)
- `project`
- `request` (string, required)
- `to_version`
- `version` (string)

### `quickshell_project_analyze` (~123 tokens)

Inspect a Quickshell project and produce a structured project overview
containing, where detectable: Quickshell version, Qt version, entrypoints,
QML files, JS files, imports, Quickshell modules, components, services,
compositor integrations, runtime dependencies, and project configuration.

Builds on the shared ProjectContext. Unknown or undetected values are
explicitly marked; no information is fabricated. File listings are capped
to a reasonable sample; the full list is available via the specialized
project tools.

Input parameters:

- `project` (string, required)

### `quickshell_project_map` (~104 tokens)

Build a machine-readable project graph showing relationships between
QML components, imports, service dependencies, entrypoints, and module
dependencies. Relies on reliable static relationships.

The output clearly distinguishes:
\- confirmed relationships (directly observed import statements, type
  matches against local file stems)
\- inferred relationships (references that could not be proven local)

Reports cyclic component usage and references that match no local file
and no known namespace.

Input parameters:

- `project` (string, required)

### `quickshell_project_find` (~92 tokens)

Project-aware search: find where a concept, API, type, or property
is used in a Quickshell project. Supports both exact textual matching
and semantic/project-aware matching (type names, import modules).

Returns file, location, match context, and why the result matched.
Exact textual matches are ranked first; semantic matches follow.

Input parameters:

- `project` (string, required)
- `query` (string, required)

### `quickshell_project_dependencies` (~97 tokens)

Detect a Quickshell project's dependencies from source and
configuration, without executing anything.

Classes are:
\- required: Quickshell and Qt modules the project imports
\- optional: imports that match known namespaces without local files
\- detected: runtime hooks, services, config keywords, environment
  variable references
\- missing: imports that resolve to neither a known namespace nor a
  local component

Input parameters:

- `project` (string, required)

### `quickshell_project_config` (~59 tokens)

Detect a Quickshell project's configuration conventions:
entrypoints, configuration files, environment variables, structural
conventions, and runtime hints. Inferred values include confidence
levels; directly observed values carry high confidence.

Input parameters:

- `project` (string, required)

### `quickshell_project_validate` (~104 tokens)

Run the static QML validator across an entire Quickshell project and
aggregate syntax errors, import problems, type problems, property and
signal issues, version mismatches, and deprecated or unavailable APIs.

Results are grouped by file and severity. One bad file never prevents
analysis of the rest: unreadable files are reported and skipped. Reuses
the existing validator rather than duplicating logic.

Input parameters:

- `project` (string, required)
- `version` (string)

### `quickshell_project_lint` (~91 tokens)

Run quality-oriented lint checks across a Quickshell project.

Every rule has a stable diagnostic code, severity, explanation, and
remediation. Rules are conservative and evidence-based; they flag
suspicious patterns (duplicate imports, duplicate object ids, suspicious
timers) rather than subjective style opinions. The rule table is
extensible for future additions.

Input parameters:

- `project` (string, required)

### `quickshell_project_compatibility` (~92 tokens)

Analyze a whole project's Quickshell API compatibility against a
target version: unavailable, deprecated, or changed APIs with affected
files and concrete locations.

Reuses the version compatibility engine. A verdict of 'uncertain' means
the docs did not prove availability either way — it is never reported as
a runtime incompatibility.

Input parameters:

- `project` (string, required)
- `version` (string)

### `quickshell_project_migrate` (~109 tokens)

Analyze a whole Quickshell project for what must change to move from
one Quickshell version to another: breaking and deprecated APIs, required
changes, and a machine-readable proposed-edit list.

Never modifies files. Every proposed edit carries file, line, and
old/new API context so it can be applied safely. Reuses the existing
migration engine per file.

Input parameters:

- `from_version` (string, required)
- `project` (string, required)
- `to_version` (string, required)

### `quickshell_runtime_start` (~117 tokens)

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.

Input parameters:

- `arguments`
- `compositor`
- `config_dir`
- `entrypoint`
- `environment`
- `project` (string, required)

### `quickshell_runtime_stop` (~62 tokens)

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.

Input parameters:

- `session_id` (string, required)

### `quickshell_runtime_reset` (~59 tokens)

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.

Input parameters:

- `session_id` (string, required)

### `quickshell_runtime_status` (~48 tokens)

Return structured status for a runtime session: session id, running
state, PID, startup duration, exit code, and profile identity. Read-only.

Input parameters:

- `session_id` (string, required)

### `quickshell_runtime_logs` (~68 tokens)

Return structured logs from a runtime session with optional filtering
by stream (stdout/stderr), text, and a bounded limit. Read-only.

Input parameters:

- `limit` (integer)
- `session_id` (string, required)
- `severity`
- `stream`
- `text`

### `quickshell_runtime_ping` (~49 tokens)

Lightweight readiness/health check for a runtime session.

Distinguishes: process_running, exited (with exit code), or unhealthy.
Fast, read-only.

Input parameters:

- `session_id` (string, required)

### `quickshell_windows` (~57 tokens)

Enumerate windows/surfaces belonging to a managed Quickshell runtime
session. Read-only. Requires a compositor adapter; when unavailable
returns an empty list with an explanatory note (never fails).

Input parameters:

- `session_id` (string, required)

### `quickshell_screenshot` (~143 tokens)

Capture a bounded screenshot of a managed Quickshell runtime session.

Requires the ``grim`` compositor screenshot tool on PATH. **Full-desktop
capture is disabled by default.** Pass ``rectangle=`` with ``x``, ``y``,
\``width``, ``height`` to target a specific region. Object-derived
geometry is not yet available and will report an explanatory note.

Set ``QUICKSHELL_DOCS_MCP_ALLOW_FULLSCREEN_CAPTURE=1`` at server launch
to allow full-screen captures (high-risk: includes all desktop content).
Read-only.

Input parameters:

- `object_name`
- `rectangle`
- `session_id` (string, required)

### `quickshell_screenshot_diff` (~64 tokens)

Compare two runtime screenshots with ImageMagick ``compare``.

Returns whether they differ, the diff image path, and a metric.
Deterministic for CI. Read-only.

Input parameters:

- `actual` (string, required)
- `baseline` (string, required)
- `output`

### `quickshell_ui_tree` (~61 tokens)

Inspect the live QML object tree of a managed runtime session.

Returns a compact, depth-limited hierarchy from the injected
'inspector' IpcHandler target. Read-only.

Input parameters:

- `depth` (integer)
- `session_id` (string, required)

### `quickshell_ui_find` (~59 tokens)

Search the live QML object tree of a managed runtime session by name,
type, text, or property. Returns stable references for later runtime
tools. Read-only.

Input parameters:

- `query` (string, required)
- `session_id` (string, required)

### `quickshell_ui_get_property` (~65 tokens)

Read a live QML property value from a managed runtime object via
\``qs ipc prop get``. Validates the object/property exist. Read-only.

Input parameters:

- `property_name` (string, required)
- `session_id` (string, required)
- `target` (string, required)

### `quickshell_ui_set_property` (~80 tokens)

Set a live QML property on a managed runtime object. Mutating.

Requires an explicit runtime session, validates the property exists,
returns the old and new values, and never modifies project files.

Input parameters:

- `property_name` (string, required)
- `session_id` (string, required)
- `target` (string, required)
- `value` (string, required)

### `quickshell_ui_invoke` (~79 tokens)

Invoke a QML method on a managed runtime object via ``qs ipc call``.
Mutating. Validates the method and arguments; enforces runtime session
boundaries; no arbitrary process/system calls.

Input parameters:

- `arguments`
- `method` (string, required)
- `session_id` (string, required)
- `target` (string, required)

### `quickshell_ui_eval` (~96 tokens)

HIGH-RISK: evaluate QML/JavaScript in a managed runtime session.

Explicitly opt-in, session-scoped, with an execution timeout and output
limits. No filesystem or process access is granted. Prefer
quickshell_ui_get_property / quickshell_ui_invoke for controlled reads
and calls.

Input parameters:

- `js_code` (string, required)
- `session_id` (string, required)
- `timeout` (integer)

### `quickshell_test` (~121 tokens)

Run a single machine-readable runtime test against a managed
Quickshell session.

A test has a name, a list of steps (wait, invoke, set_property), and a
list of assertions (object_exists, property_equals, property_contains,
property_matches, visible, enabled, text_matches, window_exists). Returns
pass/fail, per-step and per-assertion results, duration, and an optional
screenshot on failure. Mutating (drives the runtime).

Input parameters:

- `session_id` (string, required)
- `test` (object, required)

### `quickshell_test_suite` (~61 tokens)

Run multiple named runtime tests in isolation. One failing test never
corrupts the rest of the suite. Returns pass/fail totals and per-test
results. Mutating.

Input parameters:

- `session_id` (string, required)
- `tests` (array, required)

### `quickshell_assert` (~72 tokens)

Run a single reusable assertion primitive against a managed runtime
session: object_exists, property_equals, property_contains,
property_matches, visible, enabled, text_matches, window_exists.

Returns a structured pass/fail with useful context. Read-only.

Input parameters:

- `assertion` (object, required)
- `session_id` (string, required)

### `quickshell_test_macro` (~76 tokens)

Define or retrieve a reusable parameterized runtime macro: a named
sequence of safe runtime steps that tests can invoke. Pass steps= to
save a macro; omit steps to load one by name. Macros are project-scoped
for the process. Read-only.

Input parameters:

- `name` (string, required)
- `steps`

### `quickshell_test_record` (~59 tokens)

Record a list of runtime actions into a reproducible test
representation. Uses stable selectors (target + method/property), not
fragile generated object ids. Read-only.

Input parameters:

- `actions` (array, required)
- `session_id` (string, required)

### `quickshell_test_report` (~64 tokens)

Produce a structured test report: passed/failed tests, durations,
assertions, runtime logs, screenshots, and diagnostics. Suitable for
both an LLM and human CI output. Read-only.

Input parameters:

- `session_id` (string, required)
- `suite` (object, required)

### `quickshell_runtime_diagnose` (~60 tokens)

Diagnose a managed runtime session: combine runtime logs, errors,
project context, and version info into a probable root cause with
confidence. Never fabricates a cause when evidence is insufficient.
Read-only.

Input parameters:

- `session_id` (string, required)

### `quickshell_runtime_errors` (~79 tokens)

Extract and normalize common Quickshell/QML runtime problems from a
session's stderr: import failures, undefined properties, type mismatches,
binding loops, component load failures, JS exceptions, and signal/method
errors. Original error text is preserved. Read-only.

Input parameters:

- `limit` (integer)
- `session_id` (string, required)

### `quickshell_trace` (~63 tokens)

Trace a selected runtime interaction across observable state
transitions. Reports observed log events; inferred transitions are always
kept separate from observed evidence. Read-only.

Input parameters:

- `action` (string, required)
- `session_id` (string, required)
- `steps` (integer)

### `quickshell_binding_inspect` (~67 tokens)

Inspect a binding on a managed runtime object: current live value,
likely source expression (from the project QML), and files that
reference it. Read-only.

Input parameters:

- `property_name` (string, required)
- `session_id` (string, required)
- `target` (string, required)

### `quickshell_reload` (~61 tokens)

Reload a managed runtime session, preserving session tracking. Reuses
the lifecycle implementation; cleans up after failed reloads. Never
touches production Quickshell processes. Mutating.

Input parameters:

- `hard` (boolean)
- `session_id` (string, required)

### `quickshell_visual_check` (~122 tokens)

Analyze a runtime screenshot for objective UI problems: clipping,
overflow, missing expected elements, unexpected empty areas, misalignment,
or off-screen content. Returns observations with confidence and affected
regions. It does not claim to prove semantic correctness. Read-only.

Pass an explicit screenshot_path to analyze an existing file, or
rectangle= to capture a bounded region. Full-desktop capture is disabled
by default (see quickshell_screenshot).

Input parameters:

- `object_name`
- `rectangle`
- `screenshot_path`
- `session_id` (string, required)

### `quickshell_visual_diff` (~74 tokens)

Compare baseline and actual screenshots deterministically for
visual-regression testing: diff image, differing pixels metric,
configurable threshold, and ignored regions. Read-only.

Input parameters:

- `actual` (string, required)
- `baseline` (string, required)
- `ignored_regions`
- `output`
- `threshold` (integer)

### `quickshell_screenshot_region` (~100 tokens)

Capture a region-based screenshot of a managed runtime, preferring an
object-derived region over manual coordinates. Read-only; requires grim.

Pass ``rectangle=`` (x, y, width, height) to capture a bounded region.
Full-desktop capture is disabled by default; object-derived geometry
requires a compositor adapter (reports an explanatory note).

Input parameters:

- `object_name`
- `rectangle`
- `session_id` (string, required)

### `quickshell_ui_snapshot` (~101 tokens)

Create a single serializable UI snapshot: screenshot, UI tree, live
properties, runtime state, timestamp, and project metadata. Comparable for
regression detection. Read-only.

Pass ``rectangle=`` to capture a bounded screenshot region; full-desktop
capture is disabled by default (see quickshell_screenshot).

Input parameters:

- `include_tree` (boolean)
- `object_name`
- `rectangle`
- `session_id` (string, required)

### `quickshell_profile` (~58 tokens)

Measure runtime characteristics of a managed session: CPU usage,
memory (RSS), and sample duration via bounded /proc sampling. Reports
methodology and limitations. Read-only.

Input parameters:

- `seconds` (number)
- `session_id` (string, required)

### `quickshell_profile_component` (~47 tokens)

Identify components with potential performance concerns from static
evidence: timer/animation counts and layout bindings. Never attributes
cost without evidence. Read-only.

Input parameters:

- `project` (string, required)

### `quickshell_profile_bindings` (~51 tokens)

Identify high-frequency or broad property bindings statically (potential
re-evaluation chains). Static only; re-evaluation frequency needs runtime
instrumentation. Read-only.

Input parameters:

- `project` (string, required)

### `quickshell_profile_timers` (~49 tokens)

Find timers with potentially suspicious configuration (very short
intervals, repeat disabled). Frequent timers are not labeled bugs by
themselves. Read-only.

Input parameters:

- `project` (string, required)

### `quickshell_profile_object_tree` (~54 tokens)

Report object-tree statistics from static QML structure: total objects,
repeated component patterns, and nesting depth. Useful for optimization;
large trees are not automatically bad. Read-only.

Input parameters:

- `project` (string, required)

### `quickshell_performance_diagnose` (~54 tokens)

Correlate static project evidence (bindings, timers, object tree) into
prioritized performance hypotheses with evidence and confidence. Never
modifies source. Read-only.

Input parameters:

- `project` (string, required)

### `quickshell_hyprland_info` (~65 tokens)

Inspect the Hyprland compositor read-only: monitors, workspaces, the
active workspace, and clients, via ``hyprctl -j``. Returns an explanatory
note when Hyprland/hyprctl is unavailable. Never modifies the compositor.

### `quickshell_wayland_layers` (~37 tokens)

Inspect Wayland layer/surface information for the managed runtime.
Requires a compositor adapter; reports a note when unavailable. Read-only.

### `quickshell_pipewire_info` (~49 tokens)

Inspect PipeWire read-only: sinks, sources, and device identity via
\``pw-cli``. Returns a note when PipeWire/pw-cli is unavailable. Never
changes device state.

### `quickshell_dbus_services` (~39 tokens)

List user-session D-Bus services read-only via ``busctl``. Discovery
only — method invocation is never performed. Read-only.

### `quickshell_system_diagnostics` (~37 tokens)

Report verified-only environment problems for Quickshell development:
missing commands and services. Only evidence-backed issues are reported.
Read-only.

### `quickshell_api_diff` (~59 tokens)

Compare two Quickshell versions and report added, removed, renamed,
and deprecated APIs, each with provenance (changelog and type-page
URLs). Read-only.

Input parameters:

- `from_version` (string, required)
- `to_version` (string, required)

### `quickshell_api_graph` (~64 tokens)

Build a documented API dependency graph for a type: its declared
properties (with their types) and its documented base type. Only
documented relationships are included — no speculative edges. Read-only.

Input parameters:

- `api` (string, required)
- `version` (string)

### `quickshell_best_practice` (~57 tokens)

Return evidence-backed implementation guidance ranked by authority:
official docs > official examples > real-world shells. Documented
behavior is separated from community convention. Read-only.

Input parameters:

- `query` (string, required)
- `version` (string)

### `quickshell_pattern_compare` (~75 tokens)

Compare how the indexed real-world shells (Caelestia, Noctalia,
dots-hyprland) solve the same problem: per-project matches and source
locations. Presents differences for comparison; never declares one
implementation correct. Read-only.

Input parameters:

- `query` (string, required)
- `version` (string)

### `quickshell_provenance` (~68 tokens)

Return provenance for knowledge results: source, version, URL, and
authority level (docs > examples > real-world), so higher-level results
can cite them. Read-only.

Input parameters:

- `limit` (integer)
- `query` (string, required)
- `version` (string)

### `quickshell_nix_diagnostics` (~84 tokens)

Detect the Nix infrastructure of a Quickshell project: flake.nix
presence, devShells, nixpkgs inputs, and whether the flake is locked.
File-based detection only (no nix evaluation). Falls back to the system
package manager when no flake.nix is present. Read-only.

Input parameters:

- `project` (string, required)

### `quickshell_runtime_dependencies` (~75 tokens)

Detect what a Quickshell project needs at runtime, statically and
safely: QML types (Process, IpcHandler, ...), config keywords, imports,
compositor, services, and which system binaries are on PATH. Nothing is
executed. Read-only.

Input parameters:

- `project` (string, required)

### `quickshell_profile_save` (~92 tokens)

Save a named runtime launch profile in this server's in-memory
registry. Profiles are pure data (never launched by saving); combine
them with quickshell_runtime_start. Mutates the profile registry only.

Input parameters:

- `arguments`
- `compositor`
- `config_dir`
- `entrypoint`
- `environment`
- `name` (string, required)
- `project` (string, required)

### `quickshell_profile_list` (~37 tokens)

List all saved runtime profiles with summary info: name, project
root, entrypoint, compositor, and schema version. Read-only.

### `quickshell_profile_get` (~39 tokens)

Get a single saved runtime profile by name, with its full launch
configuration and schema version. Read-only.

Input parameters:

- `name` (string, required)

### `quickshell_profile_delete` (~37 tokens)

Delete a saved runtime profile from the in-memory registry by name.
Mutates the profile registry only.

Input parameters:

- `name` (string, required)

### `quickshell_profile_export` (~46 tokens)

Export a saved runtime profile as a JSON-serializable dict (with its
schema version), for backup or sharing between servers. Read-only.

Input parameters:

- `name` (string, required)

### `quickshell_profile_import` (~70 tokens)

Import a runtime profile into the registry from a dict (e.g. the
output of quickshell_profile_export). A payload with a newer schema
version than this server supports is refused. Mutates the profile
registry only.

Input parameters:

- `data` (object, required)
- `name` (string, required)

### `quickshell_build_feature` (~118 tokens)

Build a feature end-to-end: analyze the project, research the APIs,
generate a verified component, validate it, and optionally apply a
permitted edit set. Returns the full staged plan. Read-only unless
apply=True and an explicit edit set is given (then mutating).

Input parameters:

- `apply` (boolean)
- `compositor`
- `context`
- `description` (string, required)
- `edits`
- `filename`
- `project`
- `style`
- `version` (string)

### `quickshell_debug` (~106 tokens)

Debug a failure end-to-end: explain the error from the docs, then
correlate live runtime evidence (errors, diagnosis, trace, binding)
when a session id is given. Inferred causes are kept separate from
observed evidence. Read-only.

Input parameters:

- `code`
- `error`
- `filename`
- `project`
- `property_name`
- `session_id`
- `target`
- `version` (string)

### `quickshell_migrate_project` (~70 tokens)

Migrate a whole project between Quickshell versions: summarize the
API delta, run the per-file migration engine, and report confirmed
breaking issues with sources. Read-only.

Input parameters:

- `from_version` (string, required)
- `project` (string, required)
- `to_version` (string, required)

### `quickshell_test_feature` (~100 tokens)

Test a feature end-to-end: start an isolated Quickshell session, run
the machine-readable test suite, capture a screenshot on failure, and
stop the session. Mutating (launches and stops a session).

Input parameters:

- `compositor`
- `config_dir`
- `entrypoint`
- `environment`
- `project` (string, required)
- `screenshot_on_fail` (boolean)
- `tests` (array, required)

### `quickshell_optimize` (~65 tokens)

Optimize a project: profile a live session (when given) and run
static component/binding/timer analysis plus a correlated diagnosis.
Cost is never attributed without evidence. Read-only.

Input parameters:

- `project`
- `seconds` (number)
- `session_id`

### `quickshell_engineer` (~117 tokens)

Run the full engineering loop end-to-end: build → test → debug →
optimize → verify, composing the agent tools with per-stage isolation
so one failing stage never sinks the rest. Pass tests= a machine-
readable suite to enable the test stage; the loop is otherwise
read-only. Returns every stage's result plus the flattened plan.

Input parameters:

- `compositor`
- `description` (string, required)
- `project`
- `seconds` (number)
- `tests`
- `version` (string)

### `quickshell_project_memory` (~121 tokens)

Project memory: explicit, evidence-backed notes about a project
(13.1). action= is one of save (store a keyed entry with evidence),
list (summarize), get (one entry), clear (one key), or reset (all).
Memory is session-scoped, inspectable, and resettable. Read-only except
the registry mutations it performs.

Input parameters:

- `action` (string)
- `content`
- `evidence`
- `key`
- `project` (string, required)
- `scope` (string)

### `quickshell_project_architecture` (~57 tokens)

Produce evidence-backed architecture recommendations for a project:
confirmed cycles, unresolved references, and docs-grounded guidance.
Every recommendation cites its evidence and basis. Read-only.

Input parameters:

- `project` (string, required)
- `version` (string)

### `quickshell_regression_detect` (~90 tokens)

Detect regressions by comparing the current state against a baseline:
validation of every QML file plus an optional screenshot comparison.
Only confirmed changes are reported; absent baselines are surfaced, not
fabricated. Read-only.

Input parameters:

- `actual_screenshot`
- `baseline_screenshot`
- `project` (string, required)
- `threshold` (integer)
- `version` (string)

### `quickshell_root_cause` (~85 tokens)

Correlate evidence into a root cause, separating inferred hypotheses
from observed evidence. Combines static doc-grounded explanation with
live runtime diagnosis; never fabricates a cause without evidence.
Read-only.

Input parameters:

- `code`
- `error`
- `filename`
- `project`
- `session_id`
- `version` (string)

### `quickshell_task_plan` (~75 tokens)

Plan a development request with the minimal tool set: inspect the
project first, select the fewest tools that accomplish the intent, and
stop when verification would confirm the change. Advisory and read-only;
planning never executes anything.

Input parameters:

- `project`
- `request` (string, required)
- `version` (string)

### `quickshell_stats` (~62 tokens)

Report session usage stats for this MCP server: per-tool call counts,
network fetches vs cache hits, and process uptime. Use this to check how
much the server has been consulted and how much it hit the live site vs
its 30-minute cache.

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/franklinnolasco7-quickshell-mcp/quickshell-mcp#diagnostics

## Score history

- 2026-09-21: 60
- 2026-09-20: 60
- 2026-09-19: 59
- 2026-09-18: 59
- 2026-09-17: 58
- 2026-09-16: 58
- 2026-09-15: 57
- 2026-09-14: 57
- 2026-09-13: 56
- 2026-09-12: 56
- 2026-09-11: 55
- 2026-09-10: 55
- 2026-09-09: 54
- 2026-09-08: 54
- 2026-09-07: 54
- 2026-09-06: 68
- 2026-09-05: 68
- 2026-09-04: 52
- 2026-09-03: 52
- 2026-09-02: 51
- 2026-09-01: 51
- 2026-08-31: 65
- 2026-08-30: 50
- 2026-08-29: 64
- 2026-08-28: 49
- 2026-08-27: 49

## Common questions

### What is the Quickshell MCP server?

Quickshell MCP is listed in the public MCP registry as io.github.franklinnolasco7/quickshell-mcp. Source-grounded Quickshell, QML, and Qt documentation, examples, and real-world implementations. This page covers its PyPI package (quickshell-mcp).

### Is the Quickshell MCP server safe to use?

Quickshell MCP scores 60 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 September 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Quickshell MCP server expose?

Quickshell MCP exposes 102 tools: quickshell_list_versions, quickshell_about, quickshell_changelog, quickshell_list_guide_pages, quickshell_get_guide_page, and 97 more. Their descriptions and schemas cost roughly 10,693 tokens of context every time the server is loaded.

### Is the Quickshell MCP server still maintained?

Quickshell MCP is still listed as active in the MCP registry. We last reached this channel on 21 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

## Links

- PyPI project: https://pypi.org/project/quickshell-mcp/
- Socket report: https://socket.dev/pypi/package/quickshell-mcp
- Repository: https://github.com/franklinnolasco7/quickshell-mcp
- Changelog RSS feed: https://verifymcp.io/servers/franklinnolasco7-quickshell-mcp/quickshell-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/franklinnolasco7-quickshell-mcp/quickshell-mcp.json
- HTML version of this page: https://verifymcp.io/servers/franklinnolasco7-quickshell-mcp/quickshell-mcp