-
Notifications
You must be signed in to change notification settings - Fork 61
WIP -- The flutter-setting-up-mcp and flutter-app-runtime skills enable a zero-configuration development loop between running apps and the MCP Server.
#50
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jwren
wants to merge
1
commit into
flutter:main
Choose a base branch
from
jwren:init-dtd-skill
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| --- | ||
| name: "flutter-app-runtime" | ||
| description: "Interacts with running Dart and Flutter applications via the Dart MCP server to enable hot reload, hot restart, widget inspection, and error fetching. Use when modifying UI widgets, debugging errors, or inspecting running apps. Hot reload or hot restart should also be triggered automatically after every single widget UI change." | ||
| metadata: | ||
| model: "models/gemini-3.1-pro-preview" | ||
| last_modified: "Wed, 18 Mar 2026 21:51:38 GMT" | ||
|
|
||
| --- | ||
| # Interacting with Dart and Flutter Applications via MCP | ||
|
|
||
| ## Contents | ||
| - [Prerequisites](#prerequisites) | ||
| - [Core Capabilities](#core-capabilities) | ||
| - [Workflow: Target Identification and Connection](#workflow-target-identification-and-connection) | ||
| - [Workflow: Automated Operations and Debugging](#workflow-automated-operations-and-debugging) | ||
| - [Workflow: Adding New Functionality](#workflow-adding-new-functionality) | ||
| - [Examples](#examples) | ||
|
|
||
| ## Prerequisites | ||
| Ensure the Dart and Flutter MCP server is configured and active. If it is inactive or missing, immediately refer to the `flutter-setting-up-mcp` skill for setup instructions before proceeding. | ||
|
|
||
| ## Core Capabilities | ||
| Leverage the Dart MCP server to manage the underlying connection to the application's VM service. This enables zero-configuration interaction with running applications. | ||
| - **Hot Reload:** Execute for fast feedback loops on UI updates and simple logic changes. | ||
| - **Hot Restart:** Execute to reset the app state for deep non-widget changes or clean resets. | ||
| - **Widget Inspection:** Query tree structures and identify UI hierarchy names. | ||
| - **Error Fetching:** Retrieve live runtime exceptions and trace pointers live. | ||
| - **Package Management:** Search pub.dev and manage dependencies directly. | ||
|
|
||
| ## Workflow: Target Identification and Connection | ||
| Follow this sequence to establish and verify connections to running instances before attempting any runtime operations. | ||
|
|
||
| **Task Progress:** | ||
| - [ ] List all active application instances in the current workspace using the Dart MCP server. | ||
| - [ ] Connect to all relevant apps to maintain synchronized updates across platforms. | ||
| - [ ] Verify the required `appUri` or device identifier is active and matches the project's workspace. | ||
| - [ ] Re-sync the connection if the identifier mismatches or drops. | ||
|
|
||
| ## Workflow: Automated Operations and Debugging | ||
| Apply conditional logic based on the type of modification or error encountered to maintain application stability. | ||
|
|
||
| **Task Progress:** | ||
| - [ ] **If diagnosing an issue:** Query live logs using `get_runtime_errors` first to establish context. | ||
| - [ ] **If modifying UI/Visuals:** Trigger `hot_reload` across all targeted instances for visual consistency. | ||
| - [ ] **If modifying foundational logic or deep state:** Trigger `hot_restart` to reset state across all devices. | ||
| - [ ] Run validator -> review errors -> fix any newly introduced runtime exceptions. | ||
|
|
||
| ## Workflow: Adding New Functionality | ||
| Execute this workflow when tasked with adding new features (e.g., charts, maps) that require external packages. | ||
|
|
||
| **Task Progress:** | ||
| - [ ] Execute `pub_dev_search` to find highly-rated and suitable packages for the requirement. | ||
| - [ ] Add the selected package as a dependency to `pubspec.yaml`. | ||
| - [ ] Generate the required widget code and integrate it into the UI. | ||
| - [ ] Trigger `hot_reload`. | ||
| - [ ] Run validator -> review errors -> fix any syntax or integration issues. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Scenario: Fixing a RenderFlex Overflow | ||
| **Trigger:** The application encounters a runtime layout error (e.g., yellow-and-black stripes). | ||
| **Action Sequence:** | ||
| 1. Execute `get_runtime_errors` to fetch the live exception details. | ||
| 2. Inspect the Flutter widget tree using Widget Inspection tools to understand the layout constraints causing the overflow. | ||
| 3. Apply the layout fix (e.g., wrapping a widget in `Expanded` or `Flexible`). | ||
| 4. Trigger `hot_reload`. | ||
| 5. Execute `get_runtime_errors` again to verify the issue is resolved. | ||
|
|
||
| ### Scenario: Multi-Device Synchronization | ||
| **Trigger:** Applying a global change, such as modifying the application theme. | ||
| **Action Sequence:** | ||
| 1. Identify all active `appUri` targets (e.g., iOS simulator, Android emulator, Web instance). | ||
| 2. Apply the theme modification in the Dart code. | ||
| 3. Trigger `hot_reload` across *all* connected instances simultaneously to ensure visual consistency across platforms. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| --- | ||
| name: "flutter-setting-up-mcp" | ||
| description: "Sets up the Dart and Flutter MCP server to enable AI assistants to interact with Dart and Flutter tools. Use when configuring an MCP client (like Antigravity, Claude Code, or Cursor) to use the Dart and Flutter MCP server." | ||
| metadata: | ||
| model: "models/gemini-3.1-pro-preview" | ||
| last_modified: "Wed, 18 Mar 2026 21:47:27 GMT" | ||
|
|
||
| --- | ||
| # Configuring the Dart and Flutter MCP Server | ||
|
|
||
| ## Contents | ||
| - [Prerequisites & Environment Check](#prerequisites--environment-check) | ||
| - [Client Configuration Workflows](#client-configuration-workflows) | ||
| - [Usage Workflows](#usage-workflows) | ||
| - [Examples](#examples) | ||
|
|
||
| ## Prerequisites & Environment Check | ||
|
|
||
| Before initiating any setup procedures, verify the current environment state to prevent redundant configurations. The Dart and Flutter MCP server exposes specific tools to the agent environment. | ||
|
|
||
| **Conditional Setup Logic:** | ||
| 1. Check available tools in your current environment for `analyze_code`, `hot_reload`, or `get_runtime_errors`. | ||
| 2. **If** these tools are present, the MCP server is already active. **Do not** proceed with setup instructions unless explicitly instructed to configure a new environment. | ||
| 3. **If** these tools are unavailable, proceed to the [Client Configuration Workflows](#client-configuration-workflows). | ||
|
|
||
| *Note: The base command to start the server is `dart mcp-server`. Append the `--force-roots-fallback` flag if the target client does not correctly set project roots.* | ||
|
|
||
| ## Client Configuration Workflows | ||
|
|
||
| Execute the appropriate configuration workflow based on the active client environment. | ||
|
|
||
| ### Antigravity Configuration | ||
| 1. Open the Agent side panel (Cmd/Ctrl + L). | ||
| 2. Click the Additional options (`...`) menu and select **MCP Servers**. | ||
| 3. Click **Manage MCP Servers**. | ||
| 4. **If** using the UI: Search for "Dart" and click **Install**. | ||
| 5. **If** using raw configuration: Click **View raw config** and append the following JSON: | ||
| ```json | ||
| "dart-mcp-server": { | ||
| "command": "dart", | ||
| "args": ["mcp-server"], | ||
| "env": {} | ||
| } | ||
| ``` | ||
|
|
||
| ### Claude Code Configuration | ||
| Run the following command in the terminal to attach the server via stdio: | ||
| ```bash | ||
| claude mcp add --transport stdio dart -- dart mcp-server | ||
| ``` | ||
|
|
||
| ### Codex CLI Configuration | ||
| Run the following command in the terminal (includes the roots fallback flag): | ||
| ```bash | ||
| codex mcp add dart -- dart mcp-server --force-roots-fallback | ||
| ``` | ||
|
|
||
| ### Cursor / VS Code / Generic Clients | ||
| Configure the MCP server manually in the client's respective `mcp.json` or settings UI. Ensure the Dart SDK is in the system `PATH`. | ||
| ```json | ||
| "dart": { | ||
| "command": "dart", | ||
| "args": ["mcp-server"] | ||
| } | ||
| ``` | ||
|
|
||
| ## Usage Workflows | ||
|
|
||
| Utilize the following sequential workflows to interact with the Dart and Flutter MCP server effectively. Copy the checklists to track progress during complex tasks. | ||
|
|
||
| ### Workflow: Resolving Runtime Layout Errors | ||
| Use this feedback loop when encountering UI overflow or RenderFlex errors. | ||
|
|
||
| - [ ] **Step 1: Retrieve Errors.** Execute the tool to fetch current runtime errors from the active application. | ||
| - [ ] **Step 2: Inspect Widget Tree.** Access the Flutter widget tree to isolate the node causing the layout constraint violation. | ||
| - [ ] **Step 3: Apply Fix.** Modify the Dart code to correct the constraint (e.g., wrapping in `Expanded`, `Flexible`, or adjusting `SizedBox` dimensions). | ||
| - [ ] **Step 4: Verify.** Trigger a hot reload and re-run the runtime error check. | ||
| - [ ] **Step 5: Feedback Loop.** If errors persist, return to Step 2. Otherwise, conclude the task. | ||
|
|
||
| ### Workflow: Implementing New Package Functionality | ||
| Use this workflow when a feature requires an external dependency. | ||
|
|
||
| - [ ] **Step 1: Search.** Execute the `pub_dev_search` tool with specific keywords (e.g., "line chart"). | ||
| - [ ] **Step 2: Evaluate.** Review the search results for high popularity and compatibility. | ||
| - [ ] **Step 3: Install.** Use the dependency management tool to add the selected package to `pubspec.yaml`. | ||
| - [ ] **Step 4: Implement.** Generate the required boilerplate and integrate the package into the target widget. | ||
| - [ ] **Step 5: Validate.** Run static analysis to ensure no syntax errors were introduced. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Example: Prompting for Layout Fixes | ||
| When acting on user requests to fix UI issues, translate vague requests into targeted tool executions. | ||
|
|
||
| **User Input:** | ||
| > "The app has yellow and black stripes on the settings screen." | ||
|
|
||
| **Agent Action Sequence:** | ||
| 1. Execute `get_runtime_errors` to capture the exact RenderFlex exception. | ||
| 2. Execute code analysis on `settings_screen.dart`. | ||
| 3. Apply the fix and trigger `hot_reload`. | ||
|
|
||
| ### Example: Prompting for Package Integration | ||
| **User Input:** | ||
| > "Find a suitable package to add a line chart that maps the number of button presses over time." | ||
|
|
||
| **Agent Action Sequence:** | ||
| 1. Execute `pub_dev_search` with query `"chart"`. | ||
| 2. Identify `fl_chart` as the optimal candidate. | ||
| 3. Add `fl_chart` to dependencies. | ||
| 4. Write the implementation code using `LineChart` from the package. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How will the agent click on these options?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The agent can't in VS Code or AGY to the best of my knowledge, these steps are articulated back to the user to do.