/pixel-loop setup — 픽셀 루프 처음 한 번 준비하기#

한마디로#

디자인(Figma)과 실제 앱 화면을 픽셀 단위로 맞추는 작업을 시작하기 전에, 필요한 도구 3종을 한 번에 설치하고 연결하는 초기 세팅 단계입니다. 새 작업실에 들어가서 책상, 모니터, 전화선을 한꺼번에 깔아두는 것과 같아요. 한 번만 해두면 됩니다.

누가·언제 쓰나요#

• 픽셀 퍼펙트 루프(디자인과 앱 화면을 똑같이 맞추는 작업)를 처음 시작하는 사람
• 새 컴퓨터·새 작업 환경에서 도구가 아직 연결되어 있지 않을 때

👉 이미 한 번 해뒀어도 다시 실행해도 안전합니다(중복 설치되지 않음). 도구 연결이 끊겼을 때 다시 맞추는 용도로도 씁니다.

무엇을 해주나요#

Claude Code에 세 가지 도구(MCP 서버)를 설치하고 연결해 줍니다.

• Figma MCP — 디자인 파일을 읽어오는 통로
• Marionette MCP — 실행 중인 앱 화면을 조작하고 스크린샷을 찍는 도구 (cc-marionette 플러그인과 같은 서버를 씁니다 — 이미 등록했다면 그대로 재사용됩니다)
• Dart MCP — 실행 중인 Flutter 앱과 대화하는 연결선

마무리되면 이 세 항목이 Claude Code 전역 설정(~/.claude.json 또는 작업공간의 .mcp.json)에 등록됩니다. 저장소에도 plugins/cc-pixel-loop/.mcp.json이 함께 들어 있어, 저장소를 내려받는 누구나 같은 연결을 쓸 수 있습니다.

어떻게 쓰나요#

# 1) Figma 플러그인 설치
claude plugin install figma@claude-plugins-official

# 2) Marionette 설치 + 등록
dart pub global activate marionette_mcp
claude mcp add marionette -- marionette_mcp

# 3) Dart MCP 등록
claude mcp add dart -- dart mcp-server

# 4) 잘 붙었는지 최종 확인
claude mcp list

Figma는 설치 후 Claude Code 안에서 /mcp를 실행해 figma 서버를 고르고, 자동으로 열리는 브라우저에서 로그인(OAuth)을 마치면 연결됩니다. Marionette는 앱에 marionette_flutter 패키지를 추가하고 디버그 모드에서 MarionetteBinding.ensureInitialized()를 호출해야 붙습니다. Dart는 앱을 flutter run --print-dtd로 실행할 때 콘솔에 찍히는 연결 주소(ws://...)를 알려주면 됩니다. 마지막 claude mcp list에서 세 서버가 모두 connected로 보이면 준비 완료입니다. 끊긴 항목이 있으면 해당 단계만 다시 실행하세요.

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

1. Figma 연결 — Figma 플러그인을 설치하고, 브라우저 로그인으로 디자인 읽기 권한을 받아옵니다.
2. Marionette 연결 — Marionette 도구를 설치해 Claude Code에 화면 조작·촬영 도구로 등록하고, 앱 쪽에 디버그 전용 바인딩을 넣습니다.
3. Dart 연결 — 실행 중인 Flutter 앱과 이어주는 Dart 도구를 등록하고, 앱이 알려준 연결 주소로 연결합니다.
4. 최종 점검 — 세 도구가 모두 정상 연결됐는지 한눈에 확인하고, 끊긴 게 있으면 그 부분만 다시 맞춥니다.

참고: Marionette·Dart 모두 디버그(또는 profile) 빌드에만 붙습니다 — 릴리스 빌드 QA에는 쓸 수 없습니다. 웹(Flutter web)은 이 루프의 대상이 아니며 cc-jaspr-web 또는 cc-flutter:figma:analyze의 Playwright 경로를 안내합니다. iOS·Android 실제 기기를 쓸 때는 기기와 컴퓨터가 같은 네트워크에 있거나 USB 디버깅이 켜져 있어야 합니다.

# Install the official Figma plugin for Claude Code
claude plugin install figma@claude-plugins-official

# Marionette MCP server (LeanCode)
dart pub global activate marionette_mcp

# Verify
marionette_mcp --version

# Register as an MCP for Claude Code
claude mcp add marionette -- marionette_mcp

flutter pub add marionette_flutter

// main.dart
if (kDebugMode) {
  MarionetteBinding.ensureInitialized();
}

# Register
claude mcp add dart -- dart mcp-server

flutter run --print-dtd

The Dart Tooling Daemon is listening on ws://127.0.0.1:54321/abc123token

claude mcp list
# expected (subset):
# figma      ✓ connected
# marionette ✓ connected
# dart       ✓ connected