flutter-mcp-toolkit-inspect

使用する場面

実行中の Flutter アプリの読み取り専用の状態確認に使用します。画面に表示されている内容、最近のエラー、利用可能なデバッグターゲット、VM メタデータ、ウィジェットツリーの詳細を確認できます。操作の実行には使用しないでください。操作には interact スキルを使用します。接続先が確立されていない場合は、discover_debug_apps から開始します。画面上のウィジェットを確認する必要がある場合は、semantic_snapshot から開始します。

レシピ

高速な確認サイクル（batch を優先）

flutter-mcp-toolkit batch --steps '[
  {"name":"semantic_snapshot"},
  {"name":"get_app_errors","args":{"count":5}},
  {"name":"get_screenshots","args":{"mode":"flutter_layer","compress":true}}
]'

macOS で Screen Recording の権限エラーを回避するには、get_screenshots で mode: flutter_layer を使用します。capture_ui_snapshot では、別の screenshotMode フィールドを使用します。

表示中の UI のスナップショットを取得する

1. semantic_snapshot() を呼び出します。
2. interactionSurface を確認します。flutter_widgets（ref によるタップが可能）、hybrid（セマンティクスがまばら）、game_canvas（evaluate_dart_expression とスクリーンショットを使用）があります。
3. 各インタラクティブノードには安定した ref（s_0、s_1、…）があり、レスポンスには snapshot_id が含まれます。
4. ref を操作ツールに渡します。古いスナップショットかどうかを検出するには、snapshot_id の値を snapshotId として渡します。

コードを編集した後

個別にリロード、スナップショット、スクリーンショットを呼び出すより、hot_reload_and_capture を優先してください。

メッセージからエラーを見つける

1. get_app_errors(count: 10) を呼び出します。
2. errors 配列を確認します。各エントリーには、メッセージ、スタックトレース、タイムスタンプが含まれています。
3. メッセージのテキストを照合して、発生元を見つけます。

デバッグモードのアプリを一覧表示する

1. discover_debug_apps() を呼び出します。
2. 各アクティブなターゲットの targetId（正規の WebSocket URI）を確認します。
3. 選択した URI を、後続のツール呼び出しで connection.targetId として渡します。

座標位置のウィジェットを取得する

1. inspect_widget_at_point(x: 200, y: 400) を呼び出します。
2. レスポンスには、指定したグローバルな論理ピクセル座標にある最深のウィジェットとレンダーノードが示されます。

スクリーンショットをファイルに保存する

1. get_screenshots() を呼び出します。
2. meta.fileUrls が空でない場合、スクリーンショットはそのパスにディスク上で保存されています。それ以外の場合、レスポンスには base64 の ImageContent ブロックが含まれます。手動で抽出して書き込んでください。
3. ファイル出力を強制するには、呼び出す前にサーバーで画像の出力ディレクトリを設定します。

ツールリファレンス

discover_debug_apps

アクティブな Flutter デバッグターゲットを、正規の WebSocket URI とともにすべて一覧表示します。

• connection（オブジェクト、省略可）— スキーマでは受け付けますが、実行側では無視されます。検出は常にローカルで行われます。

discover_debug_apps()

戻り値：{"targets": [{"targetId": "ws://127.0.0.1:8181/<token>/ws", "host": "...", "port": 8181}]}

• vm_service_unavailable — デバッグモードの Flutter プロセスが見つかりません。
• tool_not_found — バイナリのバージョンが v3.0.0 より前です。make build を実行してください。

get_app_errors

Dart VM からアプリケーションの最新のエラーを取得します。

• count（整数、省略可、デフォルト：4）— 返すエラーの数です。
• connection（オブジェクト、省略可）— 接続の上書き設定です。

get_app_errors(count: 5)

戻り値：{"message": "2 errors found", "errors": [{"message": "...", "stack": "..."}]}

• vm_service_unavailable — アプリに到達できません。
• connection_selection_required — 複数のターゲットがあります。connection.targetId を指定してください。

