# cross-dev-mcp

面向 React Native 本地开发的跨平台真机调试 MCP。V1 支持 Android、iOS 与 HarmonyOS 真机，优先提供实时连接状态、截图/画面、日志、Doctor、Evidence 和 Codex 上下文回传。

完整设计和路线图见 [`docs/cross-dev-mcp-design-and-roadmap.md`](docs/cross-dev-mcp-design-and-roadmap.md)。

## V1 架构

```text
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。

## 开发

```bash
pnpm install
pnpm dev
```

`pnpm dev` 会同时启动 `http://127.0.0.1:4110` 的设备 Daemon 与 `http://127.0.0.1:5173` 的 Vue/Vite 开发页面。MCP 前端分为两种模式：

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

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

常用验证：

```bash
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 安装并注册：

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

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

```bash
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` 即可。

一键构建并发布：

```bash
pnpm release
```

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

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

```bash
pnpm release -- --dry-run
```

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

### 提交信息规范

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

### 本地源码调试

在当前机器上可直接注册 stdio MCP：

```bash
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`。设备写操作、签名、安装、隧道和提权不会在未确认时执行。