cross-dev-mcp

React Native 로컬 개발을 위한 크로스 플랫폼 실기기 디버깅 MCP입니다. V1은 Android, iOS 및 HarmonyOS 실기기를 지원하며, 실시간 연결 상태, 스크린샷/화면, 로그, Doctor, Evidence 및 Codex 컨텍스트 전달을 우선 제공합니다.

전체 설계 및 로드맵은 docs/cross-dev-mcp-design-and-roadmap.md를 참조하세요.

V1 아키텍처

Codex / MCP Host
  ├─ stdio MCP tools
  └─ Vue 3 MCP App
          │ REST + WebSocket
       Hono Daemon
          │ unified TypeScript API
     CrossDevService
       ├─ Android: Tango + Google ADB Server（无 scrcpy）
       ├─ iOS: go-ios（仅真机）
       └─ HarmonyOS: 官方 HDC / UITest / HiLog（仅真机）

기기 기능은 Provider를 통해 구현되며, 애플리케이션 계층은 RuntimeTarget, RawFrame, NormalizedLogRecord 등 통일된 프로토콜만 사용합니다. DOM/요소 검사는 향후 인터페이스 경계만 유지하며, 현재 P0에는 포함되지 않습니다.

Related MCP server: React Native Debug MCP

개발

pnpm install
pnpm dev

pnpm dev는 http://127.0.0.1:4110의 기기 Daemon과 http://127.0.0.1:5173의 Vue/Vite 개발 페이지를 동시에 시작합니다. MCP 프론트엔드는 두 가지 모드로 나뉩니다:

# 调试模式：从 Vite 加载实时源码并启用 HMR
pnpm mcp:dev

# 正式模式：读取 apps/dashboard/dist 构建产物
pnpm build
pnpm mcp

일반적인 검증:

pnpm typecheck
pnpm test
pnpm build

Daemon 기본 주소는 http://127.0.0.1:4110입니다. Dashboard는 독립적으로 열 수 있으며, MCP Apps를 지원하는 Host에서는 MCP tool mobile_open_dashboard를 통해서도 열 수 있습니다.

실기기 없이 UI를 시연해야 하는 경우 임시로 CROSS_DEV_FAKE=1 pnpm dev:daemon을 사용할 수 있습니다. 프로덕션/MCP 시작 시에는 기본적으로 Fake Provider가 등록되지 않습니다.

Codex에 추가

현재 머신에서 stdio MCP를 직접 등록할 수 있습니다:

codex mcp add cross-dev-mcp -- \
  pnpm --silent --dir /Users/didi/VscodeProjects/phone-dev-mcp mcp:dev

위 등록은 로컬 디버깅용으로, Codex MCP App이 Vite 실시간 소스 코드를 직접 로드하도록 합니다. 정식 사용 시末尾의 mcp:dev를 mcp로 변경하세요. Codex MCP 목록을 재시작하거나 새로고침한 후 mobile_open_dashboard를 호출하여 작업 대시보드를 열 수 있습니다. 프로젝트를 다른 디렉터리로 이동한 경우 명령어의 절대 경로도 함께 교체하세요.

각 하위 패키지의 역할, API, 플랫폼 원리 및 검증 명령은 해당 packages/*/README.md를 참조하세요. 모든 공개 및 핵심 구현 메서드는 중국어 JSDoc으로 작성되어 있습니다.

기본적으로 127.0.0.1만 수신합니다. 기기 쓰기 작업, 서명, 설치, 터널 및 권한 상승은 확인 전에는 실행되지 않습니다.