Skip to main content
Glama

At a glance

Fact

Value

Package

tapir

Install

flutter pub add tapir, then dart run tapir tapir:install

Import

package:tapir/tapir.dart (TapirPlugin.install(), behind if (!kReleaseMode))

Entry points

dart run tapir <command>, ./bin/dowel <command>, TapirPlugin.install(), TapirPlugin.enrichers, TapirDowelProvider (package:tapir/cli.dart), dart run tapir mcp:serve

Platforms

Any Flutter target that exposes a VM Service in a debug or profile build: Android, iOS, web, macOS, Windows, Linux; viewport and device emulation need Chrome with a CDP port; tapir_hot_reload_and_snap writes to the flutter run stdin FIFO, so it needs a POSIX host; on a Windows host mcp:install writes a dart run entry, never ./bin/dowel

Requires

Dart 3.13, Flutter 3.47; a plugin of dowel (^1.0.5)

Dependencies

dowel, image, meta, wind_kit_diagnostics_contracts, yaml, the Flutter SDK

License

MIT

Related MCP server: Flutter Driver MCP

Install

flutter pub add tapir
dart run tapir tapir:install
dart run tapir start --device=macos   # dowel records the session every tapir:* command dials
dart run tapir tapir:snap

tapir:install patches lib/main.dart (the import, WidgetsFlutterBinding.ensureInitialized() when missing, and TapirPlugin.install() inside a !kReleaseMode guard), then scaffolds the fast ./bin/dowel wrapper and registers tapir as a dowel plugin. Re-running it changes nothing. The installation guide also adds dowel as a direct dependency (dart pub add dowel). Wired by hand, main.dart looks like this:

import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:tapir/tapir.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) {
    TapirPlugin.install();
  }
  runApp(const MyApp()); // MyApp is the host app's root widget.
}

The guard is !kReleaseMode, not kDebugMode: debug and profile builds carry tapir (tapir:perf_run measures a profile build) and a release build tree-shakes it. Without the guard tapir ships in release, and anyone who reaches that app's VM Service can drive it. --dart-define=TAPIR_DISABLE=1 skips registration in a build that must not expose the extensions. The example/ app gives each verb a live target widget.

Snapshot and refs

dart run tapir tapir:snap --interactiveOnly
# - textbox "Email" [ref=e1]
#   typeable: true
# - button "Sign in" [ref=e2]

Token

Minted by

Lifetime

e<N>

tapir:snap

The same Semantics node keeps its token across snapshots, and a token outlives its widget. A ref whose element left the tree is relocated by label (reresolved on the response) only when the snapshot recorded a binding for it, the live tree has the same number of nodes with that label and the match sits on the route the ref was minted on; otherwise it fails as defunct and you re-snap

q<N>

tapir:find, tapir:observe

Re-resolved against the live tree on every action; survives rebuilds

Narrow a read with --within=<eN>, --interactiveOnly and --grep=<regex>; they compose. --includeEnrichers adds Wind state under each W-widget that has a className: up to seven contract fields, of which bgColor and textColor appear only when they resolve (tapir:observe keeps only breakpoint and states unless you pass --includeEnrichers=full; the host calls Wind.installDebugResolver() from wind_kit, read through wind_kit_diagnostics_contracts) and Magic state (MagicTapirIntegration.install() from package:magic_devtools/tapir.dart, after Magic.init(); it exists only in a magic_devtools release built on tapir, and tapir:install warns and skips it otherwise; see Magic integration). A ref line ending in [offscreen] or [occluded] names why an action would fail before you try it.

Actions and the actionability gate

dart run tapir tapir:tap --ref=e2 --snapshot=diff
dart run tapir tapir:fill --ref=e1 --text="ada@example.com" --json

Gestures (tap, hover, drag, scroll, double_click, right_click, triple_click) and text verbs (type, clear, fill, press_key) dispatch real pointer and key events into the widget tree. tap, hover, drag, the click variants, type, fill and set_checkbox (on the control it taps) first pass the gate (clear, scroll, press_key and select_option skip it), in a fixed order, and a refusal names the reason an agent can branch on:

Check

Refusal substring

Recovery

Defunct (preflight)

defunct (...)

Re-snap

Enabled

not enabled

Re-snap; the widget may enable later

Zero rect

zero rect

Re-snap or re-find

Off-viewport (scrolls into view first)

off-viewport

tapir:scroll into view, then retry

Stable across two frames

not stable

Wait for the animation; --no-checkStable

Receives events (hit test)

obscured by

Dismiss the overlay (tapir:reset_overlays); --no-checkReceivesEvents

A green tick is dispatch, not effect. Add --json to print the whole response and read the effect block: effect.changed for tap and scroll, effect.verified and effect.value for type, fill and clear. When the hit test could not answer (routine on a web debug build) the response of a gated verb such as tap, type or fill carries a checks block with receivesEvents: indeterminate instead of a silent pass. A target tapir will not act on at all (a ref that is not a text field, say) answers the error type refused (code -32001), and a value it cannot use answers invalid_param. tapir:run "tap --ref=e5" "snap --grep Counter" batches verbs into one round trip.

Waiting and observing

dart run tapir tapir:observe --roles=button,textbox   # q<N> handles, re-resolved per action
dart run tapir tapir:wait_for --text="Welcome back" --timeoutMs=5000

Verb

Returns

tapir:wait_for

Waits for --text, --textGone or --expression

tapir:wait_for_network_idle

Waits until in-flight HTTP requests stay at zero for --idleMs

tapir:observe

A flat candidate list of interactive widgets with q<N> handles: observe once, act many times (no model call inside tapir)

tapir:console, tapir:exceptions

In-app debugPrint output and FlutterErrors, overflow included; --since=<iso8601> scopes errors to one action; --grep and --logger narrow the console buffer

