Flutter Inspector Reference Guide#

Detailed MCP tool API documentation, troubleshooting, and advanced patterns.

MCP Tool API Reference#

Core Tools#

listClientToolsAndResources

Returns all dynamic tools and resources registered in the app.

{
   " tools " : [
    {
       " name " :  " bloc_get_all " ,
       " description " :  " Return all BLoC instances " ,
       " inputSchema " : {...}
    }
  ],
   " resources " : [
    {
       " uri " :  " visual://localhost/app/errors/latest " ,
       " description " :  " Recent app errors " 
     }
  ]
}

runClientTool

Executes a dynamic tool.

{
   " toolName " :  " bloc_get_state " ,
   " arguments " : {
     " blocName " :  " AuthBloc " 
   }
}

runClientResource

Reads a resource.

{
   " resourceUri " :  " visual://localhost/app/errors/latest " 
 }

hot_reload_flutter

Hot reloads the app.

{
   " force " : false,
   " port " : 8181
}

Sub-Inspector Tools#

Navigation (nav)#

nav_get_current_route

Returns currently active route info

Response:

{
   " route " : {
     " name " :  " /home " ,
     " path " :  " /home " ,
     " params " : {},
     " queryParams " : {}
  }
}

nav_get_stack

Returns full navigation stack

Response:

{
   " stack " : [
    { " name " :  " /splash " ,  " type " :  " push " },
    { " name " :  " /login " ,  " type " :  " push " },
    { " name " :  " /home " ,  " type " :  " replace " }
  ]
}

nav_test_deep_link

Deep link test

Parameters:

• uri: Deep link URI to test

Response:

{
   " uri " :  " app://petmedi/pet/123 " ,
   " matched " : true,
   " route " :  " /pet/:id " ,
   " params " : { " id " :  " 123 " }
}

nav_get_redirects

Redirect history query

BLoC (bloc)#

bloc_get_all

Returns all BLoC/Cubit instances

Response:

{
   " blocs " : [
    {
       " name " :  " AuthBloc " ,
       " type " :  " Bloc " ,
       " state " :  " AuthAuthenticated " ,
       " eventCount " : 5
    }
  ]
}

bloc_get_state

Current state of a specific BLoC

Parameters:

• blocName: BLoC name

Response:

{
   " blocName " :  " AuthBloc " ,
   " state " : {
     " type " :  " AuthAuthenticated " ,
     " user " : { " id " : 1,  " name " :  " John " }
  }
}

bloc_get_events

Event history query

Parameters:

• blocName: BLoC name
• limit: Maximum count (default 20)

Response:

{
   " events " : [
    {
       " timestamp " :  " 2024-01-01T10:00:00Z " ,
       " event " :  " LoginRequested " ,
       " data " : { " email " :  " user@example.com " }
    }
  ]
}

bloc_emit_event

Manual event emission (for testing)

Parameters:

• blocName: BLoC name
• event: Event data

Authentication (auth)#

auth_get_status

Returns authentication status

Response:

{
   " isAuthenticated " : true,
   " user " : { " id " : 1,  " name " :  " John " },
   " tokenValid " : true,
   " expiresAt " :  " 2024-01-01T12:00:00Z " 
 }

auth_get_tokens

Token information (masked)

Response:

{
   " accessToken " :  " eyJ***abc " ,
   " refreshToken " :  " eyJ***xyz " ,
   " expiresAt " :  " 2024-01-01T12:00:00Z " ,
   " isExpired " : false
}

auth_get_session

Session information

auth_check_auto_login

Auto-login status check

Network (network)#

network_get_logs

HTTP request/response logs

Parameters:

• limit: Maximum count (default 50)
• status: HTTP status filter (2xx, 4xx, 5xx)
• method: HTTP method filter

Response:

{
   " logs " : [
    {
       " timestamp " :  " 2024-01-01T10:00:00Z " ,
       " method " :  " POST " ,
       " url " :  " /api/login " ,
       " status " : 200,
       " duration " : 245
    }
  ]
}

network_get_errors

Filter error requests only

network_get_stats

Network statistics

Response:

{
   " stats " : {
     " totalRequests " : 150,
     " successRate " : 0.95,
     " averageResponseTime " : 180,
     " errorsByStatus " : { " 401 " : 5,  " 500 " : 3}
  }
}

network_clear_logs

Clear logs

Logging (log)#

log_get_recent

Retrieve recent logs

Parameters:

• limit: Maximum count (default 50)
• level: Log level (debug, info, warning, error)

Response:

{
   " logs " : [
    {
       " timestamp " :  " 2024-01-01T10:00:00Z " ,
       " level " :  " info " ,
       " tag " :  " AuthBloc " ,
       " message " :  " User logged in " ,
       " data " : { " userId " : 1}
    }
  ]
}

