name	dart-flutter-mcp
description	Provides Flutter and Dart development workflows using dart-mcp tools. Triggers when working with .dart files, pubspec.yaml, or when user mentions Flutter, widget, Riverpod, Freezed, or Dart development. MUST BE USED for Flutter project work involving dart_analyzer, dart_run_tests, hot_reload, or IDE MCP tools.

Master the Dart/Flutter MCP (Model Context Protocol) server tools for efficient Flutter development. These tools provide direct integration with the Dart toolchain and running Flutter apps, enabling static analysis, testing, debugging, and live app inspection without leaving the conversation. **Validate code quality:** ``` dart_analyzer → Check for errors/warnings dart_format → Ensure consistent style ```

Run tests:

dart_analyzer → Catch compile errors first
dart_run_tests → Execute tests

Debug running app:

get_runtime_errors → Capture current errors
get_widget_tree → Inspect UI hierarchy
[make fix]
hot_reload → Apply changes
get_runtime_errors → Verify fix

Understand an API:

dart_resolve_symbol → Get signature and documentation

**Static Analysis and Code Quality:**

Tool	Purpose	When to Use
`dart_analyzer`	Static analysis for errors, warnings, hints	After writing code, before running tests
`dart_format`	Apply consistent code formatting	After all code changes
`dart_fix`	Apply automated fixes for analyzer issues	When analyzer reports fixable issues

Testing:

Tool	Purpose	When to Use
`dart_run_tests`	Execute Dart/Flutter tests	After writing tests, in TDD cycles

Symbol Resolution:

Tool	Purpose	When to Use
`dart_resolve_symbol`	Get symbol documentation and signatures	Understanding APIs, checking method signatures

Package Discovery:

Tool	Purpose	When to Use
`pub_dev_search`	Search pub.dev for packages	Finding packages for specific functionality

**Runtime Debugging (requires running app):**

Tool	Purpose	When to Use
`get_runtime_errors`	Fetch current runtime errors and stack traces	First step in debugging, verify fixes
`get_widget_tree`	Inspect widget hierarchy at runtime	Layout debugging, finding widget issues
`hot_reload`	Apply code changes without losing state	After making fixes, during development
`hot_restart`	Full restart preserving debug session	When hot reload fails or state is corrupted

Prerequisites: App must be running in debug mode with Dart tooling daemon connected.

**IDE Integration (mcp__ide__*):**

Tool	Purpose	When to Use
`mcp__ide__getDiagnostics`	Get IDE diagnostics for a file	Check for issues in specific file
`mcp__ide__readFile`	Read file contents	Understanding existing code
`mcp__ide__writeFile`	Write/create files	Creating new files
`mcp__ide__getCurrentEditor`	Get active editor content	Context-aware operations
`mcp__ide__getOpenEditors`	Get currently open files	Understanding user context
`mcp__ide__searchInProject`	Search across project files	Finding patterns, usages
`mcp__ide__getProjectStructure`	Get project file tree	Understanding project layout

**TDD Red-Green-Refactor with MCP Tools:**

1. Write failing test
2. dart_run_tests → Verify RED (test fails)
3. Write minimal implementation
4. dart_run_tests → Verify GREEN (test passes)
5. Refactor code
6. dart_run_tests → Verify still GREEN
7. dart_analyzer → Check for issues
8. dart_format → Apply consistent style

This cycle ensures tests drive implementation and code quality stays high.

**Runtime Debugging Workflow:**

1. Verify app is connected:
   get_runtime_errors → If fails, app not connected

2. Gather evidence:
   get_runtime_errors → Capture current errors
   get_widget_tree → Inspect UI structure

3. Analyze error patterns:
   - RenderFlex overflow → Layout constraints issue
   - Null check operator → Null safety issue
   - setState after dispose → Lifecycle issue

4. Make targeted fix (use mcp__ide__readFile/writeFile)

5. Apply and verify:
   hot_reload → Apply changes
   get_runtime_errors → Should be empty or reduced

6. If hot_reload fails:
   dart_analyzer → Check for syntax errors
   hot_restart → Try full restart

**Pre-Commit Quality Check:**

1. dart_analyzer → Must show 0 errors, 0 warnings
2. dart_run_tests → All tests must pass
3. dart_format → Apply consistent formatting
4. dart_fix → Apply any remaining automated fixes

