BeautifulChina MCP

Cursor 用 MCP 驱动 bc_* 工具，自动化测试 BeautifulChina Android App（adb + uiautomator2）。测试清单见 docs/test-checklist.md。

---

安装

git clone git@github.com:shuaici/BeautifulChinaMCP.git
cd BeautifulChinaMCP
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
adb devices   # 确认手机已连接

环境：macOS/Linux · Python 3.10–3.12 · adb · 手机已装 com.kuen.beautifulchina · USB 调试已开。

---

配置 Cursor

command 用 venv 里 python3 的绝对路径，args 指向 server.py 绝对路径。改完重启 Cursor。

项目级（推荐）：BeautifulChina/.cursor/mcp.json

全局：~/.cursor/mcp.json

{
  "mcpServers": {
    "beautiful-china": {
      "command": "/path/to/BeautifulChinaMCP/.venv/bin/python3",
      "args": ["/path/to/BeautifulChinaMCP/server.py"],
      "env": {
        "BC_SCREENSHOT_DIR": "~/Downloads/BC",
        "BC_DEVICE_ID": ""
      }
    }
  }
}

环境变量	说明
BC_SCREENSHOT_DIR	截图目录，默认 ~/Downloads/BC
BC_DEVICE_ID	多设备时填序列号，留空自动选第一台

对 Agent 说 「按清单测一遍」 → 默认 快速模式 + P0（bc_assert_text 判定，失败才截图）。要说 「完整模式」 才每步截图。

---

工具

工具	说明
bc_launch / bc_terminate	启停 App
bc_screenshot	截图，name 为文件名前缀
bc_list_elements	列元素，返回 activity；include_non_clickable=true 含文字
bc_click	text / resource_id / 坐标点击
bc_wait / bc_assert_text	等待 / 断言文字
bc_swipe / bc_press_back	滑动 / 返回
bc_device_info / bc_setup	设备健康检查 / 初始化（通常自动）

---

常见问题

现象	处理
点击无反应，bc_click 失败并带 manual_steps	小米开 USB 调试（安全设置）；验证 adb shell input tap 500 500 不报错
adb devices 空 / unauthorized	换线重插、手机点允许、adb kill-server && adb start-server
看不到省份名文字	bc_list_elements include_non_clickable=true
MCP 红灯	检查 mcp.json 绝对路径、venv 已 pip install
Python 3.14 装依赖失败	改用 3.12 重建 venv

---

P0 实测（2026-07-20，小米 MIUI）

8/8 通过（启动 · 地区 · 省份 · 景点 · 返回 · 世界遗产 · 答题 · 我的）

截图（docs/screenshots/）：
<div style="display: flex; flex-wrap: wrap; gap: 8px;"> <img src="docs/screenshots/p0-launch-home.png" width="150" alt="地区首页" /> <img src="docs/screenshots/p0-province-detail.png" width="150" alt="省份详情" /> <img src="docs/screenshots/p0-scenery-detail.png" width="150" alt="景点详情" /> <img src="docs/screenshots/p0-unesco-tab.png" width="150" alt="世界遗产" /> <img src="docs/screenshots/p0-games-hub.png" width="150" alt="答题 Hub" /> </div>

运行时截图带时间戳写入 ~/Downloads/BC/。

---

License

MIT