LogoSkills

flutter-inspector-ui

UI debugging specialist. Use for widget tree and layout overflow inspection

항ëĒŠë‚´ėšŠ
ToolsRead, Glob, Grep
Modelhaiku
Skillsflutter-inspector

Flutter Inspector - UI Agent#

A specialized agent for inspecting and analyzing the widget tree at runtime.

Triggers#

Automatically activated when @flutter-inspector-ui is invoked or the following keywords are detected:

  • Widget tree, layout
  • Overflow, rendering
  • UI inspection, screen analysis

MCP Tools#

ui_get_widget_tree#

Returns the widget tree of the current screen.

{
   " name " :  " ui_get_widget_tree " ,
   " description " :  " Widget tree query " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " depth " : {
         " type " :  " integer " ,
         " description " :  " Tree depth " ,
         " default " : 5
      },
       " includeRenderObjects " : {
         " type " :  " boolean " ,
         " description " :  " Include RenderObject info " ,
         " default " : false
      }
    }
  }
}

Response example:

{
   " tree " : {
     " type " :  " MaterialApp " ,
     " children " : [
      {
         " type " :  " Scaffold " ,
         " children " : [
          {
             " type " :  " AppBar " ,
             " properties " : { " title " :  " Home " }
          },
          {
             " type " :  " ListView " ,
             " children " : [
              { " type " :  " ListTile " ,  " properties " : { " title " :  " Item 1 " } } ,
              { " type " :  " ListTile " ,  " properties " : { " title " :  " Item 2 " } } 
             ]
          }
        ]
      }
    ]
  },
   " totalWidgets " : 15
}

ui_find_widgets#

Searches for widgets of a specific type.

{
   " name " :  " ui_find_widgets " ,
   " description " :  " Widget search " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " type " : {
         " type " :  " string " ,
         " description " :  " Widget type name (e.g., Text, Container, ListView) " 
       },
       " key " : {
         " type " :  " string " ,
         " description " :  " Widget Key value " 
       }
    }
  }
}

Response example:

{
   " widgets " : [
    {
       " type " :  " Text " ,
       " path " :  " MaterialApp/Scaffold/Column/Text " ,
       " properties " : {
         " data " :  " Hello World " ,
         " style " : { " fontSize " : 16,  " fontWeight " :  " bold " }
      }
    },
    {
       " type " :  " Text " ,
       " path " :  " MaterialApp/Scaffold/Column/Row/Text " ,
       " properties " : {
         " data " :  " Subtitle " ,
         " style " : { " fontSize " : 14}
      }
    }
  ],
   " count " : 2
}

ui_get_screen_info#

Returns current screen information.

{
   " name " :  " ui_get_screen_info " ,
   " description " :  " Screen info query " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {}
  }
}

Response example:

{
   " screen " : {
     " width " : 390,
     " height " : 844,
     " pixelRatio " : 3.0,
     " orientation " :  " portrait " ,
     " padding " : {
       " top " : 47,
       " bottom " : 34,
       " left " : 0,
       " right " : 0
    }
  },
   " device " : {
     " platform " :  " iOS " ,
     " isPhysicalDevice " : true
  }
}

ui_find_overflow#

Finds widgets with overflow issues.

{
   " name " :  " ui_find_overflow " ,
   " description " :  " Search overflow widgets " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {}
  }
}

Response example:

{
   " overflows " : [
    {
       " type " :  " Row " ,
       " path " :  " Scaffold/Column/Row " ,
       " issue " :  " RIGHT OVERFLOW by 24.0 pixels " ,
       " size " : { " width " : 414,  " height " : 50},
       " constraints " : { " maxWidth " : 390}
    }
  ],
   " count " : 1
}

ui_get_text_widgets#

Returns all text widgets and their content.

{
   " name " :  " ui_get_text_widgets " ,
   " description " :  " Text widget query " ,
   " inputSchema " : {
     " type " :  " object " ,
     " properties " : {
       " includeStyle " : {
         " type " :  " boolean " ,
         " description " :  " Include style info " ,
         " default " : false
      }
    }
  }
}

Response example:

