feat: rn-mcp CLI with Snapshot + Refs pattern

.github/workflows/e2e-android.yml

@@ -63,7 +63,7 @@ jobs:
 
       - name: 디스크 공간 확보
         run: |
-          sudo apt-get remove -y '^dotnet-.*' 'php.*' '^mongodb-.*' '^mysql-.*' azure-cli google-chrome-stable firefox powershell mono-devel libgl1-mesa-dri
+          sudo apt-get remove -y '^dotnet-.*' 'php.*' '^mongodb-.*' '^mysql-.*' azure-cli google-chrome-stable firefox powershell mono-devel
           sudo apt-get autoremove -y
           sudo apt-get clean
           sudo rm -rf /usr/share/dotnet/ /usr/local/graalvm/ /usr/local/.ghcup/ /usr/local/share/powershell /usr/local/share/chromium
@@ -152,14 +152,21 @@ jobs:
           mkdir -p examples/demo-app/android/app/build/outputs/apk/release
           cp "${{ runner.temp }}/e2e-app-cache/android/app-release.apk" examples/demo-app/android/app/build/outputs/apk/release/
 
+      - name: Android SDK PATH 설정 및 adb 시작
+        run: |
+          echo "$ANDROID_HOME/platform-tools" >> $GITHUB_PATH
+          echo "$ANDROID_HOME/emulator" >> $GITHUB_PATH
+          $ANDROID_HOME/platform-tools/adb start-server
+          $ANDROID_HOME/platform-tools/adb devices
+
       - name: AVD 캐시
         uses: actions/cache@v4
         id: avd-cache
         with:
           path: |
             ~/.android/avd/*
             ~/.android/adb*
-          key: avd-${{ steps.avd.outputs.name }}-1080x1920-ram4096-v3
+          key: avd-${{ steps.avd.outputs.name }}-1080x1920-ram4096-v4
 
       - name: AVD 스냅샷 생성 (캐시 미스 시)
         if: steps.avd-cache.outputs.cache-hit != 'true'
@@ -173,6 +180,7 @@ jobs:
           heap-size: 2048M
           force-avd-creation: false
           emulator-options: -no-window -skin 1080x1920 -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none -cores 4
+          emulator-boot-timeout: 600
           disable-animations: false
           script: echo "Generated AVD snapshot for caching."
 
@@ -188,6 +196,7 @@ jobs:
           heap-size: 2048M
           force-avd-creation: false
           emulator-options: -no-snapshot-save -no-window -skin 1080x1920 -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none -cores 4
+          emulator-boot-timeout: 600
           disable-animations: true
           script: |
             echo "=== Connected Android devices (adb devices -l) ==="
@@ -232,6 +241,16 @@ jobs:
             E2E_CMD="node packages/react-native-mcp-server/dist/test/cli.js run examples/demo-app/e2e/all-steps.yaml -p android -o e2e-artifacts/yaml-results --no-auto-launch"
             $E2E_CMD || { echo "--- E2E 1차 실패, 재시도 ---"; sleep 5; $E2E_CMD; }
 
+            # CLI (rn-mcp) E2E smoke test
+            echo ""
+            echo "=== CLI (rn-mcp) E2E smoke test ==="
+            # YAML 테스트 후 앱 재시작
+            adb shell am force-stop com.reactnativemcp.demo
+            sleep 2
+            adb shell monkey -p com.reactnativemcp.demo -c android.intent.category.LAUNCHER 1
+            sleep 8
+            bash examples/demo-app/e2e/cli-smoke.sh --platform android
+
       - name: 실패 시 스크린샷·로그 저장
         if: failure()
         timeout-minutes: 2

.github/workflows/e2e-ios.yml

@@ -248,6 +248,19 @@ jobs:
           max_attempts: 2
           command: node packages/react-native-mcp-server/dist/test/cli.js run examples/demo-app/e2e/all-steps.yaml -p ios -o e2e-artifacts/yaml-results --no-auto-launch
 
+      - name: CLI (rn-mcp) E2E smoke test
+        if: success()
+        timeout-minutes: 5
+        env:
+          REACT_NATIVE_MCP_TAP_TIMEOUT_MS: 25000
+        run: |
+          # YAML 테스트 후 앱이 마지막 화면에 있으므로 재시작
+          xcrun simctl terminate booted org.reactnativemcp.demo 2>/dev/null || true
+          sleep 2
+          xcrun simctl launch booted org.reactnativemcp.demo 2>/dev/null || true
+          sleep 8
+          bash examples/demo-app/e2e/cli-smoke.sh --platform ios
+
       - name: 실패 시 스크린샷·로그 저장
         if: failure()
         timeout-minutes: 2

.github/workflows/test.yml

@@ -46,3 +46,21 @@ jobs:
 
       - name: 테스트 실행
         run: bun run test:unit
+
+      - name: CLI smoke test
+        run: |
+          node packages/react-native-mcp-server/dist/cli.js --version
+          node packages/react-native-mcp-server/dist/cli.js --help | grep -q "WORKFLOW"
+          echo "✓ CLI --help and --version work"
+
+      - name: CLI init-agent test
+        run: |
+          cd "$(mktemp -d)"
+          node "$GITHUB_WORKSPACE/packages/react-native-mcp-server/dist/cli.js" init-agent --lang en
+          grep -q "rn-mcp snapshot" AGENTS.md
+          grep -q "rn-mcp snapshot" CLAUDE.md
+          # 한국어로 교체
+          node "$GITHUB_WORKSPACE/packages/react-native-mcp-server/dist/cli.js" init-agent --lang ko
+          grep -q "연결 확인" AGENTS.md
+          grep -q "연결 확인" CLAUDE.md
+          echo "✓ init-agent creates and updates guide files"

AGENTS.MD

@@ -116,3 +116,58 @@ bun run format       # oxfmt
 - [E2E YAML Reference](document/docs/en/testing/e2e-yaml-reference.md) — YAML scenario syntax and steps
 - Runner: `packages/react-native-mcp-server/src/e2e/`
 - Config: `e2e.yaml` at project root
+
+---
+
+## CLI (rn-mcp) — AI 에이전트 권장 인터페이스
+
+셸 접근이 가능한 AI 에이전트(Claude Code, Codex 등)는 MCP 도구 대신 `rn-mcp` CLI를 사용하세요.
+Snapshot + Refs 패턴으로 토큰 소비를 크게 절감합니다.
+
+### 필수 워크플로우
+
+```bash
+# 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. 화면이 바뀌었으면 snapshot 재호출
+rn-mcp snapshot -i
+```
+
+### 핵심 규칙
+
+1. **snapshot -i를 먼저** — 앱 화면을 모르는 상태에서 tap하지 마세요
+2. **화면 전환 후 snapshot 재호출** — 탭 후 화면이 바뀌면 기존 refs는 무효
+3. **ref "not found" = snapshot 필요** — `✗ @e3 not found` 에러 시 `rn-mcp snapshot -i`
+4. **스크린샷보다 assert** — `rn-mcp assert text "Welcome"`이 스크린샷보다 토큰 절약
+5. **iOS orientation 자동 처리** — CLI가 내부적으로 좌표 변환 (별도 조치 불필요)
+
+### 명령어 빠른 참조
+
+| 명령 | 용도 |
+|------|------|
+| `rn-mcp status` | 연결 상태 확인 |
+| `rn-mcp snapshot -i` | interactive 요소 + @ref 할당 |
+| `rn-mcp tap @e3` | 탭 |
+| `rn-mcp tap @e3 --long 500` | 롱프레스 |
+| `rn-mcp type @e5 "텍스트"` | 텍스트 입력 |
+| `rn-mcp swipe @e2 down` | 스와이프 |
+| `rn-mcp key back` | 하드웨어 키 (back, home, enter) |
+| `rn-mcp assert text "Welcome"` | 텍스트 존재 확인 |
+| `rn-mcp assert visible @e3` | 가시성 확인 |
+| `rn-mcp query "#btn"` | 요소 조회 |
+| `rn-mcp screenshot -o s.png` | 스크린샷 |
+
+### CLI vs MCP 선택 기준
+
+- **CLI 가능** (Claude Code, Codex 등) → `rn-mcp` CLI 사용 (토큰 효율)
+- **CLI 불가** (Cursor, Windsurf 등 MCP만 지원) → 기존 MCP 도구 사용
+
+자세한 사용법: `rn-mcp --help`