// 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.
| name | flutter-mcp-toolkit-guide |
| description | 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. |
Use this skill when the user wants to inspect or drive a running Flutter app from this conversation. Examples:
If the user is asking about Flutter concepts unrelated to a running app (architecture questions, package selection), this skill does not apply.
Always run flutter-mcp-toolkit doctor --json first. Parse the output:
status: "ok" — proceed to Step 2.status: "error" and error.code: "binary_not_found" — load
flutter-mcp-toolkit-setup and follow its install instructions.status: "error" and error.code: "vm_not_connected" — load
flutter-mcp-toolkit-setup and follow its troubleshooting section.flutter-mcp-toolkit-debug and read the error
envelope playbook.| User intent | Load skill |
|---|---|
| Read state ("what's on screen?", "show me errors", "screenshot") | flutter-mcp-toolkit-inspect |
| Drive UI ("tap X", "type into Y", "scroll to Z", "hot reload") | flutter-mcp-toolkit-control |
| Diagnose ("why is X failing?", "show recent logs", "evaluate expression") | flutter-mcp-toolkit-debug |
Register app-specific MCP tools/resources (MCPCallEntry, bootstrapFlutter additionalEntries) | flutter-mcp-toolkit-custom-tools |
Harness Script lint/run/Maestro (*.hs.yaml, app registry) | Install flutter_harness — skill flutter-mcp-semantic-test in that repo |
| HS capture bundles / promo video | flutter_harness + flutter_mcp_video (not bundled in toolkit init) |
If the task spans more than one (e.g. "tap the button and show me what
changed"), load inspect AND control. Skills are additive.
Each task skill has the tool list, parameter shapes, and example calls. Follow the prelude at the top of the skill — it tells you whether you're calling MCP tools or shelling out to the CLI.
The core toolkit tools fall into these categories. The full list with parameter shapes lives in the task skills.
discover_debug_apps, get_app_errors,
get_screenshots, get_view_details, get_vm, get_extension_rpcs,
semantic_snapshot, inspect_widget_at_point, capture_ui_snapshot,
connect_debug_app. → flutter-mcp-toolkit-inspect.tap_widget, long_press, enter_text,
fill_form, scroll, swipe, drag, hover, press_key, wait_for,
navigate, handle_dialog, hot_reload_flutter, hot_restart_flutter,
hot_reload_and_capture. → flutter-mcp-toolkit-control.get_recent_logs, evaluate_dart_expression. →
flutter-mcp-toolkit-debug.list_client_tools_and_resources, then client_tool /
client_resource — wire names as fmt_* when calling MCP. →
flutter-mcp-toolkit-custom-tools.If doctor is green but a tool call fails, read the returned error.code
and error.recovery fields. The full code → recovery table is in
flutter-mcp-toolkit-debug.
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.
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.
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.