#rn-mcp CLI (Snapshot + Refs)

AI 에이전트가 셸에서 직접 React Native 앱을 제어하는 CLI 인터페이스입니다. agent-browser의 Snapshot + Refs 패턴을 적용하여 토큰 효율적인 상호작용을 지원합니다.

#왜 CLI인가?

#설치

CLI는 같은 패키지에 포함되어 있습니다:

# 글로벌 설치
npm install -g @ohah/react-native-mcp-server

# 또는 npx
npx rn-mcp --help

# 또는 프로젝트 로컬
npm install -D @ohah/react-native-mcp-server
npx rn-mcp --help

#전제 조건

• MCP 서버가 실행 중이어야 합니다 (에디터가 시작하거나 npx react-native-mcp-server)
• 앱이 시뮬레이터/에뮬레이터에서 실행 중이고 WebSocket(포트 12300)으로 연결되어야 합니다
• iOS: idb 설치 필요
• Android: adb 설치 필요

#워크플로우

# 1. 연결 확인
rn-mcp status

# 2. interactive 요소를 @ref로 조회
rn-mcp snapshot -i

# 3. @ref로 요소 조작
rn-mcp tap @e3
rn-mcp type @e5 "user@example.com"

# 4. 화면 전환 후 refs 갱신
rn-mcp snapshot -i

#Snapshot 출력 예시

@e1   View #login-screen
@e2     TextInput #email "이메일"
@e3     TextInput #password "비밀번호"
@e4     Pressable #login-btn "로그인"
@e5     Pressable #signup-link "회원가입"

각 요소에 @e1, @e2, ... 순번이 depth-first 순회로 부여됩니다.

#명령어

#연결

#Snapshot

#상호작용

사용 가능한 키: back, home, enter, tab, delete, up, down, left, right

#검증 (Assert)

#조회 (Query)

#스크린샷

#AI 에이전트 가이드 설정

#전역 옵션

-d, --device <id>        대상 디바이스 (다중 연결 시)
-p, --platform <os>      ios 또는 android
--port <n>               WebSocket 포트 (기본: 12300)
--json                   스크립팅용 JSON 출력
--timeout <ms>           명령 타임아웃 (기본: 10000)
-h, --help               도움말
-v, --version            버전 정보

#Refs 시스템

#동작 방식

1. rn-mcp snapshot -i가 각 요소에 @e1, @e2, ... 할당 (depth-first 순회)
2. Refs가 ~/.rn-mcp/session.json에 저장됨
3. 이후 명령에서 refs 사용: rn-mcp tap @e3
4. snapshot을 다시 실행하면 이전 refs 전부 무효화

#언제 re-snapshot 해야 하나

• 화면 전환 후 (네비게이션, 모달 열기/닫기)
• @ref not found 에러 발생 시
• UI 구조가 변경되는 액션 후

#셀렉터 (refs 대안)

snapshot 없이 셀렉터를 직접 사용할 수도 있습니다:

rn-mcp tap "#login-btn"                    # testID로
rn-mcp tap "Pressable:text(\"로그인\")"     # type + text로
rn-mcp tap "TextInput[placeholder=\"이메일\"]"  # 속성으로

#주의사항

• iOS orientation은 자동 처리됩니다 — 별도 조치 불필요
• Android dp→px 변환도 자동입니다
• 좌표는 points(dp) 단위, 픽셀이 아닙니다
• --json 플래그로 프로그래밍 방식의 출력 파싱 가능

#예시: 로그인 플로우

# 연결 확인
rn-mcp status

# 화면 요소 확인
rn-mcp snapshot -i
# @e1   TextInput #email "이메일"
# @e2   TextInput #password "비밀번호"
# @e3   Pressable #login-btn "로그인"

# 폼 입력 및 제출
rn-mcp type @e1 "test@example.com"
rn-mcp type @e2 "password123"
rn-mcp tap @e3

# 네비게이션 확인
rn-mcp assert text "대시보드"

# 새 화면 요소 확인
rn-mcp snapshot -i