Arenukvern avatar

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-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Arenukvern/mcp_flutter.

Contents

Discovered from source

Skills 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

NeedSurfaceSkill / doc
Chat-driven debugging ("tap X, what changed?")MCP fmt_* toolsflutter-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 codesflutter_mcp_harnessflutter-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 CDPflutter-mcp-toolkit-maintain-web
Intent → driver routing without hardcoding transportIntentDriverRouter + hintsthis 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 same AppTarget contract as desktop tiers.
  • driverForLiveSession(projectDir) — attach a driver to a session oka already owns (read the signature and example/emulator_smoke.dart in the oka repo's packages/oka_harness/; never launch a second owner).
  • While oka dev owns the app, MCP fmt_* tools attach as usual — the server reads .flutter_mcp/runner-session.json and 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 LaunchedApp around 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_toolkit first; harness extensions mirror that list.

Related

Sources

  • decisions/0014_external_dev_sessions_runner_delegation.mdx — runner-session contract (spec v2)
  • decisions/0015_flutter_mcp_harness_extraction.mdx — harness extraction and boundaries
  • decisions/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 required fields 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 registrationAuthoring → discovery payload
Dynamic or plugin registration on the app/runtime sideRuntime validate-before-handler
Server registry, forward/dispatch, catalog *_client_tool helpersRegistry listing + invoke
Host gateway (VM extension, IPC, HTTP proxy) before delegating to runtimeHost 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 sourcesSchema preservation, not permissive fallbacks
Shared schema module vs duplicate definitionsDual-path parity
Bridge handlers, non-scalar argumentsEncoding (JSON, protobuf, etc.) vs handler expectations
Platform / ADR / registration docsStale 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:

StepQuestionWhere to look (your repo)
AuthoringDoes the canonical input schema reach the registration/descriptor type (not dropped at a toolkit/bridge wrapper)?Authoring layer / entry model / code generator output
AuthoringDo bridge tools encode non-scalar args consistently for legacy handlers?Bridge helpers, adapter layers
DiscoveryDoes dynamic registration send the full inputSchema (not {} or implicit-any)?App registration API, manifest emitter
DiscoveryDoes the host list/catalog tool expose the same schemas as the runtime registry?List-tools handler vs app registration
Server registryDoes 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
ExecuteAny .execute( / handler dispatch without prior validate in production code?Grep (below)
MigratorDoes migration preserve primitive/required/additionalProperties from source schema?Migrator, codegen
DocsDo 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 roleMust validate beforeFail if schema missing?
Runtime callback (extension, plugin hook)handleryes (production tools)
Registry forwardexecute / handleryes
Host gateway (proxy to runtime)delegate callyes
In-process invokeexecuteyes
Catalog / fmt_* / CLI wrapperforward to runtimeyes (same as listing)
CLI execcommand dispatchyes

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:

MechanismRole
Coerce-for-schemaProperty-type coercion from wire strings before strict schema validation
Handler-side wire parsersOptional when handlers still read raw wire maps
Outbound wire encodingHandler 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:

PathTypical roleListing / invoke
Runtime / app dynamicRegistered in the running app or plugin hostExtension name, dynamic registry
Host catalogServer-side MCP tools, CLI aliases, OpenAPI routesPrefixed or bare names on wire

For each shared tool, compare:

  • required keys
  • additionalProperties: 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:

  1. List tools/resources (or OpenAPI GET) shows required and strict additionalProperties where intended.
  2. Invoke with missing required → structured failure (ok: false, 4xx, or validation error)—before handler side effects.
  3. Invoke with extra properties when schema is strict → same failure mode.
  4. 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):

RoleYour locationNotes
Authoringe.g. entry model, OpenAPI spec, @Tool annotationsWhere canonical schema is defined
Discoverye.g. registerDynamics, plugin manifest, MCP tools/listWhat clients read
Registry / cataloge.g. dynamic registry, server tool tableListing vs invoke entry points
Host gatewaye.g. VM extension proxy, API gateway, sidecarValidates before delegate?
Runtime callbacke.g. service extension, plugin host RPCValidates before handler?
In-process invokee.g. WebMCP, embedded JS bridgeSame as tools/list?
CLIe.g. exec, bare vs prefixed aliasesSame schema as MCP?
Shared schema modulee.g. interaction_input_schemas, OpenAPI componentsSingle source of truth?
Migrator / codegene.g. migrate agent-entriesPreserves required/properties?
Platform doce.g. INTENTCALL_PLATFORM.md, README contract sectionMatches 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 entries
  • flutter-mcp-toolkit-intentcall-migration — migrate agent-entries
  • flutter-mcp-toolkit-maintain-web — WebMCP / in-process invoke
  • flutter-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

  1. Launch the Flutter app in debug mode.
  2. 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-runtime stays read/write only for visual capture and defaults to auto_request_once.
  • doctor remains read-only.
  • On macOS, Screen Recording permission belongs to the host process running flutter-mcp-toolkit.
  • On web: desktop_window uses macOS ScreenCaptureKit then Chrome CDP (Page.captureScreenshot); Linux/Windows use CDP when remote debugging is reachable. Pass --web-browser-debugging-port if discovery fails. For web targets, pass --flutter-device chrome so validation does not pick macOS host desktop_window by mistake.
  • Executor recovery retries host capture once (desktopCaptureRetried in screenshot payloads). If desktop_window still fails (including when platform views are detected), validate-runtime retries once with flutter_layer. Check data.summary.captureFallbackUsed.
  • You may pass the VM URI as global --vm-service-uri instead of validate-runtime --target when only one URI is needed.

What validate-runtime Must Prove

  • Doctor preflight passes critical checks.
  • Required toolkit extensions exist:
    • ext.mcp.toolkit.app_errors
    • ext.mcp.toolkit.view_details
    • ext.mcp.toolkit.view_screenshots
    • ext.mcp.toolkit.inspect_widget_at_point
  • Screenshot capture works.
  • View details (layout metadata) are available.
  • App errors are retrievable.
  • If --after-reload is enabled, post-reload screenshot also works.

Output Handling

  • Use data.summary as pass/fail status for automation.
  • Use data.summary.capturePlatformViewsDetected and captureFocusAttempted for platform-view routing.
  • Use data.summary.captureFallbackUsed to see whether a flutter_layer retry ran after a failed desktop_window attempt (including when platform views are detected).
  • Use data.steps for per-step evidence and retries.
  • Use data.doctor.checks to explain setup blockers.
  • Use data.summary.screenshotFiles for saved screenshot paths when --save-images is enabled.
  • When --save-images is 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_toolkit to app dependencies
    • ensure MCPToolkitBinding.instance.bootstrapFlutter(...) or equivalent manual initialization runs before runApp
    • hot restart or rerun the app
  • 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 status
    • dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions request
    • dart 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_point output.
  • Map defects to source using get_app_errors top 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: doctor critical failure on vm_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.

NeedUse
Repeatable scenario as code, CI-friendly exit codesthis skill (flutter_mcp_harness)
One-off interactive debugging from chat/editorflutter-mcp (MCP fmt_* tools)
Browser/WebMCP dogfood of the web showcaseflutter-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:

TierProvesCannot 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 toolkitanything 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 neededreal-hand comfort, camera noise, latency feel
Live camera trial (a human hand)the real sensor story: detection robustness, comfort, fatiguerepeatability — 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.enable missing, AX nodes resolving to TEXT nodes, callFunctionOn this rebinding) — fixed in universal_browser_cdp and guarded by the opt-in live fixture (XS_TEST_CDP_LIVE=1 in the cdp package).
  • Locate by text/aria-label in the LIVE flt-semantics DOM; 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; WebBuildTarget defaults 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).

