convez.ai
MCP ServerDevOps & InfraestruturaAvançado
dhruvanbhalara

Flutter Agent Lens MCP Server

dhruvanbhalara/flutter_agent_lens

Debug e profiling de Flutter apps com IA via MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Um servidor MCP que conecta assistentes de IA a aplicações Flutter em execução via Dart VM Service. Fornece acesso direto a estado da aplicação, dados de performance, constraints de layout e logs do console para debugging e profiling assistido por IA.

Instalação

$npx convez-ai dhruvanbhalara/flutter_agent_lens

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
50
Forks
4
Acompanhando
1
Saúde
42%
Último commit
há 3 semanas
Versão
v1.8.2
Issues abertas
4
Contribuidores
1

Casos de uso

  • Diagnosticar jank de renderização e bottlenecks de performance em tempo real
  • Analisar padrões de rebuild de widgets e otimizar layout
  • Auditar uso de memória e identificar memory leaks via caminhos de retenção
  • Capturar e analisar logs, stdout, stderr para troubleshooting assistido

Veredito

Ferramenta especializada que eleva o debugging de Flutter apps ao próximo nível, permitindo IA inspecionar estado interno e performance em tempo real. Exige conhecimento profundo de Flutter, Dart VM e profiling para máximo proveito.

README

A tradução para o português deste README ainda está na fila.

Flutter Agent Lens MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to running Flutter applications. It communicates with the Dart VM Service over WebSockets, giving AI tools direct access to application state, performance data, layout constraints, and console logs.


Features

AI assistants (such as Claude or Copilot) can inspect, profile, and debug any Flutter application running in debug or profile mode. You can use this server to:

  • Track widget rebuild frequencies.
  • Diagnose rendering bottlenecks and frame jank.
  • Analyze CPU usage and execution hotspots.
  • Audit memory usage and find retaining paths that cause memory leaks.
  • Capture console, stdout, stderr, and logging streams.
  • Read local build sizes to locate heavy packages and assets.
  • Validate App Links and Universal Links configurations.
  • Drive scroll behaviors and trigger hot reloads.

Requirements

  • Dart SDK / Flutter SDK (installed and added to the system PATH).
  • A Flutter application running in debug or profile mode.

Setup

1. Install the CLI

Activate the package globally to register the flutter-agent-lens binary:

dart pub global activate flutter_agent_lens

Ensure your global pub cache bin directory is in your system PATH (typically ~/.pub-cache/bin on macOS/Linux or %USERPROFILE%\AppData\Local\Pub\Cache\bin on Windows).

2. Configure the MCP Host

Add the server details to the configuration file of your MCP client host:

Claude Desktop

Add the following to your configuration file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "flutter_agent_lens": {
      "command": "flutter-agent-lens"
    }
  }
}

Cursor

  1. Go to Settings > Features > MCP.
  2. Click + Add New MCP Server.
  3. Set the configuration:
    • Name: flutter_agent_lens
    • Type: command
    • Command: flutter-agent-lens

Tool Catalog

All tools require an active connection to a running application, unless stated otherwise.

Connection and Discovery

Tool NameParametersDescription
connect_to_app / connecturi (required, or vmServiceUri for alias), workspace_root (optional)Connect to a running Flutter application via its VM Service URI.
list_running_appsNoneScan for running Flutter VM Service ports on the host.
autodiscover_app / discover_appsworkspace_root (optional)Scan active OS processes and connect automatically if exactly one application is running.
disconnectNoneDisconnect from the currently active application.
get_app_infoNoneRetrieve VM metadata, isolates, platform details, and active extension RPCs.

Performance and Build

