Dart Flutter MCP

<objective> 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. </​objective>

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

Testing:

Symbol Resolution:

Package Discovery:

<flutter_runtime_tools> Runtime Debugging (requires running app):

Prerequisites: App must be running in debug mode with Dart tooling daemon connected. </​flutter_runtime_tools>

<ide_tools> IDE Integration (mcp__ide__*):

<workflows> <tdd_workflow> **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> </​workflows>

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