// Read state from a running Flutter app — semantic snapshot, view details, errors, screenshots, VM info. Use when you need to understand what the app is showing.
Run Flutter MCP runtime validation from CLI in two steps (launch app, then run validate-runtime), including toolkit-extension gating, screenshot/layout capture, app error collection, optional reload verification, and retry handling for transient first-connect failures.
Diagnose problems in a running Flutter app — read logs, evaluate Dart expressions, interpret error envelopes. Use when something broke.
Maintain mcp_flutter releases, CHANGELOG, version pins, docs, and CI. Use when cutting a release, editing CHANGELOG.md, bumping VERSION, running release-please, sync-skills, check-contracts, or updating install/docs for npx skills and flutter-mcp-toolkit init.
Entry point for inspecting or driving a running Flutter app from your AI assistant — routes to the right task skill (inspect / control / debug / custom app surfaces) and runs preflight.
Verify the flutter-mcp-toolkit install, run doctor preflight, troubleshoot connection issues. Use when the toolkit isn't responding or first-time setup.
Use this skill when the agent exposes app-specific surfaces by registering custom MCP tools and resources inside the Flutter app (mcp_toolkit dynamic registry — MCPCallEntry, bootstrapFlutter additionalEntries / addEntries). Covers tool vs resource vs evaluate-expression, Map-based handlers, schema strictness, discovery via fmt_list_client_tools_and_resources, fmt_client_tool, fmt_client_resource, and lifecycle pitfalls.
| name | flutter-mcp-toolkit-inspect |
| description | Read state from a running Flutter app — semantic snapshot, view details, errors, screenshots, VM info. Use when you need to understand what the app is showing. |
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.
batch)flutter-mcp-toolkit batch --steps '[
{"name":"semantic_snapshot"},
{"name":"get_app_errors","args":{"count":5}},
{"name":"get_screenshots","args":{"screenshotMode":"flutter_layer","compress":true}}
]'
Use screenshotMode: flutter_layer on macOS to avoid Screen Recording permission failures.
semantic_snapshot().interactionSurface: flutter_widgets (tap-by-ref works), hybrid (sparse semantics), game_canvas (use evaluate_dart_expression + screenshots).ref (s_0, s_1, …) and the response includes a snapshot_id.snapshot_id to detect staleness.Prefer hot_reload_and_capture over separate reload + snapshot + screenshot calls.
get_app_errors(count: 10).errors array — each entry has message, stack trace, and timestamp.discover_debug_apps().targetId (canonical WebSocket URI) for each active target.connection.targetId on subsequent tool calls.inspect_widget_at_point(x: 200, y: 400).get_screenshots().meta.fileUrls is non-empty, screenshots are on disk at those paths. Otherwise the response contains base64 ImageContent blocks — extract and write manually.List all active Flutter debug targets with canonical WebSocket URIs.
connection (object, optional) — accepted by schema, ignored by executor; discovery is always local.discover_debug_apps()
Returns: {"targets": [{"targetId": "ws://127.0.0.1:8181/<token>/ws", "host": "...", "port": 8181}]}
vm_service_unavailable — no debug-mode Flutter process found.tool_not_found — binary predates v3.0.0; run make build.Retrieve the most recent application errors from the Dart VM.
count (integer, optional, default: 4) — number of errors to return.connection (object, optional) — connection override.get_app_errors(count: 5)
Returns: {"message": "2 errors found", "errors": [{"message": "...", "stack": "..."}]}
vm_service_unavailable — app not reachable.connection_selection_required — multiple targets; supply connection.targetId.Capture screenshots of all views.
compress (boolean, optional, default: true) — compress PNG output.mode (string, optional, default: auto) — auto, flutter_layer, or desktop_window.permissionPolicy (string, optional, default: check_only) — check_only, auto_request_once, or request_always.connection (object, optional) — connection override.get_screenshots(mode: "flutter_layer", compress: false)
Returns: ImageContent blocks (base64 PNG) when no output dir configured, or TextContent URL refs + meta.fileUrls when file output is enabled.
permission_denied — retry with permissionPolicy: "auto_request_once".vm_service_unavailable — app not reachable.Get dimensions, device pixel ratio, and display ID for all views.
connection (object, optional) — connection override.get_view_details()
Returns: {"views": [{"id": 0, "width": 1280, "height": 800, "devicePixelRatio": 2.0}]}
vm_service_unavailable — app not running.connection_selection_required — multiple targets; supply connection.targetId.Return Dart VM metadata: version, isolates list, pid, and architecture.
connection (object, optional) — connection override.get_vm()
Returns: {"type": "VM", "name": "vm", "version": "3.x.x", "isolates": [...]}
vm_service_unavailable — app not reachable.connection_selection_required — multiple targets active.List all registered VM service extension RPCs in the running app.
isolateId (string, optional) — schema-declared but not read by executor; checks all isolates when omitted.isRawResponse (boolean, optional) — schema-declared but not read by executor.connection (object, optional) — connection override.get_extension_rpcs()
Returns: {"extensionRPCs": ["ext.flutter.inspector.getRootWidget", "ext.mcp.toolkit.semantic_snapshot"]}
vm_service_unavailable — app not running.connection_selection_required — multiple targets.Return a compact accessibility tree of interactive widgets with stable ref strings and a snapshot_id.
connection (object, optional) — connection override.semantic_snapshot()
Returns: {"snapshot_id": 3, "nodes": [{"ref": "s_0", "label": "Increment", "actions": ["tap"]}]}
vm_service_unavailable — app not running or MCPToolkitBinding.initialize() not called.connection_selection_required — multiple targets; supply connection.targetId.Identify the deepest widget and render node at a global logical coordinate.
x (integer, required) — global logical X coordinate.y (integer, required) — global logical Y coordinate.viewId (integer, optional) — FlutterView ID for multi-view apps.connection (object, optional) — connection override.inspect_widget_at_point(x: 200, y: 400)
Returns: {"widget": {"type": "ElevatedButton", "rect": {"left": 180, "top": 380, "right": 280, "bottom": 420}}}
vm_service_unavailable — app not reachable.invalid_argument — coordinates out of view bounds.Capture screenshots, view details, and app errors in one bundled response.
errorsCount (integer, optional, default: 4) — errors to include.compress (boolean, optional, default: true) — compress screenshots.includeViewDetails (boolean, optional, default: true) — include view data.includeErrors (boolean, optional, default: true) — include app errors.screenshotMode (string, optional, default: auto) — auto, flutter_layer, or desktop_window.permissionPolicy (string, optional, default: check_only) — check_only, auto_request_once, or request_always.connection (object, optional) — connection override.capture_ui_snapshot(errorsCount: 2, includeViewDetails: false)
Returns: single TextContent JSON block with screenshots, viewDetails, and errors keys.
vm_service_unavailable — app not running.permission_denied — retry with permissionPolicy: "auto_request_once".Explicitly select and connect to a Flutter debug VM target. Use when multiple apps are running or to pin a specific target for the session.
connection (object, optional) — pass connection.targetId with a WebSocket URI from discover_debug_apps.connect_debug_app(connection: {targetId: "ws://127.0.0.1:8181/<token>/ws"})
Returns: {"connected": true, "targetId": "ws://127.0.0.1:8181/<token>/ws", "isolates": [...]}
target_not_found — URI doesn't match a running app; re-run discover_debug_apps for the exact URI.connection_failed — VM refused connection; verify the app is still running in debug mode.