Tool NameParametersDescription
diagnose_jankduration_seconds (default: 3)Analyze frame render times and highlight frames exceeding the 16.6ms budget.
get_cpu_profileduration_seconds (default: 3)Sample CPU ticks to identify performance hotspots in Dart functions.
get_widget_rebuild_countsduration_seconds (default: 3)Track widget rebuild counts to identify unnecessary layout updates.
hot_reloadNoneTrigger a hot reload on the connected main isolate.
hot_restartNoneTrigger a hot restart of the running application.
analyze_bundle_sizebuild_target (default: 'apk')Parse local code-size-details.json maps to find bloated packages.

Layout Inspection

Tool NameParametersDescription
get_widget_treemaxDepth (optional, default: 15), projectOnly (optional, default: false)Retrieve the structured widget tree of the running Flutter application.
inspect_layout_constraints / inspect_widgetwidget_id (required, or widgetId for alias)Inspect parent constraints, render size, and diagnostics of a widget.
compare_layout_screenshotsbaseline_name (required), action (required), threshold (optional)Capture screenshots and run pixel diff comparison to detect visual changes.
take_screenshotscreenshot_type (optional), device_id (optional), output_path (optional)Capture a standalone screenshot of the running Flutter application.
toggle_widget_selectionenabled (required)Toggle the on-device widget selection overlay.
toggle_package_widgetsenabled (required)Configure whether third-party packages appear in the inspector tree.
toggle_layout_guidelines / toggle_debug_paintenabled (required)Toggle layout guidelines (debug paint) on the device.
toggle_oversized_imagesenabled (required)Highlight oversized images by inverting their colors.
toggle_repaint_rainbowenabled (required)Show color borders around repaint boundaries during redraws.
toggle_baselinesenabled (required)Render alignment baselines for text rendering.
toggle_slow_animationsenabled (required)Apply a 5x time dilation factor to slow down UI animations.
toggle_debug_flagflag_name (required), value (required)Set a custom value for any registered Flutter service extension flag.

Memory and Debugging

Tool NameParametersDescription
save_snapshotname (required), forceGC (optional, default: true)Save a named memory allocation profile snapshot for later comparison.
compare_snapshotsbefore (required), after (required)Compare two saved memory snapshots to calculate instance and byte differences.
list_snapshotsNoneList saved memory snapshots available for comparison.
audit_class_memory_leakclass_name (required)Scan heap instances of a class to verify if disposed objects are leaking.
diff_heap_allocationsduration_seconds (default: 3), expression (optional), force_gc (default: true)Calculate memory growth and instance delta metrics over a window.
get_object_referrersobject_id (required), limit (default: 15)Trace reference paths keeping an object alive in the heap.
get_call_stacklimit (default: 20)Retrieve stack frames of active or paused isolates.
set_exception_pause_modemode (required: 'None', 'Unhandled', 'All')Configure exception pausing behavior.
add_breakpointfile_path (required), line (required), column (optional)Install a breakpoint in a source file.
remove_breakpointbreakpoint_id (required)Remove a breakpoint.
eval_expression / evaluate_expressionexpression (required)Evaluate a Dart expression in the context of the running application library.

Logs and Gestures

Tool NameParametersDescription
fetch_console_logslimit (default: 50, max: 200)Fetch buffered stdout, stderr, and logging streams.
get_network_profileNoneList HTTP requests recorded in the timeline.
trigger_scroll_gesturescroll_controller_expression (required), offset (default: 500.0)Programmatically animate a scroll controller for layout testing.

Troubleshooting

Connection Fails

  • Ensure your Flutter application is running in debug or profile mode. Release builds disable the VM Service.
  • Check that the port is accessible. If running on physical devices or emulators, you may need to map ports using ADB:
    adb reverse tcp:8181 tcp:8181
    
  • If autodiscover_app fails to connect, verify that your application has initialized the Dart Development Service (DDS). You can check by running list_running_apps to list active endpoints.

Layout File Path Mapping Fails

  • When connecting via connect_to_app, ensure you provide the absolute path to your local Flutter project directory in the workspace_root argument. This allows the path resolver to match package references back to your local files.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Ver o original no GitHub

Bom para

Relacionados