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。

开发

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 中打开。

当前 Codex 不提供普通网页预填对话输入框的公开接口。独立 Dashboard 在框选备注按 Enter 确认后，会把标注截图、所选日志和说明保存到系统临时目录，并只将一个指向 evidence.md 的 [cross-dev-mcp 证据] 链接写入系统剪贴板。复制成功后清空全部框选，并显示“证据已复制，可粘贴到 Codex 输入框”Toast。临时 Evidence 默认只保留最近 50 份。

需要在没有真机时演示 UI，可临时使用 CROSS_DEV_FAKE=1 pnpm dev:daemon；生产/MCP 启动默认不注册 Fake Provider。

添加到 Codex

正式版本可从 npm 安装并注册：

npm install --global cross-dev-mcp
codex mcp add cross-dev-mcp -- cross-dev-mcp

也可以不全局安装，直接使用 npx：

codex mcp add cross-dev-mcp -- npx --yes cross-dev-mcp@latest

在 Codex 中打开

注册或更新 MCP 后重启 Codex，然后在对话中要求“打开 cross-dev-mcp 真机调试工作台”。Codex 会调用 mobile_open_dashboard，并在右侧打开内嵌 MCP App 面板。

不要把 http://127.0.0.1:4110 作为可长期保留的 Codex 面板入口：该地址只在 MCP Daemon 运行期间有效。如果旧的独立浏览器页显示 ERR_CONNECTION_REFUSED，关闭旧页面并重新调用 mobile_open_dashboard 即可。

一键构建并发布：

pnpm release

脚本会自动选择可发布版本，检查 npm 登录状态并执行完整测试与构建。验证通过后，它只提交根 package.json 的版本变化，提交信息为 release: 更新版本至 x.y.z，再隐藏输入 6 位 OTP，发布后自动回查 Registry。其他工作区或暂存区改动不会进入该提交；如果 package.json 除 version 外还有改动，流程会终止。脚本不会自动打标签或推送 Git。

只验证流程但不修改版本、不创建 Git 提交、不请求 OTP、不发布：

pnpm release -- --dry-run

也可以单独运行 pnpm release:check，它会执行完整检查、生成生产 Dashboard、构建 npm 可执行文件并预览最终包内容。

提交信息规范

提交信息采用 Conventional Commits 风格并使用英文半角冒号：用户可见的新能力使用 feat: 中文摘要，问题修复使用 fix: 中文摘要，重构、文档、测试和工程调整分别使用 refactor:、docs:、test:、chore:；版本号及发布元数据变更统一使用 release: 更新版本至 x.y.z。

本地源码调试

在当前机器上可直接注册 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。设备写操作、签名、安装、隧道和提权不会在未确认时执行。