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 など）は、利用可能かどうかを決めるのが Quickshell のバージョンではなく Qt のバージョンであるため、origin: "qt" とともに compatible と表示されます。

{"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 は、Quickshell のあるバージョンから別のバージョンへアップグレードする際に、QML 設定を引き続き動作させるために必要な変更を分析します。QML ソース（または単一の api／type）と、from_version および to_version（どちらも必須で、古い順に指定）を渡します。

削除、名前変更、非推奨化、または変更された 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 型とプロパティ／メソッドを quickshell_check_compatibility で指定バージョンに照らして確認し、組み立てた QML を quickshell_validate_qml で検証します。確認できない 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 は返されるため、それらを使って自分でコンポーネントを組み立てられます。生成される各ファイルには、最上位のウィンドウが 1 つ含まれます。リクエストに複数のウィンドウ（バーと通知ポップアップなど）が含まれる場合は、主要なウィンドウが生成され、残りはネストされずに assumptions に記載されます。このツールがディスクに書き込むことはありません。

コーディングアシスタント

quickshell_coding_assistant は、複数のツールにまたがるタスク向けのオーケストレーションレイヤーです。平易な言葉で開発リクエストを 1 つ渡すと、検索、検証、生成、バリデーション、移行、調査（出典の確認）、および任意の実行という固定パイプラインの各段階を実行します。各段階では、リクエストに必要なツールのみが有効になります。結果は構造化され、出典に基づいており、理解、関連 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"}

リクエストは 5 つのインテントに分類され、それぞれ関連するパイプラインの段階を実行します。

• build（「build/add/make a ...」）では、検索と検証の段階を quickshell_generate_component に委ねます。このツールは内部でこれらの段階を実行し、バリデーション済みの QML が grounded_result になります。
• debug（「why is X failing?」「fix this error」）では、検索（quickshell_explain_error）と検証（関連する型のページと互換性）を実行し、その後バリデーション（quickshell_validate_qml）を実行します。grounded_result は診断と修正です。
• migrate（「migrate/upgrade from vX to vY」）では、検索（コードが指定されていない場合は破壊的変更のチェンジログ）、対象バージョンに対するバリデーション、および移行（quickshell_migrate）を実行します。grounded_result は順序付けられた移行計画です。
• pattern（「find an implementation ... and adapt it」）では、検索（上位の実装から短い抜粋を含む quickshell_find_pattern）と検証（提示された API の互換性）を実行します。grounded_result は抜粋と検証済み API です。
• research（「what is X?」「how do I ...?」）では、検索（すべての情報源）と検証（上位の型およびガイドのページと互換性）を実行します。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 フラグによって、検証済みの事実（公式ドキュメントに基づくもの）と推奨事項を区別できます。

使用する場面： 複数ステップにわたる開発リクエストや、どの単一ツールが適切かまだわからない場合に使用します。単一の対象に絞った検索（1 つの型のページ、1 つのエラーメッセージ、1 つのバージョン確認）には、該当するツールを直接呼び出してください。そのほうが低コストで、生の回答を得られます。

プロジェクト分析

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 は拡張可能なルールテーブルを使用します。互換性の判定で、ランタイムの非互換性を過剰に主張することはありません。migrate は機械可読な編集案を生成しますが、書き込みは行いません。

ランタイムツールは、分離された XDG ディレクトリ内で実際の qs プロセスを起動するため、管理対象のシェルがデスクトップセッションに触れることはありません。これらはオプトイン方式で、状態を変更するため、PATH 上に qs が必要です。

{"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_* ツールで管理できます。また、start で再利用できます。

ビジュアルおよび UI の検査

quickshell_windows、quickshell_ui_tree、quickshell_ui_find で、実行中のセッションを検査します。スクリーンショットの撮影には grim とコンポジターが必要です。UI のイントロスペクションには、シェル内に 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 は証拠を関連付け、確信度付きの仮説を導き出します。証拠がない場合にコストの原因を断定することはありません。

エージェント

quickshell_build_feature、quickshell_debug、quickshell_migrate_project、quickshell_test_feature、quickshell_optimize、quickshell_engineer は、それぞれ低レベルのツールを使って、明示的な段階的計画を実行します。各段階は分離されているため、どれかが失敗しても計画全体が頓挫することはありません。quickshell_engineer は一連の作業全体（ビルド、テスト、デバッグ、最適化、検証）を組み合わせ、各段階の結果と、フラット化された計画を返します。