TargetWhenNotes
FlutterRunTargetYou 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 / WindowsAppTargetFresh 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.attachOnlyThe 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 appConstruct 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's finally.
  • HarnessContext.bag passes 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) → a ToolkitDriver over the app's VM service. snapshot() → the semantic AxNode tree (label, role, bounds, and the selectable-text value — 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.
  • WidgetDriver was removed (ADR-0019) — one driver per wire; do not reintroduce per-package driver shells.
  • VmClient extras: extensionNames() (discoverability), evaluate(expr), hotReload(), callExtensionUntil(...) (folds the -32601-before-registration window, the isolate rebind, and the dropped-socket reconnect). Raw reloadSources cannot compile without an owning flutter run/attach session — treat true as "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 (or make-less dart run packages/harness/tool/showcase.dart --web --detach) spawns headless-ish, waits for the ws:// VM URI in .showcase/web_app.log, prints WS_URI=…, exits 0 — the CI-friendly variant.
  • Artifacts under .showcase/: flutter_app.log / web_app.log (teed output) and flutter.pid / web_flutter.pid pid 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-uri pins one) and the IntentCall CLI from INTENTCALL_ROOT, sibling checkouts, or PATH.
  • Interactive mode tees every line to the log (which make exec-sweep greps) 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. ToolkitExtensions mirrors mcp_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_harness experiment (ADR-0012) is retired (ADR-0017). Composition roots are consuming-project code (see example/).
  • 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 extensions
  • flutter-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 lanes
  • packages/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 findScan fieldExample value
