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 フロントエンドは2つのモードに分かれています：

# 调试模式：从 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 のみをリッスンします。デバイスへの書き込み操作、署名、インストール、トンネル、権限昇格は、確認なしでは実行されません。