dart-flutter-mcp

<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__*):

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>