By semantics identifieridentifier"nav.tasks"
By visible label / textlabel"Login"
By value or hintvalue / hint"user@example.com"
By semantic roletype"button"
By what it acceptsactions["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 AgentCallEntry or mcpToolkitTool / mcpToolkitResource. See flutter-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

NeedUse
One-off read of a simple valuefmt_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 operationAgentCallEntry.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.arguments on 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},
  ),
),
  • name must be snake_case. Published resource URIs follow visual://localhost/... conventions; agents use fmt_client_resource and listings from fmt_list_client_tools_and_resources.

Schema rules (tools)

The MCP server enforces strict JSON Schema:

  • Prefer additionalProperties: false unless you intentionally accept arbitrary keys.
  • Mark required for anything the handler reads unconditionally.
  • AgentResult.data / MCPCallResult.parameters must be JSON-serializable.

Discovery from the agent side

  1. fmt_list_client_tools_and_resources — enumerate app-registered tools and resources.
  2. fmt_client_tool — invoke a dynamic tool by name with JSON args.
  3. 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 + addEntries from widget code → duplicate registrations. Register once in main() / 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 called app_identity is one of the collisions above.

When the agent authors surfaces for the user’s app

  1. Ensure mcp_toolkit is in pubspec.yaml.
  2. Add lib/mcp_tools/<domain>_surfaces.dart returning Set<AgentCallEntry> or calling addEntries once.
  3. Wire from addEntries(...) before bootstrapFlutter(...) — never from StatefulWidget lifecycle.
  4. Tight schemas; hot restart; then fmt_list_client_tools_and_resources before 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 AgentArguments with Map<String, String> — pick one API (native vs mcpToolkitTool).
  • Missing await on addEntries → race before discovery.
  • inputSchema out of sync with the handler → agents trust the schema; update both.