log_get_errors

Filter error logs only

Parameters:

• limit: Maximum count
• includeStackTrace: Whether to include stack trace

log_search

Log search

Parameters:

• query: Search string
• tag: Tag filter
• limit: Maximum count

log_get_stats

Log statistics

log_clear

Clear logs

UI (ui)#

ui_get_widget_tree

Returns widget tree

Parameters:

• depth: Tree depth (default 5)
• includeRenderObjects: Include RenderObject info

Response:

{
   " tree " : {
     " type " :  " MaterialApp " ,
     " children " : [
      {
         " type " :  " Scaffold " ,
         " children " : [
          { " type " :  " AppBar " },
          { " type " :  " ListView " }
        ]
      }
    ]
  }
}

ui_find_widgets

Search by widget type

Parameters:

• type: Widget type name
• key: Widget Key value

ui_get_screen_info

Returns screen info

Response:

{
   " screen " : {
     " width " : 390,
     " height " : 844,
     " pixelRatio " : 3.0,
     " orientation " :  " portrait " 
   }
}

ui_find_overflow

Overflow issue detection

Response:

{
   " overflows " : [
    {
       " widget " :  " Row " ,
       " path " :  " Scaffold/Column/Row " ,
       " overflow " : { " right " : 45.5},
       " suggestion " :  " Use Expanded or Flexible " 
     }
  ]
}

ui_get_text_widgets

Returns all text widgets

Configuration (config)#

config_get_all

Returns all configuration values

Parameters:

• includeSecrets: Include sensitive values (masked)

Response:

{
   " config " : {
     " apiBaseUrl " :  " https://api.example.com " ,
     " apiKey " :  " ***masked*** " ,
     " timeout " : 30000
  }
}

config_get_value

Retrieve specific configuration value

Parameters:

• key: Configuration key

config_get_feature_flags

Feature flag status

Response:

{
   " featureFlags " : {
     " darkModeEnabled " : true,
     " newHomeLayout " : false,
     " useNewEndpoint " : true
  }
}

config_get_environment

Environment info

Response:

{
   " environment " : {
     " name " :  " development " ,
     " isDebug " : true,
     " flavor " :  " dev " ,
     " version " :  " 1.0.0 " 
   }
}

Form (form)#

form_list

Lists all forms on current screen

Response:

{
   " forms " : [
    {
       " key " :  " loginForm " ,
       " fieldCount " : 3,
       " isValid " : false,
       " fields " : [ " email " ,  " password " ,  " rememberMe " ]
    }
  ]
}

form_get_state

Detailed form state

Parameters:

• formKey: Form key

Response:

{
   " formKey " :  " loginForm " ,
   " state " : {
     " isValid " : false,
     " fields " : {
       " email " : {
         " value " :  " user@example " ,
         " isValid " : false,
         " error " :  " Invalid email format " 
       }
    }
  }
}

form_get_errors

Form error query

form_validate

Run manual validation

Image (image)#

img_get_cache_stats

Image cache statistics

Response:

{
   " cache " : {
     " currentSize " : 52428800,
     " currentSizeFormatted " :  " 50 MB " ,
     " maximumSize " : 104857600,
     " usagePercent " : 50,
     " liveImageCount " : 25
  },
   " memory " : {
     " currentUsage " : 157286400,
     " currentUsageFormatted " :  " 150 MB " 
   }
}

img_analyze_warnings

Image issue analysis

Parameters:

• threshold: Warning threshold (MB)

Response:

{
   " warnings " : [
    {
       " type " :  " oversized " ,
       " severity " :  " high " ,
       " message " :  " Image is 4x larger than display size " ,
       " image " :  " banner_home.png " ,
       " suggestion " :  " Recommend using cacheWidth/cacheHeight " 
     }
  ],
   " score " : 65,
   " grade " :  " C " 
 }

img_clear_cache

Clear image cache

Parameters:

• type: Clear type (all, memory, disk, expired)

Troubleshooting#

MCP Connection Failure#

Hot Reload Failure#

Tool Execution Error#

Performance Considerations#

Tool Call Optimization#

• Batch calls: Call related tools sequentially
• Caching: Avoid repeated requests for the same information
• Filtering: Use limit parameter to restrict data volume

Resource Usage#

• Screenshots consume high memory
• Deep widget tree depth increases response time
• Large log volumes increase search time

Platform Considerations#

iOS#

• Impeller used by default
• Favorable for performance profiling

Android#

• Skia/Impeller mixed
• Watch for OpenGLES related issues

Web#

• VM Service is limited
• Some tools are unavailable

External Resources#

• Flutter DevTools
• MCP Toolkit Package
• Dart VM Service Protocol