flutter_maestro_mcp

# Flutter Maestro MCP Server Experimental Model Context Protocol (MCP) server that enables AI agents to interact with running Flutter applications via the VM Service and execute Maestro flows. Just for playing around with custom MCPs ## Prerequisites - **Maestro CLI**: Required for running Maestro flows with the `run_maestro_flow` tool. - Install via Homebrew: `brew install maestro` - Or follow the [official installation guide](https://maestro.mobile.dev/getting-started/installing-maestro) ## Installation 1. Clone this repository. 2. Run `dart pub get` to install dependencies. ## Configuration ### VS Code Add the following to your MCP settings file (typically `~/.vscode/mcp.json` or similar, depending on the extension): ```json { "servers": { "flutter-maestro": { "command": "dart", "args": [ "/absolute/path/to/flutter_maestro_mcp/bin/flutter_maestro_mcp.dart" ] } } } ``` **Note:** Replace `/absolute/path/to/flutter_maestro_mcp` with the actual path to your cloned repository. ## Testing with Example App This repository includes an example Flutter application instrumented with test hooks to verify the MCP server functionality. **Using VS Code (Recommended):** 1. Open the repository in VS Code. 2. Go to **Run and Debug** and select **"Flutter Example App"**. 3. Copy the VM Service URI from the Debug Console. **Using Command Line:** 1. Navigate to `example/`. 2. Run the app: `flutter run`. 3. Note the VM Service URI from the output (e.g., `ws://127.0.0.1:12345/ws`). **Once Running:** 1. Copy the complete VM Service URI from the Flutter app output 2. Use the `connect` tool with this URI 3. Try tools like `inspect_ui` and `tap` to interact with the running example app **Finding the VM Service URI:** The VM Service URI is printed when your Flutter app starts. You MUST copy the complete URI including the authentication token: - **VS Code Debug Console**: Search for "VM Service" or "Observatory" - **Flutter CLI output**: Look for "The Dart VM service is listening on ws://..." - **URI format**: `ws://127.0.0.1:PORT/AUTH_TOKEN/ws` - **Example**: `ws://127.0.0.1:59548/-ppep2G-MyI=/ws` ⚠️ **Important**: Auto-discovery is not supported. You must provide the complete URI with the authentication token. The token is only printed once at app startup and cannot be retrieved later. ## Available Tools - **`connect`**: Connect to a running Flutter app using its VM Service URI. - Arguments: `uri` (required - the complete VM Service WebSocket URI including auth token from your Flutter app output, e.g., `ws://127.0.0.1:59548/-ppep2G-MyI=/ws`) - **`disconnect`**: Disconnect from the current Flutter app. - **`inspect_ui`**: Get a simplified JSON representation of the current UI hierarchy (keys, text, semantics). - **`tap`**: Tap on a widget matching criteria. - Arguments: `key`, `text`, `tooltip`, `semantics` - **`enter_text`**: Enter text into a widget matching criteria. - Arguments: `input` (required), plus matcher arguments (`key`, `text`, etc.) - **`scroll_to`**: Scroll until a widget is visible. - Arguments: Matcher arguments (`key`, `text`, etc.) - **`take_screenshot`**: Take a screenshot of the current screen. - **`get_logs`**: Retrieve application logs. - **`hot_reload`**: Trigger a hot reload. - **`write_maestro_flow`**: Write a Maestro YAML flow to a file. - Arguments: `path`, `content` - **`run_maestro_flow`**: Run a Maestro YAML flow using `maestro test`. - Arguments: `path`