Related

  • flutter-mcp-toolkit-intentcall-migration — CLI migrator, breaking upgrade
  • flutter-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 control action (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 via AgentRegistry on the host.
  • App-registered surfaces appear after MCPToolkitBinding.addEntries / AgentCallEntry — discover with fmt_list_client_tools_and_resources, then fmt_client_tool / fmt_client_resource.

Triage flow

  1. Error envelope returned? Read error.code first, then error.descriptor.retryable. Look the code up in the Error envelope playbook below.
  2. Retryable error? Run flutter-mcp-toolkit doctor --json. If doctor fails, load flutter-mcp-toolkit-setup.
  3. Need log output? Call get_recent_logs with count: 100 and a level filter. Look for stack traces or assertion messages near the timestamp of the failure.
  4. Need live state? Call evaluate_dart_expression with a targeted expression (e.g. MyBloc.instance.state.toString()). Do this after logs, not instead of them.
  5. 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.
  6. Multiple targets? If connection_selection_required, call discover_debug_apps, pick the targetId, then pass connection: {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):

  1. Call discover_debug_apps() — read targets[*].targetId for each running app.
  2. Identify the target by port or hostname.
  3. Call connect_debug_app(connection: {targetId: "ws://127.0.0.1:<port>/<token>/ws"}) to pin the session.
  4. Pass the same connection object 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:

  1. flutter-mcp-toolkit doctor --json
  2. 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:

  1. flutter-mcp-toolkit exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}'
  2. Get the exact URI from app.debugPort.wsUri in Flutter output.

vmNotConnected (vm_not_connected)

Means: a VM-dependent command was called before a connection was established. Recovery:

  1. flutter-mcp-toolkit exec --name status --args '{}'
  2. 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:

  1. flutter-mcp-toolkit exec --name discover_debug_apps --args '{}'
  2. Pick the correct targetId from details.availableTargets.
  3. 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:

  1. flutter-mcp-toolkit exec --name get_app_errors --args '{}'
  2. 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:

  1. flutter-mcp-toolkit doctor --json — check visual_capture_permission_denied separately.
  2. Check captureHints on get_view_details or screenshot payloads. Strong signals (platformViewsDetected): UiKitView, AppKitView, AndroidView, HtmlElementView — use desktop_window or auto (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): Texture only — prefer desktop_window on macOS host but auto does not upgrade. WGPU/custom engines without platform views: set MCPToolkitBinding.captureHintsContributor in the app. Image-only get_screenshots tools also return routing JSON in meta and a leading text block. Showcase: make showcase-stop then make showcase (macOS AppKitView) or flutter run -d chrome (web HtmlElementView + CDP capture).
  3. Run focus_window (MCP: fmt_focus_window) then retry get_screenshots with mode: desktop_window.
  4. For validate-runtime, executor recovery retries focus+capture once (desktopCaptureRetried). If desktop_window still fails, validate-runtime retries once with flutter_layer even when platform views are detected. Read capturePlatformViewsDetected, captureFocusAttempted, and captureFallbackUsed in data.summary.

visualCapturePermissionDenied (visual_capture_permission_denied)

Means: macOS Screen Recording permission is not granted. Recovery:

  1. flutter-mcp-toolkit permissions request --kind visual_capture
  2. 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:

  1. evaluate_dart_expression(expression: "true") — verify app is reachable.
  2. 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:

  1. Read error.details.hint — a refusal names its own cause and next step, and that hint is what error.recovery.summary carries.
  2. 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:

  1. semantic_snapshot() — verify the expected widget state.
  2. Increase timeoutMs or 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.

DimensionWeight
connectivity20
schema_validity10
handler_correctness20
capture_quality10
visual_fidelity10
webmcp_parity10
intentcall_authoring10
docs_truth10

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: updates maintainers/evidence/dogfood/dogfood_web_eval.yaml (yq or dart run mcp_server_dart/tool/merge_dogfood_tracker.dart)

Verdicts

