# BeautifulChina MCP

Cursor 用 [MCP](https://modelcontextprotocol.io/) 驱动 `bc_*` 工具，自动化测试 **BeautifulChina** Android App（`adb` + `uiautomator2`）。测试清单见 [`docs/test-checklist.md`](docs/test-checklist.md)。

---

## 安装

```bash
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`

```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/`](docs/screenshots/)）：  
![地区首页](docs/screenshots/p0-launch-home.png) ![省份详情](docs/screenshots/p0-province-detail.png) ![景点详情](docs/screenshots/p0-scenery-detail.png) ![世界遗产](docs/screenshots/p0-unesco-tab.png) ![答题 Hub](docs/screenshots/p0-games-hub.png)

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

---

## License

MIT