# Cursor MCP 配置指南

## 🎯 在 Cursor 中使用 Mobile MCP 的优势

将 `mobile_mcp` 封装为 MCP 服务后，你可以在 Cursor 中直接使用 AI 来控制 Android 手机，享受以下优势：

### ✨ 核心优势

1. **🤖 AI 智能理解**
   - Cursor 的 AI 可以理解自然语言指令
   - 例如："帮我测试登录功能" → AI 自动调用 `mobile_click("登录按钮")`、`mobile_input("用户名", "admin")` 等
   - **不需要写代码**，直接用自然语言描述测试流程

2. **🧠 上下文感知**
   - Cursor AI 可以记住之前的操作
   - 如果点击失败，AI 会自动调用 `mobile_snapshot` 分析页面结构
   - AI 会根据错误信息智能调整策略（如尝试视觉识别）

3. **🔄 自动重试和优化**
   - AI 可以自动处理弹窗、等待页面加载等复杂场景
   - 失败时自动尝试替代方案（如从 XML 定位降级到视觉识别）

4. **📝 代码生成**
   - AI 可以根据你的自然语言描述生成完整的测试代码
   - 例如："帮我写一个测试，点击云文档，然后点击我的空间"
   - AI 会自动生成 pytest 测试用例

5. **🔍 智能调试**
   - 测试失败时，AI 可以分析日志、截图、页面结构
   - 自动定位问题并提供解决方案

### 📊 对比：直接使用 vs Cursor MCP

| 特性 | 直接使用 Python 脚本 | Cursor MCP |
|------|---------------------|-----------|
| **编写测试** | 需要写代码 | 自然语言描述 |
| **调试** | 手动分析日志 | AI 自动分析 |
| **错误处理** | 手动处理 | AI 智能重试 |
| **代码生成** | 手动编写 | AI 自动生成 |
| **上下文理解** | 无 | AI 记住历史 |
| **学习曲线** | 需要学习 API | 自然语言即可 |

---

## 🚀 快速配置

### 步骤 1：安装依赖

```bash
cd /Users/mac/Desktop/douzi-ai/backend/mobile_mcp
pip install -r requirements.txt
```

### 步骤 2：配置 Cursor

在项目根目录创建 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "mobile-automation": {
      "command": "python",
      "args": [
        "backend/mobile_mcp/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": ".",
        "MOBILE_DEVICE_ID": "auto"
      }
    }
  }
}
```

**注意**：
- `PYTHONPATH` 设置为项目根目录（`.`）
- `MOBILE_DEVICE_ID` 设置为 `"auto"` 会自动选择第一个连接的设备

### 步骤 3：重启 Cursor

配置完成后，重启 Cursor IDE，MCP Server 会自动启动。

### 步骤 4：验证配置

在 Cursor 中打开聊天窗口，输入：

```
帮我查看当前手机页面结构
```

AI 应该会自动调用 `mobile_snapshot` 工具。

---

## 💡 使用示例

### 示例 1：自然语言测试

**你：**
```
帮我测试登录功能：
1. 启动 com.im30.mind 应用
2. 点击登录按钮
3. 输入用户名 "admin"
4. 输入密码 "123456"
5. 点击提交按钮
6. 验证页面是否显示"欢迎"
```

**AI 会自动：**
- 调用 `mobile_launch_app("com.im30.mind")`
- 调用 `mobile_click("登录按钮")`
- 调用 `mobile_input("用户名输入框", "admin")`
- 调用 `mobile_input("密码输入框", "123456")`
- 调用 `mobile_click("提交按钮")`
- 调用 `mobile_assert_text("欢迎")`

### 示例 2：智能调试

**你：**
```
为什么点击"云文档"失败了？
```

**AI 会自动：**
1. 调用 `mobile_snapshot` 查看当前页面结构
2. 分析为什么找不到"云文档"元素
3. 可能发现是弹窗场景，建议使用视觉识别
4. 自动调用 `mobile_click` 并降级到视觉识别

### 示例 3：代码生成

**你：**
```
帮我生成一个 pytest 测试用例，测试云文档发帖功能
```

**AI 会自动：**
- 生成完整的 pytest 测试代码
- 包含 Allure 报告支持
- 包含错误处理和重试逻辑

---

## 🛠️ 可用的 MCP Tools

配置完成后，Cursor AI 可以使用以下工具：

| Tool | 说明 | 示例 |
|------|------|------|
| `mobile_click` | 点击元素 | `mobile_click({"element_desc": "登录按钮"})` |
| `mobile_input` | 输入文本 | `mobile_input({"element_desc": "用户名", "text": "admin"})` |
| `mobile_swipe` | 滑动屏幕 | `mobile_swipe({"direction": "up"})` |
| `mobile_snapshot` | 获取页面结构 | `mobile_snapshot({})` |
| `mobile_launch_app` | 启动应用 | `mobile_launch_app({"package_name": "com.im30.mind"})` |
| `mobile_assert_text` | 断言文本 | `mobile_assert_text({"text": "欢迎"})` |
| `mobile_get_current_package` | 获取当前应用 | `mobile_get_current_package({})` |

---

## 🎨 高级用法

### 自定义设备 ID

如果有多台设备，可以指定设备 ID：

```json
{
  "mcpServers": {
    "mobile-automation": {
      "command": "python",
      "args": ["backend/mobile_mcp/mcp_server.py"],
      "env": {
        "PYTHONPATH": ".",
        "MOBILE_DEVICE_ID": "emulator-5554"  // 指定设备ID
      }
    }
  }
}
```

### 调试模式

如果遇到问题，可以查看 MCP Server 的日志：

MCP Server 的输出会显示在 Cursor 的 MCP 日志中（通常在 Cursor 的设置中可以看到）。

---

## ❓ 常见问题

### Q: MCP Server 启动失败？

**A:** 检查：
1. Python 环境是否正确（`python --version`）
2. 依赖是否安装（`pip install -r requirements.txt`）
3. 设备是否连接（`adb devices`）

### Q: AI 不调用 MCP Tools？

**A:** 
1. 确保已重启 Cursor
2. 检查 `.cursor/mcp.json` 配置是否正确
3. 尝试明确告诉 AI："使用 mobile_click 工具点击登录按钮"

### Q: 如何查看 MCP Server 日志？

**A:** 在 Cursor 设置中查找 "MCP" 或 "Model Context Protocol" 相关设置，查看日志输出。

---

## 🎉 总结

通过将 `mobile_mcp` 封装为 MCP 服务，你可以：

✅ **用自然语言控制手机** - 不需要写代码  
✅ **AI 智能调试** - 自动分析问题  
✅ **自动生成测试代码** - 提高效率  
✅ **上下文感知** - AI 记住历史操作  
✅ **智能重试** - 自动处理复杂场景  

**这就是 Cursor MCP 的强大之处！** 🚀