**dart_analyzer**

Performs static analysis on Dart/Flutter code.

Returns:

Errors (compilation failures)
Warnings (potential issues)
Hints (suggestions)
Lints (style violations)

Best Practices:

Run BEFORE tests to catch compile errors early
Run AFTER code changes to verify quality
Fix ALL errors before proceeding
Address warnings unless explicitly justified
Target zero issues in production code

Example Output:

lib/src/auth/repository.dart:45:12
  ERROR: The argument type 'String' can't be assigned to parameter type 'int'

lib/src/widgets/profile.dart:23:5
  WARNING: Unused import 'package:flutter/foundation.dart'

Analysis complete. 1 error, 1 warning.

**dart_run_tests**

Executes Dart/Flutter tests with filtering and coverage.

Options:

Filter by file: path/to/test_file.dart
Filter by name: --name "test description"
With coverage: --coverage
Specific reporter: --reporter expanded

Best Practices:

Run dart_analyzer first to catch compile errors
Use specific test filters during development
Run full suite before commits
Check coverage for new code

Interpreting Results:

✓ should return user when authenticated
✓ should throw when token expired
✗ should handle network timeout
  Expected: Left<NetworkFailure>
  Actual: Right<User>

2 passed, 1 failed

**dart_resolve_symbol**

Resolves symbols to their documentation and type signatures.

Use Cases:

Understanding API methods before use
Checking parameter types and return types
Finding documentation for Flutter widgets
Verifying method signatures

Example:

Query: "TaskEither.tryCatch"

Result:
TaskEither<L, R>.tryCatch(
  Future<R> Function() run,
  L Function(Object error, StackTrace stackTrace) onError,
)

Creates a TaskEither that runs the given function and catches any errors.

Best Practices:

Use before implementing unfamiliar APIs
Verify signatures match your usage
Check for nullability in return types

**get_runtime_errors**

Fetches current runtime errors from a running Flutter app.

Requires: App running in debug mode with daemon connected.

Returns:

Exception type and message
Stack trace with file:line references
Widget that threw (if applicable)

Best Practices:

ALWAYS run first when debugging
Re-run AFTER every fix attempt
Empty result = no current errors

Common Error Patterns:

RenderFlex overflowed → Layout constraints
Null check operator used on null value → Null safety
setState() called after dispose() → Lifecycle bug
type 'Null' is not a subtype → Type mismatch

get_widget_tree

Inspects the widget hierarchy of a running Flutter app.

Returns:

Widget tree structure
Widget types and keys
Constraints and sizes (if RenderObject attached)

Use For:

Layout debugging
Finding unexpected widgets
Verifying widget structure

Look For:

Unbounded constraints → Missing Expanded/Flexible
Unexpected nesting → Widget composition issues
Missing widgets → Conditional rendering bugs

hot_reload

Applies code changes to a running app without losing state.

When It Works:

Method body changes
Widget build changes
Most code changes

When It Fails:

Syntax errors in code
Static field initializer changes
Main function changes
New dependencies added

If Hot Reload Fails:

Run dart_analyzer to check for errors
Fix any syntax/type errors
Try hot_restart for full restart

**Common Mistakes:**

Running tests before analyzer → Wastes time on compile errors
Skipping get_runtime_errors → Guessing at fixes without evidence
Ignoring analyzer warnings → Technical debt accumulation
Hot reload with syntax errors → Will always fail
Not verifying after fixes → May introduce regressions

Correct Order:

dart_analyzer → dart_run_tests → dart_format
get_runtime_errors → [fix] → hot_reload → get_runtime_errors

MCP tool usage is correct when:

dart_analyzer shows 0 errors before running tests
dart_run_tests executes without compile failures
get_runtime_errors returns empty after fix verification
hot_reload succeeds (no syntax errors in code)
Code quality workflow runs in correct order
Runtime debugging gathers evidence before making changes

Uncertainty Handling:

NEVER guess at solutions when evidence is insufficient. If you cannot determine the answer with confidence, explicitly state: "I don't have enough information to confidently assess this."

For advanced patterns and detailed examples:

Runtime debugging patterns: references/runtime-debugging.md
IDE tool integration: references/ide-tools.md

dart-flutter-mcp

Install Skill

SKILL.md