cross-dev-mcp

Cross-platform real-device debugging MCP for React Native local development. V1 supports Android, iOS, and HarmonyOS real devices, prioritizing real-time connection status, screenshots/frames, logs, Doctor, Evidence, and Codex context callbacks.

See the full design and roadmap in docs/cross-dev-mcp-design-and-roadmap.md.

V1 Architecture

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（仅真机）

Device capabilities are implemented through Provider, and the application layer only uses unified protocols such as RuntimeTarget, RawFrame, and NormalizedLogRecord. DOM/element inspection only retains the future interface boundary and is not part of the current P0.

Related MCP server: React Native Debug MCP

Development

pnpm install
pnpm dev

pnpm dev starts both the device Daemon at http://127.0.0.1:4110 and the Vue/Vite development page at http://127.0.0.1:5173. The MCP frontend has two modes:

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

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

Common verification:

pnpm typecheck
pnpm test
pnpm build

The Daemon default address is http://127.0.0.1:4110. The Dashboard can be opened independently, and can also be opened in Hosts that support MCP Apps via the MCP tool mobile_open_dashboard.

To demo the UI without a real device, you can temporarily use CROSS_DEV_FAKE=1 pnpm dev:daemon; production/MCP startup does not register the Fake Provider by default.

Adding to Codex

You can register the stdio MCP directly on the current machine:

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

The registration above is for local debugging and lets the Codex MCP App load the Vite live source directly. For production use, change mcp:dev at the end to mcp. After restarting or refreshing the Codex MCP list, you can call mobile_open_dashboard to open the workbench. If the project moves to another directory, update the absolute path in the command accordingly.

See the corresponding packages/*/README.md for each subpackage's responsibilities, APIs, platform principles, and verification commands; all public and key implementation methods use Chinese JSDoc.

Only 127.0.0.1 is listened on by default. Device write operations, signing, installation, tunneling, and privilege escalation are not executed without confirmation.