dhruvanbhalara/flutter_agent_lens

AI 어시스턴트를 실행 중인 Flutter 애플리케이션에 연결하는 Model Context Protocol (MCP) 서버입니다. 이 서버는 WebSockets를 통해 Dart VM Service와 통신하며, AI 도구가 애플리케이션 상태(application state), 성능 데이터(performance data), 레이아웃 제약 조건(layout constraints) 및 콘솔 로그(console logs)에 직접 접근할 수 있도록 합니다.

AI 어시스턴트(Claude 또는 Copilot 등)는 디버그(debug) 또는 프로파일(profile) 모드로 실행 중인 모든 Flutter 애플리케이션을 검사, 프로파일링 및 디버깅할 수 있습니다. 이 서버를 사용하여 다음을 수행할 수 있습니다:

• 위젯 리빌드 빈도(widget rebuild frequencies) 추적.

• 렌더링 병목 현상(rendering bottlenecks) 및 프레임 저하(frame jank) 진단.

• CPU 사용량 및 실행 핫스팟(execution hotspots) 분석.

• 메모리 사용량 감사 및 메모리 누수(memory leaks)를 유발하는 리테이닝 경로(retaining paths) 탐색.

• 콘솔(console), stdout, stderr 및 로깅 스트림(logging streams) 캡처.

• 로컬 빌드 크기를 읽어 무거운 패키지 및 에셋(assets) 위치 파악.

• 앱 링크(App Links) 및 유니버설 링크(Universal Links) 설정 검증.

• 스크롤 동작 제어 및 핫 리로드(hot reloads) 트리거.

• Dart SDK / Flutter SDK (설치되어 시스템 PATH에 추가되어 있어야 함).

• 디버그(debug) 또는 프로파일(profile) 모드로 실행 중인 Flutter 애플리케이션.

flutter-agent-lens 바이너리를 등록하기 위해 패키지를 전역(globally)으로 활성화하세요:

dart pub global activate flutter_agent_lens

전역 pub 캐시 bin 디렉토리가 시스템 PATH에 포함되어 있는지 확인하세요 (macOS/Linux의 경우 일반적으로 ~/.pub-cache/bin, Windows의 경우 %USERPROFILE%\AppData\Local\Pub\Cache\bin).

MCP 클라이언트 호스트의 설정 파일에 서버 세부 정보를 추가하세요:

