flutter-mcp

AI Community

Repo stars 0
Author repo skills-registry

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Use this skill whenever inspecting, interacting with, or live-editing a running Flutter app via the Flutter MCP toolkit server (…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “When to use”, “Preflight (always first)”, “Tool naming (v3.0.0+)”, “Interaction loop (Playwright-style)”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name flutter-mcp directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “When to use / Preflight (always first) / Tool naming (v3.0.0+)” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Flutter MCP

Golden path for agents driving a live Flutter app via the flutter-mcp-toolkit MCP server entry. Older configs may use the legacy flutter-inspector mcpServers registry id for the same binary (that id is not the Claude subagent flutter-mcp-toolkit-runtime).

When to use

User references a running Flutter app (debug mode) and wants to inspect, screenshot, interact with, or hot-reload it.
User pastes a VM service URI (ws://127.0.0.1:8181/.../ws) or mentions port 8181.
You need runtime proof (before/after screenshots) that a code edit took effect.

Preflight (always first)

Before any VM-dependent call:

Call doctor (or run flutter-mcp-toolkit doctor --json) — parses env, ports, app reachability.
Confirm required toolkit extensions exist on the target:
- ext.mcp.toolkit.app_errors
- ext.mcp.toolkit.view_details
- ext.mcp.toolkit.view_screenshots
- ext.mcp.toolkit.inspect_widget_at_point

If missing, stop and report the instrumentation gap — do not guess:

Add mcp_toolkit to pubspec.yaml.
Ensure MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit(); runs before runApp.
Hot restart (not reload) — reload is often insufficient for extension registration.

Tool naming (v3.0.0+)

All MCP tools surface under the fmt_ capability prefix (fmt_tap_widget, fmt_hot_reload_and_capture, etc.). The prefix is mandatory in tools/call. Skill-local references below use the bare name for readability — when invoking, prepend fmt_. Dynamic-registry host tools (fmt_list_client_tools_and_resources, fmt_client_tool, fmt_client_resource) use the same prefix for a single consistent surface.

Interaction loop (Playwright-style)

fmt_semantic_snapshot → returns s_0..s_N refs + snapshot_id.
fmt_tap_widget / fmt_enter_text / fmt_scroll / fmt_swipe / fmt_long_press / fmt_drag — act on a ref. Always pass snapshotId — you get a structured stale_snapshot error if the tree moved, instead of a silent wrong tap.
fmt_evaluate_dart_expression — read state directly (e.g. AgentState.instance.counter).
fmt_hot_reload_and_capture — after a code edit, returns reload status + screenshot + fresh snapshot + errors in one response. Prefer this over manual reload + separate capture.

Error envelope contract

Errors are {code, message, details, descriptor, recovery}. Parse error.descriptor (not the top-level object) for the machine-readable shape. Strict schemas default to additionalProperties: false — unknown params reject.

Common codes and recovery:

connection_selection_required — retry with arguments.connection.targetId or exact arguments.connection.uri from app.debugPort.wsUri.
target_not_found — refresh targets, then prefer exact arguments.connection.uri.
stale_snapshot — call fmt_semantic_snapshot again, then retry the action with the new snapshot_id.
tool_not_found — confirm the prefixed name (fmt_<tool>); v3.0.0 dropped legacy unprefixed names.
Empty screenshot output — verify the server was not started with --no-images.
Missing view resource/tool — verify the server was not started with --no-resources.

Visual QA

Before/after screenshots are the proof artifact for any UI claim. Capture before with fmt_capture_ui_snapshot (or one of the visual://localhost/... resources), edit, fmt_hot_reload_and_capture, compare.
For each reported visual issue, attach coordinate + fmt_inspect_widget_at_point output.
Map defects to source via fmt_get_app_errors top stack frame (file, line, column) when available.
Do not use fmt_debug_dump_* unless explicitly requested (server must be started with --dumps; high token cost).

Permissions (macOS)

Screen Recording permission belongs to the process running flutter-mcp-toolkit (or the MCP server host). If visual capture is denied:

flutter-mcp-toolkit permissions status
flutter-mcp-toolkit permissions request
flutter-mcp-toolkit permissions open-settings

Non-modifiable apps

If the target app cannot be instrumented (third-party binary, restricted env), report flutter-mcp as unavailable for that app. Do not claim screenshot/layout/error inspection success.

For the dynamic-tools side (registering custom MCP tools from inside the Flutter app), see the flutter-mcp-toolkit-custom-tools skill.
For routing across setup / inspect / control / debug skills, see flutter-mcp-toolkit-guide.

Source: Arenukvern/mcp_flutter — distributed by TomeVault.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: AI
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @tomevault-io · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: macOS
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview flutter-mcp.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

<!-- @FMT_MODE_PRELUDE -->

# Flutter MCP

Golden path for agents driving a live Flutter app via the **`flutter-mcp-toolkit`** MCP server entry. Older configs may use the legacy **`flutter-inspector`** `mcpServers` registry id for the same binary (that id is **not** the Claude subagent **`flutter-mcp-toolkit-runtime`**).

## When to use

- User references a running Flutter app (debug mode) and wants to inspect, screenshot, interact with, or hot-reload it.
- User pastes a VM service URI (`ws://127.0.0.1:8181/.../ws`) or mentions port 8181.
- You need runtime proof (before/after screenshots) that a code edit took effect.

## Preflight (always first)

Before any VM-dependent call:

1. Call `doctor` (or run `flutter-mcp-toolkit doctor --json`) — parses env, ports, app reachability.
2. Confirm required toolkit extensions exist on the target:
   - `ext.mcp.toolkit.app_errors`
   - `ext.mcp.toolkit.view_details`
   - `ext.mcp.toolkit.view_screenshots`
   - `ext.mcp.toolkit.inspect_widget_at_point`

If missing, stop and report the instrumentation gap — do **not** guess:

- Add `mcp_toolkit` to `pubspec.yaml`.
- Ensure `MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit();` runs before `runApp`.
- Hot **restart** (not reload) — reload is often insufficient for extension registration.

## Tool naming (v3.0.0+)

All MCP tools surface under the `fmt_` capability prefix
(`fmt_tap_widget`, `fmt_hot_reload_and_capture`, etc.). The prefix is
mandatory in `tools/call`. Skill-local references below use the bare name
for readability — when invoking, prepend `fmt_`. Dynamic-registry host
tools (`fmt_list_client_tools_and_resources`, `fmt_client_tool`,
`fmt_client_resource`) use the same prefix for a single consistent surface.

## Interaction loop (Playwright-style)

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> When to use → Preflight (always first) → Tool naming (v3.0.0+) → Interaction loop (Playwright-style) → Error envelope contract → Visual QA
terms    -> flutter-mcp-toolkit · flutter-inspector · not · flutter-mcp-toolkit-runtime · restart · Always pass snapshotId
files/cmd -> flutter-mcp-toolkit · flutter-inspector · mcpServers · flutter-mcp-toolkit-runtime · ws://127.0.0.1:8181/.../ws · doctor · flutter-mcp-toolkit doctor --json · ext.mcp.toolkit.apperrors
body sha256 -> a0fb1692e5c3