VerdictMeaning
passscore ≥80, no blocking warnings
pass_with_warningsscore ≥80, e.g. visual_capture_truth_mode
failscore <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 accepts fmt_* aliases
  • MCP: fmt_ prefix (fmt_get_recent_logs, fmt_client_tool + listing name)
  • Connection: global --vm-service-uri (not exec --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 (external flutter_harness) is retired, so the visual evidence is paused, not regenerable
  • validate-runtime --save-images can hang >5m on Chrome; battery omits it unless DOGFOOD_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

  1. Diff dimension_scores vs previous iteration in tracker.
  2. Add to recurring_warnings / recurring_errors when repeated.
  3. Update fix_recommendations with actionable doc/code deltas.
  4. Do not treat tracker YAML as gate without a fresh battery run.

Related skills

  • flutter-mcp-toolkit-maintain-web — WebMCP launch + verify
  • flutter-mcp-toolkit-maintain-macos — macOS showcase
  • flutter-mcp-toolkit-repo-maintainer — make sync-skills after 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" and error.code: "binary_not_found" — load flutter-mcp-toolkit-setup and follow its install instructions.
  • status: "error" and error.code: "vm_not_connected" — load flutter-mcp-toolkit-setup and follow its troubleshooting section.
  • Any other error — load flutter-mcp-toolkit-debug and read the error envelope playbook.

Step 2: Pick the right skill for the user's intent

User intentLoad 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 APIsflutter-mcp-toolkit-intentcall-migration
Audit CLI/MCP/schema/dynamic-registry parity before changing tool surfacesflutter-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 hooksflutter-mcp-toolkit-maintain-macos
Score dogfood iterations or route dogfood evidenceflutter-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 sessionsflutter-mcp-automation-chain
Release, version, or plugin skill bundle maintenanceflutter-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, then fmt_client_tool / fmt_client_resource. When shelling out to the CLI, command names appear only as exec --name <name> values; do not call bare list_client_tools_and_resources, client_tool, or client_resource as MCP tools. → flutter-mcp-toolkit-custom-tools.
  • Boundary/proof maintenance: use flutter-mcp-boundary-audit before changing catalog/schema/registry surfaces; use flutter-mcp-toolkit-maintain-web or flutter-mcp-toolkit-maintain-macos for showcase platform hooks; use flutter-mcp-toolkit-repo-maintainer for release, version, and generated skill-bundle work.
  • True WebMCP (browser): with Chrome DevTools MCP (--categoryExperimentalWebmcp), use list_webmcp_tools / execute_webmcp_tool after navigating to the web app. Details in flutter-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

  1. Call semantic_snapshot().
  2. Read interactionSurface: flutter_widgets (tap-by-ref works), hybrid (sparse semantics), game_canvas (use evaluate_dart_expression + screenshots).
  3. Each interactive node has a stable ref (s_0, s_1, …) and the response includes a snapshot_id.
  4. Pass refs to interaction tools; pass the snapshot_id value as snapshotId to detect staleness.

After a code edit

Prefer hot_reload_and_capture over separate reload + snapshot + screenshot calls.

Find an error by message

  1. Call get_app_errors(count: 10).
  2. Inspect the errors array — each entry has message, stack trace, and timestamp.
  3. Match on message text to find the source.

List debug-mode apps

  1. Call discover_debug_apps().
  2. Read the targetId (canonical WebSocket URI) for each active target.
  3. Pass the chosen URI as connection.targetId on subsequent tool calls.

Get widget at coordinates

  1. Call inspect_widget_at_point(x: 200, y: 400).
  2. The response identifies the deepest widget and render node at those global logical pixel coordinates.

Save a screenshot to a file

  1. Call get_screenshots().
  2. If meta.fileUrls is non-empty, screenshots are on disk at those paths. Otherwise the response contains base64 ImageContent blocks — extract and write manually.
  3. 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; run make 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; supply connection.targetId.

get_screenshots

Capture screenshots of all views.

  • compress (boolean, optional, default: true) — compress PNG output.
  • mode (string, optional, default: auto) — auto, flutter_layer, or desktop_window.
  • permissionPolicy (string, optional, default: check_only) — check_only, auto_request_once, or request_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 with permissionPolicy: "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; supply connection.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; ref is 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 — subtreeOf is neither a ref of the latest snapshot nor an identifier in the tree; no snapshot was taken, refs and snapshot_id are unchanged.
  • unknown_field — a name in fields is not a node key; acceptedFields lists them. Over MCP and the CLI the name is refused at the boundary instead — an invalid fields argument naming the accepted keys, without spending a call on the app.
  • vm_service_unavailable — app not running or MCPToolkitBinding.initialize() not called.
  • connection_selection_required — multiple targets; supply connection.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, or desktop_window.
  • permissionPolicy (string, optional, default: check_only) — check_only, auto_request_once, or request_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 with permissionPolicy: "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) — pass connection.targetId with a WebSocket URI from discover_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-run discover_debug_apps for 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 analyze reports undefined MCPCallEntry after upgrading mcp_toolkit
  • User asks to migrate custom tools/resources to the new API
  • Before shipping a major mcp_toolkit bump 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: { ... }) before bootstrapFlutter(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)

  1. flutter-mcp-toolkit migrate agent-entries --check on showcase/flutter_test_app/lib
  2. make sync-skills after any plugin/skills/ edit
  3. cd mcp_server_dart && dart test test/contract/
  4. Grep: no MCPCallEntry in skills except this file's BEFORE examples

