Flutter MCP Toolkit

MCP Toolkit Server (Dart)

Migrating from v2.x

Tool names on MCP are prefixed with `fmt_`, binaries and mcpServers keys were renamed — see [Migrating from v2.x to v3.0](../docs/start_here/migration_v2_to_v3.mdx).

Architecture

This project now uses a shared core execution layer:

1. flutter-mcp-toolkit is the canonical command surface (connect, inspect, execute, diagnostics). fmtk is the short alias for the same CLI entrypoint.
2. flutter-mcp-toolkit-server is a thin MCP protocol adapter that maps MCP tool/resource calls to the same core executor.
3. MCP `tools/list` names use the `fmt_` capability prefix; CLI `exec --name` uses command catalog names or aliases outside the MCP tools/call namespace. Resource URIs are unchanged.

The shared core module is available as flutter_mcp_core inside this package.

Golden Path

Use this sequence first on macOS:

1. Add mcp_toolkit to the app and call MCPToolkitBinding.instance.bootstrapFlutter(...).
2. Launch the app in debug mode.
3. Run fmtk validate-runtime (or the canonical long form flutter-mcp-toolkit validate-runtime).
4. Query dynamic entries in this order: fmt_list_client_tools_and_resources, fmt_client_tool, fmt_client_resource.

Treat exec as expert mode. validate-runtime is the default first-pass proof command.

CLI v3 Surface (Hard Cut)

The CLI is now agent-first and exposes a canonical interface:

• exec --name --args
• schema [--name ]
• capabilities
• serve (JSON-RPC 2.0 over stdio)
• snapshot create --name [--args ]
• snapshot diff --from --to
• bundle create --from-snapshot [--output ]
• doctor [--json] [--target ] [--timeout-ms ]
• permissions status|request|open-settings [--kind visual_capture]

Safe-write flags for write-producing commands:

• snapshot create: --check --diff --backup --no-overwrite
• bundle create: --check --diff --backup --no-overwrite

exec targets commands in the shared CommandCatalog (CLI command names may be bare because they appear only after --name; the CLI is not the MCP tools/call namespace): connect, session_start, session_exec, session_end, diagnose, watch, explain_errors, status, discover_debug_apps, get_vm, get_extension_rpcs, hot_reload_flutter, hot_restart_flutter, get_active_ports, get_app_errors, get_screenshots, focus_window, get_view_details, inspect_widget_at_point, capture_ui_snapshot, debug_dump_layer_tree, debug_dump_semantics_tree, debug_dump_render_tree, debug_dump_focus_tree, fmt_list_client_tools_and_resources, fmt_client_tool, fmt_client_resource, dynamicRegistryStats, semantic_snapshot, tap_widget, long_press, enter_text, reveal_search, scroll, swipe, drag, hot_reload_and_capture, evaluate_dart_expression, get_recent_logs.

MCP names. When invoked via MCP tools/call, exposed tools use the

fmt_ capability prefix (e.g. fmt_tap_widget,

fmt_hot_reload_and_capture). The dynamic-registry host trio is exposed as

fmt_list_client_tools_and_resources, fmt_client_tool, and

fmt_client_resource where enabled. dynamicRegistryStats remains available

from the CLI catalog for low-level diagnostics and is not part of the default

MCP tool surface.

Interaction tools (catalog names: semantic_snapshot → tap_widget / enter_text / reveal_search / scroll / swipe / long_press / drag) follow a Playwright-style ref model: take a snapshot, then pass ref: "s_N" (and optional snapshotId for staleness detection) into the interaction tool. reveal_search is the bounded helper for off-screen semantic targets: it snapshots, matches one narrow selector, scrolls up to maxAttempts, and returns a fresh ref/snapshotId plus trace. hot_reload_and_capture fuses reload + screenshot + fresh snapshot + errors. evaluate_dart_expression runs an ad-hoc Dart expression against the app's root library. See docs/start_here/cli_quick_recipes.mdx and docs/guides/interaction_cookbook.mdx for the full surface and golden paths.

Packaged installs include both flutter-mcp-toolkit and fmtk; examples below use dart run for source-tree development. Prefer fmtk for compact local loops and keep flutter-mcp-toolkit in onboarding, install, PATH, and MCP config docs where the searchable canonical name helps.

CLI runs the same shared command catalog/executor as MCP. Preferred debugging path: discover_debug_apps -> capture_ui_snapshot -> inspect_widget_at_point. get_active_ports and dynamicRegistryStats remain available in CLI for low-level diagnostics, but are intentionally not MCP-exposed by default.

CLI Quick Use (v3)

# introspection

dart run bin/flutter_mcp_toolkit.dart schema dart run bin/flutter_mcp_toolkit.dart capabilities

one-shot execution (machine envelope)

dart run bin/flutter_mcp_toolkit.dart exec --name status --args '{}' dart run bin/flutter_mcp_toolkit.dart exec --name get_vm --args '{}' dart run bin/flutter_mcp_toolkit.dart exec --name get_vm --args '{"connection":{"targetId":"ws://127.0.0.1:8181/ /ws"}}' dart run bin/flutter_mcp_toolkit.dart exec --name discover_debug_apps --args '{}' dart run bin/flutter_mcp_toolkit.dart exec --name capture_ui_snapshot --args '{"connection":{"targetId":"ws://127.0.0.1:8181/ /ws"}}' dart run bin/flutter_mcp_toolkit.dart exec --name inspect_widget_at_point --args '{"x":120,"y":220,"connection":{"targetId":"ws://127.0.0.1:8181/ /ws"}}'

session lifecycle

