Dart Flutter MCP

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

Testing:

Symbol Resolution:

Package Discovery:

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

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.

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

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

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.

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

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

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

• 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

• 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."

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