get_screenshots

すべてのビューのスクリーンショットを取得します。

• compress（ブール値、省略可、デフォルト：true）— PNG 出力を圧縮します。
• mode（文字列、省略可、デフォルト：auto）— auto、flutter_layer、または desktop_window です。
• permissionPolicy（文字列、省略可、デフォルト：check_only）— check_only、auto_request_once、または request_always です。
• connection（オブジェクト、省略可）— 接続の上書き設定です。

get_screenshots(mode: "flutter_layer", compress: false)

戻り値：出力ディレクトリが設定されていない場合は ImageContent ブロック（base64 PNG）、ファイル出力が有効な場合は TextContent の URL 参照と meta.fileUrls です。

• permission_denied — permissionPolicy: "auto_request_once" を指定して再試行してください。
• vm_service_unavailable — アプリに到達できません。

get_view_details

すべてのビューのサイズ、デバイスのピクセル比、ディスプレイ ID を取得します。

• connection（object、optional） — 接続のオーバーライド。

get_view_details()

戻り値：{"views": [{"id": 0, "width": 1280, "height": 800, "devicePixelRatio": 2.0}]}

• vm_service_unavailable — アプリが実行されていません。
• connection_selection_required — 複数のターゲットがあります。connection.targetId を指定してください。

get_vm

Dart VM のメタデータ（バージョン、isolate の一覧、pid、アーキテクチャ）を返します。

• connection（object、optional） — 接続のオーバーライド。

get_vm()

戻り値：{"type": "VM", "name": "vm", "version": "3.x.x", "isolates": [...]}

• vm_service_unavailable — アプリに到達できません。
• connection_selection_required — 複数のターゲットがアクティブです。

get_extension_rpcs

実行中のアプリに登録されている VM service 拡張 RPC をすべて一覧表示します。

• isolateId（string、optional） — スキーマで宣言されていますが、エグゼキューターでは読み取られません。省略すると、すべての isolate がチェックされます。
• isRawResponse（boolean、optional） — スキーマで宣言されていますが、エグゼキューターでは読み取られません。
• connection（object、optional） — 接続のオーバーライド。

get_extension_rpcs()

戻り値：{"extensionRPCs": ["ext.flutter.inspector.getRootWidget", "ext.mcp.toolkit.semantic_snapshot"]}

• vm_service_unavailable — アプリが実行されていません。
• connection_selection_required — 複数のターゲットがあります。

semantic_snapshot

安定した ref 文字列と snapshot_id を持つ、操作可能なウィジェットの簡潔なアクセシビリティツリーを返します。ノードは、読み取り可能な値（ラベル、値）がある場合、操作可能な要素（ボタン、テキストフィールド、タップ、スクロールなど）である場合、または Semantics(identifier:) を持つ場合に一覧表示されます。

• identifierPrefix（string、optional） — 識別子がこの値で始まるノードだけを残します（1 つのレールだけに絞る場合は "nav."）。
• subtreeOf（string、optional） — 1 つのノードとその子孫だけを残します。最新のスナップショットの ref、または識別子を指定します。ref が優先して試されます。
• fields（array of strings、optional） — 返すノードキー。ref は常に含まれます。名前：ref id type identifier label value hint enabled focused checked toggled selected bounds actions children visibleInViewport centerInViewport center。
• connection（object、optional） — 接続のオーバーライド。

ツリーは常に全体を走査するため、フィルター済みスナップショットから読み取った ref は、完全なスナップショットで得られる ref と同じであり、すべての操作ツールで使用できます。フィルター済みの応答には totalNodeCount が追加され、filter がそのまま返されます。children には、残された ref のみが列挙されます。

semantic_snapshot()
semantic_snapshot(identifierPrefix: "nav.", fields: ["identifier", "selected"])
semantic_snapshot(subtreeOf: "panel.tabs")

