# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目概述
AutoBot MCP 是一个基于 Model Context Protocol 的服务器实现，用于远程控制和自动化 Android 设备。项目使用 FastMCP 框架构建，通过 HTTP 接口与 AutoBot 服务通信。
## 开发环境设置
### 环境要求
- Python >= 3.12
- [uv](https://github.com/astral-sh/uv) Python 包管理器
- Android 设备运行 AutoBot HTTP 服务
### 安装依赖
```bash
uv sync
```
### 运行 MCP 服务器
**方式一：使用 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 # 直接运行脚本
```
### 激活虚拟环境
```bash
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
```
## 项目架构
### 核心文件结构
- `main.py` - MCP 服务器主入口，定义所有 MCP 工具函数
- `config.yaml` - 配置文件（需要手动创建，从 config.yaml.example 复制）
- `config.yaml.example` - 配置文件示例
- `pyproject.toml` - 项目依赖和配置（使用 uv 管理器）
- `docs/` - 项目文档目录
- `autobot_http_api.md` - AutoBot HTTP API 详细文档
- `prompts.md` - 设备操作最佳实践和提示
### MCP 工具完整分类
#### 设备信息获取
- `get_packages()` - 获取所有已安装应用包名
- `get_device_info()` - 获取设备详细信息（硬件、系统、内存、存储）
- `get_screen_info()` - 获取屏幕信息（宽度、高度、旋转角度）
- `get_uilayout()` - 获取当前 UI 布局（JSON 格式）
- `get_screen_xml(is_wait)` - 获取当前 UI 布局（XML 格式）
- `get_screen_rotation()` - 获取屏幕旋转方向
- `get_screenshot()` - 获取设备截图（返回 Image 对象）
- `get_device_id()` - 获取设备 ID
- `get_device_ip()` - 获取设备所有 IP 地址
- `get_version()` - 获取 AutoBot 版本号
- `hello()` - 测试服务器连接
#### 设备控制
- `click(x, y)` - 点击屏幕（支持绝对坐标和百分比坐标）
- `long_click(x, y)` - 长按屏幕
- `press(x, y, duration)` - 指定时长按压屏幕
- `swipe(x1, y1, x2, y2, duration)` - 滑动操作
- `input_text(text)` - 输入文本（支持多语言）
- `input_char(text)` - 输入 ASCII 字符（按键模拟）
- `clear_text()` - 清除输入框文本
- `press_key(key_code)` - 按键模拟（如 Home、Back 键）
#### 手势操作
- `gesture(duration, points)` - 单指手势操作
- `gestures(gestures_data)` - 多指手势操作
#### 应用管理
- `start_app(package_name)` - 启动应用
- `stop_app(package_name)` - 停止应用
- `get_package_action_intents(package_name)` - 获取应用信息和启动 Activity
- `get_top_activity()` - 获取当前顶层 Activity 信息
- `clear_app_data(package_name)` - 清除应用数据（不可恢复，谨慎使用）
#### 系统操作
- `execute_adb_shell_command(command)` - 执行 ADB Shell 命令
#### 联系人管理
- `get_contacts(number)` - 获取所有联系人或指定号码联系人
- `delete_contact(number)` - 删除联系人（谨慎使用）
- `insert_contact(name, number)` - 插入新联系人
#### 短信管理
- `get_sms(number)` - 获取所有短信或指定号码短信
- `send_sms(phone_number, message)` - 发送短信
#### 文件操作
- `list_files(path)` - 列出目录内容
- `delete_file(path)` - 删除文件或目录
- `get_file_url(path)` - 获取文件下载 URL
#### 剪切板操作
- `set_clipboard_text(text)` - 设置剪切板内容
- `get_clipboard_text()` - 获取剪切板内容
#### 通话功能
- `call_phone(number)` - 拨打电话（仅支持主卡）
- `end_call()` - 挂断电话
#### 屏幕控制
- `turn_screen_on()` - 亮屏
- `turn_screen_off()` - 熄屏（设备仍可控制）
- `start_screen_recording(limit)` - 开始录屏（默认最长 180 秒）
- `stop_screen_recording()` - 停止录屏
#### 音乐播放
- `play_music(url)` - 播放网络音乐（Android 10+ 可能失败）
- `stop_music()` - 停止播放音乐
#### 脚本执行
- `execute_script(script, path, delay, interval, loop_times)` - 执行 AutoX.js 脚本
- `stop_all_scripts()` - 停止所有运行中的脚本
#### 设备名称管理
- `set_device_name(name)` - 设置设备显示名称
- `get_device_name()` - 获取设备显示名称
#### 安全模式
- `turn_safe_mode_on()` - 开启安全模式（无法获取屏幕布局和通知）
- `turn_safe_mode_off()` - 关闭安全模式
- `is_safe_mode()` - 检查安全模式状态
#### 服务控制
- `exit_service()` - 退出 AutoBot 服务
### HTTP 通信
项目使用 `requests` 库与 AutoBot HTTP API 通信，配置了重试策略：
- 最大重试次数: 3
- 重试间隔: 指数退避
- 超时时间: 10 秒
- 重试状态码: 500, 502, 503, 504
基础 URL 格式: `http://{ip}:{port}/api`
## 坐标系统
AutoBot API 支持两种坐标系统：
1. **绝对坐标**：直接使用像素值，如 `x=300, y=500`
2. **百分比坐标**：使用 0-1 之间的浮点数，如 `x=0.5, y=0.5`（屏幕正中心）
百分比坐标在不同分辨率设备上具有更好的兼容性。
## 屏幕旋转值
- `0`: 竖直方向（纵向模式）
- `1`: 逆时针旋转 90 度（横向，顶部在右侧）
- `2`: 旋转 180 度（倒置模式）
- `3`: 顺时针旋转 90 度（横向，顶部在左侧）
## 添加新工具
添加新的 MCP 工具函数时，遵循以下模式：
```python
@mcp.tool()
def new_tool_name(param: type) -> return_type:
"""
工具函数描述（必需，会被 LLM 读取）
Args:
param: 参数说明
Returns:
返回值说明
"""
try:
# 实现逻辑
response = make_request("METHOD", f"{BASE_URL}/endpoint")
return result
except Exception as e:
return f"Error: {str(e)}"
```
重要提示：
- 工具函数的文档字符串会被 LLM 读取，用于理解工具功能
- 始终包含异常处理，返回格式化的错误信息
- 使用 `make_request()` 函数以获得自动重试功能
- 对于需要返回图像的工具，使用 `Image` 类型
## 配置管理
- 配置文件必须存在才能运行，否则程序会报错退出
- 配置文件示例: `config.yaml.example`
- 配置文件使用 YAML 格式，包含设备 IP 和端口
- 配置文件位置：项目根目录的 `config.yaml`
## 最佳实践
### 设备操作前检查
在执行设备操作前，应确保设备处于亮屏和解锁状态。参考 `docs/prompts.md` 中的详细说明。
### 错误处理
所有工具函数都包含异常处理，返回格式化的错误信息：
```python
return f"Error: {str(e)}"
```
### 坐标选择
- 推荐使用百分比坐标以提高跨设备兼容性
- 需要精确定位时可使用绝对坐标
- 使用 `get_screen_info()` 获取设备屏幕尺寸
### 性能优化
- 避免频繁调用 `get_screenshot()`，图像传输开销较大
- 批量操作时考虑使用 `execute_adb_shell_command()` 执行脚本
- 使用缓存减少重复的设备信息查询
## 测试
### 测试 MCP 服务器初始化
```bash
uv run python -c "from main import mcp; print('MCP initialized successfully')"
```
### 测试连接
```bash
uv run python -c "from main import hello; print(hello())"
```
### 测试设备连接
确保 AutoBot 服务在设备上运行，且设备 IP 配置正确。
## 常见问题
1. **连接失败**: 检查设备 IP 地址和端口是否正确，确保设备和电脑在同一网络
2. **配置文件缺失**: 从 `config.yaml.example` 复制并创建 `config.yaml`
3. **依赖安装问题**: 确保使用最新版本的 uv: `uv self update`
4. **屏幕操作无响应**: 检查设备是否亮屏和解锁
5. **应用启动失败**: 确认应用包名正确，且应用有启动入口
6. **录屏文件保存位置**: 默认保存在设备的 `/sdcard/screen.mp4`
7. **坐标不准确**: 不同设备屏幕尺寸不同，建议使用百分比坐标
## 安全注意事项
- `delete_contact()` 和 `clear_app_data()` 等操作不可恢复，使用时需谨慎
- `exit_service()` 会终止 AutoBot 服务，需要重新激活
- 安全模式下无法获取屏幕布局，部分功能受限
- 执行脚本时注意权限和安全性
## 相关资源
- [FastMCP 文档](https://gofastmcp.com/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [AutoBot HTTP API 文档](docs/autobot_http_api.md)
- [设备操作最佳实践](docs/prompts.md)