tapir:get_routes

The router's location and the top page (tapir:navigate and tapir:navigate_back change it)

When the app is not producing frames (a hidden window or a backgrounded tab) tapir forces frames outside the web and reports framesForced: true; where it cannot, every response carries a warnings block rather than a stale answer that looks fresh. See frame production.

Screenshots and web

dart run tapir tapir:screenshot --output=shot.jpg
dart run tapir start --device=chrome --cdp-port=9333
dart run tapir tapir:device_profile --preset=pixel-8

Surface

Behaviour

tapir:screenshot

JPEG (default) or PNG of the viewport, or of one widget with --ref (and a sub-rect of it with --rect); --strict exits 1 without writing the file when the app is not producing frames (on a web session it covers --ref captures only)

Web screenshot

With --cdp-port, the CLI captures through CDP Page.captureScreenshot; the tapir_screenshot MCP tool stays in-isolate and can time out under CanvasKit, so prefer the CLI on web; a --cdp-port session cannot run tapir_evaluate (the web-server device has no evaluate)

tapir:device_profile

Presets iphone-x, iphone-13, iphone-15-pro, pixel-5, pixel-8, ipad-pro-12.9, desktop-1440, desktop-1920 (viewport, DPR, touch, user agent); the emulation ends with the command, the window size stays. tapir:resize_viewport --width --height overrides the viewport until exit, or longer with --hold

tapir:hot_reload_and_snap

Hot reload, then snapshot, screenshot and recent exceptions in one round trip

Performance tracing

dart run tapir tapir:perf_begin --mode=attribution
dart run tapir tapir:tap --ref=e7
dart run tapir tapir:perf_end

Verb

Does

tapir:perf_begin, tapir:perf_end

Bracket one interaction; attribution ranks the widget builds that cost time next to Wind and Magic counters, timing reports frame timings you can quote. A session in which the engine rendered nothing is refused (refused: true, exit 1), never reported as zeros that read as fast

tapir:perf_insight

The rows behind one insight of the last report

tapir:perf_run, tapir:perf_compare, tapir:perf_campaign

Repeat a scenario from a clean start and write medians, judge one run against another, run a campaign of scenarios from cold starts

tapir:perf_trace --out=trace.json

The last session as a Chrome Trace JSON for ui.perfetto.dev

MCP server and clients

The tapir_* tools ride on the dowel MCP server, so the client config key is dowel. dart run tapir mcp:install writes the entry into .mcp.json: ./bin/dowel mcp:serve when the fast wrapper exists on a POSIX host, and dart run tapir mcp:serve otherwise (always on Windows, where ./bin/dowel is not used). Standard config for any client that reads .mcp.json:

{ "mcpServers": { "dowel": { "command": "./bin/dowel", "args": ["mcp:serve"], "cwd": "." } } }

Client

Install

Claude Code

claude mcp add dowel -- ./bin/dowel mcp:serve, then /mcp reconnect dowel after a change

VS Code

code --add-mcp '{"name":"dowel","type":"stdio","command":"dart","args":["run","tapir","mcp:serve"]}'

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (user)

Windsurf

~/.codeium/windsurf/mcp_config.json

Goose, Warp

Paste the standard config into Goose (Advanced settings, Extensions, Add custom extension) or Warp (Settings, AI, Manage MCP Servers)

Claude Desktop

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)

Codex

codex mcp add dowel ./bin/dowel mcp:serve

Without tapir you hot reload, take a screenshot, drag the PNG into the chat, paste the widget source and ask why the button does nothing. With it the agent calls tapir_snap, then tapir_tap on e7: the gate checks the button, the tap lands and a fresh snap confirms it. A timing issue no longer needs a Future.delayed and a re-run to tell it from a bug, because the gate refuses with a reason that names the cause (not stable, obscured by, off-viewport).

For AI coding agents

Do

Because

Install tapir only behind if (!kReleaseMode)

Anyone who reaches the VM Service of a build that carries tapir can drive the app

Start the app with dart run tapir start, not flutter run

Every tapir:* command dials the session dowel records

Snap again after a navigation or rebuild, or use a q<N> handle from tapir:find

e<N> refs are frozen to the snapshot that minted them

Narrow a snapshot with --within, --interactiveOnly or --grep

A full tree costs context, and a sidebar that repeats page labels misleads an exact-label lookup

Read effect (and checks when present) before trusting a green tick

A tick says the event left tapir, not that the widget took it

Branch on the leading refusal substring, never on the trailing detail

The substrings and the gate order are a frozen contract; the detail is not

Read framesForced and warnings on a response that looks empty

A hidden window or tab stops frames, and the tree then reads as a broken screen

Check refused first on a tapir:perf_end report

A refused session carries no metrics

Point the MCP client at the dowel key and reconnect after mcp:install

The tools ride on the dowel server, and clients do not reload an entry on their own

Dependencies

dowel for the CLI, the MCP server and the VM Service connection; wind_kit_diagnostics_contracts to read Wind state without depending on Wind; image for screenshot encoding; yaml and meta. The rest is the Flutter SDK.

License

MIT, see LICENSE. Built by Anılcan Çakır.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that lets AI agents see, tap, type, scroll, and assert inside live Flutter apps — no pre-written tests required.
      28
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes a stdio JSON-RPC tool surface that lets AI agents control running Flutter and Dart apps — starting, stopping, reloading, and hot-restarting sessions, reading logs, running doctor/list/tinker checks, and invoking plugin-contributed tools. It gives agents one shared protocol instead of ad hoc shell scripts.
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to automate Android and iOS devices, including emulators and physical devices, by capturing screenshots, reading UI accessibility trees, performing touch and text input, and managing app lifecycle and logs.
      18
      4
      MIT