Hosted IntentCall packages

IntentCall now lives outside this repository. Normal consumer state uses hosted intentcall_* packages.

  1. Use hosted intentcall_*: ^0.6.0 dependencies for committed consumer state.
  2. Use local path overrides only for deliberate cross-repo development against a local IntentCall checkout.
  3. Run flutter pub get and migrate agent-entries --check again after dependency changes.
  4. CI: use make check-intentcall-hosted-consumer for hosted mcp_flutter proof; use make check-intentcall-sibling-matrix only for deliberate local IntentCall checkout matrix proof. The historical make check-intentcall-integration target is a compatibility alias for the sibling-matrix lane, not a fresh-adopter hosted gate.

Related skills

  • flutter-mcp-toolkit-custom-tools — authoring AgentCallEntry surfaces
  • flutter-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:…/ws from 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
TargetRole
macos/intentcall_codegen.shXcode Run Script → codegen sync --platform macos
macos/Runner.xcodeprojRun Script phase (see script comment if manual)
lib/main.dartIntentCallInvokeLinkListener 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, extensions
  • flutter-mcp-toolkit-maintain-web — WebMCP enablement
  • flutter-mcp-toolkit-dogfood-iterations — rubric + tracker
  • flutter-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

PathProves
VM extensions + fmt_* toolsMCP toolkit dogfood (always)
navigator.modelContext / document.modelContextTrue 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 so chrome://flags survive 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

  1. App must serve (e.g. make web-showcase or VS Code Chrome + WebMCP on :8080).
  2. list_pages — chrome-devtools may start its own browser (about:blank).
  3. navigate_page → http://localhost:8080/ (or your app URL).
  4. Wait for Flutter/Dart bootstrap (first list_webmcp_tools can be empty).
  5. list_webmcp_tools — expect IntentCall tools + often mcp_* toolkit tools registered on modelContext.
  6. execute_webmcp_tool with toolName + JSON-string input when 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
ArtifactSource
web/intentcall_webmcp.generated.jscodegen sync from web/agent_manifest.json
web/index.htmlinit intentcall-platform script tag
Dart bootstrapprojection 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

  1. Duplicate tool name — generated JS + the WebMCP projection (projectEntriesToWebMcp) both call registerTool; dedupe or gate one path (agent_web_mcp_bootstrap_web.dart name cache).
  2. CDP probe — webmcp verify may report webmcp_active_log_evidence while CDP hasModelContext is false (Flutter execution context).
  3. Stale WS_URI — always grep fresh token after hot restart before eval/validate.
  4. Empty WebMCP list right after navigate — wait until Dart hook / registration finishes, then list again.
  5. Temp Chrome profile — without --user-data-dir, Flutter wipes chrome://flags every stop/start.
  6. 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.md
  • flutter-mcp-cli-runtime-validation — validate-runtime details
  • flutter-mcp-toolkit-dogfood-iterations — scored iterations
  • flutter-mcp-e2e-harness — programmatic scenarios over this showcase (packages/harness, --web --detach variant)
  • 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.yml binaries, or install.sh version pins

