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 tool mobile_open_dashboard 在支持 MCP Apps 的 Host 中打开。

需要在没有真机时演示 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。设备写操作、签名、安装、隧道和提权不会在未确认时执行。