dart run bin/flutter_mcp_toolkit.dart exec --name session_start --args '{"mode":"uri","uri":"ws://127.0.0.1:8181/ /ws"}' dart run bin/flutter_mcp_toolkit.dart exec --name session_exec --args '{"command":"get_app_errors","arguments":{"count":4}}' dart run bin/flutter_mcp_toolkit.dart exec --name session_end --args '{}'

reproducible artifacts

dart run bin/flutter_mcp_toolkit.dart snapshot create --name baseline --args '{"commands":[{"name":"status","args":{}}]}' --check --diff dart run bin/flutter_mcp_toolkit.dart snapshot diff --from baseline --to after_fix dart run bin/flutter_mcp_toolkit.dart bundle create --from-snapshot baseline --backup

environment preflight

dart run bin/flutter_mcp_toolkit.dart doctor --json dart run bin/flutter_mcp_toolkit.dart permissions status dart run bin/flutter_mcp_toolkit.dart permissions request dart run bin/flutter_mcp_toolkit.dart permissions open-settings dart run bin/flutter_mcp_toolkit.dart exec --name get_extension_rpcs --args '{}'

explicit capture policy/mode

dart run bin/flutter_mcp_toolkit.dart exec --name get_screenshots --args '{"mode":"desktop_window","permissionPolicy":"auto_request_once"}' dart run bin/flutter_mcp_toolkit.dart exec --name capture_ui_snapshot --args '{"screenshotMode":"auto","permissionPolicy":"auto_request_once"}'

one-command runtime validation (after app launch)

dart run bin/flutter_mcp_toolkit.dart --save-images --output-dir .flutter_mcp/app validate-runtime \ --target ws://127.0.0.1:8181/ /ws \ --timeout-ms 10000 \ --post-reload-delay-ms 500 \ --after-reload

same, using global VM URI (equivalent to --target when only one is passed)

dart run bin/flutter_mcp_toolkit.dart --vm-service-uri ws://127.0.0.1:8181/ /ws validate-runtime \ --timeout-ms 10000

optional: install bundled skill during runtime validation

dart run bin/flutter_mcp_toolkit.dart validate-runtime \ --target ws://127.0.0.1:8181/ /ws \ --install-skill

CLI runtime gate for app inspection:

• Require ext.mcp.toolkit.app_errors, ext.mcp.toolkit.view_details, ext.mcp.toolkit.view_screenshots, and ext.mcp.toolkit.inspect_widget_at_point from get_extension_rpcs.
• If missing, app-level screenshot/layout/error inspection is blocked until mcp_toolkit is installed, initialized, and the app is hot restarted or rerun.
• If screenshots show a black rectangle where a map/camera/web view should be, check captureHints on get_view_details or screenshot payloads (platformViewsDetected or weakSignalsDetected). Use mode: desktop_window (or keep auto, which upgrades on macOS host when strong signals are present) instead of flutter_layer.
• Host capture runs one automatic focus+capture recovery cycle on retryable failures (desktopCaptureRetried in the payload). You can also call focus_window then retry get_screenshots with desktop_window.
• If first explicit-URI connect times out, retry once and validate with doctor --json --target --timeout-ms 10000.
• When --output-dir is set, validate-runtime mirrors its JSON envelope to /validate-runtime.json and screenshot files are written under /.mcp_screenshots/.
• validate-runtime tries host desktop_window first when auto selects it. Executor recovery retries focus+capture once (desktopCaptureRetried). If desktop_window still fails, validate-runtime retries once with flutter_layer (including when platform views are detected, e.g. the showcase AppKitView). Check data.summary.capturePlatformViewsDetected, captureFocusAttempted, and captureFallbackUsed. Web headful capture options: ADR 0007.

Visual Capture Permissions

• doctor stays read-only. It now reports visual_capture_backend, visual_capture_permission, visual_capture_truth_mode, and app_permission_bridge.
• Interactive CLI capture flows default to auto_request_once for exec get_screenshots, exec capture_ui_snapshot, and validate-runtime. Raw command schemas still default to check_only.
• macOS truthful capture is desktop_window (including iOS Simulator and Chrome / web on a Mac host). Screen Recording permission belongs to the host process running flutter-mcp-toolkit, not the Flutter app. Use permissions request for the native prompt and permissions open-settings after a denial.
• get_view_details and view_screenshots include captureHints when native platform views are detected (AndroidView, UiKitView, AppKitView, HtmlElementView, PlatformViewLink). Texture sets weakSignalsDetected with a soft warning (no auto upgrade). Hybrid engines without platform views can use MCPToolkitBinding.captureHintsContributor in the app.
• Image-only get_screenshots MCP responses include routing metadata in meta and a leading JSON text block when captureHints / warnings are present.
• Showcase Capture section: AppKitView on macOS (make showcase), HtmlElementView on web (flutter run -d chrome). Use make showcase-stop before a new macOS run.
• Web (chrome / web / web-server): desktop_window uses macOS ScreenCaptureKit → Chrome CDP (Page.captureScreenshot) → flutter_layer. Global flags: --web-browser-debugging-port, --web-port. Opt-in live test: RUN_WEB_CDP_INTEGRATION=1 dart test test/web_cdp_integration_test.dart. See ADR 0007.
• App-owned capture targets such as iOS/Android/Linux must have a reachable VM target selected before permissions or doctor can verify bridge-backed permission tools/resources. Use --target or the global --vm-service-uri when probing those platforms.
• desktop_window never silently falls back. auto may fall back to flutter_layer, but responses always report requestedMode, actualMode, permissionStatus, and fallbackReason.

Troubleshooting:

• If macOS capture is denied, rerun flutter-mcp-toolkit permissions status first. If status is still denied, open System Settings from the CLI and grant Screen Recording to the terminal or client process you are using.
• If doctor --json shows visual_capture_truth_mode=flutter_layer on macOS, you are not getting native window p