flutter-inspector Reference

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

MCP Tool API Reference#

Core Tools#

fmt_list_client_tools_and_resources

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"
    }
  ]
}

fmt_client_tool

Executes a dynamic tool.

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

fmt_client_resource

Reads a resource.

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

fmt_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://kobic/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