dart-flutter-mcp

---

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.

<quick_start> <common_workflows> 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

</common_workflows> </quick_start>

<tool_categories> <dart_tools> 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
</dart_tools>

<flutter_runtime_tools> 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. </flutter_runtime_tools>

<ide_tools> 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
</ide_tools>
</tool_categories>

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. </tdd_workflow>

<debug_workflow> 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

</debug_workflow>

<code_quality_workflow> 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

</code_quality_workflow>

<tool_details> <dart_analyzer_detail> 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_analyzer_detail>

<dart_run_tests_detail> 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_run_tests_detail>

<dart_resolve_symbol_detail> 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 </dart_resolve_symbol_detail>

<runtime_tools_detail> 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:

1. Run dart_analyzer to check for errors
2. Fix any syntax/type errors
3. Try hot_restart for full restart </runtime_tools_detail> </tool_details>

<anti_patterns> 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

</anti_patterns>

<success_criteria> 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." </success_criteria>

<reference_guides> For advanced patterns and detailed examples:

• Runtime debugging patterns: references/runtime-debugging.md
• IDE tool integration: references/ide-tools.md </reference_guides>