Quickshell MCP

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

静态验证

quickshell_validate_qml 会使用其他工具所用的相同 Quickshell 和 Qt 文档索引检查 QML。它可以捕获：

• 未知的 Quickshell 和 Qt 类型
• 未知的属性、方法和信号
• 缺少导入
• 明显的类型不匹配
• 请求的 Quickshell 版本中不可用的 API

quickshell_validate_qml 是对 qmlls 的补充，并不能取代它。动态 JavaScript 和本地组件解析不在其范围内。

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

版本兼容性

quickshell_check_compatibility 会检查 Quickshell API、QML 属性／方法／信号、类型或整段代码片段是否适用于特定版本。传入 api、type 或 code 其中之一；使用 version 选择版本（或者使用 from_version／to_version 指定范围）。

它不会仅依据最新文档页面进行判断，而是交叉参考所请求版本的类型索引和页面以及更新日志；如果证据不足，则返回 uncertain。Qt／QML 类型（Rectangle、Item 等）会显示为 compatible，并带有 origin: "qt"，因为它们是否可用取决于 Qt 版本，而非 Quickshell 版本。

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

结果包含判定、版本依据（已知的最早／最新版本）、任何重命名或变更及可能的替代项、匹配的更新日志条目，以及引用的文档 URL。

版本间迁移

quickshell_migrate 会分析将 QML 配置从一个 Quickshell 版本升级到另一个版本时必须进行的更改，以确保其继续正常工作。传入 QML 源代码（或单个 api／type），以及 from_version 和 to_version（两者均为必填项，且顺序必须从旧到新）。

它会报告每个已移除、重命名、弃用或变更的 API，并提供严重性、位置、旧 API 和新 API、必须更改的原因、建议的迁移方案、置信度以及引用来源。它还会扫描两个版本之间提及所引用符号的破坏性变更日志条目，因此，在中间版本中生效的重命名会附上生效版本。问题会分类为 definite（有文档或更新日志作为依据）、likely（有记录但影响较小，例如弃用）或 manual_review（证据表明发生了变更，但无法确证具体迁移方式）。

该工具只进行分析并提供建议，不会重写代码或文件。

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

报告包含总体判定（compatible、changes_required、uncertain）、各问题的发现结果，以及按顺序排列的迁移计划。

组件生成

quickshell_generate_component 可将自然语言描述转换为最简 QML 组件，例如“创建一个 Hyprland 工作区指示器”“带动画的音量 OSD”“包含工作区、时钟和系统托盘的顶部栏”“弹出式控制中心”或“通知弹窗”。

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

生成器会搜索请求（使用与其他工具相同的搜索和模式工具），根据章节模板构建一个小型组件，然后使用 quickshell_check_compatibility 检查其中引用的每种 Quickshell 类型、属性和方法是否兼容指定版本，并通过 quickshell_validate_qml 验证组装后的 QML。无法验证的 API 会显示在结果中，而不会被悄悄输出，因此输出绝不会将未经验证的 API 冒充为有效 API。

结果包含生成的 QML，以及：

• dependencies：导入项、所需的 Quickshell 类型和 Qt 类型
• verified_surface：组件使用的每种类型中有文档说明的属性、方法和信号，便于你根据已验证成员重写 QML
• integration：合成器和外部服务要求（Hyprland 套接字、PipeWire、通知守护进程等）
• verification：各 API 的兼容性判定，以及总体 verified/unverified 标记
• validation：静态验证器的诊断信息
• references：可供对照的文档、官方示例和实际实现
• assumptions：所采用的保守选择（默认配色、无法识别的合成器、未嵌入的请求窗口）

compositor="hyprland" 会生成 Hyprland 专用类型；其他任何值都会被注明，且不会生成合成器专用代码。若请求与任何模板都不匹配，仍会返回 verified_surface 和 references，因此你可以自行组合组件。每个生成的文件只包含一个顶层窗口：如果请求提到了多个窗口（例如状态栏和通知弹窗），则只生成主要窗口，其余窗口会列在 assumptions 下，而不会嵌套其中。该工具不会向磁盘写入任何内容。

编码助手

quickshell_coding_assistant 是其他工具之上的编排层，适用于需要调用多个工具的任务。向它提供一条自然语言开发请求，它就会运行一条固定的阶段流水线：搜索、验证、生成、校验、迁移、研究（出处），以及可选的执行。每个阶段只会启用请求所需的工具。结果结构化且有来源依据，包含以下部分：需求理解、相关 API、推荐方案、实现参考、兼容性、校验、待解决问题、来源、出处，以及末尾的 grounded_result。

{"request": "Build a Hyprland workspace bar"}
{"request": "Why is this PanelWindow failing?", "code": "PanelWindow { foo: 1 }"}
{"request": "Migrate this shell from v0.2 to v0.3", "from_version": "v0.2.0", "to_version": "v0.3.1"}
{"request": "Find an implementation of a volume OSD and adapt the pattern"}

请求会映射到五种意图，每种意图都会运行相关的流水线阶段：