戻り値：{"snapshot_id": 3, "nodeCount": 1, "viewport": {...}, "nodes": [{"ref": "s_0", "label": "Increment", "actions": ["tap"], "bounds": {...}, "visibleInViewport": true, "centerInViewport": true, "center": {...}}]} — viewport はエンベロープ内に一度だけ記載され、各ノードには記載されません。

• subtree_root_not_found — subtreeOf が最新のスナップショットの ref でも、ツリー内の識別子でもありません。スナップショットは取得されず、ref と snapshot_id は変わりません。
• unknown_field — fields にノードキーではない名前が指定されています。acceptedFields に使用可能な名前が列挙されます。MCP および CLI 経由では、代わりに境界でその名前が拒否されます。使用可能なキー名を示す無効な fields 引数が返され、アプリへの呼び出しは行われません。
• vm_service_unavailable — アプリが実行されていないか、MCPToolkitBinding.initialize() が呼び出されていません。
• connection_selection_required — 複数のターゲットがあります。connection.targetId を指定してください。

inspect_widget_at_point

グローバル論理座標にある最も深いウィジェットとレンダーノードを特定します。

• x（integer、required） — グローバル論理 X 座標。
• y（integer、required） — グローバル論理 Y 座標。
• viewId（integer、optional） — マルチビューアプリの FlutterView ID。
• connection（object、optional） — 接続のオーバーライド。

inspect_widget_at_point(x: 200, y: 400)

戻り値：{"widget": {"type": "ElevatedButton", "rect": {"left": 180, "top": 380, "right": 280, "bottom": 420}}}

• vm_service_unavailable — アプリに到達できません。
• invalid_argument — 座標がビューの範囲外です。

capture_ui_snapshot

スクリーンショット、詳細情報、アプリのエラーをまとめてキャプチャし、1つのレスポンスで返します。

• errorsCount（整数、任意、デフォルト：4）— 含めるエラーの数です。
• compress（ブール値、任意、デフォルト：true）— スクリーンショットを圧縮します。
• includeViewDetails（ブール値、任意、デフォルト：true）— ビューのデータを含めます。
• includeErrors（ブール値、任意、デフォルト：true）— アプリのエラーを含めます。
• screenshotMode（文字列、任意、デフォルト：auto）— auto、flutter_layer、または desktop_window です。
• permissionPolicy（文字列、任意、デフォルト：check_only）— check_only、auto_request_once、または request_always です。
• connection（オブジェクト、任意）— 接続設定を上書きします。

capture_ui_snapshot(errorsCount: 2, includeViewDetails: false)

戻り値：screenshots、viewDetails、errors キーを含む TextContent JSON ブロックです。screenshots.images にインラインの base64 データが含まれる場合、各ペイロードは兄弟の画像ブロックに移され、JSON では screenshots.imagesDeliveredAs: "image_blocks" と報告されます。このとき images リストが空になるのは通常の形式であり、キャプチャの失敗を示すものではありません。screenshots.fileUrls を介して配信されたキャプチャは JSON 内に保持され、画像ブロックは生成されません。

• vm_service_unavailable — アプリが実行されていません。
• permission_denied — permissionPolicy: "auto_request_once" を指定して再試行してください。

connect_debug_app

Flutter デバッグ VM の接続先を明示的に選択して接続します。複数のアプリが実行されている場合や、セッション中に特定の接続先を固定する場合に使用します。

• connection（オブジェクト、任意）— discover_debug_apps から取得した WebSocket URI を connection.targetId に指定します。

connect_debug_app(connection: {targetId: "ws://127.0.0.1:8181/<token>/ws"})

戻り値：{"connected": true, "targetId": "ws://127.0.0.1:8181/<token>/ws", "isolates": [...]}

• target_not_found — URI が実行中のアプリと一致しません。正確な URI を取得するため、discover_debug_apps を再実行してください。
• connection_failed — VM が接続を拒否しました。アプリがデバッグモードで引き続き実行されていることを確認してください。