flutter-mcp-cli-runtime-validation

Flutter MCP CLI ランタイム検証

最小限のオペレーター手順で、flutter-mcp-toolkit を介してエージェント形式のランタイム検証を行う必要がある場合は、このスキルを使用してください。

2 ステップのフロー

1. Flutter アプリをデバッグモードで起動します。
2. CLI コマンドを 1 つ実行します。

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart --save-images --output-dir .flutter_mcp/runtime_validation validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --timeout-ms 10000 \
  --post-reload-delay-ms 500 \
  --after-reload

同じコマンドでスキルをインストールすることもできます。

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --install-skill

このフローにおける権限の動作：

• validate-runtime はビジュアルキャプチャのみ読み取り／書き込みを行い、既定では auto_request_once を使用します。
• doctor は読み取り専用のままです。
• macOS では、画面収録の権限は flutter-mcp-toolkit を実行しているホストプロセスに付与されます。
• Web の場合：desktop_window は macOS では ScreenCaptureKit を使用し、その後 Chrome CDP（Page.captureScreenshot）を使用します。Linux／Windows では、リモートデバッグに接続できる場合、CDP を使用します。検出に失敗した場合は、--web-browser-debugging-port を指定してください。Web ターゲットでは、macOS ホストの desktop_window を誤って選択しないよう、--flutter-device chrome を指定してください。
• Executor は、ホストキャプチャを 1 回再試行します（スクリーンショットのペイロードでは desktopCaptureRetried）。それでも desktop_window が失敗した場合（プラットフォームビューが検出された場合を含む）、validate-runtime は flutter_layer で 1 回再試行します。data.summary.captureFallbackUsed を確認してください。
• URI が 1 つだけ必要な場合は、validate-runtime --target の代わりに、グローバルオプション --vm-service-uri に VM URI を渡すことができます。

validate-runtime で確認すること

• Doctor の事前チェックで重要な項目がすべて合格すること。
• 必須のツールキット拡張機能が存在すること：
  • ext.mcp.toolkit.app_errors
  • ext.mcp.toolkit.view_details
  • ext.mcp.toolkit.view_screenshots
  • ext.mcp.toolkit.inspect_widget_at_point
• スクリーンショットをキャプチャできること。
• ビューの詳細（レイアウトメタデータ）を取得できること。
• アプリのエラーを取得できること。
• --after-reload が有効な場合、リロード後のスクリーンショットも取得できること。

出力の処理

• 自動化の合否判定には data.summary を使用します。
• プラットフォームビューのルーティングには data.summary.capturePlatformViewsDetected と captureFocusAttempted を使用します。
• data.summary.captureFallbackUsed を使用して、desktop_window の失敗後に flutter_layer による再試行が行われたかどうか（プラットフォームビューが検出された場合を含む）を確認します。
• ステップごとのエビデンスと再試行には data.steps を使用します。
• セットアップを妨げている要因の説明には data.doctor.checks を使用します。
• --save-images が有効な場合、保存されたスクリーンショットのパスには data.summary.screenshotFiles を使用します。
• --save-images が有効な場合は、ステップデータからスクリーンショットファイルの URL を読み取ります。
• ビジュアルデバッグレポートを作成するには、次のコマンドも実行します：
  • exec --name capture_ui_snapshot --args '{"errorsCount":4,"compress":true,"includeViewDetails":true,"includeErrors":true}'
  • exec --name inspect_widget_at_point --args '{"x":<int>,"y":<int>}'

失敗時のルール

• ツールキット拡張機能が不足している場合は、作業を停止し、具体的な修正方法を添えて計測の不足を報告します：
  • アプリの依存関係に mcp_toolkit を追加します。
  • MCPToolkitBinding.instance.bootstrapFlutter(...) または同等の手動初期化が runApp の前に実行されることを確認します。
  • アプリをホットリスタートするか、再実行します。
• 明示的に指定した最初の URI への接続に失敗した場合、再試行可能な接続エラーであれば自動的に再試行されます。
• スクリーンショットが真っ白な場合は、アプリのウィンドウが表示されていることを確認して再試行します。
• macOS のビジュアルキャプチャが拒否された場合は、次を使用します：
  • dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions status
  • dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions request
  • dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions open-settings
• アプリに計測を追加できない場合は、スクリーンショット／レイアウト／エラーの検査に成功したと主張しないでください。

ビジュアル QA とソースマッピングのルール

• 変更前後のスクリーンショットのエビデンスを必ず比較します。
• 報告するビジュアル上の問題ごとに、座標と inspect_widget_at_point の出力を提示します。
• 可能な場合は、get_app_errors の最上位スタックフレーム（file、line、column）を使って、不具合をソースに対応付けます。
• 明示的に要求されない限り、debug_dump_* は使用しないでください。

課題となるケース（必ず明示してください）

• デバッグアプリが起動していない場合：vm_target_reachable で doctor が重大なエラーを報告します。続行する前に、アプリの起動を依頼してください。
• ターゲット URI／トークンが間違っている場合：接続先の不一致として扱い、正確な app.debugPort.wsUri を使って再試行してください。
• ツールキットを追加しても拡張機能が見つからない場合：ホットリロードでは不十分なことが多く、ホットリスタートまたは完全な再実行が必要です。
• 変更できないアプリ（ツールキットを追加できない場合）：推測で補わず、検査を利用できないと報告してください。