v0.4.0 — Phase 3（执行预算按 MCP session 细化 + eval 超时 + SoM 通路 + OCR 去重）

Android Phone MCP Server v0.4.0（阶段 3 收尾优化）

在 v0.3.0（18 工具）基础上完成 6 项收口优化。

新增能力

• 执行预算按 MCP session 细化：多客户端预算隔离（session_id 键控 + 进程级兜底）；超限错误含 session 标识；reset_session(session_id?) 按 session 重置
• 计费时序修正：无效调用（目标未命中/歧义/非法参数）不再消耗预算
• eval runner 超时强制：per-task 看门狗，超时标记 timeout 并继续后续任务
• SoM 通路激活：locate 流程 SoM 编号截图优先（失败降级无编号）
• smart_scroll OCR 跨页去重：同文本跨视口仅计一次
• diff_state 冷缓存确认单帧

质量

• 160 单测 + 27 真机探针全绿（+12 新测试）
• 代码评审 R1 PASS WITH NOTES（0 BLOCKER）

安装

pip install android-phone-mcp[ocr,vlm]   # PyPI 发布后

v0.3.0 — Phase 2（VLM 视觉融合 + 执行预算 + 增量 diff + AndroidWorld 评测）

Android Phone MCP Server v0.3.0（阶段 2 完整版）

在 v0.2.0（16 工具）基础上补齐第三感知层与护栏。

18 个 MCP 工具（16→18）

既有 16 工具 + reset_session（清快照缓存 + 重置预算）+ locate（VLM 视觉定位）

新增能力

• VLM 视觉 grounding（第三感知层）：树 → OCR → VLM 三级降级；[vlm] extra（openai 客户端，OpenAI 兼容端点 + SoM 编号截图）；vlm- 伪元素共享 id 空间；tap/type_text 前 VLM 重确认（VLM_STALE）
• 执行预算：进程级动作数/时长上限（ANDROID_MCP_BUDGET_MAX_ACTIONS/SECONDS，默认关）；超限 EXECUTION_BUDGET_EXCEEDED；reset_session 恢复
• 增量 diff：diff_state 与缓存上一快照增量对比
• AndroidWorld 子集评测：python -m eval.runner（3 样例任务真机 3/3 PASS）
• PyPI 就绪：twine check 通过（实际发布待 token）

质量

• 148 单测 + 27 真机探针全绿（OPPO PKT110 / Android 16）
• 代码评审 2 轮闭环（BLOCKER 修复后 PASS）

安装

pip install android-phone-mcp[ocr,vlm]   # PyPI 发布后；ocr/vlm 可选 extra

v0.2.0 — Phase 1（OCR 融合感知 + 校验工具集 + 多设备并行）

Android Phone MCP Server v0.2.0（阶段 1 通用性）

在 v0.1.0（Phase 0，12 工具）基础上补齐融合感知与校验工具。

16 个 MCP 工具（12→16）

list_devices get_device_info get_screen get_screen_hash tap swipe scroll_page type_text scroll_until open_app open_settings press_key + wait_for verify_element diff_state smart_scroll

新增能力

• OCR 融合感知：树失效（Flutter/Unity/游戏）自动 OCR 兜底（rapidocr_onnxruntime，[ocr] extra 可关）；ocr- 伪元素共享 id 空间；tap 前重确认位置（OCR_STALE）
• 校验工具：wait_for（出现/消失/超时）、verify_element（结构化布尔）、diff_state（stable-id diff）、smart_scroll（滚动聚合 + OCR 感知）
• 多设备并行：per-serial 锁，并发调用互不串扰

质量

• 114 单测 + 15 真机探针全绿（OPPO PKT110 / Android 16）
• 代码评审 2 轮闭环（BLOCKER 修复后 PASS）

安装

pip install android-phone-mcp[ocr]   # PyPI 发布后；ocr extra 含识别引擎

v0.1.0 — Phase 0 MVP

Android Phone MCP Server v0.1.0 (Phase 0 MVP)

代码 Agent 无关的 Android 控制 MCP Server：语义动作 + 验证闭环 + 融合感知。

12 个 MCP 工具

list_devices get_device_info get_screen get_screen_hash tap swipe scroll_page type_text scroll_until open_app open_settings press_key

核心能力

• 语义选择器（text/desc/id）+ SELECTOR_AMBIGUOUS 消歧，坐标仅服务端传递
• 动作后验证证据三件套 {executed, screen_changed, changed_elements[], screen_hash}
• 滚动优化：末尾检测（reached_end）、原生一屏滚动、scroll_page 工具
• 默认只读 + 双通道 30s 超时 + 注入防护；结构化错误直达客户端
• 设备池 serial 隔离 + 懒加载；紧凑 text 快照（summary ~14x 压缩）+ 稳定元素 id

质量

• 93 测试全绿（80 单测 + 13 真机探针，OPPO PKT110 / Android 16）
• 代码评审 3 轮闭环（0 BLOCKER）

安装

pip install android-phone-mcp   # PyPI 发布后
# 或本地: uv pip install dist/android_phone_mcp-0.1.0-py3-none-any.whl