# AutoBot MCP

[Python Version](https://www.python.org/downloads/)
[MCP](https://modelcontextprotocol.io/)
[License](LICENSE)

一个基于 AutoBot API 的 MCP（Model Context Protocol）服务器实现，用于远程控制和自动化 Android 设备。

## ✨ 功能特点

AutoBot MCP 提供了全面的 Android 设备控制功能，包括：

### 📱 设备信息获取

- 获取已安装应用列表
- 获取设备详细信息（硬件、系统、内存、存储）
- 获取屏幕信息和截图
- 获取 UI 布局（JSON/XML 格式）

### 🎮 设备控制

- 点击、长按、滑动等触摸操作
- 文本输入和按键模拟
- 手势操作（单指/多指）
- 屏幕亮灭控制和录屏
- **智能屏幕常亮**（自动保持屏幕常亮，操作结束后恢复）

### 📲 应用管理

- 启动和停止应用
- 获取应用信息
- 清除应用数据

### 📞 通信功能

- 联系人管理（增删查）
- 短信管理（收发）
- 电话拨打和挂断

### 📁 文件操作

- 文件列表和删除
- 文件上传下载

### 🔧 系统操作

- 执行 ADB Shell 命令
- 剪切板操作
- 脚本执行（AutoX.js）

## 🚀 快速开始

### 环境要求

- **Python**: >= 3.12
- **uv**: 最新版本的 Python 包管理器
- **Android 设备**: 运行 AutoBot HTTP 服务

### 安装步骤

1. **克隆仓库**

```bash
git clone https://github.com/yourusername/autobot-mcp.git
cd autobot-mcp
```

1. **安装依赖**

```bash
uv sync
```

1. **配置设备**

创建配置文件（从示例复制）：

```bash
cp config.yaml.example config.yaml
```

编辑 `config.yaml`，填入你的设备信息：

```yaml
device:
  ip: "192.168.1.100"  # 替换为你的设备IP地址
  port: 18080          # 替换为你的设备端口
```

### 运行服务器

**方式一：使用 autobot-mcp 命令**

```bash
uv run autobot-mcp
```

**方式二：直接运行 Python 脚本**

```bash
uv run python main.py
```

**方式三：激活虚拟环境后运行**

```bash
# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

autobot-mcp
# 或者
python main.py
```

## 📖 使用示例

### Claude Code

**添加 AutoBot MCP 服务器：**

在项目目录下执行：

```bash
claude mcp add --transport stdio autobot-mcp -- \
  uv run --directory /path/to/autobot-mcp autobot-mcp
```

**说明：**

- `--transport stdio`：指定使用 stdio 传输方式
- `autobot-mcp`：服务器名称（可自定义）
- `uv run autobot-mcp`：启动命令，确保在项目目录下执行以正确加载 `config.yaml`

**注意事项：**

- 确保已创建并配置 `config.yaml` 文件
- 命令需要在项目根目录执行，以便找到配置文件
- 如果使用虚拟环境，也可以使用 `python main.py` 作为启动命令

### 测试连接

**使用 autobot-mcp 命令测试：**

```bash
uv run autobot-mcp
# MCP 服务器将在 stdio 上运行，等待来自 MCP 客户端的连接
```

**使用 Python 脚本测试：**

```bash
uv run python -c "from main import hello; print(hello())"
```

### Python API 使用

```python
from main import mcp

# 设备已连接后，可以使用各种工具
# 获取设备信息
device_info = get_device_info()

# 启动应用
start_app("com.android.chrome")

# 点击屏幕
click(0.5, 0.5)  # 点击屏幕中心（百分比坐标）

# 获取截图
screenshot = get_screenshot()
```

## 🛠️ 可用工具函数

### 设备信息

- `get_packages()` - 获取所有已安装应用
- `get_device_info()` - 获取设备详细信息
- `get_screen_info()` - 获取屏幕信息
- `get_screenshot()` - 获取设备截图
- `get_uilayout()` - 获取当前 UI 布局
- `hello()` - 测试服务器连接

### 屏幕操作

- `click(x, y)` - 点击屏幕（支持百分比和绝对坐标）
- `long_click(x, y)` - 长按屏幕
- `swipe(x1, y1, x2, y2, duration)` - 滑动操作
- `input_text(text)` - 输入文本（支持多语言）
- `press_key(key_code)` - 模拟按键
- `gesture(duration, points)` - 单指手势
- `gestures(gestures_data)` - 多指手势

### 应用管理

- `start_app(package_name)` - 启动应用
- `stop_app(package_name)` - 停止应用
- `get_package_action_intents(package_name)` - 获取应用信息
- `clear_app_data(package_name)` - 清除应用数据

### 系统操作

- `execute_adb_shell_command(command)` - 执行 ADB 命令
- `turn_screen_on()` - 亮屏
- `turn_screen_off()` - 熄屏
- `start_screen_recording(limit)` - 开始录屏
- `stop_screen_recording()` - 停止录屏

### 通信功能

- `get_contacts(number)` - 获取联系人
- `send_sms(phone_number, message)` - 发送短信
- `call_phone(number)` - 拨打电话
- `get_clipboard_text()` - 获取剪切板内容
- `set_clipboard_text(text)` - 设置剪切板内容

### 文件操作

- `list_files(path)` - 列出文件
- `delete_file(path)` - 删除文件
- `get_file_url(path)` - 获取文件下载链接

## 📚 文档

- **[CLAUDE.md](CLAUDE.md)** - 项目开发指南和完整工具文档
- **[USAGE.md](USAGE.md)** - 命令行工具使用说明
- **[docs/autobot_http_api.md](docs/autobot_http_api.md)** - AutoBot HTTP API 详细文档
- **[docs/prompts.md](docs/prompts.md)** - 设备操作最佳实践

## 🎯 坐标系统

AutoBot MCP 支持两种坐标系统：

1. **绝对坐标**：直接使用像素值，如 `x=300, y=500`
2. **百分比坐标**：使用 0-1 之间的浮点数，如 `x=0.5, y=0.5`（屏幕正中心）

**推荐使用百分比坐标**以提高跨设备兼容性。

## ⚠️ 注意事项

### 设备状态

- 执行操作前确保设备处于亮屏和解锁状态
- 参考文档了解屏幕状态检查方法

### 安全警告

- `delete_contact()` 和 `clear_app_data()` 等操作不可恢复
- `exit_service()` 会终止 AutoBot 服务
- 执行脚本时注意权限和安全性

### 性能建议

- 避免频繁调用 `get_screenshot()`，图像传输开销较大
- 批量操作时考虑使用 ADB 命令
- 使用百分比坐标提高兼容性

## 🔧 故障排除

### 连接失败

- 检查设备 IP 地址和端口是否正确
- 确保设备和电脑在同一网络
- 确认 AutoBot 服务正在设备上运行

### 配置问题

- 确保已创建 `config.yaml` 文件
- 检查配置文件格式是否正确

### 操作无响应

- 检查设备是否亮屏和解锁
- 确认应用包名是否正确
- 查看错误信息了解具体问题

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🔗 相关链接

- [FastMCP 文档](https://gofastmcp.com/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [AutoBot 项目](https://github.com/yourusername/autobot)