Android MCP Lab 0.1.3

Android MCP Lab 是面向 Codex 的 Windows Android Studio 模拟器控制层，派生自 danielealbano/android-remote-control-mcp v1.11.1 Companion。上游版本、固定提交、APK/证书 SHA-256、许可证和本地改动范围见 UPSTREAM.md。

稳定公开线提供受 lease 约束的本机模拟器控制链：

• 57 个固定版本的上游 Android 工具；

• 6 个 Global Lab 管理工具，用于设备发现、lease、启动、停止和状态查询；

• 稳定 android_lab catalog 共 63 个工具；

• canonical ty-android-mcp v0.2.0 自愈式 Skill。

Broker、stdio proxy、registry 和 Supervisor 仅在当前 Windows 用户环境内运行。本项目不修改 Android 系统镜像或业务应用源码。

版本与能力边界

稳定线不包含实时模拟器视频。Mirror 预览只有在真实 Codex Browser WebRTC 首帧、持续播放、断线处理、TTL 到期和 lease 清理全部通过后，才可能升级为正式能力。

publicHeadInstallParity=pending 表示公开源码 HEAD 包含 0.1.3 维护性修订，但不能据此推断任意电脑上的 install\0.1.3 已同步到相同内容。使用者应通过 release 对应提交、manifest 和 SHA-256 确认实际安装版本。

Related MCP server: Universal Tools

从源码构建

环境要求：

• Windows 10/11 x64；

• PowerShell 7；

• Node.js 与 npm；

• 运行时需要 Android Studio、Android SDK、Android Emulator 和可用的 x86_64 虚拟化环境。

在仓库根目录执行：

npm ci
npm run typecheck
npm run build
npm run build:bundle:dry-run
node .\tests\vnext-contract.mjs
pwsh -File .\tests\status-contract.ps1

这些命令只构建和验证 host 源码，不会启动 AVD、获取 lease、注册 Codex 或读取凭据。安装流程见 START_HERE_FOR_CODEX.md 和 docs/INSTALL.md。

基本运行流程

全局 MCP 名称为 android_lab：

android_lab_devices
android_lab_acquire(codex_api36)
android_lab_status
android_lab_start(codex_api36)  # 仅当 status 不是 ready
android_lab_get_screen_state
android_lab_release(codex_api36)

android_lab_status 是 readiness 的权威来源。只有 bootCompleted=true 不代表可用；ADB 和 Companion 也必须 ready。每次 UI 写操作后必须重新读取 fresh screen state，状态变化后不得复用旧 node id。

设备与控制边界

• 只允许已登记的本机 Android Studio 模拟器。

• 普通自动化拒绝真机、局域网端点、未知 transport、禁用 AVD，以及标记为 contains-credentials 或 preserve 的设备。

• 不支持以 scrcpy、VNC、MJPEG、WebSocket 帧流、独立 ADB 或局域网控制作为旁路或降级方案。

• 所有副作用操作必须绑定有效 lease，并在成功、失败、取消和超时时执行 finally-style release。

源码与发行资产

Git 跟踪 host/Skill 源码、脚本、测试、文档、manifest、SHA-256 sidecar 和脱敏验证记录。以下内容不进入 Git：

• ZIP、APK、bundled Node、node_modules；

• AVD snapshot、runtime staging；

• Broker state、lease、session、日志和配置备份；

• 凭据、DPAPI 数据和私密内容。

历史 0.1.2/0.1.3 ZIP 保持原内容和 SHA-256，不由维护性提交静默重定义。后续二进制应作为 GitHub Release 资产发布，并绑定准确提交、manifest 和 SHA-256 sidecar。

安全

API Key、OAuth、Authorization、Worker Key、DPAPI、Broker/lease token、私密会话正文、敏感 UI tree、图片字节和敏感截图不得进入源码、日志、验证证据或发行资产。完整规则见 SECURITY.md。

English Summary

Android MCP Lab 0.1.3 is a Windows/Codex host layer for registered local Android Studio emulators. The stable catalog has 63 tools and uses the ty-android-mcp v0.2.0 Skill. The separate 66-tool Mirror branch remains PROTOCOL_MOCK_ONLY. Physical devices, LAN control, scrcpy, VNC, and independent-ADB bypasses are out of scope. Binary assets and machine state are not stored in Git. publicHeadInstallParity remains pending; verify release assets against their exact commit, manifest, and SHA-256 before installation.