flutter-mcp-toolkit-inspect

When to use

Use this skill for read-only state inspection of a running Flutter app: what is shown on screen, recent errors, available debug targets, VM metadata, and widget tree details. Do not use for driving interaction — that is the interact skill. Start with discover_debug_apps when no connection target is established. Start with semantic_snapshot when you need to know which widgets are on screen.

Recipes

Fast inspect cycle (prefer 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}}
]'

Use mode: flutter_layer on get_screenshots on macOS to avoid Screen Recording permission failures. capture_ui_snapshot uses the separate screenshotMode field.

Snapshot the visible UI

1. Call semantic_snapshot().
2. Read interactionSurface: flutter_widgets (tap-by-ref works), hybrid (sparse semantics), game_canvas (use evaluate_dart_expression + screenshots).
3. Each interactive node has a stable ref (s_0, s_1, …) and the response includes a snapshot_id.
4. Pass refs to interaction tools; pass the snapshot_id value as snapshotId to detect staleness.

After a code edit

Prefer hot_reload_and_capture over separate reload + snapshot + screenshot calls.

Find an error by message

1. Call get_app_errors(count: 10).
2. Inspect the errors array — each entry has message, stack trace, and timestamp.
3. Match on message text to find the source.

List debug-mode apps

1. Call discover_debug_apps().
2. Read the targetId (canonical WebSocket URI) for each active target.
3. Pass the chosen URI as connection.targetId on subsequent tool calls.

Get widget at coordinates

1. Call inspect_widget_at_point(x: 200, y: 400).
2. The response identifies the deepest widget and render node at those global logical pixel coordinates.