flutter-mcp-toolkit-guide

使用する場面

ユーザーがこの会話から実行中の Flutter アプリを確認または操作したい場合に、このスキルを使用します。例：

• 「アプリのログインボタンをタップして」
• 「ホーム画面が真っ白なのはなぜ？」
• 「スクリーンショットを撮って、問題点を教えて」
• 「MCP 経由で、カート／フラグ／内部状態をエージェントに公開して」

ユーザーが実行中のアプリとは関係のない Flutter の概念について質問している場合（アーキテクチャに関する質問、パッケージの選定など）、このスキルは適用されません。

手順 1：事前確認

必ず最初に flutter-mcp-toolkit doctor --json を実行します。出力を解析します。

• status: "ok" — 手順 2 に進みます。
• status: "error" かつ error.code: "binary_not_found" — flutter-mcp-toolkit-setup を読み込み、インストール手順に従います。
• status: "error" かつ error.code: "vm_not_connected" — flutter-mcp-toolkit-setup を読み込み、トラブルシューティングのセクションに従います。
• その他のエラー — flutter-mcp-toolkit-debug を読み込み、エラーエンベロープの手順書を確認します。

手順 2：ユーザーの意図に合ったスキルを選ぶ

ユーザーの意図	読み込むスキル
状態の確認（「画面に何が表示されている？」「エラーを見せて」「スクリーンショット」）	flutter-mcp-toolkit-inspect
UI の操作（「X をタップ」「Y に入力」「Z までスクロール」「ホットリロード」）	flutter-mcp-toolkit-control
診断（「X が失敗するのはなぜ？」「最近のログを見せて」「式を評価して」）	flutter-mcp-toolkit-debug
アプリ固有の MCP ツール／リソースの登録（AgentCallEntry、addEntries）	flutter-mcp-toolkit-custom-tools
廃止されたレガシーのコールエントリー API からのアップグレード	flutter-mcp-toolkit-intentcall-migration
ツールのインターフェースを変更する前に、CLI／MCP／スキーマ／動的レジストリの同等性を監査する	flutter-mcp-boundary-audit
showcase/flutter_test_app の Web／WebMCP ショーケース用フックを保守する。Chrome DevTools MCP 経由でエージェントリストの取得／実行を行う（list_webmcp_tools／execute_webmcp_tool）	flutter-mcp-toolkit-maintain-web
showcase/flutter_test_app の macOS／ネイティブ IntentCall 用フックを保守する	flutter-mcp-toolkit-maintain-macos
dogfood のイテレーションを評価する、または dogfood のエビデンスを振り分ける	flutter-mcp-toolkit-dogfood-iterations
Dart で再利用可能な E2E シナリオを記述する（flutter_mcp_harness：ビルド／起動／接続／操作／アサート、ショーケースランチャー）	flutter-mcp-e2e-harness
複数のインターフェースにわたるアプリの自動化を接続する（MCP／CLI／ハーネス／oka）、初期ループ、ランナーセッション	flutter-mcp-automation-chain
リリース、バージョン管理、プラグインのスキルバンドルの保守	flutter-mcp-toolkit-repo-maintainer

ハーネススクリプトの lint／実行／Maestro と、プロモーション動画のキャプチャは、それぞれの担当リポジトリで行います。このプラグイン内で flutter-mcp-semantic-test、flutter-mcp-capture、hyperframes-video を探さないでください。

複数のスキルにまたがるタスク（例：「ボタンをタップして、何が変わったか見せて」）の場合は、inspect と control の両方を読み込みます。スキルは組み合わせて使用できます。

手順 3：実行

各タスクスキルには、ツールの一覧、パラメーターの形式、呼び出し例が記載されています。スキル冒頭の前置きに従ってください。MCP ツールを呼び出すのか、CLI をシェルから実行するのかが示されています。

ツールの分類リファレンス

コアツールキットのツールは、次のカテゴリに分類されます。パラメーターの形式を含む完全な一覧は、タスクスキルに記載されています。

• 調査（読み取り専用）： discover_debug_apps、get_app_errors、 get_screenshots、get_view_details、get_vm、get_extension_rpcs、 semantic_snapshot、inspect_widget_at_point、capture_ui_snapshot、 connect_debug_app。→ flutter-mcp-toolkit-inspect。
• 操作（変更あり）： tap_widget、long_press、enter_text、 reveal_search、fill_form、scroll、swipe、drag、hover、 focus_widget、press_key、wait_for、navigate、handle_dialog、 hot_reload_flutter、hot_restart_flutter、hot_reload_and_capture。→ flutter-mcp-toolkit-control。
• デバッグ： get_recent_logs、evaluate_dart_expression。→ flutter-mcp-toolkit-debug。
• 動的レジストリ（アプリ定義）： Flutter アプリへの登録後、MCP の呼び出しでは fmt_list_client_tools_and_resources を使用し、続いて fmt_client_tool / fmt_client_resource を使用します。CLI からシェルコマンドを実行する場合、 コマンド名は exec --name <name> の値としてのみ指定します。MCP ツールとして list_client_tools_and_resources、client_tool、client_resource を単独で呼び出さないでください。→ flutter-mcp-toolkit-custom-tools。
• 境界／証明のメンテナンス： カタログ／スキーマ／レジストリの対象範囲を変更する前に flutter-mcp-boundary-audit を使用します。ショーケースのプラットフォームフックには flutter-mcp-toolkit-maintain-web または flutter-mcp-toolkit-maintain-macos を使用し、リリース、バージョン、生成された スキルバンドルの作業には flutter-mcp-toolkit-repo-maintainer を使用します。
• 真の WebMCP（ブラウザー）： Chrome DevTools MCP （--categoryExperimentalWebmcp）を使用し、ウェブアプリに移動してから list_webmcp_tools / execute_webmcp_tool を使用します。 詳細は flutter-mcp-toolkit-maintain-web を参照してください。

判断に迷った場合

doctor が正常でもツール呼び出しに失敗する場合は、返された error.code フィールドと error.recovery フィールドを確認してください。コードから復旧方法への完全な対応表は flutter-mcp-toolkit-debug に記載されています。