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.

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.

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

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