설정 파일에 다음을 추가하세요 (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
"mcpServers": {
"flutter_agent_lens": {
...

• Settings > Features > MCP로 이동합니다.
• + Add New MCP Server를 클릭합니다.
• 설정을 지정합니다:
  Name: flutter_agent_lens
  Type: command
  Command: flutter-agent-lens

별도로 명시되지 않는 한, 모든 도구는 실행 중인 애플리케이션에 대한 활성 연결이 필요합니다.

도구 이름 (Tool Name)	파라미터 (Parameters)	설명 (Description)
connect_to_app / connect	uri (필수, 또는 별칭으로 vmServiceUri), workspace_root (선택 사항)	VM 서비스 URI (VM Service URI)를 통해 실행 중인 Flutter 애플리케이션에 연결합니다.
list_running_apps	없음	호스트에서 실행 중인 Flutter VM 서비스 포트를 스캔합니다.
autodiscover_app / discover_apps	workspace_root (선택 사항)	활성 OS 프로세스를 스캔하며, 정확히 하나의 애플리케이션이 실행 중인 경우 자동으로 연결합니다.
disconnect	없음	현재 활성화된 애플리케이션에서 연결을 해제합니다.
get_app_info	없음	VM 메타데이터, 아이솔레이트 (isolates), 플랫폼 세부 정보 및 활성 확장 RPC를 가져옵니다.

도구 이름 (Tool Name)	파라미터 (Parameters)	설명 (Description)
diagnose_jank	duration_seconds (기본값: 3)	프레임 렌더링 시간을 분석하고 16.6ms 예산을 초과하는 프레임을 강조 표시합니다.
get_cpu_profile	duration_seconds (기본값: 3)	CPU 틱 (ticks)을 샘플링하여 Dart 함수 내의 성능 핫스팟 (hotspots)을 식별합니다.
get_widget_rebuild_counts	duration_seconds (기본값: 3)	위젯 재빌드 (widget rebuild) 횟수를 추적하여 불필요한 레이아웃 업데이트를 식별합니다.
hot_reload	없음	연결된 메인 아이솔레이트 (main isolate)에 핫 리로드 (hot reload)를 트리거합니다.
hot_restart	없음	실행 중인 애플리케이션의 핫 리스타트 (hot restart)를 트리거합니다.
analyze_bundle_size	build_target (기본값: 'apk')	로컬 code-size-details.json 맵을 파싱하여 비대해진 패키지를 찾습니다.

도구 이름 (Tool Name)	파라미터 (Parameters)	설명 (Description)
get_widget_tree	maxDepth (선택 사항, 기본값: 15), projectOnly (선택 사항, 기본값: false)	실행 중인 Flutter 애플리케이션의 구조화된 위젯 트리 (Widget Tree)를 가져옵니다.
inspect_layout_constraints / inspect_widget	widget_id (필수, 또는 별칭으로 widgetId)	위젯의 부모 제약 조건 (Constraints), 렌더링 크기 (Render Size) 및 진단 정보 (Diagnostics)를 검사합니다.
compare_layout_screenshots	baseline_name (필수), action (필수), threshold (선택 사항)	스크린샷을 캡처하고 픽셀 차이 비교 (Pixel Diff Comparison)를 실행하여 시각적 변화를 감지합니다.
take_screenshot	screenshot_type (선택 사항), device_id (선택 사항), output_path (선택 사항)	실행 중인 Flutter 애플리케이션의 단독 스크린샷을 캡처합니다.
toggle_widget_selection	enabled (필수)	기기 내 위젯 선택 오버레이 (Widget Selection Overlay)를 토글합니다.
toggle_package_widgets	enabled (필수)	서드파티 패키지 (Third-party Packages)가 인스펙터 트리 (Inspector Tree)에 표시될지 여부를 설정합니다.
toggle_layout_guidelines / toggle_debug_paint	enabled (필수)	기기에서 레이아웃 가이드라인 (Layout Guidelines, 디버그 페인트)을 토글합니다.
toggle_oversized_images	enabled (필수)	색상을 반전시켜 크기가 너무 큰 이미지 (Oversized Images)를 강조합니다.
toggle_repaint_rainbow	enabled (필수)	다시 그리기 (Redraw) 중에 리페인트 경계 (Repaint Boundaries) 주변에 색상 테두리를 표시합니다.
toggle_baselines	enabled (필수)	텍스트 렌더링을 위한 정렬 기준선 (Alignment Baselines)을 렌더링합니다.
toggle_slow_animations	enabled (필수)	UI 애니메이션을 느리게 하기 위해 5배의 시간 팽창 계수 (Time Dilation Factor)를 적용합니다.
toggle_debug_flag	flag_name (필수), value (필수)	등록된 모든 Flutter 서비스 확장 플래그 (Service Extension Flag)에 대해 사용자 정의 값을 설정합니다.

도구 이름 (Tool Name)	매개변수 (Parameters)	설명 (Description)
save_snapshot	name (필수), forceGC (선택 사항, 기본값: true)	나중에 비교할 수 있도록 이름이 지정된 메모리 할당 프로파일 스냅샷 (Memory Allocation Profile Snapshot)을 저장합니다.
compare_snapshots	before (필수), after (필수)	저장된 두 개의 메모리 스냅샷을 비교하여 인스턴스 및 바이트 차이를 계산합니다.
list_snapshots	없음	비교 가능한 저장된 메모리 스냅샷 목록을 나열합니다.
audit_class_memory_leak	class_name (필수)	클래스의 힙 (Heap) 인스턴스를 스캔하여 폐기된(disposed) 객체가 누수되고 있는지 확인합니다.
diff_heap_allocations	duration_seconds (기본값: 3), expression (선택 사항), force_gc (기본값: true)	특정 시간 범위 동안의 메모리 증가량 및 인스턴스 델타 (Delta) 지표를 계산합니다.
get_object_referrers	object_id (필수), limit (기본값: 15)	힙에서 객체를 계속 살아있게 만드는 참조 경로 (Reference Paths)를 추적합니다.
get_call_stack	limit (기본값: 20)	활성 또는 일시 중지된 아이솔레이트 (Isolate)의 스택 프레임 (Stack Frames)을 가져옵니다.
set_exception_pause_mode	mode (필수: 'None', 'Unhandled', 'All')	예외 발생 시 일시 중지 동작을 설정합니다.
add_breakpoint	file_path (필수), line (필수), column (선택 사항)	소스 파일에 중단점 (Breakpoint)을 설치합니다.
remove_breakpoint	breakpoint_id (필수)	중단점을 제거합니다.
eval_expression / evaluate_expression	expression (필수)	실행 중인 애플리케이션 라이브러리 컨텍스트 내에서 Dart 표현식을 평가합니다.

도구 이름 (Tool Name)	매개변수 (Parameters)	설명 (Description)
fetch_console_logs	limit (기본값: 50, 최대: 200)	버퍼링된 stdout, stderr 및 로깅 스트림을 가져옵니다.
get_network_profile	없음	타임라인에 기록된 HTTP 요청 목록을 나열합니다.
trigger_scroll_gesture	scroll_controller_expression (필수), offset (기본값: 500.0)	레이아웃 테스트를 위해 프로그래밍 방식으로 스크롤 컨트롤러 (Scroll Controller)를 애니메이션화합니다.

• Flutter 애플리케이션이 디버그 (debug) 또는 프로파일 (profile) 모드로 실행 중인지 확인하세요. 릴리스 (Release) 빌드는 VM Service를 비활성화합니다.

• 포트 (port)에 접근 가능한지 확인하세요. 실제 기기나 에뮬레이터에서 실행 중인 경우, ADB를 사용하여 포트를 매핑해야 할 수도 있습니다:
  adb reverse tcp:8181 tcp:8181

• autodiscover_app 연결에 실패하는 경우, 애플리케이션이 Dart Development Service (DDS)를 초기화했는지 확인하세요. list_running_apps를 실행하여 활성화된 엔드포인트 (endpoints) 목록을 확인하여 점검할 수 있습니다.

• connect_to_app을 통해 연결할 때는 workspace_root 인자에 로컬 Flutter 프로젝트 디렉토리의 절대 경로를 제공해야 합니다. 이를 통해 경로 리졸버 (path resolver)가 패키지 참조를 로컬 파일과 일치시킬 수 있습니다.

이 프로젝트는 MIT License 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.