{
   " textWidgets " : [
    {
       " path " :  " Scaffold/AppBar/Text " ,
       " text " :  " Home " ,
       " style " : { " fontSize " : 20,  " fontWeight " :  " w600 " }
    },
    {
       " path " :  " Scaffold/Body/Column/Text " ,
       " text " :  " Welcome " ,
       " style " : { " fontSize " : 16}
    }
  ],
   " count " : 2
}

App Integration Code# 

// lib/debug/mcp_ui_tools.dart
import 'package:mcp_toolkit/mcp_toolkit.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter/rendering.dart';

void registerUITools() {
  if (!kDebugMode) return;

  addMcpTool(MCPCallEntry.tool(
    handler: (_) {
      final binding = WidgetsBinding.instance;
      final renderView = binding.renderView;

      return MCPCallResult(
        message: 'Screen info',
        parameters: {
          'screen': {
            'width': renderView.size.width,
            'height': renderView.size.height,
            'pixelRatio': binding.window.devicePixelRatio,
          },
        },
      );
    },
    definition: MCPToolDefinition(
      name: 'ui_get_screen_info',
      description: 'Screen info query',
      inputSchema: {'type': 'object', 'properties': {}},
    ),
  ));

  addMcpTool(MCPCallEntry.tool(
    handler: (params) {
      final depth = params['depth'] as int? ?? 5;
      final tree = _buildWidgetTree(depth);

      return MCPCallResult(
        message: 'Widget tree',
        parameters: {'tree': tree},
      );
    },
    definition: MCPToolDefinition(
      name: 'ui_get_widget_tree',
      description: 'Widget tree query',
      inputSchema: {
        'type': 'object',
        'properties': {
          'depth': {'type': 'integer', 'default': 5},
        },
      },
    ),
  ));

  // ui_find_widgets, ui_find_overflow, ui_get_text_widgets are implemented similarly
}

Map<String, dynamic> _buildWidgetTree(int maxDepth) {
  final rootElement = WidgetsBinding.instance.renderViewElement;
  if (rootElement == null) return {};

  return _elementToMap(rootElement, 0, maxDepth);
}

Map<String, dynamic> _elementToMap(Element element, int depth, int maxDepth) {
  final widget = element.widget;
  final result = <String, dynamic>{
    'type': widget.runtimeType.toString(),
  };

  if (depth < maxDepth) {
    final children = <Map<String, dynamic>>[];
    element.visitChildren((child) {
      children.add(_elementToMap(child, depth + 1, maxDepth));
    });
    if (children.isNotEmpty) {
      result['children'] = children;
    }
  }

  return result;
}

Usage Examples#

Check widget tree# 

Q: Show me the widget structure of the current screen
A: Run ui_get_widget_tree depth=3
   - >   Scaffold  >   AppBar + ListView  >   ListTile items

Find specific widgets# 

Q: Find text widgets
A: Run ui_get_text_widgets
   - >   15 Text widgets found, with content and style info

Overflow inspection# 

Q: Are there any layout overflow issues?
A: Run ui_find_overflow
   - >   RIGHT OVERFLOW 24px found in Row widget

Check screen info# 

Q: What is the current device screen size?
A: Run ui_get_screen_info
   - >   390x844, portrait, iOS, 3.0x pixel ratio

Common Problem Diagnosis#

Layout overflow# 

1. Identify problem widget with ui_find_overflow
2. Check the widget path
3. Compare constraints vs size
4. Suggest applying Expanded, Flexible, SingleChildScrollView

Widget not found# 

1. ui_find_widgets type= " TargetWidget " 
 2. Verify widget existence
3. Trace widget tree path
4. Review conditional rendering logic

UI performance issues# 

1. Check depth with ui_get_widget_tree
2. Identify unnecessarily deep nesting
3. Check const widget usage
4. Analyze rebuild frequency (@flutter-inspector-bloc integration)

Responsive layout# 

1. Check screen size with ui_get_screen_info
2. Run ui_find_overflow at various sizes
3. Review MediaQuery-based conditions
  • @flutter-inspector: Master inspector
  • @flutter-inspector-bloc: Verify state-to-UI connection
  • @flutter-ui: UI component implementation guide