Version touchpoints (must match root VERSION)

FileField
VERSIONrepo pin
plugin/EXPECTED_SERVER_VERSIONinstaller pin
packages/core/lib/src/runtime_version.dartkFlutterMcpVersion (x-release-please-version)
packages/server_capability_core/lib/src/fmt_capability.dartversion getter
mcp_server_dart/pubspec.yamlversion:
mcp_toolkit/pubspec.yamlversion:
packages/core/pubspec.yamlversion:
packages/server_capability_kernel/pubspec.yamlversion: + same-train dependency constraints
packages/server_capability_core/pubspec.yamlversion: + same-train dependency constraints
plugin/.cursor-plugin/plugin.jsonversion
plugin/.codex-plugin/plugin.jsonversion
plugin/.claude-plugin/plugin.jsonversion
.claude-plugin/marketplace.jsonplugins[0].version
.release-please-manifest.json"." key
mcp_server_dart/lib/src/skill_assets.g.dartgenerated — 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

  1. Add user-facing notes under ## [Unreleased] in CHANGELOG.md (Keep a Changelog sections: Added, Changed, Fixed, Documentation).
  2. Use conventional commit titles on main (feat:, fix:, docs:) so release-please can aggregate.
  3. 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 in make 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]
  1. Merge PRs to main with conventional commits.
  2. Wait for Release PR from release-please.yml.
  3. version train: release_pr_sync_versions.yml runs tool/release/sync_version.sh on Release PRs and commits any drift from root VERSION.
  4. skill assets: release_pr_sync_skills.yml auto-commits skill_assets.g.dart on Release PRs when drift is detected; posts a checklist comment on PR open. If skill-assets-drift still fails, run make sync-skills locally and push.
  5. Review VERSION, CHANGELOG, pubspecs, plugin pins in that PR → merge.
  6. release-please creates vX.Y.Z + GitHub release notes.
  7. release.yml asserts tag == VERSION, then attaches flutter_mcp_* tarballs (does not overwrite release body).
  8. 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:

  1. Move ## [Unreleased] bullets into ## [X.Y.Z] (add date), leave empty ## [Unreleased].
  2. Update VERSION to X.Y.Z.
  3. make sync-version to derive all version touchpoints and .release-please-manifest.json.
  4. make sync-skills (required whenever plugin manifests or skills change).
  5. make check-contracts
  6. Commit: chore: release X.Y.Z
  7. Optional pub.dev preflight: make publish-pub-dry-run.
  8. Tag: git tag vX.Y.Z and 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)

