flutter-mcp-toolkit-control

When to use

Use this skill when you need to drive a running Flutter app as a user would:

• Tap buttons, icons, list items, or any interactive widget.
• Type text into fields, submit forms, clear inputs.
• Scroll or swipe to reveal off-screen content.
• Navigate between routes programmatically (push, pop, popUntil).
• Dismiss dialogs and bottom sheets.
• Give a widget keyboard focus, then press keys (Enter, Escape, Tab, arrows, ASCII chars).
• Hot-reload or hot-restart after editing Dart source files.
• Combine reload + screenshot + semantics in one round-trip for fast iteration.

Selectors

Most interaction tools target a widget by ref — a short string like "s_0" returned by semantic_snapshot. For visible widgets, call semantic_snapshot, scan the returned nodes, find the right ref, then pass it. Narrow the node set with identifierPrefix or subtreeOf (a ref or an identifier), and cut every node down to the keys you read with fields; refs are those of the full tree either way. For off-screen targets with stable semantics text or identifier, use reveal_search; it performs a bounded snapshot → match → scroll loop and returns a fresh ref/snapshotId.

Snapshot node keys to scan:

Want to find	Scan field	Example value
By semantics identifier	identifier	"nav.tasks"
By visible label / text	label	"Login"
By value or hint	value / hint	"[email protected]"
By semantic role	type	"button"
By what it accepts	actions	["tap"]

Example — find the "Login" button ref:

semantic_snapshot()
→ nodes: [{ref:"s_0", label:"Login", actions:["tap"]}, ...]
tap_widget(ref: "s_0")

Pass snapshotId (from the snapshot response) to any interaction call. If the tree has changed, the call returns stale_snapshot with both IDs so you know to re-snapshot. Refs are only valid against the most recent snapshot.

Recipes

Tap a widget by text

semantic_snapshot()
→ find node where label == "Submit" → ref "s_3"
tap_widget(ref: "s_3", snapshotId: <id>)