/flutter-mcp-automation-chain

name: flutter-mcp-automation-chain
description: Use this skill when wiring automation for a Flutter app — choosing the right surface (interactive MCP `fmt_*` tools, CLI one-shots, programmatic `flutter_mcp_harness` Dart scenarios, the browser CDP tier, or an external build+lifecycle runner like oka), composing the chain end-to-end, or integrating `oka` (`oka init`/`dev`/`run`, device targets, the runner-session contract, `driverForLiveSession`). Also use when the user asks which tier or mode to use, how to drive/build their app from Dart or CI without a chat round-trip, or how oka and flutter-mcp-toolkit fit together. For authoring repeatable scenarios inside this repo's showcase, use `flutter-mcp-e2e-harness`; for interactive debugging, use `flutter-mcp`.

<!-- @FMT_MODE_PRELUDE -->

Flutter MCP Automation Chain

The toolkit's surfaces are **one chain, not competing products**. The app registers `ext.mcp.toolkit.*` service extensions (`mcp_toolkit`), and every surface drives those same extensions through the universal `AutomationDriver` contract (`universal_automation_interface`, ADR-0038): **observe** (semantic snapshot with refs/bounds) → **act** (tap/type/navigate) → **verify** (snapshot again, read values). Agents learn one grammar regardless of the target — Flutter apps, browsers (`CdpDriver`), OS-native tiers.

 intentcall hints (MCP _meta)                     declarative build + lifecycle
        │                                         (oka: oka.yaml → targets)
        ▼                                                │
 ┌──────────────┐   transport over ext.mcp.toolkit.*   ▼
 │ MCP fmt_*    │ ◄── the same extensions ──►  flutter_mcp_harness
 │ CLI (fmtk)   │      (ToolkitDriver implements      Scenario / AppTargets /
 │ dynamic      │       AutomationDriver)             VmClient / LogTap
 │ app tools    │
 └──────────────┘ ◄── universal_automation_* contracts ──► CdpDriver (web)

The one ownership law

**At most one owning attach session per app.** The owning session (a `flutter run`, or an external runner's `dev` command like `oka dev`) is the only compile-capable reload channel — a second attach on a session someone else owns is the ADR-0014 failure mode (the second attach can kill the first). Everything else in the chain is an **observer**: it reads the same VM service and drives extensions, but never takes ownership. When an external runner owns the session, it writes `.flutter_mcp/runner-session.json` (spec v2, ADR-0014) so the toolkit and harness can find the VM and delegate reload/restart to the owner. Absence of the file is the liveness signal.

Pick the surface

| Need | Surface | Skill / doc | |---|---|---| | Chat-driven debugging ("tap X, what changed?") | MCP `fmt_*` tools | `flutter-mcp` | | Script/CI one-shot commands (snapshot, exec, batch) | CLI (`flutter-mcp-toolkit` / `fmtk`) | [CLI vs MCP](/start_here/cli_vs_mcp) | | Repeatable scenario as checked-in Dart, CI exit codes | `flutter_mcp_harness` | `flutter-mcp-e2e-harness` | | Build + install + launch + process lifecycle (Android/iOS devices) | **oka** (separate repo) | this skill, oka section below | | Browser tier (web demos, WebMCP dogfood) | `CdpDriver` over CDP | `flutter-mcp-toolkit-maintain-web` | | Intent → driver routing without hardcoding transport | `IntentDriverRouter` + hints | this skill, intentcall section |

First loop: interactive MCP (five minutes)

curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash
cd my-flutter-app
flutter-mcp-toolkit codegen-init        # adds mcp_toolkit + emits main.dart snippet
flutter-mcp-toolkit init claude-code    # or: cursor | codex | cline | all
flutter run --debug

The agent now inspects, taps, types, hot-reloads, and reads logs over MCP. This is the fastest path and needs nothing else on this page.

Second loop: own the lifecycle in Dart

For CI or test batteries that must not depend on a chat session, add the published harness to your project and compose a scenario:

# pubspec.yaml (hosted package)
dependencies:
  flutter_mcp_harness: ^0.1.0

final app = await MacosAppTarget(projectDir: '.', binaryPath: binary).launch();
final driver = ToolkitDriver(await app.vm());
final ref = await driver.findRef('login');      // snapshot refs are stable ids
// …perform click/type, re-snapshot, read values…
await app.stop();                                // scenarios stop what they started

Desktop targets (`FlutterRunTarget`, `BinaryAppTarget`, `MacosAppTarget`, `WindowsAppTarget`, `ChromeAppTarget`), `Scenario` anatomy, and the in-repo showcase launcher are covered step-by-step in `flutter-mcp-e2e-harness` — read it before writing your first scenario.

Third loop: device builds + lifecycle via oka

oka (separate repo, `dart pub global activate oka`) owns **build + process lifecycle** so the toolkit can stay the observation oracle. You do **not** need oka unless you want declarative, no-Gradle device builds and owned dev sessions.

oka init            # scaffolds tool/oka_pipeline.dart — project-owned targets
oka build apk       # no-Gradle Android pipeline, cached artifacts
oka run device      # install → launch → failure-signature scan
oka dev             # owning dev session; agents: oka dev --watch --json (JSON events + stdin control)

Consuming projects compose `oka_harness` (which depends on the published `flutter_mcp_harness`) instead of shelling out:

• `AndroidAppTarget` / `IosSimulatorAppTarget` — launch device/simulator apps

with the 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/res