From 8f9b9c6c794cf7254cfb9c0c91bf4cb9fe0af72e Mon Sep 17 00:00:00 2001 From: Ortes Date: Wed, 25 Mar 2026 15:12:56 -0300 Subject: [PATCH 1/6] docs: add Flutter Driver example to MCP server page Add a third usage example showing how to connect to a running Flutter app and interact with its UI using Flutter Driver via the MCP server. --- sites/docs/src/content/ai/mcp-server.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/sites/docs/src/content/ai/mcp-server.md b/sites/docs/src/content/ai/mcp-server.md index 7495483c8ef..4036931cfac 100644 --- a/sites/docs/src/content/ai/mcp-server.md +++ b/sites/docs/src/content/ai/mcp-server.md @@ -392,6 +392,29 @@ is now a single request. [`package:fl_chart`]: {{site.pub-pkg}}/fl_chart +### Interact with a running app using Flutter Driver + +You can use the Dart and Flutter MCP server to connect to a running +Flutter app and interact with its UI—taking screenshots, tapping +buttons, entering text, and scrolling. + +Launch your app with `--print-dtd` and ask your AI assistant: + +> Connect to my running Flutter app using the DTD URI from the +> terminal output, then take a screenshot and tap "Sign In". + +The AI agent connects via the `dtd` tool, takes a screenshot with +`flutter_driver_command`, and taps the button—all without you +writing test code. + +:::note +Your app must call `enableFlutterDriverExtension()` before `runApp()` +for Flutter Driver commands to work. See the +[full setup guide][flutter-driver-guide] for details. +::: + +[flutter-driver-guide]: https://github.com/dart-lang/ai/blob/main/pkgs/dart_mcp_server/README.md#connect-to-a-running-flutter-app + ## Provide feedback If you encounter any issues or have feedback about the From 51aad899b6e705e33619511d86768f298e6a5cc4 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 6 May 2026 12:47:09 -0700 Subject: [PATCH 2/6] Update src/content/ai/mcp-server.md --- sites/docs/src/content/ai/mcp-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/content/ai/mcp-server.md b/sites/docs/src/content/ai/mcp-server.md index 4036931cfac..daea26ea1ee 100644 --- a/sites/docs/src/content/ai/mcp-server.md +++ b/sites/docs/src/content/ai/mcp-server.md @@ -403,7 +403,7 @@ Launch your app with `--print-dtd` and ask your AI assistant: > Connect to my running Flutter app using the DTD URI from the > terminal output, then take a screenshot and tap "Sign In". -The AI agent connects via the `dtd` tool, takes a screenshot with +The AI agent connects with the `dtd` tool, takes a screenshot with `flutter_driver_command`, and taps the button—all without you writing test code. From fe0798407860d2c2f8200ab29eac27710ca4cc59 Mon Sep 17 00:00:00 2001 From: Ortes Date: Thu, 7 May 2026 19:17:24 -0400 Subject: [PATCH 3/6] docs(mcp): drop --print-dtd, clarify web limitation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove --print-dtd from the launch command (auto-discovered via DDS in Flutter ≥3.27; flag no longer needed) - Add explicit web note: flutter_driver doesn't compile under dart2js, pair with a browser-driving MCP for UI actions - Trim wording to keep this section setup-oriented; full reference lives in dart-lang/ai --- sites/docs/src/content/ai/mcp-server.md | 35 ++++++++++++++++--------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/sites/docs/src/content/ai/mcp-server.md b/sites/docs/src/content/ai/mcp-server.md index daea26ea1ee..d72f5438187 100644 --- a/sites/docs/src/content/ai/mcp-server.md +++ b/sites/docs/src/content/ai/mcp-server.md @@ -392,25 +392,34 @@ is now a single request. [`package:fl_chart`]: {{site.pub-pkg}}/fl_chart -### Interact with a running app using Flutter Driver +### Interact with a running app -You can use the Dart and Flutter MCP server to connect to a running -Flutter app and interact with its UI—taking screenshots, tapping -buttons, entering text, and scrolling. +You can use the Dart and Flutter MCP server to drive a running +Flutter app from your AI assistant—take screenshots, tap buttons, +enter text, scroll, and hot reload. -Launch your app with `--print-dtd` and ask your AI assistant: +Launch your app and ask your assistant to connect: -> Connect to my running Flutter app using the DTD URI from the -> terminal output, then take a screenshot and tap "Sign In". +```bash +flutter run -d --dart-define=ENABLE_FLUTTER_DRIVER=true +``` + +> Connect to my running Flutter app, take a screenshot, then tap "Sign In". -The AI agent connects with the `dtd` tool, takes a screenshot with -`flutter_driver_command`, and taps the button—all without you -writing test code. +The agent uses the `dtd` tool to discover the app and `flutter_driver_command` +to drive its UI—no integration test setup required. :::note -Your app must call `enableFlutterDriverExtension()` before `runApp()` -for Flutter Driver commands to work. See the -[full setup guide][flutter-driver-guide] for details. +**Mobile (iOS, Android) and desktop**: gate +`enableFlutterDriverExtension()` behind a `--dart-define` flag so it stays +out of production builds. +**Web**: the `flutter_driver` package doesn't compile under dart2js. Pair +the Dart MCP server with a browser-driving MCP for clicks and screenshots; +the Dart MCP server still handles widget tree, runtime errors, and hot +reload through DTD. + +See the [setup guide][flutter-driver-guide] for the snippet, web modes, +and common pitfalls. ::: [flutter-driver-guide]: https://github.com/dart-lang/ai/blob/main/pkgs/dart_mcp_server/README.md#connect-to-a-running-flutter-app From 1d915a78f931cd52527e660683b574136b22393b Mon Sep 17 00:00:00 2001 From: Ortes Date: Thu, 7 May 2026 20:21:38 -0400 Subject: [PATCH 4/6] docs(mcp): prefer -d web-server for agent-driven web testing With `-d chrome`, only the Chrome window Flutter spawns receives hot reload patches; a second browser at the same URL renders the bundle but is invisible to dwds. Spell out the recommendation in the note block so readers don't hit the trap. --- sites/docs/src/content/ai/mcp-server.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sites/docs/src/content/ai/mcp-server.md b/sites/docs/src/content/ai/mcp-server.md index d72f5438187..efb71c8fd5e 100644 --- a/sites/docs/src/content/ai/mcp-server.md +++ b/sites/docs/src/content/ai/mcp-server.md @@ -416,7 +416,9 @@ out of production builds. **Web**: the `flutter_driver` package doesn't compile under dart2js. Pair the Dart MCP server with a browser-driving MCP for clicks and screenshots; the Dart MCP server still handles widget tree, runtime errors, and hot -reload through DTD. +reload through DTD. Prefer `flutter run -d web-server` so the browser the +agent drives is the one DTD is connected to — with `-d chrome`, only the +window Flutter spawned receives hot reload patches. See the [setup guide][flutter-driver-guide] for the snippet, web modes, and common pitfalls. From 4480de7f6e01085a26edbf33798d5f4b3c30a834 Mon Sep 17 00:00:00 2001 From: Ortes Date: Thu, 7 May 2026 20:26:36 -0400 Subject: [PATCH 5/6] Update src/content/ai/mcp-server.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- sites/docs/src/content/ai/mcp-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/content/ai/mcp-server.md b/sites/docs/src/content/ai/mcp-server.md index efb71c8fd5e..2319132402e 100644 --- a/sites/docs/src/content/ai/mcp-server.md +++ b/sites/docs/src/content/ai/mcp-server.md @@ -417,7 +417,7 @@ out of production builds. the Dart MCP server with a browser-driving MCP for clicks and screenshots; the Dart MCP server still handles widget tree, runtime errors, and hot reload through DTD. Prefer `flutter run -d web-server` so the browser the -agent drives is the one DTD is connected to — with `-d chrome`, only the +agent drives is the one DTD is connected to—with -d chrome, only the window Flutter spawned receives hot reload patches. See the [setup guide][flutter-driver-guide] for the snippet, web modes, From fd3acb7c49c8e58347626dd965fcb582b550749b Mon Sep 17 00:00:00 2001 From: Ortes Date: Thu, 7 May 2026 20:46:52 -0400 Subject: [PATCH 6/6] docs(mcp): show driver-extension setup before flag use Reorder the section so readers see the flag's origin before they hit it on the command line: gate enableFlutterDriverExtension() in main() first, launch with --dart-define second, then prompt the assistant. ENABLE_FLUTTER_DRIVER is a user-defined flag, not a Flutter built-in, so explaining it after the run command read backwards. --- sites/docs/src/content/ai/mcp-server.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/sites/docs/src/content/ai/mcp-server.md b/sites/docs/src/content/ai/mcp-server.md index 2319132402e..d489e64f4c3 100644 --- a/sites/docs/src/content/ai/mcp-server.md +++ b/sites/docs/src/content/ai/mcp-server.md @@ -398,21 +398,35 @@ You can use the Dart and Flutter MCP server to drive a running Flutter app from your AI assistant—take screenshots, tap buttons, enter text, scroll, and hot reload. -Launch your app and ask your assistant to connect: +On mobile and desktop, gate `enableFlutterDriverExtension()` behind a +`--dart-define` flag in your app's `main()` so it stays out of +production builds: + +```dart +import 'package:flutter_driver/driver_extension.dart'; + +void main() { + if (const bool.fromEnvironment('ENABLE_FLUTTER_DRIVER')) { + enableFlutterDriverExtension(); + } + runApp(const MyApp()); +} +``` + +Launch your app with the flag turned on: ```bash flutter run -d --dart-define=ENABLE_FLUTTER_DRIVER=true ``` +Then ask your assistant to connect: + > Connect to my running Flutter app, take a screenshot, then tap "Sign In". The agent uses the `dtd` tool to discover the app and `flutter_driver_command` to drive its UI—no integration test setup required. :::note -**Mobile (iOS, Android) and desktop**: gate -`enableFlutterDriverExtension()` behind a `--dart-define` flag so it stays -out of production builds. **Web**: the `flutter_driver` package doesn't compile under dart2js. Pair the Dart MCP server with a browser-driving MCP for clicks and screenshots; the Dart MCP server still handles widget tree, runtime errors, and hot