/marionette setup — Marionette 처음 한 번 설치하기#

한마디로#

실행 중인 Flutter 앱을 Claude가 직접 "보고 만질 수 있게" 연결해 주는 최초 설치 작업입니다. 리모컨(Marionette)을 처음 한 번 페어링해 두면, 이후부터 Claude가 그 리모컨으로 앱 화면을 보고 버튼을 누를 수 있게 됩니다.

누가·언제 쓰나요#

• Marionette를 처음 설치할 때 (이 앱에서 한 번만 하면 됨)
• marionette_mcp 버전을 올렸을 때, 다시 실행해 최신 상태로 맞추고 싶을 때
• CoUI 디자인 요소(버튼, 입력창 등)가 새로 추가돼서 연결 설정을 갱신해야 할 때

👉 몇 번을 다시 실행해도 안전합니다(idempotent — 같은 작업을 반복해도 망가지지 않음).

무엇을 해주나요#

• Marionette MCP 서버를 설치하고 Claude Code에 등록합니다.
• 대상 Flutter 앱에 marionette_flutter 패키지를 연결합니다.
• 앱의 main.dart에 CoUI 요소를 인식하는 초기화 설정(MarionetteBinding)을 심어 줍니다.
• 마지막으로 연결이 잘 됐는지 확인(smoke test)하고, 첫 화면 스크린샷을 .claude/docs/marionette/<시각>/screens/00.png에 저장합니다.

어떻게 쓰나요#

# 1) MCP 서버 설치 (어디서든 쓸 수 있는 전역 설치 권장)
dart pub global activate marionette_mcp

# 2) Claude Code에 등록
claude mcp add --transport stdio marionette -- marionette_mcp

# 3) 대상 앱에 Flutter 패키지 추가
flutter pub add marionette_flutter

# 4) 앱 실행 후 연결 확인
/marionette connect --uri=ws://127.0.0.1:9101/ws
/marionette smoke --routes=/

• claude mcp list | grep marionette를 실행했을 때 connected가 보이면 등록이 잘 된 것입니다.
• 앱을 flutter run으로 띄우면 화면에 ws://... 로 시작하는 주소가 뜨는데, 이 주소를 위 --uri=에 넣어 줍니다.

안에서 무슨 일이 벌어지나요#

1. MCP 서버 설치 — Marionette MCP를 전역 또는 프로젝트에 깔아 둡니다.
2. Claude Code에 등록 — Claude가 이 서버를 통해 앱과 대화하도록 연결합니다.
3. 앱에 패키지 추가 — 대상 Flutter 앱에 marionette_flutter(필요 시 marionette_logger)를 붙입니다.
4. 초기화 설정 심기 — main.dart에 CoUI 요소를 인식하는 설정을 넣어, 버튼/입력값이 검색 가능해지도록 합니다.
5. 앱 실행 후 주소 복사 — 앱을 띄워 나온 ws://... 주소를 복사합니다.
6. 연결 확인 — connect로 붙고 smoke로 정상 동작과 스크린샷 저장까지 한 번에 점검합니다.

릴리즈 빌드에서는 동작하지 않습니다(개발 모드 전용). Flutter Web은 pub.dev 기준 0.6.0부터 지원 플랫폼에 포함되어 있지만, 이 저장소에서 CoUI Web 조합으로 직접 검증된 적은 아직 없으니 처음엔 한 번 스팟 체크를 권장합니다. CoUI에 새 요소가 생기면 main.dart의 isInteractiveWidget 목록에 추가하고 핫 리로드하면 됩니다. marionette_flutter(앱)와 marionette_mcp(서버)는 같은 저장소에서 lockstep으로 배포되므로, 두 버전이 다르면 connect 시 버전 불일치 오류가 납니다 — 항상 같은 버전(예: ^0.6.0)으로 맞추세요.

# Global tool (recommended — works from anywhere)
dart pub global activate marionette_mcp

# OR project-local dev_dependency
dart pub add dev:marionette_mcp

claude mcp add --transport stdio marionette -- marionette_mcp

cd path/to/your/flutter/app
flutter pub add marionette_flutter
flutter pub add marionette_logger   # if your app uses the `logger` package

flutter run

The Flutter DevTools debugger and profiler on iPhone 15 Pro is available at:
http://127.0.0.1:9101?uri=ws://127.0.0.1:9101/ws

# From any Claude Code session
/marionette connect --uri=ws://127.0.0.1:9101/ws
/marionette smoke --routes=/

[✓] connected
[✓] interactive elements: 14
[✓] screenshot saved: .claude/docs/marionette/ < ts > /screens/00.png