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

한마디로#

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

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

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

무엇을 해주나요#

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

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

마무리되면 Marionette·Dart 는 Claude Code 설정(~/.claude.json 또는 작업공간의 .mcp.json)과 이 플러그인의 plugins/cc-pixel-loop/.mcp.json 에, Figma 는 Figma 공식 플러그인으로 등록됩니다.

어떻게 쓰나요#

# 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://...)를 알려주면 됩니다. Marionette·Dart 는 마지막 claude mcp list 에서 Connected 로 보이면 됩니다. Figma 는 목록으로 확인하지 않습니다 — figma 라는 이름의 서버는 Figma 가 아니어도 Connected 로 보이기 때문입니다. 세션에서 Figma MCP 의 whoami 가 내 Figma 계정을 돌려주고, 맞출 프레임의 get_metadata 가 레이어 목록을 돌려주면 준비 완료입니다. 안 되는 항목이 있으면 해당 단계만 다시 실행하세요.

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

참고: Marionette·Dart 모두 디버그(또는 profile) 빌드에만 붙습니다 — 릴리스 빌드 QA에는 쓸 수 없습니다. 웹(Flutter web)은 이 루프의 대상이 아니며 cc-jaspr-web 을 안내합니다. 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) — Marionette and Dart:
# marionette ✔ Connected
# dart       ✔ Connected