TopicCanonical doc
End-user agent installdocs/install/clients.mdx
npx skills + lockfileclients.mdx § skills; .skills.json.example
Contributor / releasesdocs/contributing/guide.mdx
Plugin layoutplugin/README.md
Marketplace copy SSOTplugin/assets/marketplace_copy.yaml
Distribution / storesdocs/install/clients.mdx
Store submission runbookdocs/contributing/marketplace_submission_runbook.mdx
Skill bodiesplugin/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 root skills/ → symlink for npx skills).
  • New bundled skill: add plugin/skills/<id>/SKILL.md, append id to expectedSkillIds in build_skill_assets.dart, run make sync-skills.
  • Local Cursor copy: .cursor/skills/<id>/ may symlink to plugin/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:

  1. Append flutter-mcp-toolkit-intentcall-migration to expectedSkillIds in build_skill_assets.dart if not already present.
  2. make sync-skills — commit skill_assets.g.dart with skill edits.
  3. bash tool/contracts/check_intentcall_skills_grep.sh — no legacy call-entry symbol outside migration skill.
  4. cd mcp_server_dart && dart test test/contract/
  5. flutter-mcp-toolkit migrate agent-entries --check showcase/flutter_test_app/lib (expect exit 0)
  6. 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-skills if plugin/skills/ or plugin/*-plugin/plugin.json changed
  • CHANGELOG [Unreleased] updated for user-visible changes
  • No secrets in committed configs

When to use

Use this skill when:

  • First-time install: flutter-mcp-toolkit or its short alias fmtk is not yet on PATH.
  • doctor --json returns 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.

SubcommandPurposeMinimal example
execRun a single named command against the VMfmtk exec --name get_vm --args '{}'
batchRun multiple commands in one callfmtk batch --steps '[{"name":"get_vm"},{"name":"status"}]'
schemaPrint the JSON schema for a named commandfmtk schema --name hot_reload_flutter
capabilitiesList all registered capabilitiesfmtk capabilities
serveStart the MCP server (stdio transport)fmtk serve
snapshot createCapture and save a named snapshotfmtk snapshot create --name baseline --args '{}'
snapshot diffDiff two snapshotsfmtk snapshot diff --from baseline --to current
bundle createPackage a snapshot into a publishable bundlefmtk bundle create --from-snapshot baseline --output ./out
doctorRun preflight checks (VM + toolkit + registry)fmtk doctor --json
permissions statusCheck a permission (e.g. visual_capture)fmtk permissions status --kind visual_capture
permissions requestRequest a permissionfmtk permissions request --kind visual_capture
permissions open-settingsOpen OS settings for a permissionfmtk permissions open-settings --kind visual_capture
validate-runtimeEnd-to-end VM + toolkit + capture smoke testfmtk validate-runtime --target ws://127.0.0.1:8181/<token>/ws
init <agent>Install skills + MCP server config for an AI agentflutter-mcp-toolkit init claude-code
codegen-initAdd toolkit dependency and emit main.dart boilerplateflutter-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:

  1. Ensure the app is running in debug mode with mcp_toolkit bootstrap (see flutter-mcp-toolkit codegen-init).
  2. Call fmt_discover_debug_apps or fmt_connect_debug_app (use connection.uri when multiple targets exist).
  3. Optionally run fmt_get_extension_rpcs to confirm ext.mcp.toolkit.* extensions exist.

Core loop

  1. fmt_semantic_snapshot — read UI structure and refs.
  2. fmt_tap_widget / fmt_enter_text / fmt_scroll — act on refs from the snapshot.
  3. fmt_hot_reload_flutter or fmt_hot_reload_and_capture — apply code changes.
  4. fmt_wait_for with {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

  1. Preflight before any VM call. Run doctor first. If critical checks fail, stop and report — don't guess at state from an unreachable app.

  2. 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 (add mcp_toolkit, initialize in main(), hot restart). Do not continue app-level inspection.

  3. Always pass snapshotId on fmt_tap_widget / fmt_enter_text / fmt_scroll / fmt_swipe / fmt_long_press / fmt_drag. A structured stale_snapshot error is far better than a silent wrong tap. On stale, re-snapshot and retry.

  4. Use fmt_hot_reload_and_capture after code edits — single call returning reload status + screenshot + fresh snapshot + errors. Beats manual reload + separate capture.

  5. 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_point output.

  6. Error envelope. Parse error.descriptor, not the top-level. Common codes: connection_selection_required (retry with exact arguments.connection.uri), target_not_found (refresh targets), stale_snapshot (re-snapshot), tool_not_found (use the fmt_* prefixed name).

  7. Map defects to source via fmt_get_app_errors top stack frame (file:line:col) before proposing a fix.

  8. Do not use fmt_debug_dump_* unless the server was started with --dumps and the user asked — high token cost.

  9. Non-modifiable apps: if mcp_toolkit can'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/during runApp). Not inside widget lifecycles.
  • Tight schema: additionalProperties: false, explicit required, enums over free strings.
  • Hot restart after adding — hot reload may not re-emit DTD registration events.
  • Confirm with fmt_list_client_tools_and_resources before calling.

When to hand back

  • User asks for non-runtime work (pure refactor, static analysis, docs).
  • mcp_toolkit cannot 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