• build（“构建／添加／制作一个……”）会将搜索和验证阶段交给 quickshell_generate_component，由它在内部运行这两个阶段，并将其通过校验的 QML 作为 grounded_result。
• debug（“为什么 X 失败了？”、“修复此错误”）会运行搜索（quickshell_explain_error）和验证（相关类型页面 + 兼容性），然后进行校验（quickshell_validate_qml）；grounded_result 是诊断结果和修复方案。
• migrate（“从 vX 迁移／升级到 vY”）会运行搜索（未提供代码时查找破坏性变更日志）、针对目标版本进行校验，以及迁移（quickshell_migrate）；grounded_result 是按顺序排列的迁移计划。
• pattern（“查找某个实现……并进行调整”）会运行搜索（quickshell_find_pattern，并提供排名最高的实现的简短摘录）和验证（检查提示中 API 的兼容性）；grounded_result 是该摘录及已验证的 API。
• research（“X 是什么？”、“我该如何……？”）会运行搜索（所有来源）和验证（排名靠前的类型页面与指南页面 + 兼容性）；grounded_result 会列出已确定的类型和指南。

默认情况下不执行任何操作：助手绝不会修改文件。若要让它应用明确且经过校验的编辑集，请同时传入 permitted_execution=True、edits=[...]（格式与 quickshell_apply_patch 相同）以及 project= 路径。对于未获准的请求，系统会记录一个执行步骤，然后继续以只读方式运行。

版本和合成器信息可从请求文本中获取（0.2、hyprland），也可通过 version／compositor／from_version／to_version 参数传入。运行时会根据已发布的版本列表解析宽泛的版本提示。每个步骤都会独立运行，因此某个来源出错时，错误会出现在 errors 中，而不会导致整个请求失败。结果包含一条记录所用工具的 orchestration 跟踪信息，以及去重后的 sources 列表。方案步骤上的 basis 标签和 API 条目上的 verified 标记，可区分已验证事实（来自官方文档）与建议。

**适用场景：**多步骤开发请求，或尚不确定该使用哪个单一工具时。对于单项且范围明确的查询（一个类型页面、一条错误信息、一次版本检查），请直接调用相应工具；这样成本更低，也能获得原始答案。

项目分析

quickshell_project_analyze、quickshell_project_map 和 quickshell_project_find 会读取磁盘上的项目，但不会执行任何内容。分析结果会明确标记未知值；映射会区分已确认和推断出的边，并报告循环；查找会搜索项目文件并提供位置和上下文。quickshell_project_dependencies 会将导入项归类为必需、可选、已检测或缺失。

{"project": "/path/to/shell"}

quickshell_project_validate、quickshell_project_lint、quickshell_project_compatibility 和 quickshell_project_migrate 会对每个 QML 文件运行与单文件工具相同的引擎，并按文件和严重程度分组。Lint 使用可扩展的规则表；兼容性检查不会夸大运行时不兼容情况；迁移会生成机器可读的拟议编辑，且绝不会写入文件。

运行时工具会在隔离的 XDG 目录中启动真实的 qs 进程，确保受管理的 shell 不会触碰你的桌面会话。这些工具需主动启用且会修改状态，并要求 qs 位于 PATH 中。

{"project": "/path/to/shell", "entrypoint": "main.qml"}

quickshell_runtime_start 会返回会话 ID；quickshell_runtime_status、quickshell_runtime_logs 和 quickshell_runtime_ping 用于检查会话；quickshell_runtime_stop 和 quickshell_runtime_reset 用于管理生命周期。配置文件通过生态系统中的 quickshell_profile_* 工具命名并进行版本管理，也可以在启动时重复使用。

视觉和 UI 检查

quickshell_windows、quickshell_ui_tree 和 quickshell_ui_find 用于检查正在运行的会话。截图需要 grim 和合成器；UI 自省需要 shell 中有一个 inspector IpcHandler 目标。quickshell_ui_set_property 和 quickshell_ui_invoke 通过 IPC 修改会话并返回修改前后的状态；quickshell_ui_eval 风险较高（需显式启用、设有时间限制且输出有上限），并且绝不会触碰文件系统。

测试

quickshell_test 运行可机器读取的测试（先执行步骤，再进行断言，失败时截图）；quickshell_test_suite 在隔离环境中运行多个测试；quickshell_assert、quickshell_test_macro 和 quickshell_test_record 用于构建步骤；quickshell_test_report 用于汇总测试套件。

{"session_id": "abc123", "tests": [{"name": "bar shows", "assertions": [{"type": "visible", "target": "bar"}]}]}

性能

quickshell_profile 在有限的时间窗口内采集会话的 CPU／内存数据。quickshell_profile_component、quickshell_profile_bindings、quickshell_profile_timers 和 quickshell_profile_object_tree 对项目进行静态分析。quickshell_performance_diagnose 会将证据关联起来，形成带置信度的假设，绝不会在没有证据的情况下归因开销。

Agent

quickshell_build_feature、quickshell_debug、quickshell_migrate_project、quickshell_test_feature、quickshell_optimize 和 quickshell_engineer 均会通过较低层级的工具，按明确分阶段的计划执行。每个阶段彼此隔离，因此单个阶段失败不会导致整个计划失败。quickshell_engineer 会组合完整流程（构建、测试、调试、优化、验证），并返回每个阶段的结果以及扁平化计划。