flutter-mcp

Flutter MCP

flutter-mcp-toolkit MCP サーバーエントリーを介して、実行中の Flutter アプリをエージェントが操作するための推奨手順です。古い設定では、同じバイナリに対してレガシーの flutter-inspector mcpServers レジストリ ID が使われている場合があります（この ID は Claude のサブエージェント flutter-mcp-toolkit-runtime ではありません）。

使用するタイミング

• ユーザーが実行中の Flutter アプリ（デバッグモード）に言及し、調査、スクリーンショットの撮影、操作、またはホットリロードを求めている場合。
• ユーザーが VM サービス URI（ws://127.0.0.1:8181/.../ws）を貼り付けた場合、またはポート 8181 に言及した場合。
• コード編集が反映されたことを示す実行時の証拠（編集前後のスクリーンショット）が必要な場合。

事前確認（必ず最初に実施）

VM に依存する呼び出しを行う前に、次の手順を実施します。

1. doctor を呼び出す（または flutter-mcp-toolkit doctor --json を実行する）— 環境変数とポートを解析し、アプリへの到達可能性を確認します。
2. 対象に次の必須ツールキット拡張機能が存在することを確認します。
   • ext.mcp.toolkit.app_errors
   • ext.mcp.toolkit.view_details
   • ext.mcp.toolkit.view_screenshots
   • ext.mcp.toolkit.inspect_widget_at_point

存在しない場合は停止し、計測機能の不足を報告します。推測で補ってはいけません。

• pubspec.yaml に mcp_toolkit を追加します。
• runApp の前に MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit(); が実行されることを確認します。
• ホットリスタートを行います（リロードではありません）。拡張機能の登録には、リロードだけでは不十分なことがよくあります。

ツール名（v3.0.0 以降）

すべての MCP ツールは fmt_ ケイパビリティプレフィックス付きで公開されます （fmt_tap_widget、fmt_hot_reload_and_capture など）。tools/call ではこのプレフィックスが 必須です。以下のスキル内の参照では読みやすさのためにプレフィックスを省略していますが、 呼び出す際には fmt_ を付けてください。動的レジストリのホストツール （fmt_list_client_tools_and_resources、fmt_client_tool、 fmt_client_resource）にも、一貫したインターフェースにするため同じプレフィックスが付いています。

インタラクションループ（Playwright 形式）

1. fmt_semantic_snapshot → s_0..s_N の参照と snapshot_id を返します。
2. fmt_tap_widget / fmt_enter_text / fmt_scroll / fmt_swipe / fmt_long_press / fmt_drag — 参照を使って操作します。必ず snapshotId を渡してください — ツリーが移動した場合、誤ったタップが黙って実行されるのではなく、構造化された stale_snapshot エラーが返されます。
3. fmt_reveal_search — 画面外にあるセマンティックターゲットに対して、範囲を限定してスナップショット取得、検索、スクロールを行い、新しい ref と snapshotId を返します。
4. fmt_evaluate_dart_expression — 状態を直接読み取ります（例：AgentState.instance.counter）。
5. fmt_hot_reload_and_capture — コード編集後に呼び出すと、リロードのステータス、スクリーンショット、新しいスナップショット、エラーを1つのレスポンスで返します。手動でリロードしてから別途キャプチャするより、こちらを優先してください。

エラーエンベロープの仕様

エラーは {code, message, details, descriptor, recovery} です。機械可読な構造を解析するには、トップレベルのオブジェクトではなく error.descriptor を解析してください。厳格なスキーマでは、デフォルトで additionalProperties: false が設定されているため、未知のパラメーターは拒否されます。

一般的なコードと対処方法：

• connection_selection_required — app.debugPort.wsUri にある arguments.connection.targetId または正確な arguments.connection.uri を指定して再試行します。
• target_not_found — ターゲットを再取得してから、正確な arguments.connection.uri を優先して指定します。
• stale_snapshot — fmt_semantic_snapshot を再度呼び出してから、新しい snapshotId 入力で操作を再試行します。
• tool_not_found — プレフィックス付きの名前（fmt_<tool>）を確認します。v3.0.0 ではプレフィックスなしのレガシー名が廃止されました。
• スクリーンショットの出力が空 — サーバーが --no-images を付けて起動されていないことを確認します。
• ビューのリソース／ツールが見つからない — サーバーが --no-resources を付けて起動されていないことを確認します。

ビジュアル QA

• UI に関する主張の証拠として、編集前後のスクリーンショットを用意します。編集前に fmt_capture_ui_snapshot（または visual://localhost/... リソースのいずれか）でキャプチャし、編集後に fmt_hot_reload_and_capture を実行して比較します。
• 報告する視覚的な問題ごとに、座標と fmt_inspect_widget_at_point の出力を添付します。
• 利用可能な場合は、fmt_get_app_errors のスタックトレース最上位フレーム（file、line、column）を使って、問題をソースコードに対応付けます。
• 明示的に要求されない限り、fmt_debug_dump_* は使用しないでください（サーバーの起動時に --dumps が必要で、トークン消費も大きくなります）。

権限（macOS）

画面収録の権限は、flutter-mcp-toolkit を実行するプロセス（または MCP サーバーのホスト）に付与します。画面のキャプチャが拒否された場合：

flutter-mcp-toolkit permissions status
flutter-mcp-toolkit permissions request
flutter-mcp-toolkit permissions open-settings

変更できないアプリ

対象アプリにインストゥルメントできない場合（サードパーティのバイナリ、制限された環境など）は、そのアプリでは flutter-mcp を利用できないと報告してください。スクリーンショット／レイアウト／エラーの検査に成功したと主張してはいけません。

関連項目

• 動的ツール（Flutter アプリ内からカスタム MCP ツールを登録する機能）については、flutter-mcp-toolkit-custom-tools スキルを参照してください。
• セットアップ／検査／操作／デバッグの各スキル間の振り分けについては、flutter-mcp-toolkit-guide を参照してください。
• チェックイン済みの Dart として再現可能なシナリオを扱う場合（MCP を使わずにビルド／起動／アタッチ／操作／アサートする場合）は、flutter-mcp-e2e-harness を参照してください。