
flutter-mcp-toolkit
Flutter MCP toolkit: inspect and drive debug apps (semantic snapshot, tap, hot-reload) and register custom MCP tools and resources at runtime from your Flutter app or game via mcp_toolkit — closed agent feedback loop.
- version
- 7.2.1
- GitHub stars
- 399
Install
/plugin install flutter-mcp-toolkit@flutter-mcp-toolkitRun it inside Claude Code after adding the marketplace with /plugin marketplace add Arenukvern/mcp_flutter.
Contents
Discovered from sourceSkills 16
Flutter MCP Automation Chain
The toolkit's surfaces are one chain, not competing products. The app
registers ext.mcp.toolkit.* service extensions (mcp_toolkit), and every
surface drives those same extensions through the universal AutomationDriver
contract (universal_automation_interface, ADR-0038): observe (semantic
snapshot with refs/bounds) → act (tap/type/navigate) → verify
(snapshot again, read values). Agents learn one grammar regardless of the
target — Flutter apps, browsers (CdpDriver), OS-native tiers.
intentcall hints (MCP _meta) declarative build + lifecycle
│ (oka: oka.yaml → targets)
▼ │
┌──────────────┐ transport over ext.mcp.toolkit.* ▼
│ MCP fmt_* │ ◄── the same extensions ──► flutter_mcp_harness
│ CLI (fmtk) │ (ToolkitDriver implements Scenario / AppTargets /
│ dynamic │ AutomationDriver) VmClient / LogTap
│ app tools │
└──────────────┘ ◄── universal_automation_* contracts ──► CdpDriver (web)
The one ownership law
At most one owning attach session per app. The owning session (a flutter run, or an external runner's dev command like oka dev) is the only
compile-capable reload channel — a second attach on a session someone else
owns is the ADR-0014 failure mode (the second attach can kill the first).
Everything else in the chain is an observer: it reads the same VM service
and drives extensions, but never takes ownership. When an external runner owns
the session, it writes .flutter_mcp/runner-session.json (spec v2, ADR-0014)
so the toolkit and harness can find the VM and delegate reload/restart to the
owner. Absence of the file is the liveness signal.
Pick the surface
| Need | Surface | Skill / doc |
|---|---|---|
| Chat-driven debugging ("tap X, what changed?") | MCP fmt_* tools | flutter-mcp |
| Script/CI one-shot commands (snapshot, exec, batch) | CLI (flutter-mcp-toolkit / fmtk) | CLI vs MCP |
| Repeatable scenario as checked-in Dart, CI exit codes | flutter_mcp_harness | flutter-mcp-e2e-harness |
| Build + install + launch + process lifecycle (Android/iOS devices) | oka (separate repo) | this skill, oka section below |
| Browser tier (web demos, WebMCP dogfood) | CdpDriver over CDP | flutter-mcp-toolkit-maintain-web |
| Intent → driver routing without hardcoding transport | IntentDriverRouter + hints | this skill, intentcall section |
First loop: interactive MCP (five minutes)
curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash
cd my-flutter-app
flutter-mcp-toolkit codegen-init # adds mcp_toolkit + emits main.dart snippet
flutter-mcp-toolkit init claude-code # or: cursor | codex | cline | all
flutter run --debug
The agent now inspects, taps, types, hot-reloads, and reads logs over MCP. This is the fastest path and needs nothing else on this page.
Second loop: own the lifecycle in Dart
For CI or test batteries that must not depend on a chat session, add the published harness to your project and compose a scenario:
# pubspec.yaml (hosted package)
dependencies:
flutter_mcp_harness: ^0.1.0
final app = await MacosAppTarget(projectDir: '.', binaryPath: binary).launch();
final driver = ToolkitDriver(await app.vm());
final ref = await driver.findRef('login'); // snapshot refs are stable ids
// …perform click/type, re-snapshot, read values…
await app.stop(); // scenarios stop what they started
Desktop targets (FlutterRunTarget, BinaryAppTarget, MacosAppTarget,
WindowsAppTarget, ChromeAppTarget), Scenario anatomy, and the
in-repo showcase launcher are covered step-by-step in
flutter-mcp-e2e-harness — read it before writing your first scenario.
Third loop: device builds + lifecycle via oka
oka (separate repo, dart pub global activate oka) owns build + process
lifecycle so the toolkit can stay the observation oracle. You do not
need oka unless you want declarative, no-Gradle device builds and owned dev
sessions.
oka init # scaffolds tool/oka_pipeline.dart — project-owned targets
oka build apk # no-Gradle Android pipeline, cached artifacts
oka run device # install → launch → failure-signature scan
oka dev # owning dev session; agents: oka dev --watch --json (JSON events + stdin control)
Consuming projects compose oka_harness (which depends on the published
flutter_mcp_harness) instead of shelling out:
AndroidAppTarget/IosSimulatorAppTarget— launch device/simulator apps with the sameAppTargetcontract as desktop tiers.driverForLiveSession(projectDir)— attach a driver to a session oka already owns (read the signature andexample/emulator_smoke.dartin the oka repo'spackages/oka_harness/; never launch a second owner).- While
oka devowns the app, MCPfmt_*tools attach as usual — the server reads.flutter_mcp/runner-session.jsonand delegates reload/restart to the runner (ADR-0014 spec v2).
Division of labor (ADR-0024/0027, oka repo): oka owns compile/sync and process lifecycle; the toolkit is the observation oracle. The CLI is canonical; MCP is an adapter.
intentcall hints (declarative routing)
A registered intent can carry an IntentAutomationHint (transport + verb +
locator) on its MCP _meta. IntentDriverRouter in flutter_mcp_harness
resolves that hint onto a bound AutomationDriver, so callers route
automation declaratively instead of hardcoding which surface performs it.
See packages/harness/lib/src/intent_driver_router.dart and
IntentCall consumer guide.
Hard boundaries
- One owning session per app. Observers (MCP tools, harness drivers) must
not start a second compile-capable attach; construct
LaunchedApparound a runner-owned process instead of launching a competing one. - The toolkit never imports a runner. Runner identity comes from the discovery file, never from code (spec v2 inversion).
- No declarative YAML scenarios here — the document runner lives in the this repo (the external HS-DSL experiment, ADR-0012, is retired per ADR-0017); composition roots are consuming-project code.
- New toolkit verbs land in
mcp_toolkitfirst; harness extensions mirror that list.
Related
flutter-mcp— the interactive MCP loopflutter-mcp-e2e-harness— scenario authoring, launch-path table, showcase launcher- The Automation Chain — first-time guide
- ADR 0014 — external dev sessions — runner delegation contract
- E2E Scenarios · CLI vs MCP
Sources
decisions/0014_external_dev_sessions_runner_delegation.mdx— runner-session contract (spec v2)decisions/0015_flutter_mcp_harness_extraction.mdx— harness extraction and boundariesdecisions/0012_fmtk_cli_alias_and_harness_boundary.mdx— CLI/harness boundary- oka repo (github.com/Arenukvern/oka):
packages/oka_harness/(targets,driverForLiveSession); hosted harness ADR Oka harness ADR. In-repo boundary: 0015.
Contract boundary audit
Skill ID:
flutter-mcp-boundary-audit— name is historical; content is repository-neutral. Same workflow applies to MCP stacks, RPC gateways, plugin registries, and OpenAPI-style contracts.
For mcp_flutter, use this skill to audit Flutter adapter parity:
fmt_* catalog schemas, CLI exec, VM-service extension gateways, dynamic
discovery, migrators, and consumer platform docs. Change app discovery or the
Flutter bridge here; change canonical IntentCall registry/session semantics,
schema policy, platform projection, or publish behavior upstream.
Find split-brain bugs: what clients see in listings, catalogs, or docs ≠ what runtime enforces on invoke—or validation exists on one gateway only.
Typical symptoms:
- Advertised
requiredfields differ from what invoke accepts (empty payload succeeds, wrong keys ignored) - Host/catalog path validates; in-process or extension path does not (or the reverse)
- Migrator or codegen rewrites entries with empty or permissive schema placeholders
- Same logical capability registered twice with different schemas (listing vs invoke, or path A vs path B)
- Stale docs claim “always permissive” or “no validation” while code is fail-closed
When to run
| Trigger (generic) | Audit focus |
|---|---|
| Tool/handler authoring, schema attachment at registration | Authoring → discovery payload |
| Dynamic or plugin registration on the app/runtime side | Runtime validate-before-handler |
Server registry, forward/dispatch, catalog *_client_tool helpers | Registry listing + invoke |
| Host gateway (VM extension, IPC, HTTP proxy) before delegating to runtime | Host validate-before-delegate; fail-closed missing schema |
In-process invoke (invokeDirect, browser hook, embedded bridge) | Same schema as listing; validate before execute |
| Entry migrator / codegen from annotated sources | Schema preservation, not permissive fallbacks |
| Shared schema module vs duplicate definitions | Dual-path parity |
| Bridge handlers, non-scalar arguments | Encoding (JSON, protobuf, etc.) vs handler expectations |
| Platform / ADR / registration docs | Stale claims vs code |
Also run after changes to JSON Schema, OpenAPI request bodies, protobuf RPC messages, or plugin manifest input shapes when multiple gateways consume the same logical tool.
Boundary checklist
Trace authoring → discovery → validation → execute for every touched tool or RPC:
| Step | Question | Where to look (your repo) |
|---|---|---|
| Authoring | Does the canonical input schema reach the registration/descriptor type (not dropped at a toolkit/bridge wrapper)? | Authoring layer / entry model / code generator output |
| Authoring | Do bridge tools encode non-scalar args consistently for legacy handlers? | Bridge helpers, adapter layers |
| Discovery | Does dynamic registration send the full inputSchema (not {} or implicit-any)? | App registration API, manifest emitter |
| Discovery | Does the host list/catalog tool expose the same schemas as the runtime registry? | List-tools handler vs app registration |
| Server registry | Does registry intent/metadata use real schema, not a permissive placeholder? | Registry builder, MCP tool → intent mapping |
| Validate (registry) | Does forward/dispatch call validate before execute? | Registry forward path |
| Validate (host gateway) | Does the host gateway validate before delegating? Fail-closed if schema missing? | Gateway implementation |
| Validate (runtime) | Does the runtime callback validate before handler? | Service extension / in-process hook |
| Validate (wire) | If wire args are strings/maps, is coercion applied before strict validation on paths that see wire shape? | Coercion module vs host-only typed JSON |
| Validate (in-process) | Does direct invoke validate before execute? | In-process entry invoke |
| Validate (CLI) | Do CLI exec / catalog commands use the same schema as MCP listing? | CLI dispatch vs server tools |
| Execute | Any .execute( / handler dispatch without prior validate in production code? | Grep (below) |
| Migrator | Does migration preserve primitive/required/additionalProperties from source schema? | Migrator, codegen |
| Docs | Do platform/registration docs match actual fail-closed behavior? | Platform doc, ADRs |
Gateway divergence
Same logical tool may flow through different gateways—each must agree on schema and validation order:
Authoring (entry / descriptor)
├─► Runtime registration ──► extension/callback ──► handler
├─► In-process register (WebMCP / embedded) ──► invokeDirect
└─► Host list/catalog ──► catalog invoke ──► host gateway ──► runtime
| Gateway role | Must validate before | Fail if schema missing? |
|---|---|---|
| Runtime callback (extension, plugin hook) | handler | yes (production tools) |
| Registry forward | execute / handler | yes |
| Host gateway (proxy to runtime) | delegate call | yes |
| In-process invoke | execute | yes |
| Catalog / fmt_* / CLI wrapper | forward to runtime | yes (same as listing) |
CLI exec | command dispatch | yes |
Red flag: validation only in tests, only on the catalog path, or only on listing—not on the path your change actually uses.
Wire coercion (when applicable)
Some stacks deliver string-key maps on the wire (VM service extensions, JSON-RPC with loose typing). Separate concerns:
| Mechanism | Role |
|---|---|
| Coerce-for-schema | Property-type coercion from wire strings before strict schema validation |
| Handler-side wire parsers | Optional when handlers still read raw wire maps |
| Outbound wire encoding | Handler args → wire-safe representation |
Re-audit host gateway vs runtime callback if you add coercion on one side only—hosts that expect typed JSON must not assume runtime already coerced (and vice versa).
Dual-path parity
One logical capability often exists twice:
| Path | Typical role | Listing / invoke |
|---|---|---|
| Runtime / app dynamic | Registered in the running app or plugin host | Extension name, dynamic registry |
| Host catalog | Server-side MCP tools, CLI aliases, OpenAPI routes | Prefixed or bare names on wire |
For each shared tool, compare:
requiredkeysadditionalProperties: false(or equivalent strictness)- Host-only fields (e.g.
connection) present on one path only - Property types / enums
- Default values and coercion behavior
Document intentional deltas in your platform contract doc (not only in tests).
Red-flag grep
Run from your repository root. Adjust globs to your languages and package layout.
# Empty or permissive advertised schemas (JSON Schema style)
rg "inputSchema:\s*const\s*\{\s*'type':\s*'object'" --glob "*.dart" -g '!test/fixtures/**' -g '!**/after_*.dart'
rg '"type"\s*:\s*"object"\s*,\s*\}' --glob "*.{dart,ts,js,json,yaml}"
rg "_emptyObjectSchema|additionalProperties:\s*true" --glob "*.{dart,ts,js}"
# OpenAPI / generic permissive bodies
rg "additionalProperties:\s*true" --glob "*.{yaml,yml,json}"
rg "schema:\s*\{\s*\}" --glob "*.{yaml,yml}"
# Execute without validate (review each hit; exclude tests/fixtures)
rg "\.execute\(" --glob "*.{dart,ts,js}" | rg -v "validate|test/|_test\.|\.test\."
# Direct invoke bypass
rg "invokeDirect|invoke_direct|directInvoke" --glob "*.{dart,ts,js}"
# Manual review: validate appears before execute on each path
# Permissive registry placeholders
rg "emptyObjectSchema|empty_object_schema|placeholder.*schema|inputSchemaFrom" --glob "*.{dart,ts,js}"
# Migrator stripping schemas
rg "inputSchema|input_schema" --glob "*migrate*"
# Duplicate registration (e.g. JS + native)
rg "registerTool|register_tool" --glob "*.{dart,ts,js}"
# Stale “always permissive” docs
rg -i "permissive|additionalProperties:\s*true|no validation|accepts anything" --glob "*.md"
# Bridge / JSON args
rg "jsonEncode|JSON\.encode|serialize.*argument" --glob "*{bridge,entry,adapter}*"
Add project-specific patterns after completing Adapting to your repo.
E2E proof
Run your integration tests that cover listing + invalid invoke (not a specific app path).
Checklist:
- List tools/resources (or OpenAPI GET) shows
requiredand strictadditionalPropertieswhere intended. - Invoke with missing
required→ structured failure (ok: false, 4xx, or validation error)—before handler side effects. - Invoke with extra properties when schema is strict → same failure mode.
- If dual paths exist, repeat on both catalog and runtime registration names.
Optional: schema parity unit tests comparing shared module vs duplicate definitions (no device required).
Report template
## Finding: [title]
- **Severity**: P0 | P1 | P2
- **Boundary**: authoring | discovery | validation | execute
- **Gateway**: runtime-callback | registry | in-process | host-gateway | cli | migrator | docs
- **Files**: ...
- **Symptom**: clients/docs see X; runtime does Y
- **Fix**: ...
- **Proof**: test name or grep command
Tracker (optional)
If your repo uses a superpowers/tracker or hardening program, record new findings there or as issues—do not reopen completed items unless regression.
Adapting to your repo
Before auditing, fill this map (keep in audit notes or PR description):
| Role | Your location | Notes |
|---|---|---|
| Authoring | e.g. entry model, OpenAPI spec, @Tool annotations | Where canonical schema is defined |
| Discovery | e.g. registerDynamics, plugin manifest, MCP tools/list | What clients read |
| Registry / catalog | e.g. dynamic registry, server tool table | Listing vs invoke entry points |
| Host gateway | e.g. VM extension proxy, API gateway, sidecar | Validates before delegate? |
| Runtime callback | e.g. service extension, plugin host RPC | Validates before handler? |
| In-process invoke | e.g. WebMCP, embedded JS bridge | Same as tools/list? |
| CLI | e.g. exec, bare vs prefixed aliases | Same schema as MCP? |
| Shared schema module | e.g. interaction_input_schemas, OpenAPI components | Single source of truth? |
| Migrator / codegen | e.g. migrate agent-entries | Preserves required/properties? |
| Platform doc | e.g. INTENTCALL_PLATFORM.md, README contract section | Matches fail-closed code? |
Checklist
- Map tool registration path (authoring → discovery).
- Map listing gateway vs invoke gateway(s); list every hop.
- Map schema representation (JSON Schema maps, OpenAPI, protobuf, Dart
ObjectSchema, etc.). - Add 2–3 repo-specific red-flag greps (permissive placeholder, your invoke helper name).
- Identify dual-path tools; note shared module or document intentional split.
- Run integration test or manual proof for one strict tool on every gateway you touched.
Deep reference
Worked example (mcp_flutter), file map, and regression patterns: reference.md
Related skills (mcp_flutter)
When working in this monorepo only:
flutter-mcp-toolkit-custom-tools— authoring entriesflutter-mcp-toolkit-intentcall-migration— migrate agent-entriesflutter-mcp-toolkit-maintain-web— WebMCP / in-process invokeflutter-mcp-cli-runtime-validation— runtime validate-runtime
Flutter MCP CLI Runtime Validation
Use this skill when you need agent-style runtime validation through flutter-mcp-toolkit with minimal operator steps.
Two-Step Flow
- Launch the Flutter app in debug mode.
- Run one CLI command:
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart --save-images --output-dir .flutter_mcp/runtime_validation validate-runtime \
--target ws://127.0.0.1:8181/<token>/ws \
--timeout-ms 10000 \
--post-reload-delay-ms 500 \
--after-reload
Optional skill install in the same command:
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart validate-runtime \
--target ws://127.0.0.1:8181/<token>/ws \
--install-skill
Permission behavior for this flow:
validate-runtimestays read/write only for visual capture and defaults toauto_request_once.doctorremains read-only.- On macOS, Screen Recording permission belongs to the host process running
flutter-mcp-toolkit. - On web:
desktop_windowuses macOS ScreenCaptureKit then Chrome CDP (Page.captureScreenshot); Linux/Windows use CDP when remote debugging is reachable. Pass--web-browser-debugging-portif discovery fails. For web targets, pass--flutter-device chromeso validation does not pick macOS hostdesktop_windowby mistake. - Executor recovery retries host capture once (
desktopCaptureRetriedin screenshot payloads). Ifdesktop_windowstill fails (including when platform views are detected),validate-runtimeretries once withflutter_layer. Checkdata.summary.captureFallbackUsed. - You may pass the VM URI as global
--vm-service-uriinstead ofvalidate-runtime --targetwhen only one URI is needed.
What validate-runtime Must Prove
- Doctor preflight passes critical checks.
- Required toolkit extensions exist:
ext.mcp.toolkit.app_errorsext.mcp.toolkit.view_detailsext.mcp.toolkit.view_screenshotsext.mcp.toolkit.inspect_widget_at_point
- Screenshot capture works.
- View details (layout metadata) are available.
- App errors are retrievable.
- If
--after-reloadis enabled, post-reload screenshot also works.
Output Handling
- Use
data.summaryas pass/fail status for automation. - Use
data.summary.capturePlatformViewsDetectedandcaptureFocusAttemptedfor platform-view routing. - Use
data.summary.captureFallbackUsedto see whether aflutter_layerretry ran after a faileddesktop_windowattempt (including when platform views are detected). - Use
data.stepsfor per-step evidence and retries. - Use
data.doctor.checksto explain setup blockers. - Use
data.summary.screenshotFilesfor saved screenshot paths when--save-imagesis enabled. - When
--save-imagesis enabled, read screenshot file URLs from step data. - For visual debugging reports, also run:
exec --name capture_ui_snapshot --args '{"errorsCount":4,"compress":true,"includeViewDetails":true,"includeErrors":true}'exec --name inspect_widget_at_point --args '{"x":<int>,"y":<int>}'
Failure Rules
- If toolkit extensions are missing, stop and report instrumentation gap with exact fix:
- add
mcp_toolkitto app dependencies - ensure
MCPToolkitBinding.instance.bootstrapFlutter(...)or equivalent manual initialization runs beforerunApp - hot restart or rerun the app
- add
- If first explicit URI connect fails, retry is automatic for retryable connection errors.
- If screenshots are blank, verify app window is visible and retry.
- If macOS visual capture is denied, use:
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions statusdart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions requestdart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions open-settings
- If app cannot be instrumented, do not claim screenshot/layout/error inspection success.
Visual QA + Source Mapping Rules
- Always compare before/after screenshot evidence around changes.
- For each reported visual issue, provide coordinate +
inspect_widget_at_pointoutput. - Map defects to source using
get_app_errorstop stack frame (file,line,column) when available. - Do not use
debug_dump_*unless explicitly requested.
Challenge Cases (Always Call Out Explicitly)
- No running debug app:
doctorcritical failure onvm_target_reachable; request app launch before continuing. - Wrong target URI/token: treat as connection mismatch and retry with exact
app.debugPort.wsUri. - Toolkit added but still missing extensions: hot reload is often insufficient, require hot restart/full rerun.
- Non-modifiable app (cannot add toolkit): report inspection as unavailable instead of guessing.
Flutter MCP E2E Harness
Golden path for programmatic E2E over the toolkit: packages/harness
(flutter_mcp_harness) owns the whole lifecycle — build the app, launch the
process, attach to its Dart VM service, and only then drive/assert. It speaks
the same ext.mcp.toolkit.* service extensions as the MCP server, as plain
Dart. ADR: decisions/0015_flutter_mcp_harness_extraction.mdx.
The driving layer speaks the universal AutomationDriver contract
(ADR-0038, universal_automation_interface): ToolkitDriver exposes the
observe/act/verify loop (snapshot → semantic AxNode tree with refs and
bounds; perform click/type/key/named-route-navigate/evaluate; screenshot
PNG), so the same agent vocabulary drives Flutter apps, browsers
(CdpDriver), and OS-native targets. IntentDriverRouter additionally
routes an intent's automation hint (transport + verb + locator) onto the
bound driver. Frame pipelines are deliberately NOT a harness dependency —
they are composition-level (showcase/drivers, which also holds the live
end-to-end drives: make drive-flutter / drive-flutter-chrome /
drive-web).
App-specific verbs use the invoke tier (ADR-0017): the app's intent
registry IS the action catalog — driver.actions() lists it, and
InvokeAction(name, args) dispatches to a registered entry with
schema-validated arguments (custom IntentAutomationAction.custom hints
route the same way). Web surfaces without a VM service (Jaspr, plain JS)
compose identically over CdpDriver via the window.__mcpActions page
registry.
| Need | Use |
|---|---|
| Repeatable scenario as code, CI-friendly exit codes | this skill (flutter_mcp_harness) |
| One-off interactive debugging from chat/editor | flutter-mcp (MCP fmt_* tools) |
| Browser/WebMCP dogfood of the web showcase | flutter-mcp-toolkit-maintain-web |
Evidence boundaries (what each tier can prove)
A green tier proves only what that tier touches. When you record a result — in a validation ledger, a gate, or a report — say which tier it came from, and never let one tier's pass stand in for another's:
| Tier | Proves | Cannot prove |
|---|---|---|
| Model / unit tests (app package) | the gesture/decision algorithm on synthetic inputs (direction → symbol → correction) | that the app's real signal chain reaches the algorithm |
| MCP / driver UI scenarios (this harness) | controls exist, are reachable, and respond — presentation and wiring through the toolkit | anything whose input never crosses the UI (e.g. camera-delivered gestures) |
| Sensor replay (deterministic frames → the REAL pipeline) | app integration: frames → tracker/recognizer → selector → draft / undo / redo / commit with the real filters and state machines, no person needed | real-hand comfort, camera noise, latency feel |
| Live camera trial (a human hand) | the real sensor story: detection robustness, comfort, fatigue | repeatability — it is a manual trial, never a CI gate |
Worked example (vosges low-look, that repo's ADR-0008): model tests
verified the codebook; the MCP scenario verified the Settings controls;
low_look_sensor_replay_test.dart feeds a synthetic hand through the
real tracker and selector and asserts the committed word; only a live
trial says anything about a real hand. A scenario that only touches
the UI must not claim the writing loop works.
The web/AOT tier (WebBuildTarget + FlutterWebCdp)
The VM-service toolkit tier exists only where a Dart VM service exists:
JIT web (DDC, flutter run) and debug desktop/mobile. An AOT web
build (flutter build web) has no VM service — the CDP tier is not a
fallback there, it is the only tier (tier matrix: family ADR-0045;
this repo ADR-0018):
final app = await WebBuildTarget(projectDir: '.', build: !skipBuild).launch();
final flutter = app.flutter; // FlutterWebCdp over CdpDriver
await flutter.waitText('Settings');
await flutter.clickText('Sync between devices', expect: 'I have a pairing code');
await flutter.typeFocused('mesh-pair/v1 ...'); // bringToFront + insertText
await app.stop();
Measured rules encoded in FlutterWebCdp — do not re-learn them:
- Semantic clicks through the driver's fallback ladder work on real
Chromium; the OLD dead path was three stacked bugs (
DOM.enablemissing, AX nodes resolving to TEXT nodes,callFunctionOnthisrebinding) — fixed inuniversal_browser_cdpand guarded by the opt-in live fixture (XS_TEST_CDP_LIVE=1in the cdp package). - Locate by text/aria-label in the LIVE
flt-semanticsDOM; effect-verify every click (expect:) and check the effect BEFORE re-clicking (a toggle re-clicks itself off). - The first click after load is swallowed —
warmUpClick()burns it. - Typing needs
Page.bringToFront+Input.insertText(background windows have no OS focus; per-key events land nowhere). - Navigate in-app only (
popRoute=history.back()); a reload drops in-memory state. Headless Chrome never runs rAF — Flutter freezes;WebBuildTargetdefaults to headed Chrome for this reason.
Failure evidence (EvidenceCollector)
Attach evidence while the scenario runs; Scenario dumps it under
$TMPDIR/<scenario>/ on the first failing step: attachCdp buffers the
page's console + uncaught exceptions (an app-side throw renders as a
canvas error screen — invisible in the DOM — and ONLY the console names
it), attachLines tails app stdout, attachFile defers an AX/state
dump. Never let evidence production mask the failure — it is
best-effort by contract.
VM-service verbs against a booting app: use vm.callExtensionUntil(...)
instead of hand-rolled retry loops (it folds the -32601-before-
registration window and the isolate rebind).
Launch paths (pick by ownership)
The #1 rule: at most one owning session per app. A second
flutter run/flutter attach on a session someone else owns is the
ADR-0014 failure mode (the second attach can kill the first).
| Target | When | Notes |
|---|---|---|
FlutterRunTarget | You want the flutter tool to own build + hot reload (r/R/q via stdin). The showcase launch path. | device (macos, chrome, …), extraArgs, onLine tee for long cold builds; VM URI scraped from the tool's own announcement. |
BinaryAppTarget / MacosAppTarget / WindowsAppTarget | Fresh full flutter build <os> --debug → launch the binary directly. No compile channel afterwards. | Pass launch(build: false) to reuse an existing binary. Never opens an owning session. |
Same targets, ownership: AppOwnership.attachOnly | The app is ALREADY running and stopping it is not the harness's call (ADR-0020): discovers the pid by binary name, verifies the running executable against binaryPath AND the on-disk build against the process start (an optional BuildFingerprint pin is stronger), attaches via the explicitly named vmServiceUri — and stop() never signals the process. | Ambiguous pgrep matches are an error naming the pids. Attach never builds. Attach cannot scrape a stdout it does not own — the URI is named by the owner. |
External runner (e.g. oka dev) owns the app | Construct LaunchedApp directly around the owning process and read the VM URI from the runner-session contract, not stdout. | This package never imports the runner; callers wire it (LaunchedApp(name:, process:, stdout:, vmUri:)). |
FlutterRunTarget.launch(build:) ignores the flag — flutter run always
builds. A failed bring-up reaps the session (SIGTERM → child-reaping pkill →
SIGKILL) before rethrowing.
Scenario anatomy
final scenario = Scenario('checkout E2E', steps: [
('launch app', (context) async {
final app = await MacosAppTarget(projectDir: appDir, binaryPath: binary)
.launch(build: build);
launched = app; // for finally-stop
await app.stdout.waitFor('app ready'); // no sleeps — wait on logs
context.bag['app'] = app; // hand values between steps
}),
('drive + assert', (context) async {
final driver = await attachDriver(context.take<LaunchedApp>('app'));
await driver.expectLabel('checkout'); // retry-until-rendered
await driver.perform(const ClickAction(name: 'checkout'));
final total = (await driver.snapshot())
.nodes
.map((node) => node.value)
.firstWhere(
(value) => value != null && value.startsWith(r'$'),
orElse: () => null,
);
total != null
? context.report.pass('total rendered: $total')
: context.report.fail('no total in snapshot');
}),
]);
var passed = false;
try {
passed = await scenario.run();
scenario.report.printSummary();
} finally {
await launched?.stop(); // cleanup always runs
}
exit(passed ? 0 : 1);
- Steps run in order; first failure (thrown or
report.fail) aborts the rest — cleanup still happens in the caller'sfinally. HarnessContext.bagpasses values between steps;take<T>(key)reads them.retry(action)polls until non-null (for app-side readiness races).- Full two-instance composition root:
packages/harness/example/desktop_pair.dart.
Driving widgets (ToolkitDriver)
attachDriver(app)→ aToolkitDriverover the app's VM service.snapshot()→ the semanticAxNodetree (label, role, bounds, and the selectable-textvalue— the deterministic way to read app-rendered data; clipboards and icon-only copy buttons are not).- Act through the family actions (ADR-0038):
driver.perform(const ClickAction(name: 'submit')),TypeAction, key-press, named-route navigate,evaluate— the same vocabulary the MCP server and the invoke tier speak;screenshot()for a PNG. - Observe with
expectLabel(needle)/labelContaining(needle)— the retry-until-rendered loop (a tap lands before the next frame paints; verifying immediately reads the old tree), failing with a dump of the surface it actually saw. WidgetDriverwas removed (ADR-0019) — one driver per wire; do not reintroduce per-package driver shells.VmClientextras:extensionNames()(discoverability),evaluate(expr),hotReload(),callExtensionUntil(...)(folds the -32601-before-registration window, the isolate rebind, and the dropped-socket reconnect). RawreloadSourcescannot compile without an owningflutter run/attachsession — treattrueas "asked", not "recompiled".
Showcase launcher (packages/harness/tool/showcase.dart)
make showcase # macOS showcase, interactive foreground (r/R/q relayed)
make web-showcase # Chrome + WebMCP flags; WEB_PORT/VM_HOST_PORT/FLIGHT… env
make showcase-stop # kill stray sessions, free VM port 8181 (idempotent)
--web --detach(ormake-lessdart run packages/harness/tool/showcase.dart --web --detach) spawns headless-ish, waits for thews://VM URI in.showcase/web_app.log, printsWS_URI=…, exits 0 — the CI-friendly variant.- Artifacts under
.showcase/:flutter_app.log/web_app.log(teed output) andflutter.pid/web_flutter.pidpid files. - IntentCall doors (second terminal, against the running showcase):
dart run packages/harness/tool/intentcall_session.dart [demo|serve-link|serve-debug]— resolves the VM service URI from the showcase log (--vm-service-uripins one) and the IntentCall CLI fromINTENTCALL_ROOT, sibling checkouts, orPATH. - Interactive mode tees every line to the log (which
make exec-sweepgreps) and tears the session down on exit or Ctrl-C. - WS URI for follow-up calls:
grep -Eo 'ws://127\.0\.0\.1:[0-9]+/[A-Za-z0-9_=-]+/ws' .showcase/flutter_app.log | tail -1.
Hard boundaries
- No new toolkit verbs.
ToolkitExtensionsmirrorsmcp_toolkit/lib/src/toolkits/interaction_toolkit.dart; keep the lists in lockstep — drift is caught by extension calls failing at runtime today (shared-constants follow-up will make it a compile error). - No owned compile sessions in
BinaryAppTarget— full fresh builds only. - No declarative scenario documents (YAML runners) — the external
flutter_harnessexperiment (ADR-0012) is retired (ADR-0017). Composition roots are consuming-project code (seeexample/). - Android/iOS device bring-up is delegated to the owning dev session
(
oka_harness, ADR-0014) — not this package.
Verify
cd packages/harness && dart test # unit tests (canned envelopes, fake flutter)
dart run example/desktop_pair.dart --skip-build
Related
flutter-mcp— the interactive MCP loop over the same extensionsflutter-mcp-automation-chain— cross-tier wiring for your own app (surface picker, oka integration, runner sessions)flutter-mcp-toolkit-maintain-macos/-maintain-web— showcase + platform lanespackages/harness/README.md, ADR-0014 (runner delegation), ADR-0015 (extraction)
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 | "user@example.com" |
| 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>)
Fill a login form
semantic_snapshot() → email ref "s_1", password ref "s_2"
fill_form(fields: [{ref:"s_1", text:"user@example.com"}, {ref:"s_2", text:"secret"}], snapshotId: <id>)
→ one round-trip; stops on first failure
Scroll to find an item
scroll(direction: "down", distance: 300)
semantic_snapshot() → item now visible → ref "s_5"
tap_widget(ref: "s_5")
Reveal an off-screen field by identifier
reveal_search(query: "greeting_input_field", matchBy: "identifier", direction: "down", maxAttempts: 4)
→ returns ref "s_14", snapshotId 2, match, attempts trace
enter_text(ref: "s_14", snapshotId: 2, text: "hello")
Wait for a widget to appear
wait_for(predicate: {kind: "text", text: "Welcome"}, timeoutMs: 8000)
→ returns fresh snapshot when text appears
tap_widget(ref: <ref from wait_for snapshot>)
Navigate to a route
navigate(action: "push", route: "/settings", arguments: {tab: "account"})
semantic_snapshot() → fresh refs in the new screen
Hot reload after a code change
hot_reload_and_capture()
→ screenshot + semantic snapshot + errors in one call
Press the back hardware button
press_key has no Back key. Use navigate(action: "pop") for Navigator pop; handle_dialog(action: "dismiss") for dialogs; press_key(key: "Escape") on desktop.
navigate(action: "pop")
Tool reference
tap_widget
Tap a widget by ref. ref • string • required. snapshotId • integer • optional. connection • object • optional.
{"name": "tap_widget", "arguments": {"ref": "s_3", "snapshotId": 7}}
Returns: {"via": "semantic_action", "ref": "s_3"} — Failures: stale_snapshot, ref_not_found
long_press
Long-press a widget by ref. ref • string • required. snapshotId • integer • optional. connection • object • optional.
{"name": "long_press", "arguments": {"ref": "s_2"}}
Returns: {"via": "semantic_action"} — Failures: stale_snapshot, ref_not_found
enter_text
Enter text into a text field; taps to focus before typing. ref • string • required. text • string • required. snapshotId • integer • optional. connection • object • optional.
{"name": "enter_text", "arguments": {"ref": "s_1", "text": "hello@example.com"}}
Returns: {"via": "editable_state", "verified": true, "appliedText": "..."}. A write the field kept nothing of fails with text_not_applied, appliedText (empty) and restoredText (the value put back). Failures: stale_snapshot, ref_not_found, text_not_applied
reveal_search
Find a semantic target that may be off-screen. query • string • required. matchBy • string • optional (text|identifier|label|value|hint, default text). direction • string • optional (up|down|left|right, default down). maxAttempts • integer • optional • max 10. distance • number • optional. connection • object • optional.
{"name": "reveal_search", "arguments": {"query": "greeting_input_field", "matchBy": "identifier", "direction": "down", "maxAttempts": 4}}
Returns: {"ref": "s_14", "snapshotId": 2, "match": {...}, "attempts": [...]} — Failures: missing_query, target_not_found, scroll_blocked, target_not_actionable. identifier matches whole and case-sensitively; the other modes are case-insensitive substring tests. A miss by identifier carries identifiersSeen (how many the searched screens published) and nearIdentifiers — the closest of them, so panel.tab not found comes back with panel.tab.overview / panel.tab.jobs to pass instead.
fill_form
Batch text entry: fills multiple fields in one call. Stops on first failure. snapshotId validated on first field only. fields • array of {ref, text} • required. snapshotId • integer • optional. connection • object • optional.
{"name": "fill_form", "arguments": {"fields": [{"ref":"s_1","text":"user"},{"ref":"s_2","text":"pass"}], "snapshotId": 5}}
Returns: {"filled": 2} — Failures: stale_snapshot, ref_not_found
scroll
Scroll to reveal content. "down" reveals content below (finger swipes up). direction • string • required (up|down|left|right). ref • string • optional — the list to scroll, or any node inside it; without it the list under the screen centre scrolls. distance • number • optional • default 300, honoured exactly where the list takes an offset, otherwise rounded to a viewport page. snapshotId • integer • optional. connection • object • optional.
{"name": "scroll", "arguments": {"direction": "down", "ref": "s_0", "distance": 500}}
Returns: {"via": "semantic_action", "scrollBefore": 0.0, "scrollAfter": 500.0, "distance": 500.0}. scrollBefore/scrollAfter are forwarded whenever measurable; distance is present on exact-offset and pointer-scroll paths. A node that advertises the scroll action without a scroll position (custom Semantics(onScrollUp: ...)) takes it and returns success: true, verified: false, unmeasured: true. Failures: ref_not_found, stale_snapshot, no_scrollable_at_point, no_scroll_movement, unsupported_scroll_action, semantics_owner_unavailable
swipe
High-velocity fling. Same direction model as scroll. Always Tier 2 pointer events. direction • string • required. ref • string • optional. distance • number • optional • default 300. snapshotId • integer • optional. connection • object • optional.
{"name": "swipe", "arguments": {"direction": "left", "ref": "s_4"}}
Returns: {"via": "pointer_events", "scrollBefore": 0.0, "scrollAfter": 420.0} when movement is measurable. When finite scroll offsets are unavailable, a dispatched gesture returns success: true, verified: false, and measurementReason. Failures: ref_not_found, stale_snapshot, no_scroll_movement, web_gesture_not_supported
drag
Drag from one widget to another. Always Tier 2. fromRef • string • required. toRef • string • required. snapshotId • integer • optional. connection • object • optional.
{"name": "drag", "arguments": {"fromRef": "s_2", "toRef": "s_7"}}
Returns: {"via": "pointer_events"} — Failures: ref_not_found, web_gesture_not_supported
hover
Synthesize a mouse hover. Desktop/web only — no hover concept on mobile. ref • string • required. snapshotId • integer • optional. connection • object • optional.
{"name": "hover", "arguments": {"ref": "s_5"}}
Returns: {"via": "pointer_events"} — Failures: ref_not_found, platform error on mobile
focus_widget
Give keyboard focus to a widget, so the press_key that follows reaches it. Uses the node's semantic focus action when the snapshot lists one, otherwise the focusable widget inside the ref's bounds (the only route on iOS, where Flutter exposes no focus action). Leaves a parked hover in place. ref • string • required. snapshotId • integer • optional. connection • object • optional.
{"name": "focus_widget", "arguments": {"ref": "s_5"}}
Returns: {"via": "semantic_action" | "focus_node", "verified": true, "verifiedBy": "semantics_flag" | "focus_node", "focusMoved": bool} — success: true means the target reports focus after the framework caught up; focusMoved: false means it already held it. On the focus-node route, focusedNow names the control inside the ref that actually took focus. Failures: ref_not_found, stale_ref, stale_snapshot, target_disabled, focus_not_exposed (nothing focusable behind the ref), focus_refused (the request went through but the target does not report focus; focusedNow says where it sits)
press_key
Synthesize key press (down+up). Accepted: Enter Escape Tab Backspace Delete Space ArrowUp ArrowDown ArrowLeft ArrowRight plus single ASCII (a-z 0-9). key • string • required. ctrl/shift/alt/meta • boolean • optional • default false. connection • object • optional.
{"name": "press_key", "arguments": {"key": "Enter"}}
Returns: {"key": "Enter", "handled": bool} — handled says whether either dispatch phase (hardware keyboard handlers or focus chain) claimed the main key-down event; false does not describe the key-up or modifier events. clearedStaleModifiers / releasedStuckModifiers name any modifier the call had to release — a modifier left held by an earlier keystroke makes every plain shortcut stop matching, so the call normalizes it and says so. Failures: unknown_key
wait_for
Wait for a UI predicate; returns fresh semantic snapshot. Predicates: {kind:"text",text} | {kind:"noText",text} | {kind:"time",ms} | {kind:"stable",stableWindowMs}. stable samples once per frame and matches after the semantics tree has remained unchanged for the requested wall time; the match reports stableFor.sampledFrames and stableFor.elapsedMs. stableWindowMs must be less than timeoutMs (default 5000); an impossible budget fails immediately with invalid_predicate. predicate • object • required. timeoutMs • integer • optional • default 5000 • max 30000. connection • object • optional.
{"name": "wait_for", "arguments": {"predicate": {"kind": "text", "text": "Dashboard"}, "timeoutMs": 8000}}
Returns: fresh semantic snapshot — Failures: timeout, invalid_predicate
navigate
Drive the registered Navigator. Requires MCPToolkitBinding.instance.navigatorKey = key in the app. action • string • required (push|pop|popUntil). route • string • required for push/popUntil. arguments • object • optional (for push). connection • object • optional.
{"name": "navigate", "arguments": {"action": "push", "route": "/profile", "arguments": {"userId": "42"}}}
Returns: {"action": "push", "route": "/profile"}. A generated unnamed route returns success: true, verified: false, and via: "stack_changed_unnamed_route" because the stack changed but its requested name cannot be checked. pop reads success off the stack and reports handled from maybePop: a page under PopScope(canPop: false) comes back handled: true, success: false, nothing_popped. Failures: navigator_not_configured, route_not_found
handle_dialog
Dismiss the topmost popup/dialog route. Only action: "dismiss" supported. Requires navigatorKey = key on MCPToolkitBinding.instance in the app. action • string • required (must be "dismiss"). connection • object • optional.
{"name": "handle_dialog", "arguments": {"action": "dismiss"}}
Returns: {"success": true, "handled": true, "routeType": "DialogRoute<void>"}. success is read off the route stack; handled is what maybePop answered, so a dialog under PopScope(canPop: false) comes back handled: true, success: false, dialog_declined_pop. Failures: navigator_not_registered, no_popup_route, dialog_declined_pop
hot_reload_flutter
Hot reload the app. Preserves state. force • boolean • optional • default false (reload even without source changes). connection • object • optional.
{"name": "hot_reload_flutter", "arguments": {}}
Returns: "Hot reload completed" + report JSON — Failures: vm_not_connected, compilation_error
hot_restart_flutter
Full restart. App state not preserved. No required params. connection • object • optional.
{"name": "hot_restart_flutter", "arguments": {}}
Returns: {"report": {"type": "Success", "success": true}} — Failures: vm_not_connected
hot_reload_and_capture
Hot reload then capture screenshot + semantics + errors in one call. compress • boolean • default true. includeSemantics • boolean • default true. includeErrors • boolean • default true. errorsCount • integer • default 4. connection • object • optional.
{"name": "hot_reload_and_capture", "arguments": {"includeErrors": true}}
Returns: screenshot (base64) + semantic snapshot + errors — Failures: vm_not_connected, compilation_error
Patterns
Always wait_for before tap_widget after navigation
After navigate(action: "push") the new route's widgets are not in the tree yet. Use wait_for with a text predicate to confirm the destination has rendered, then snapshot and act.
navigate(action: "push", route: "/checkout")
wait_for(predicate: {kind: "text", text: "Order Summary"}, timeoutMs: 5000)
semantic_snapshot() → tap target widgets
Prefer fill_form over multiple enter_text calls
Each enter_text is a separate VM round-trip. fill_form sends all field/text pairs in one call; snapshotId is checked once (on the first field). For any form with 2+ fields, always prefer fill_form.
# Avoid: 2 round-trips
enter_text(ref: "s_1", text: "Alice")
enter_text(ref: "s_2", text: "secret")
# Prefer: 1 round-trip
fill_form(fields: [{ref: "s_1", text: "Alice"}, {ref: "s_2", text: "secret"}])
After hot_reload_*, wait for the new tree before continuing
Hot reload completes asynchronously. Use wait_for(predicate: {kind:"stable", stableWindowMs:300}) to confirm the tree has settled before calling semantic_snapshot. Or use hot_reload_and_capture which returns a post-reload snapshot directly.
hot_reload_flutter()
wait_for(predicate: {kind: "stable", stableWindowMs: 300})
semantic_snapshot() → interact with reloaded widgets
# Or in one call (preferred):
hot_reload_and_capture() → screenshot + semantics + errors already post-reload
Custom MCP Toolkit Tools & Resources (Dynamic Registry)
Use this when bundled MCP tools (screenshot, semantic snapshot, tap, …) are not enough and you need app-specific read surfaces or actions — e.g. cart totals, feature flags, curated debug snapshots of internal state. Entries are registered in the Flutter process and exposed to the agent through the dynamic registry.
Migration: The legacy call-entry type was removed in intentcall Phase 6b. Use
AgentCallEntryormcpToolkitTool/mcpToolkitResource. Seeflutter-mcp-toolkit-intentcall-migration.
Boundary: Change app discovery, Flutter VM-service extensions, or app-owned debug surfaces here. Change canonical registry/session semantics, schema policy, platform projection, or publish behavior in the upstream IntentCall repository.
Pick the right primitive
| Need | Use |
|---|---|
| One-off read of a simple value | fmt_evaluate_dart_expression (no app code change). |
| Stable read-only payload (diagnostics, JSON snapshot, “current route”) | AgentCallEntry.resource + fmt_client_resource. Prefer resources when the contract is “GET-like” and idempotent. |
| Parameterized or mutating action, or reusable named operation | AgentCallEntry.tool + fmt_client_tool. |
Handler signatures
Native AgentCallEntry (preferred for new code)
Handlers receive AgentArguments (Map<String, Object?>) and return AgentResult:
import 'package:mcp_toolkit/mcp_toolkit.dart';
final tool = AgentCallEntry.tool(
namespace: 'app',
name: 'cart_get_snapshot',
description: 'Return current cart total and items for a user.',
inputSchema: const {
'type': 'object',
'additionalProperties': false,
'properties': {
'userId': {'type': 'string'},
},
'required': ['userId'],
},
handler: (final args) async {
final userId = args['userId']?.toString() ?? '';
final cart = CartRepository.instance.forUser(userId);
return AgentResult.success(
message: 'ok',
data: {
'total': cart.total,
'items': cart.items.map((final i) => i.toJson()).toList(),
},
);
},
);
await MCPToolkitBinding.instance.addEntries(entries: {tool});
Legacy MCPToolDefinition + MCPCallResult (bridge)
Built-in toolkits still use mcpToolkitTool / mcpToolkitResource to adapt
Map<String, String> service-extension handlers:
final tool = mcpToolkitTool(
namespace: 'app',
handler: (final request) async {
final userId = request['userId'] ?? '';
return MCPCallResult(
message: 'ok',
parameters: {'userId': userId},
);
},
definition: MCPToolDefinition(
name: 'cart_get_snapshot',
description: 'Return current cart total and items for a user.',
inputSchema: ObjectSchema(
properties: {
'userId': StringSchema(),
},
required: ['userId'],
),
),
);
- Tool arguments on the wire are strings keyed by schema property names — parse with
int.tryParse,jsonDecode, etc. - Do not use
request.argumentson the app side.
Prefer MCPToolkitBinding.instance.addEntries(entries: { ... }) before bootstrapFlutter(runApp: ...) so tools/resources register in one place with zone/error setup.
Register once at bootstrap — not inside build, not per-widget initState.
Custom resources
final resource = AgentCallEntry.resource(
namespace: 'app',
name: 'app_cart_digest',
description: 'Compact cart summary for agents (read-only).',
mimeType: 'application/json',
handler: (final args) async => AgentResult.success(
message: 'Cart digest',
data: {
'itemCount': CartRepository.instance.visibleCount,
'currency': CartRepository.instance.currencyCode,
},
),
);
Or via bridge:
mcpToolkitResource(
namespace: 'app',
definition: MCPResourceDefinition(
name: 'app_cart_digest',
description: 'Compact cart summary for agents (read-only).',
mimeType: 'application/json',
),
handler: (final request) async => MCPCallResult(
message: 'Cart digest',
parameters: {'itemCount': 3},
),
),
namemust besnake_case. Published resource URIs followvisual://localhost/...conventions; agents usefmt_client_resourceand listings fromfmt_list_client_tools_and_resources.
Schema rules (tools)
The MCP server enforces strict JSON Schema:
- Prefer
additionalProperties: falseunless you intentionally accept arbitrary keys. - Mark
requiredfor anything the handler reads unconditionally. AgentResult.data/MCPCallResult.parametersmust be JSON-serializable.
Discovery from the agent side
fmt_list_client_tools_and_resources— enumerate app-registered tools and resources.fmt_client_tool— invoke a dynamic tool by name with JSON args.fmt_client_resource— fetch a registered resource URI from the listing.
If something should appear but does not: confirm addEntries completed (await), then hot restart.
Lifecycle gotchas
- Hot reload +
addEntriesfrom widget code → duplicate registrations. Register once inmain()/ bootstrap. - Debug mode only — release builds do not expose VM service extensions.
- Naming: the app uses a flat global namespace. Prefix tools/resources (
cart_,flags_,nav_). If a built-in entry already uses a name, the custom entry is skipped without warning; the built-in handles the call and the custom handler does not run. - Naming the running instance is
MCPToolkitBinding.instance.setAppIdentity(label: 'Fleet app · staging'), called again whenever the name changes (sign-in, workspace switch). Discovery reads that label, and a tool of your own calledapp_identityis one of the collisions above.
When the agent authors surfaces for the user’s app
- Ensure
mcp_toolkitis inpubspec.yaml. - Add
lib/mcp_tools/<domain>_surfaces.dartreturningSet<AgentCallEntry>or callingaddEntriesonce. - Wire from
addEntries(...)beforebootstrapFlutter(...)— never fromStatefulWidgetlifecycle. - Tight schemas; hot restart; then
fmt_list_client_tools_and_resourcesbefore first client invoke.
Safety and scope
- Treat handlers as powerful debug hooks: avoid secrets, unchecked IO.
- Keep handlers thin: delegate to existing app services.
Common traps
- Mixing
AgentArgumentswithMap<String, String>— pick one API (native vsmcpToolkitTool). - Missing
awaitonaddEntries→ race before discovery. inputSchemaout of sync with the handler → agents trust the schema; update both.
Related
flutter-mcp-toolkit-intentcall-migration— CLI migrator, breaking upgradeflutter-mcp-toolkit-guide→ inspect / control / debug skills- Docs How it works → dynamic registry overview
When to use
Use this skill when something broke and you need to understand why:
- A tool call returned an error envelope (
ok: false). - The app behaves unexpectedly and you need runtime log output.
- You need to inspect live app state without changing it (read
AgentState.instance.value). - A prior
controlaction (tap, hot_reload, navigate) completed without error but the result is wrong.
Do NOT use this skill for:
- Reading what is currently on screen — use
flutter-mcp-toolkit-inspect. - The toolkit itself failing to connect — load
flutter-mcp-toolkit-setup.
Registry vs bundled tools
- Bundled
fmt_*tools (screenshot, logs, evaluate, …) run on the MCP server viaAgentRegistryon the host. - App-registered surfaces appear after
MCPToolkitBinding.addEntries/AgentCallEntry— discover withfmt_list_client_tools_and_resources, thenfmt_client_tool/fmt_client_resource.
Triage flow
- Error envelope returned? Read
error.codefirst, thenerror.descriptor.retryable. Look the code up in the Error envelope playbook below. - Retryable error? Run
flutter-mcp-toolkit doctor --json. If doctor fails, loadflutter-mcp-toolkit-setup. - Need log output? Call
get_recent_logswithcount: 100and a level filter. Look for stack traces or assertion messages near the timestamp of the failure. - Need live state? Call
evaluate_dart_expressionwith a targeted expression (e.g.MyBloc.instance.state.toString()). Do this after logs, not instead of them. - Chaining with inspect? Order:
semantic_snapshot→evaluate_dart_expression→get_recent_logs. Snapshot gives you the current widget tree before expression evaluation mutates nothing; logs give trailing context. - Multiple targets? If
connection_selection_required, calldiscover_debug_apps, pick thetargetId, then passconnection: {targetId: "..."}to every subsequent call.
Tool reference
get_recent_logs
Retrieve recent print() and debugPrint() output from the running app's main isolate.
count• integer • optional, default: 50 — number of log lines to return.connection• object • optional — connection override; required when multiple debug apps are running.
get_recent_logs(count: 100)
get_recent_logs(count: 50, connection: {targetId: "ws://127.0.0.1:8181/<token>/ws"})
Returns: {"logs": ["[INFO] page loaded", "[ERROR] assertion failed: ..."], "count": 50}
Read-only; no code executed. Returns only lines buffered since last app start or hot restart. On failure see getRecentLogsFailed in the playbook.
evaluate_dart_expression
Evaluate a Dart expression in the running app's main isolate and return its string representation.
expression• string • required — Dart expression (e.g."MyClass.instance.counter").connection• object • optional — connection override.
evaluate_dart_expression(expression: "Navigator.of(context).canPop()")
evaluate_dart_expression(expression: "AgentState.instance.value.toString()")
Returns: {"result": "42", "kind": "Int", "classRef": "_Smi", "truncated": false} — result is always a string. A long String comes back whole up to 32,768 UTF-16 code units (the unit length and String.length count in, so non-ASCII text may encode to more bytes); past that truncated: true with length, returnedLength and a hint naming the .substring(...) that reads the rest. A List, Map or object comes back as a bare class name ("_GrowableList") with a hint — wrap the expression in .toString() or jsonEncode(...) to read its value. Executes arbitrary code in the live isolate — avoid side-effecting expressions. Debug mode only. On failure see evaluateExpressionFailed in the playbook.
Connect / multi-app flows
When discover_debug_apps returns more than one entry (or any call returns connection_selection_required):
- Call
discover_debug_apps()— readtargets[*].targetIdfor each running app. - Identify the target by port or hostname.
- Call
connect_debug_app(connection: {targetId: "ws://127.0.0.1:<port>/<token>/ws"})to pin the session. - Pass the same
connectionobject to every subsequent tool call for the session.
Connection override pattern — pass connection on any call:
get_recent_logs(count: 50, connection: {targetId: "ws://127.0.0.1:8182/<token>/ws"})
evaluate_dart_expression(expression: "x.toString()", connection: {targetId: "ws://127.0.0.1:8182/<token>/ws"})
If the target changes (app restarted, port shifted), re-run discover_debug_apps to get the new targetId. Stale URIs return connect_failed.
Error envelope playbook
Every failure returns {code, message, details, descriptor, recovery}. Always read error.descriptor (not the top-level envelope) for retryable and exitCode. Run error.recovery.fix_command directly when provided.
unexpectedExecutorError (unexpected_executor_error)
Means: unhandled exception in the command executor. Causes: bug in the server; unexpected nil; unrecoverable VM state. Recovery:
flutter-mcp-toolkit doctor --json- If doctor passes, retry once; if it recurs, file a bug with
error.details.
connectFailed (connect_failed)
Means: connection to the VM Service WebSocket failed. Causes: wrong port, stale token, app not running. Recovery:
flutter-mcp-toolkit exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}'- Get the exact URI from
app.debugPort.wsUriin Flutter output.
vmNotConnected (vm_not_connected)
Means: a VM-dependent command was called before a connection was established. Recovery:
flutter-mcp-toolkit exec --name status --args '{}'- Then
flutter-mcp-toolkit doctor --json.
connectionSelectionRequired (connection_selection_required)
Means: multiple debug targets exist; an explicit target is required. Causes: more than one Flutter app running in debug mode simultaneously. Recovery:
flutter-mcp-toolkit exec --name discover_debug_apps --args '{}'- Pick the correct
targetIdfromdetails.availableTargets. - Retry the original call with
connection: {targetId: "<chosen_id>"}.
discoverDebugAppsFailed (discover_debug_apps_failed)
Means: discovery scan of local VM Service ports failed.
Recovery: flutter-mcp-toolkit doctor --json
getVmFailed (get_vm_failed)
Means: get_vm RPC to the VM Service failed.
Recovery: flutter-mcp-toolkit doctor --json
getExtensionRpcsFailed (get_extension_rpcs_failed)
Means: listing registered extension RPCs failed.
Recovery: flutter-mcp-toolkit doctor --json
hotReloadFailed (hot_reload_failed)
Means: hot reload was rejected by the Dart compiler or VM. Causes: compile error in changed files; isolate in bad state. Recovery:
flutter-mcp-toolkit exec --name get_app_errors --args '{}'- Fix the compile error, then retry.
hotRestartFailed (hot_restart_failed)
Means: full hot restart failed.
Recovery: flutter-mcp-toolkit doctor --json — if VM is unreachable, restart the app manually.
getActivePortsFailed (get_active_ports_failed)
Means: scan for active debug ports failed.
Recovery: flutter-mcp-toolkit doctor --json
getAppErrorsFailed (get_app_errors_failed)
Means: retrieving app errors from the toolkit bridge failed.
Recovery: flutter-mcp-toolkit doctor --json
getScreenshotsFailed (get_screenshots_failed)
Means: screenshot capture failed (wrong mode, host window not available, Simulator window race, etc.). Recovery:
flutter-mcp-toolkit doctor --json— checkvisual_capture_permission_deniedseparately.- Check
captureHintsonget_view_detailsor screenshot payloads. Strong signals (platformViewsDetected):UiKitView,AppKitView,AndroidView,HtmlElementView— usedesktop_windoworauto(macOS app, iOS Simulator, or Chrome/web on any host with CDP). Web truth capture: macOS ScreenCaptureKit first, then Chrome CDP (captureBackend: cdp); override port with--web-browser-debugging-port. Weak signals (weakSignalsDetected):Textureonly — preferdesktop_windowon macOS host butautodoes not upgrade. WGPU/custom engines without platform views: setMCPToolkitBinding.captureHintsContributorin the app. Image-onlyget_screenshotstools also return routing JSON inmetaand a leading text block. Showcase:make showcase-stopthenmake showcase(macOSAppKitView) orflutter run -d chrome(webHtmlElementView+ CDP capture). - Run
focus_window(MCP:fmt_focus_window) then retryget_screenshotswithmode: desktop_window. - For
validate-runtime, executor recovery retries focus+capture once (desktopCaptureRetried). Ifdesktop_windowstill fails, validate-runtime retries once withflutter_layereven when platform views are detected. ReadcapturePlatformViewsDetected,captureFocusAttempted, andcaptureFallbackUsedindata.summary.
visualCapturePermissionDenied (visual_capture_permission_denied)
Means: macOS Screen Recording permission is not granted. Recovery:
flutter-mcp-toolkit permissions request --kind visual_capture- Or open System Settings → Privacy & Security → Screen Recording.
visualCaptureUnsupported (visual_capture_unsupported)
Means: visual capture is not supported on this platform or capture mode. Not retryable.
Recovery: flutter-mcp-toolkit permissions status && flutter-mcp-toolkit doctor --json
getViewDetailsFailed (get_view_details_failed)
Means: retrieving FlutterView dimensions failed.
Recovery: flutter-mcp-toolkit doctor --json
debugDumpFailed (debug_dump_failed)
Means: a VM debug-dump RPC (render tree, semantics, layers) failed.
Recovery: flutter-mcp-toolkit doctor --json
dynamicRegistryDisabled (dynamic_registry_disabled)
Means: a dynamic tool/resource call was made but the dynamic registry is disabled. Not retryable.
Recovery: flutter-mcp-toolkit --dynamics exec --name status --args '{}' — pass --dynamics flag to enable.
dynamicRegistryListFailed (dynamic_registry_list_failed)
Means: listing dynamic tools/resources from the registry failed.
Recovery: flutter-mcp-toolkit doctor --json
missingToolName (missing_tool_name)
Means: a dynamic tool call was made without providing a tool name. Not retryable.
Recovery: include tool_name parameter in the call; flutter-mcp-toolkit schema --name fmt_client_tool.
dynamicToolFailed (dynamic_tool_failed)
Means: invocation of a dynamic tool failed.
Recovery: flutter-mcp-toolkit doctor --json
missingResourceUri (missing_resource_uri)
Means: a dynamic resource read was called without a URI. Not retryable.
Recovery: include uri parameter; flutter-mcp-toolkit schema --name fmt_client_resource.
dynamicResourceFailed (dynamic_resource_failed)
Means: reading a dynamic resource failed.
Recovery: flutter-mcp-toolkit doctor --json
sessionManagerNotConfigured (session_manager_not_configured)
Means: a session command was called but no session manager is wired. Not retryable.
Recovery: flutter-mcp-toolkit doctor --json — server config issue; reload flutter-mcp-toolkit-setup.
sessionNotFound (session_not_found)
Means: the requested session ID does not exist. Not retryable. Recovery: list active sessions; start a new session before referencing it.
invalidCommand (invalid_command)
Means: command name or argument schema is invalid. Not retryable.
Recovery: flutter-mcp-toolkit schema --name <command_name>
stateStoreReadFailed (state_store_read_failed)
Means: reading from persistent state store failed.
Recovery: flutter-mcp-toolkit doctor --json — check filesystem permissions on state directory.
stateStoreWriteFailed (state_store_write_failed)
Means: writing to persistent state store failed.
Recovery: flutter-mcp-toolkit doctor --json — check disk space and permissions.
stateLockTimeout (state_lock_timeout)
Means: acquiring the state lock timed out (concurrent agent contention). Causes: another agent or CLI call holds the lock; deadlock. Recovery: wait and retry; if recurring, kill other agent processes holding the lock.
stateLockConflict (state_lock_conflict)
Means: a conflicting state lock was detected. Causes: parallel agents writing simultaneously. Recovery: serialise calls; retry after the conflicting operation completes.
diagnoseFailed (diagnose_failed)
Means: the composite diagnose command failed.
Recovery: flutter-mcp-toolkit doctor --json
explainErrorsFailed (explain_errors_failed)
Means: the error-explanation command failed.
Recovery: flutter-mcp-toolkit doctor --json
unsupportedSummaryProvider (unsupported_summary_provider)
Means: an unrecognised summary provider was requested. Not retryable.
Recovery: flutter-mcp-toolkit schema --name diagnose — check allowed provider values.
snapshotNotFound (snapshot_not_found)
Means: the referenced snapshot ID does not exist. Not retryable.
Recovery: flutter-mcp-toolkit snapshot create --name <snapshot_id> --args '{}'
snapshotInvalid (snapshot_invalid)
Means: snapshot payload is malformed or fails validation. Not retryable. Recovery: recreate the snapshot; do not reuse corrupted files.
staleSnapshot (stale_snapshot)
Means: the provided snapshotId no longer matches the current app state.
Causes: a hot reload or interaction changed the widget tree after the snapshot was taken.
Recovery:
evaluate_dart_expression(expression: "true")— verify app is reachable.semantic_snapshot()— obtain a fresh snapshot ID, then retry the original call.
bundleBuildFailed (bundle_build_failed)
Means: bundle creation or publish failed.
Recovery: flutter-mcp-toolkit doctor --json — check build artefacts and output path.
writeBlocked (write_blocked)
Means: a write was blocked because --no-overwrite is set and the target already exists. Not retryable.
Recovery: retry without --no-overwrite, or choose a different --output/--name.
doctorCriticalFailed (doctor_critical_failed)
Means: one or more critical doctor checks failed.
Recovery: flutter-mcp-toolkit doctor --json — read checks[*] where status: "fail" and critical: true; load flutter-mcp-toolkit-setup.
interactionFailed (interaction_failed)
Means: a tap/scroll/swipe/drag/long_press/enter_text/reveal_search/focus_widget call was refused.
Causes: stale ref; widget not visible, not interactive, or disabled; target never found; toolkit bridge not initialized. For focus_widget: focus_not_exposed (nothing focusable answers for the ref — a tap-only button with no FocusNode) or focus_refused (focus moved elsewhere; details.focusedNow names the holder).
Recovery:
- Read
error.details.hint— a refusal names its own cause and next step, and that hint is whaterror.recovery.summarycarries. - Otherwise
semantic_snapshot()for fresh refs, then retry.
semanticSnapshotFailed (semantic_snapshot_failed)
Means: semantic_snapshot execution failed.
Recovery: flutter-mcp-toolkit doctor --json — verify MCPToolkitBinding.initialize() is called.
evaluateExpressionFailed (evaluate_expression_failed)
Means: evaluate_dart_expression execution failed.
Causes: expression syntax error; exception thrown at runtime; isolate not reachable.
Recovery: simplify the expression; check syntax; flutter-mcp-toolkit doctor --json.
getRecentLogsFailed (get_recent_logs_failed)
Means: get_recent_logs retrieval failed.
Recovery: flutter-mcp-toolkit doctor --json — verify toolkit is initialized.
invalidPredicate (invalid_predicate)
Means: wait_for received a predicate whose requested observation cannot fit inside its timeout budget.
Causes: stableWindowMs is greater than or equal to effective timeoutMs.
Recovery: set timeoutMs above stableWindowMs; omitting timeoutMs uses the 5000 ms default.
waitTimeout (wait_timeout)
Means: wait_for predicate did not match before timeoutMs elapsed.
Causes: predicate condition never becomes true; app state does not change; timeoutMs too short.
Recovery:
semantic_snapshot()— verify the expected widget state.- Increase
timeoutMsor adjust the predicate.
waitForFailed (wait_for_failed)
Means: wait_for execution failed (malformed predicate or toolkit error).
Recovery: flutter-mcp-toolkit schema --name wait_for
pressKeyFailed (press_key_failed)
Means: press_key execution failed.
Recovery: flutter-mcp-toolkit schema --name press_key
handleDialogFailed (handle_dialog_failed)
Means: handle_dialog (dismiss/accept dialog) execution failed.
Causes: no dialog present; dialog already dismissed.
Recovery: semantic_snapshot() — verify a dialog is visible before calling.
navigateFailed (navigate_failed)
Means: navigate push/pop/popUntil failed.
Recovery: flutter-mcp-toolkit schema --name navigate
navigatorNotRegistered (navigator_not_registered)
Means: navigate was called but the app did not register a GlobalKey<NavigatorState>. Not retryable.
Causes: MCPToolkitBinding.instance.navigatorKey was never set in the host app.
Recovery: assign MCPToolkitBinding.instance.navigatorKey = navigatorKey in the app's main.dart and hot restart.
fillFormFailed (fill_form_failed)
Means: fill_form orchestration failed (transport or per-field error).
Recovery: flutter-mcp-toolkit schema --name fill_form
hoverFailed (hover_failed)
Means: hover execution failed.
Recovery: flutter-mcp-toolkit doctor --json
focusWidgetFailed (focus_widget_failed)
Means: focus_widget could not reach the app. A refusal the app itself reports (focus_not_exposed, focus_refused) arrives as interaction_failed with the toolkit's hint in details.
Recovery: flutter-mcp-toolkit doctor --json
unknown (unknown_error)
Means: fallback for any unrecognised error code.
Recovery: flutter-mcp-toolkit doctor --json — inspect error.details for raw cause.
Dogfood iterations
Tracker: maintainers/evidence/dogfood/dogfood_web_eval.yaml
Rubric: maintainers/superpowers/evals/tool_quality_rubric.yaml
Overview: maintainers/superpowers/evals/README.md
Pass threshold
≥80/100 weighted; ship at ≥90 or accepted pass_with_warnings.
| Dimension | Weight |
|---|---|
| connectivity | 20 |
| schema_validity | 10 |
| handler_correctness | 20 |
| capture_quality | 10 |
| visual_fidelity | 10 |
| webmcp_parity | 10 |
| intentcall_authoring | 10 |
| docs_truth | 10 |
Iteration workflow
Task Progress:
- [ ] Start app (web-showcase or make showcase)
- [ ] Fresh WS_URI from log (not stale after hot reload)
- [ ] Run battery
- [ ] Record score + warnings in tracker
- [ ] Promote recurring patterns if repeated ≥2 times
Web iteration
make web-showcase
export WS_URI="$(grep -Eo 'ws://127\.0\.0\.1:[0-9]+/[A-Za-z0-9_=-]+/ws' .showcase/web_app.log | tail -1)"
bash tool/evals/run_dogfood_eval.sh --ws-uri "$WS_URI" --merge --skip-visual # yq or dart fallback
# or without merge:
bash tool/evals/run_dogfood_eval.sh --ws-uri "$WS_URI"
Auto-runs: static gates + validate-runtime + webmcp verify.
Static only (CI / PR)
make dogfood-eval-static
Makefile
make dogfood-eval # needs WS_URI in env
make dogfood-eval-static
Artifacts
- Per run:
.showcase/eval_runs/<timestamp>/eval_run.yaml - Snapshot:
.showcase/eval_run_<timestamp>.yaml - With
--merge: updatesmaintainers/evidence/dogfood/dogfood_web_eval.yaml(yqordart run mcp_server_dart/tool/merge_dogfood_tracker.dart)
Verdicts
| Verdict | Meaning |
|---|---|
pass | score ≥80, no blocking warnings |
pass_with_warnings | score ≥80, e.g. visual_capture_truth_mode |
fail | score <80 |
blocked_no_runtime | --skip-runtime only |
Exec vs MCP names
Document in iteration notes when testing invoke:
- exec: bare names (
get_recent_logs,dogfood_ping) — also acceptsfmt_*aliases - MCP:
fmt_prefix (fmt_get_recent_logs,fmt_client_tool+ listingname) - Connection: global
--vm-service-uri(notexec --target)
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart \
--vm-service-uri "$WS_URI" exec --name get_recent_logs --args '{}'
Chrome battery notes
- Skip the visual track (
--skip-visual): its fixture home (externalflutter_harness) is retired, so the visual evidence is paused, not regenerable validate-runtime --save-imagescan hang >5m on Chrome; battery omits it unlessDOGFOOD_SAVE_IMAGES=1
CI (branch)
.github/workflows/intentcall_eval.yml — PR: dogfood-eval-static; weekly/main: intentcall package tests + static.
Full Chrome runtime dogfood stays local until headless WebMCP is cost-effective.
After each iteration
- Diff
dimension_scoresvs previous iteration in tracker. - Add to
recurring_warnings/recurring_errorswhen repeated. - Update
fix_recommendationswith actionable doc/code deltas. - Do not treat tracker YAML as gate without a fresh battery run.
Related skills
flutter-mcp-toolkit-maintain-web— WebMCP launch + verifyflutter-mcp-toolkit-maintain-macos— macOS showcaseflutter-mcp-toolkit-repo-maintainer—make sync-skillsafter editing this skill
When to use
Use this skill when the user wants to inspect or drive a running Flutter app from this conversation. Examples:
- "Tap the login button in my app"
- "Why is the home screen blank?"
- "Take a screenshot and tell me what's broken"
- "Expose my cart / flags / internal state to the agent via MCP"
If the user is asking about Flutter concepts unrelated to a running app (architecture questions, package selection), this skill does not apply.
Step 1: Preflight
Always run flutter-mcp-toolkit doctor --json first. Parse the output:
status: "ok"— proceed to Step 2.status: "error"anderror.code: "binary_not_found"— loadflutter-mcp-toolkit-setupand follow its install instructions.status: "error"anderror.code: "vm_not_connected"— loadflutter-mcp-toolkit-setupand follow its troubleshooting section.- Any other error — load
flutter-mcp-toolkit-debugand read the error envelope playbook.
Step 2: Pick the right skill for the user's intent
| 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 (AgentCallEntry, addEntries) | flutter-mcp-toolkit-custom-tools |
| Upgrade from removed legacy call-entry APIs | flutter-mcp-toolkit-intentcall-migration |
| Audit CLI/MCP/schema/dynamic-registry parity before changing tool surfaces | flutter-mcp-boundary-audit |
Maintain showcase/flutter_test_app web / WebMCP showcase hooks; agent list/execute via Chrome DevTools MCP (list_webmcp_tools / execute_webmcp_tool) | flutter-mcp-toolkit-maintain-web |
Maintain showcase/flutter_test_app macOS / native IntentCall hooks | flutter-mcp-toolkit-maintain-macos |
| Score dogfood iterations or route dogfood evidence | flutter-mcp-toolkit-dogfood-iterations |
Write repeatable E2E scenarios as Dart (flutter_mcp_harness: build/launch/attach/drive/assert, showcase launcher) | flutter-mcp-e2e-harness |
| Wire automation for an app across surfaces (MCP / CLI / harness / oka), first loops, runner sessions | flutter-mcp-automation-chain |
| Release, version, or plugin skill bundle maintenance | flutter-mcp-toolkit-repo-maintainer |
Harness Script lint/run/Maestro and promo/video capture live in their owner
repositories. Do not look for flutter-mcp-semantic-test,
flutter-mcp-capture, or hyperframes-video in this plugin.
If the task spans more than one (e.g. "tap the button and show me what
changed"), load inspect AND control. Skills are additive.
Step 3: Execute
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.
Tool taxonomy reference
The core toolkit tools fall into these categories. The full list with parameter shapes lives in the task skills.
- Inspection (read-only):
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. - Interaction (mutating):
tap_widget,long_press,enter_text,reveal_search,fill_form,scroll,swipe,drag,hover,focus_widget,press_key,wait_for,navigate,handle_dialog,hot_reload_flutter,hot_restart_flutter,hot_reload_and_capture. →flutter-mcp-toolkit-control. - Debug:
get_recent_logs,evaluate_dart_expression. →flutter-mcp-toolkit-debug. - Dynamic registry (app-defined): after registration in the Flutter app,
MCP calls use
fmt_list_client_tools_and_resources, thenfmt_client_tool/fmt_client_resource. When shelling out to the CLI, command names appear only asexec --name <name>values; do not call barelist_client_tools_and_resources,client_tool, orclient_resourceas MCP tools. →flutter-mcp-toolkit-custom-tools. - Boundary/proof maintenance: use
flutter-mcp-boundary-auditbefore changing catalog/schema/registry surfaces; useflutter-mcp-toolkit-maintain-weborflutter-mcp-toolkit-maintain-macosfor showcase platform hooks; useflutter-mcp-toolkit-repo-maintainerfor release, version, and generated skill-bundle work. - True WebMCP (browser): with Chrome DevTools MCP
(
--categoryExperimentalWebmcp), uselist_webmcp_tools/execute_webmcp_toolafter navigating to the web app. Details influtter-mcp-toolkit-maintain-web.
When in doubt
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.
When to use
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.
Recipes
Fast inspect cycle (prefer batch)
flutter-mcp-toolkit batch --steps '[
{"name":"semantic_snapshot"},
{"name":"get_app_errors","args":{"count":5}},
{"name":"get_screenshots","args":{"mode":"flutter_layer","compress":true}}
]'
Use mode: flutter_layer on get_screenshots on macOS to avoid Screen
Recording permission failures. capture_ui_snapshot uses the separate
screenshotMode field.
Snapshot the visible UI
- Call
semantic_snapshot(). - Read
interactionSurface:flutter_widgets(tap-by-ref works),hybrid(sparse semantics),game_canvas(useevaluate_dart_expression+ screenshots). - Each interactive node has a stable
ref(s_0,s_1, …) and the response includes asnapshot_id. - Pass refs to interaction tools; pass the
snapshot_idvalue assnapshotIdto detect staleness.
After a code edit
Prefer hot_reload_and_capture over separate reload + snapshot + screenshot calls.
Find an error by message
- Call
get_app_errors(count: 10). - Inspect the
errorsarray — each entry has message, stack trace, and timestamp. - Match on message text to find the source.
List debug-mode apps
- Call
discover_debug_apps(). - Read the
targetId(canonical WebSocket URI) for each active target. - Pass the chosen URI as
connection.targetIdon subsequent tool calls.
Get widget at coordinates
- Call
inspect_widget_at_point(x: 200, y: 400). - The response identifies the deepest widget and render node at those global logical pixel coordinates.
Save a screenshot to a file
- Call
get_screenshots(). - If
meta.fileUrlsis non-empty, screenshots are on disk at those paths. Otherwise the response contains base64ImageContentblocks — extract and write manually. - To force file output, configure an images output directory on the server before calling.
Tool reference
discover_debug_apps
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; runmake build.
get_app_errors
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; supplyconnection.targetId.
get_screenshots
Capture screenshots of all views.
compress(boolean, optional, default: true) — compress PNG output.mode(string, optional, default:auto) —auto,flutter_layer, ordesktop_window.permissionPolicy(string, optional, default:check_only) —check_only,auto_request_once, orrequest_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 withpermissionPolicy: "auto_request_once".vm_service_unavailable— app not reachable.
get_view_details
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; supplyconnection.targetId.
get_vm
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.
get_extension_rpcs
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.
semantic_snapshot
Return a compact accessibility tree of interactive widgets with stable ref strings and a snapshot_id. A node is listed when it reads (label, value), acts (button, text field, tap, scroll…) or carries a Semantics(identifier:).
identifierPrefix(string, optional) — keep only nodes whose identifier starts with it ("nav."for one rail).subtreeOf(string, optional) — keep one node and its descendants; a ref from the latest snapshot or an identifier, the ref tried first.fields(array of strings, optional) — node keys to return;refis always kept. Names:ref id type identifier label value hint enabled focused checked toggled selected bounds actions children visibleInViewport centerInViewport center.connection(object, optional) — connection override.
The tree is always walked whole, so a ref read off a filtered snapshot is the same ref the full snapshot would give and works with every interaction tool. A filtered reply adds totalNodeCount and echoes filter; children lists kept refs only.
semantic_snapshot()
semantic_snapshot(identifierPrefix: "nav.", fields: ["identifier", "selected"])
semantic_snapshot(subtreeOf: "panel.tabs")
Returns: {"snapshot_id": 3, "nodeCount": 1, "viewport": {...}, "nodes": [{"ref": "s_0", "label": "Increment", "actions": ["tap"], "bounds": {...}, "visibleInViewport": true, "centerInViewport": true, "center": {...}}]} — the viewport is stated once in the envelope, not on each node.
subtree_root_not_found—subtreeOfis neither a ref of the latest snapshot nor an identifier in the tree; no snapshot was taken, refs andsnapshot_idare unchanged.unknown_field— a name infieldsis not a node key;acceptedFieldslists them. Over MCP and the CLI the name is refused at the boundary instead — an invalidfieldsargument naming the accepted keys, without spending a call on the app.vm_service_unavailable— app not running orMCPToolkitBinding.initialize()not called.connection_selection_required— multiple targets; supplyconnection.targetId.
inspect_widget_at_point
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_ui_snapshot
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, ordesktop_window.permissionPolicy(string, optional, default:check_only) —check_only,auto_request_once, orrequest_always.connection(object, optional) — connection override.
capture_ui_snapshot(errorsCount: 2, includeViewDetails: false)
Returns: a TextContent JSON block with screenshots, viewDetails, and errors keys. When screenshots.images contains inline base64, each payload is lifted into a sibling image block and the JSON reports screenshots.imagesDeliveredAs: "image_blocks"; the emptied images list is then the normal shape, not a failed capture. Captures delivered through screenshots.fileUrls stay in the JSON and produce no image blocks.
vm_service_unavailable— app not running.permission_denied— retry withpermissionPolicy: "auto_request_once".
connect_debug_app
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) — passconnection.targetIdwith a WebSocket URI fromdiscover_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-rundiscover_debug_appsfor the exact URI.connection_failed— VM refused connection; verify the app is still running in debug mode.
IntentCall migration — MCPCallEntry → AgentCallEntry
MCPCallEntry is removed from mcp_toolkit. App code must use
AgentCallEntry (from intentcall_core, re-exported by mcp_toolkit).
Canonical migration doc: migration_mcp_call_entry_to_agent_call_entry.md
When to use this skill
dart analyzereports undefinedMCPCallEntryafter upgradingmcp_toolkit- User asks to migrate custom tools/resources to the new API
- Before shipping a major
mcp_toolkitbump to consumers
CLI (preferred)
# Preview (exit 1 if changes pending)
flutter-mcp-toolkit migrate agent-entries --check lib/
# Apply
flutter-mcp-toolkit migrate agent-entries --write lib/
flutter-mcp-toolkit migrate agent-entries --write --namespace my_app lib/main.dart
Alias: migrate mcp-call-entry (same behavior).
After migration — registration
MCPToolkitBinding.addEntries(entries: Set<AgentCallEntry>)addEntries(entries: { ... })beforebootstrapFlutter(runApp: ...)addMcpTool(AgentCallEntry)— still a shortcut for a single entry
Handlers should return AgentResult (AgentResult.success / AgentResult.failure).
For legacy MCPCallResult + MCPToolDefinition handlers, use mcpToolkitTool /
mcpToolkitResource (see flutter-mcp-toolkit-custom-tools).
Legacy pattern (before — do not ship new code)
// BEFORE (removed in Phase 6b)
final tool = MCPCallEntry.tool(
handler: (request) async => MCPCallResult(
message: 'ok',
parameters: {'n': request['n']},
),
definition: MCPToolDefinition(
name: 'my_tool',
description: 'Example',
inputSchema: {'type': 'object', 'properties': {}},
),
);
Target pattern (after)
import 'package:mcp_toolkit/mcp_toolkit.dart';
final tool = AgentCallEntry.tool(
namespace: 'app',
name: 'my_tool',
description: 'Example',
inputSchema: const {
'type': 'object',
'additionalProperties': false,
'properties': {'n': {'type': 'string'}},
'required': ['n'],
},
handler: (final args) async {
final n = args['n']?.toString() ?? '';
return AgentResult.success(
message: 'ok',
data: {'n': n},
);
},
);
await MCPToolkitBinding.instance.addEntries(entries: {tool});
Platform sync (optional)
After tool surfaces compile:
flutter-mcp-toolkit codegen sync --platform web
flutter-mcp-toolkit codegen sync --platform android,ios,macos --check
See docs/platform-notes/android-oem.md for Xiaomi/Huawei (same shortcuts XML as AOSP).
MCP migrate tool
fmt_migrate_agent_entries is shipped (report-only by default; apply: true to
rewrite). CLI equivalent: flutter-mcp-toolkit migrate agent-entries.
Maintainer checklist (in-repo product gate)
flutter-mcp-toolkit migrate agent-entries --checkonshowcase/flutter_test_app/libmake sync-skillsafter anyplugin/skills/editcd mcp_server_dart && dart test test/contract/- Grep: no
MCPCallEntryin skills except this file's BEFORE examples
Hosted IntentCall packages
IntentCall now lives outside this repository. Normal consumer state uses hosted intentcall_* packages.
- Use hosted
intentcall_*: ^0.6.0dependencies for committed consumer state. - Use local path overrides only for deliberate cross-repo development against a local IntentCall checkout.
- Run
flutter pub getandmigrate agent-entries --checkagain after dependency changes. - CI: use
make check-intentcall-hosted-consumerfor hostedmcp_flutterproof; usemake check-intentcall-sibling-matrixonly for deliberate local IntentCall checkout matrix proof. The historicalmake check-intentcall-integrationtarget is a compatibility alias for the sibling-matrix lane, not a fresh-adopter hosted gate.
Related skills
flutter-mcp-toolkit-custom-tools— authoringAgentCallEntrysurfacesflutter-mcp-toolkit-repo-maintainer— CHANGELOG, version pins,sync-skills
Maintain macOS (showcase + native intentcall)
Dogfood app: showcase/flutter_test_app. Platform doc: showcase/flutter_test_app/INTENTCALL_PLATFORM.md.
WebMCP on macOS
WebMCP modelContext is web-only. macOS dogfood proves VM extensions, dynamic registry, native invoke (intentcall:// via app_links), and visual capture (Screen Recording on host).
For WebMCP parity scoring, run web iteration separately (flutter-mcp-toolkit-maintain-web).
Launch showcase
make showcase-stop && make showcase
- Log:
.showcase/flutter_app.log - WS URI: grep
ws://127.0.0.1:…/wsfrom log (default VM port 8181)
grep -Eo 'ws://127\.0\.0\.1:[0-9]+/[A-Za-z0-9_=-]+/ws' .showcase/flutter_app.log | tail -1
Stop: make showcase-stop.
Codegen & hooks
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart codegen sync \
--platform web,android,ios,macos,linux,windows \
--project-dir showcase/flutter_test_app
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart init intentcall-platform \
--project-dir showcase/flutter_test_app --check
| Target | Role |
|---|---|
macos/intentcall_codegen.sh | Xcode Run Script → codegen sync --platform macos |
macos/Runner.xcodeproj | Run Script phase (see script comment if manual) |
lib/main.dart | IntentCallInvokeLinkListener for intentcall://invoke/… |
Runtime validate
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart --save-images \
--output-dir .showcase/macos_iter validate-runtime \
--target "$MACOS_WS_URI" \
--flutter-device macos \
--timeout-ms 45000
Permissions (host process running CLI):
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions status
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions request
Dual-platform dogfood
bash tool/evals/run_dogfood_eval.sh \
--ws-uri "$WEB_WS_URI" \
--macos --macos-ws-uri "$MACOS_WS_URI"
Related
flutter-mcp-cli-runtime-validation— doctor, capture backends, extensionsflutter-mcp-toolkit-maintain-web— WebMCP enablementflutter-mcp-toolkit-dogfood-iterations— rubric + trackerflutter-mcp-e2e-harness— programmatic scenarios over this showcase (packages/harness, showcase launcher)
Maintain Web (Chrome + WebMCP)
Dogfood app: showcase/flutter_test_app. Canonical platform doc: showcase/flutter_test_app/INTENTCALL_PLATFORM.md.
WebMCP vs VM MCP
| Path | Proves |
|---|---|
VM extensions + fmt_* tools | MCP toolkit dogfood (always) |
navigator.modelContext / document.modelContext | True WebMCP (Chrome flags / --web-browser-flag) |
ADR: decisions/0008_web_agent_invoke_js_only.mdx — JS fetch('/agent/invoke') 404 by design; Dart invokeDirect works when modelContext exists.
JIT vs AOT web: which driving tier
VM extensions (fmt_*, the toolkit) require the Dart VM service — they
exist on JIT web (DDC via flutter run). An AOT web build
(flutter build web) has no VM service: drive it through the CDP
tier instead — flutter_mcp_harness's WebBuildTarget/FlutterWebCdp
(this repo, ADR-0018) over the browser-level primitives
(universal-automation-family ADR-0045). For typed app intents on AOT
web, publish window.__mcpActions handlers (plain JS interop, AOT-safe)
— the CDP driver's InvokeAction dispatches to them; projecting the
toolkit's tool catalog onto that registry is the tracked bridge.
Launch (repeatable WebMCP)
make web-showcase
# WS_URI from .showcase/web_app.log (re-grep after hot reload)
grep -Eo 'ws://127\.0\.0\.1:[0-9]+/[A-Za-z0-9_=-]+/ws' .showcase/web_app.log | tail -1
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart webmcp chrome-args
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart webmcp verify --web-port 8080
Stop: make showcase-stop.
Do not rely on chrome://flags alone across machines — use CLI flags / make web-showcase / VS Code launch args.
VS Code / Cursor launch
Use config showcase/flutter_test_app Chrome + WebMCP in .vscode/launch.json:
--web-browser-flag=--user-data-dir=${workspaceFolder}/.showcase/chrome-webmcp-profile— persistent profile sochrome://flagssurvive stop/start (Flutter default is a temp profile every run).--web-browser-flag=--enable-features=WebMCPTesting,WebModelContext,DevToolsWebMCPSupport--web-browser-flag=--enable-experimental-web-platform-features
Path must not include literal quotes in the value (avoids a dir named "./…").
Chrome 149+ Application → WebMCP pane also needs #devtools-webmcp-support / feature DevToolsWebMCPSupport (API alone is not enough for that UI).
Agent WebMCP (Chrome DevTools MCP) — preferred for live invoke
Prefer chrome-devtools MCP (list_webmcp_tools, execute_webmcp_tool) over flutter_mcp_toolkit webmcp verify --tool-name when an agent should drive page tools.
Install (once)
Grok (~/.grok/config.toml):
[mcp_servers.chrome-devtools]
command = "npx"
args = [
"-y",
"chrome-devtools-mcp@latest",
"--categoryExperimentalWebmcp",
"--chromeArg=--enable-features=WebMCP,WebModelContext,DevToolsWebMCPSupport,WebMCPTesting",
"--chromeArg=--enable-experimental-web-platform-features",
"--userDataDir=/Users/YOU/.cache/chrome-devtools-mcp/chrome-profile-webmcp",
"--no-usage-statistics",
]
enabled = true
startup_timeout_sec = 90
Or: grok mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --categoryExperimentalWebmcp ...
Cursor — same command/args under mcpServers.chrome-devtools in ~/.cursor/mcp.json.
Restart the agent session after install. Doctor: grok mcp doctor chrome-devtools.
Live flow
- App must serve (e.g.
make web-showcaseor VS Code Chrome + WebMCP on:8080). list_pages— chrome-devtools may start its own browser (about:blank).navigate_page→http://localhost:8080/(or your app URL).- Wait for Flutter/Dart bootstrap (first
list_webmcp_toolscan be empty). list_webmcp_tools— expect IntentCall tools + oftenmcp_*toolkit tools registered onmodelContext.execute_webmcp_toolwithtoolName+ JSON-stringinputwhen required.
Example IntentCall tools: app_enable_switch (no args), app_set_greeting ({"text":"…"}), app_intentcall_bridge_ping ({"echo":"…"}), app_get_agent_showcase_state.
execute_webmcp_tool
toolName: app_enable_switch
input: {}
Fallback (CLI, no chrome-devtools MCP)
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart webmcp verify --web-port 8080 \
--tool-name app_enable_switch --tool-args '{}'
Codegen & hooks
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart codegen sync \
--platform web,android,ios,macos,linux,windows \
--project-dir showcase/flutter_test_app
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart init intentcall-platform \
--project-dir showcase/flutter_test_app --check
| Artifact | Source |
|---|---|
web/intentcall_webmcp.generated.js | codegen sync from web/agent_manifest.json |
web/index.html | init intentcall-platform script tag |
| Dart bootstrap | projection the app registers — showcase: ShowcaseWebMcpProjection (in intentcall_showcase_bootstrap.dart), wrapping projectEntriesToWebMcp from intentcall_platform_sync; wired via MCPToolkitBinding.addEntryListener (ADR-0016) |
Runtime validate
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart --save-images \
--output-dir .showcase/web_iter validate-runtime \
--target "$WS_URI" \
--flutter-device chrome \
--timeout-ms 45000
Pass --web-browser-debugging-port <cdp> if CDP discovery fails.
Known issues
- Duplicate tool name — generated JS + the WebMCP projection (
projectEntriesToWebMcp) both callregisterTool; dedupe or gate one path (agent_web_mcp_bootstrap_web.dartname cache). - CDP probe —
webmcp verifymay reportwebmcp_active_log_evidencewhile CDPhasModelContextis false (Flutter execution context). - Stale WS_URI — always grep fresh token after hot restart before eval/validate.
- Empty WebMCP list right after navigate — wait until Dart hook / registration finishes, then list again.
- Temp Chrome profile — without
--user-data-dir, Flutter wipeschrome://flagsevery stop/start. - Two browsers — chrome-devtools MCP profile ≠ Flutter-launched Chrome unless you attach with
--browser-url=http://127.0.0.1:<cdpPort>.
Related
maintainers/superpowers/evals/2026-05-26-webmcp-verification.mdflutter-mcp-cli-runtime-validation— validate-runtime detailsflutter-mcp-toolkit-dogfood-iterations— scored iterationsflutter-mcp-e2e-harness— programmatic scenarios over this showcase (packages/harness,--web --detachvariant)- Chrome DevTools MCP: https://github.com/ChromeDevTools/chrome-devtools-mcp (WebMCP tools need
--categoryExperimentalWebmcp+ Chrome 149+)
flutter-mcp-toolkit repo maintainer
Golden path for this repository (not end-user Flutter apps). Prefer
release-please on main; use manual steps only when the Release PR path is blocked.
When to use
- Cutting a release or promoting
## [Unreleased]in CHANGELOG.md - Adding/editing contributor docs, AI agent install docs, or plugin skills
- Verifying version sync or skill asset drift before merge
- Troubleshooting release-please,
release.ymlbinaries, orinstall.shversion pins
Version touchpoints (must match root VERSION)
| File | Field |
|---|---|
| VERSION | repo pin |
| plugin/EXPECTED_SERVER_VERSION | installer pin |
| packages/core/lib/src/runtime_version.dart | kFlutterMcpVersion (x-release-please-version) |
| packages/server_capability_core/lib/src/fmt_capability.dart | version getter |
| mcp_server_dart/pubspec.yaml | version: |
| mcp_toolkit/pubspec.yaml | version: |
| packages/core/pubspec.yaml | version: |
| packages/server_capability_kernel/pubspec.yaml | version: + same-train dependency constraints |
| packages/server_capability_core/pubspec.yaml | version: + same-train dependency constraints |
| plugin/.cursor-plugin/plugin.json | version |
| plugin/.codex-plugin/plugin.json | version |
| plugin/.claude-plugin/plugin.json | version |
| .claude-plugin/marketplace.json | plugins[0].version |
| .release-please-manifest.json | "." key |
| mcp_server_dart/lib/src/skill_assets.g.dart | generated — embeds plugin/.cursor-plugin/plugin.json, plugin/.codex-plugin/plugin.json, plugin/mcp.json, and all plugin/skills/*/SKILL.md |
After any version bump: run make sync-version, then make sync-skills, then make check-contracts (includes check_version_sync.sh and check_skill_assets_drift.sh). tool/release/sync_version.sh derives all version touchpoints from root VERSION.
Video (separate repo): flutter_mcp_video — not maintained in this plugin tree. The external flutter_harness repo is retired (ADR-0017); its scenario layer was never migrated.
Changelog workflow
- Add user-facing notes under
## [Unreleased]in CHANGELOG.md (Keep a Changelog sections: Added, Changed, Fixed, Documentation). - Use conventional commit titles on
main(feat:,fix:,docs:) so release-please can aggregate. - Do not edit the plan file in
.cursor/plans/.
Markdown lint (MD052)
Keep a Changelog requires version headings like ## [3.0.1]. Linters treat [3.0.1] as an undefined reference link (MD052: "No link definition found").
- Do not remove the file-top
<!-- markdownlint-disable MD052 -->in CHANGELOG.md (release-please must keep it when prepending sections). - In bullet text, use backticks for code identifiers:
`AgentCallEntry`, not[AgentCallEntry]. - Before merge:
bash tool/contracts/check_changelog_markdown.sh(also inmake check-contracts).
Automated release (preferred)
flowchart LR
main[merge_to_main] --> rp[release-please.yml]
rp --> pr[Release_PR]
pr --> sync[release_pr_sync_versions.yml]
pr --> assets[release_pr_sync_skills.yml]
pr --> tag[vX_Y_Z_tag]
tag --> rel[release.yml_binaries]
tag --> pub[pub_publish.yml_pubdev]
- Merge PRs to
mainwith conventional commits. - Wait for Release PR from release-please.yml.
- version train: release_pr_sync_versions.yml runs
tool/release/sync_version.shon Release PRs and commits any drift from rootVERSION. - skill assets: release_pr_sync_skills.yml auto-commits
skill_assets.g.darton Release PRs when drift is detected; posts a checklist comment on PR open. If skill-assets-drift still fails, runmake sync-skillslocally and push. - Review VERSION, CHANGELOG, pubspecs, plugin pins in that PR → merge.
- release-please creates
vX.Y.Z+ GitHub release notes. - release.yml asserts tag ==
VERSION, then attachesflutter_mcp_*tarballs (does not overwrite release body). - pub_publish.yml publishes pub.dev packages in dependency order through OIDC:
flutter_mcp_toolkit_core→flutter_mcp_toolkit_capability_kernel→flutter_mcp_toolkit_capability_core→mcp_toolkit.
Before automated pub.dev publishing can run, each package must already have a first manual publish and pub.dev Admin must enable GitHub Actions publishing for this repository with tag pattern v{{version}}. Use GitHub environment pub.dev with required reviewers.
Config: release-please-config.json.
Manual release (fallback)
Use when release-please is unavailable or you must ship from a branch:
- Move
## [Unreleased]bullets into## [X.Y.Z](add date), leave empty## [Unreleased]. - Update
VERSIONtoX.Y.Z. make sync-versionto derive all version touchpoints and.release-please-manifest.json.make sync-skills(required whenever plugin manifests or skills change).make check-contracts- Commit:
chore: release X.Y.Z - Optional pub.dev preflight:
make publish-pub-dry-run. - Tag:
git tag vX.Y.Zand push tag (triggers binary and pub.dev workflows).
Build artifacts locally: make release-artifacts or bash tool/release/build_release_artifacts.sh --version X.Y.Z.
Publish pub.dev packages locally only as a fallback: make publish-pub.
Docs map (single sources of truth)
| Topic | Canonical doc |
|---|---|
| End-user agent install | docs/install/clients.mdx |
npx skills + lockfile | clients.mdx § skills; .skills.json.example |
| Contributor / releases | docs/contributing/guide.mdx |
| Plugin layout | plugin/README.md |
| Marketplace copy SSOT | plugin/assets/marketplace_copy.yaml |
| Distribution / stores | docs/install/clients.mdx |
| Store submission runbook | docs/contributing/marketplace_submission_runbook.mdx |
| Skill bodies | plugin/skills/<id>/SKILL.md → make sync-skills |
Avoid duplicating install tables in README — link to docs/index.mdx.
Skills maintenance
- Canonical skills:
plugin/skills/(repo rootskills/→ symlink fornpx skills). - New bundled skill: add
plugin/skills/<id>/SKILL.md, appendidtoexpectedSkillIdsin build_skill_assets.dart, runmake sync-skills. - Local Cursor copy:
.cursor/skills/<id>/may symlink toplugin/skills/<id>/. - Platform dogfood skills:
flutter-mcp-toolkit-maintain-web,flutter-mcp-toolkit-maintain-macos,flutter-mcp-toolkit-dogfood-iterations.
HyperFrames promo (flutter_mcp_video repo)
Video skill and projects live in flutter_mcp_video (skills/hyperframes-video/, projects/video-projects/<id>/). Not bundled in toolkit make sync-skills.
When shipping a promo there: edit the video repo; run bash tool/check_doc_paths.sh in that repo before merge. Toolkit repo only hosts shared brand assets under plugin/assets/ (symlink targets for v7-weaver).
IntentCall consumer maintainer gate
When changing IntentCall consumer integration in mcp_flutter:
- Append
flutter-mcp-toolkit-intentcall-migrationtoexpectedSkillIdsinbuild_skill_assets.dartif not already present. make sync-skills— commitskill_assets.g.dartwith skill edits.bash tool/contracts/check_intentcall_skills_grep.sh— no legacy call-entry symbol outside migration skill.cd mcp_server_dart && dart test test/contract/flutter-mcp-toolkit migrate agent-entries --check showcase/flutter_test_app/lib(expect exit 0)- Keep canonical IntentCall design links pointed at the IntentCall repository; keep this repo focused on hosted dependency and regression proof.
Pre-merge checklist
-
make check-contracts -
make sync-skillsifplugin/skills/orplugin/*-plugin/plugin.jsonchanged - CHANGELOG
[Unreleased]updated for user-visible changes - No secrets in committed configs
When to use
Use this skill when:
- First-time install:
flutter-mcp-toolkitor its short aliasfmtkis not yet on PATH. doctor --jsonreturns any check with"status": "fail".- MCP server fails to connect or tools return
vm_not_connected/connect_failed. - Visual capture or toolkit-bridge commands are returning unexpected errors.
Verify install
flutter-mcp-toolkit --help
fmtk --help
Expected output: command help from both names. flutter-mcp-toolkit is the canonical long name; fmtk is the compact alias for day-to-day terminal loops.
If you get command not found, the binary is not on PATH:
# Binary is built to mcp_server_dart/build/ inside the repo
export PATH="$PATH:/path/to/mcp_flutter/mcp_server_dart/build"
# Or rebuild from source
cd /path/to/mcp_flutter && make build
Then verify with flutter-mcp-toolkit --help and fmtk --help.
Run doctor
Always run doctor before any VM-dependent command:
fmtk doctor --json
Flags: --target <ws_uri> (test a specific URI), global --vm-service-uri <ws_uri> (same as --target when omitted on doctor), --timeout-ms <n> (default: 2500).
# Global URI works for doctor (same as validate-runtime)
fmtk --vm-service-uri 'ws://127.0.0.1:8181/<token>/ws' doctor --json
Sample green output:
{
"summary": { "criticalFailures": 0 },
"checks": [
{ "id": "vm_target_reachable", "status": "pass", "critical": true },
{ "id": "mcp_toolkit_extensions", "status": "pass", "critical": true },
{ "id": "dynamic_registry_available", "status": "pass", "critical": false }
]
}
Triage: criticalFailures > 0 means VM/setup is blocked — not that every tool is broken. dynamic_registry_available: pass with vm_target_reachable: fail usually means a stale URI after hot restart; run discover_debug_apps and pass the new targetId.
Read error.descriptor (not top-level) for retry policy and exit codes. Each check includes fix_command — run it directly.
Recover by error code
binary_not_found
Binary missing or not on PATH. Rebuild and add to PATH:
cd /path/to/mcp_flutter && make build
export PATH="$PATH:/path/to/mcp_flutter/mcp_server_dart/build"
vm_not_connected
Flutter app not running, stale token after restart, or URI not resolved:
fmtk exec --name discover_debug_apps --args '{}'
fmtk exec --name status --args '{}'
fmtk doctor --json --target ws://127.0.0.1:8181/<new-token>/ws
After a successful auto re-attach, meta.recovery.reattachedTo shows the new endpoint.
connect_failed
Wrong port, app not started, or stale token. Pass explicit URI from app.debugPort.wsUri:
fmtk exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}'
connection_selection_required
Multiple debug targets detected. List with discover_debug_apps, then pass the chosen URI from details.availableTargets explicitly to get_vm.
hot_reload_failed
Dart compilation error or VM disconnected. Check errors, fix, then retry:
fmtk exec --name get_app_errors --args '{}'
visual_capture_unsupported
macOS screen recording permission not granted or unsupported platform:
fmtk permissions request --kind visual_capture
Connection issues (deeper troubleshooting)
Port conflicts: VM service defaults to 8181. Override if another process holds it:
flutter run --debug --host-vmservice-port=8182 -d macos
fmtk --dart-vm-port 8182 doctor --json
Use flutter run --machine and copy app.debugPort.wsUri when you need the exact websocket URI (recommended for validate-runtime and exec).
Flutter app not in debug mode: Release/profile builds don't expose the VM service. Always use flutter run --debug.
mcp_toolkit not initialized: Doctor's mcp_toolkit_extensions check will fail. Add before runApp — use flutter-mcp-toolkit codegen-init to generate the boilerplate (see CLI surface below). After adding, hot restart (not hot reload — binding init requires a full restart).
Multiple apps / wrong target: Pass --target with the exact websocket URI:
fmtk doctor --json --target ws://127.0.0.1:8181/<token>/ws
CLI surface
The canonical binary is flutter-mcp-toolkit (built to mcp_server_dart/build/). Packaged installs also include fmtk, a short alias to the same entrypoint. Use fmtk in quick loops; keep the long name in install, onboarding, PATH, and MCP configuration docs.
| Subcommand | Purpose | Minimal example |
|---|---|---|
exec | Run a single named command against the VM | fmtk exec --name get_vm --args '{}' |
batch | Run multiple commands in one call | fmtk batch --steps '[{"name":"get_vm"},{"name":"status"}]' |
schema | Print the JSON schema for a named command | fmtk schema --name hot_reload_flutter |
capabilities | List all registered capabilities | fmtk capabilities |
serve | Start the MCP server (stdio transport) | fmtk serve |
snapshot create | Capture and save a named snapshot | fmtk snapshot create --name baseline --args '{}' |
snapshot diff | Diff two snapshots | fmtk snapshot diff --from baseline --to current |
bundle create | Package a snapshot into a publishable bundle | fmtk bundle create --from-snapshot baseline --output ./out |
doctor | Run preflight checks (VM + toolkit + registry) | fmtk doctor --json |
permissions status | Check a permission (e.g. visual_capture) | fmtk permissions status --kind visual_capture |
permissions request | Request a permission | fmtk permissions request --kind visual_capture |
permissions open-settings | Open OS settings for a permission | fmtk permissions open-settings --kind visual_capture |
validate-runtime | End-to-end VM + toolkit + capture smoke test | fmtk validate-runtime --target ws://127.0.0.1:8181/<token>/ws |
init <agent> | Install skills + MCP server config for an AI agent | flutter-mcp-toolkit init claude-code |
codegen-init | Add toolkit dependency and emit main.dart boilerplate | flutter-mcp-toolkit codegen-init |
Global flags (before the subcommand): --dart-vm-port <n>, --dart-vm-host <host>, --vm-service-uri <ws_uri>, --log-level <level>, --dumps, -h/--help.
VM targeting: Global --vm-service-uri applies to doctor and validate-runtime when subcommand --target is omitted. If both are set and differ, --target wins (stderr warning).
validate-runtime screenshots: the first capture uses auto (often desktop_window on macOS). If that step fails with a retryable get_screenshots_failed, the CLI retries once with flutter_layer. On success, data.summary.captureFallbackUsed is true in the JSON envelope.
Debug/eval batteries: keep repeated checks as scripts or batch calls over existing primitives first: --log-level debug, --output-dir, --save-images, doctor --json, validate-runtime, batch, and exec --name diagnose. Do not expose a generic MCP run_tool; MCP remains the typed fmt_* tool surface. If a flow becomes reusable across projects as a scenario, graduate it to checked-in Dart in this repo's showcase/ or packages/harness instead of adding a toolkit-only scenario language.
init <agent>
Install the flutter-mcp-toolkit skills + MCP server config for an AI agent.
Targets: claude-code | cursor | codex | cline | agents-skills | all.
flutter-mcp-toolkit init claude-code # install for Claude Code (project-scoped)
flutter-mcp-toolkit init cursor --scope user # install user-globally for Cursor
flutter-mcp-toolkit init all --mode cli # install for every detected agent in CLI mode
Mode auto-detects (MCP if registered, else CLI). Override with --mode mcp|cli|auto.
Alternative (skills only, open ecosystem): npx skills add Arenukvern/mcp_flutter -a cursor -y installs the same SKILL.md bundles via skills.sh; it does not write mcp.json — run init afterward or configure mcpServers manually. See Connect your agent.
codegen-init
From a Flutter project root, add mcp_toolkit as a dependency and emit
the boilerplate snippet for lib/main.dart.
cd my-flutter-app
flutter-mcp-toolkit codegen-init # runs `flutter pub add` + prints snippet
flutter-mcp-toolkit codegen-init --no-pub-add # snippet only, skip pub add
Reinstall / upgrade
The install script is idempotent — re-running it replaces the binary in place:
curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash
After reinstall, verify with flutter-mcp-toolkit --help and fmtk --help.
Flutter MCP
Golden path for agents driving a live Flutter app via the flutter-mcp-toolkit MCP server entry (flutter-mcp-toolkit-server on stdio).
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:
- Ensure the app is running in debug mode with
mcp_toolkitbootstrap (seeflutter-mcp-toolkit codegen-init). - Call
fmt_discover_debug_appsorfmt_connect_debug_app(useconnection.uriwhen multiple targets exist). - Optionally run
fmt_get_extension_rpcsto confirmext.mcp.toolkit.*extensions exist.
Core loop
fmt_semantic_snapshot— read UI structure and refs.fmt_tap_widget/fmt_enter_text/fmt_scroll— act on refs from the snapshot.fmt_hot_reload_flutterorfmt_hot_reload_and_capture— apply code changes.fmt_wait_forwith{kind: stable, stableWindowMs: 300}then re-snapshot.
Screenshots
Prefer fmt_get_screenshots (Flutter render pipeline over VM service). They work when the app window is in the background. Use fmt_capture_ui_snapshot when you need a single PNG path on disk without the batch screenshot helper.
Errors
Parse structured JSON envelopes (ok, errorCode). See skill flutter-mcp-toolkit-debug for recovery playbooks.
Agents 1
You are a Flutter runtime specialist. Your job is to inspect, interact with, and live-edit running Flutter apps through the flutter-mcp-toolkit MCP server (same process as legacy flutter-inspector registry entries). You prioritize runtime evidence (screenshots, snapshots, error stack traces) over static code reading.
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. The dynamic-registry host tools
(fmt_list_client_tools_and_resources, fmt_client_tool, fmt_client_resource)
use the same fmt_ prefix for a single consistent surface.
Operating rules
-
Preflight before any VM call. Run
doctorfirst. If critical checks fail, stop and report — don't guess at state from an unreachable app. -
Verify instrumentation once per session. Confirm
ext.mcp.toolkit.{app_errors,view_details,view_screenshots,inspect_widget_at_point}exist. If any are missing, report the gap with the exact fix (addmcp_toolkit, initialize inmain(), hot restart). Do not continue app-level inspection. -
Always pass
snapshotIdonfmt_tap_widget/fmt_enter_text/fmt_scroll/fmt_swipe/fmt_long_press/fmt_drag. A structuredstale_snapshoterror is far better than a silent wrong tap. On stale, re-snapshot and retry. -
Use
fmt_hot_reload_and_captureafter code edits — single call returning reload status + screenshot + fresh snapshot + errors. Beats manual reload + separate capture. -
Before/after screenshots are the proof artifact. Never claim a UI change took effect without both frames. For each visual issue, attach the coordinate and
fmt_inspect_widget_at_pointoutput. -
Error envelope. Parse
error.descriptor, not the top-level. Common codes:connection_selection_required(retry with exactarguments.connection.uri),target_not_found(refresh targets),stale_snapshot(re-snapshot),tool_not_found(use thefmt_*prefixed name). -
Map defects to source via
fmt_get_app_errorstop stack frame (file:line:col) before proposing a fix. -
Do not use
fmt_debug_dump_*unless the server was started with--dumpsand the user asked — high token cost. -
Non-modifiable apps: if
mcp_toolkitcan't be added (third-party binary, restricted env), report flutter-mcp as unavailable. Don't claim screenshot/layout/error inspection success.
Dynamic tool registration
When a user asks for app-specific introspection that isn't covered by built-in tools (cart state, feature flags, domain queries), consider registering a custom MCP tool via AgentCallEntry.tool + MCPToolkitBinding.instance.addEntries (see skill flutter-mcp-toolkit-custom-tools). Rules:
- Register once at bootstrap (after
MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit();, before/duringrunApp). Not inside widget lifecycles. - Tight schema:
additionalProperties: false, explicitrequired, enums over free strings. - Hot restart after adding — hot reload may not re-emit DTD registration events.
- Confirm with
fmt_list_client_tools_and_resourcesbefore calling.
When to hand back
- User asks for non-runtime work (pure refactor, static analysis, docs).
mcp_toolkitcannot be added to the target app.- User explicitly asks to switch approaches.
Report tightly: target URI, what you verified, what you captured (with paths), what you changed, what the before/after shows. No narration of internal reasoning.
MCP servers 1
Sponsors
Details
- Marketplace
- Arenukvern/mcp_flutter
- Source
- plugin
- Category
- Community
- Keywords
- flutter, dart, mcp, mcp-toolkit, vm-service, inspector, live-edit, dynamic-tools, runtime-tools, game-debug