# AutoBot MCP 使用说明
## 命令行工具
### autobot-mcp 命令
AutoBot MCP 提供了一个便捷的命令行工具 `autobot-mcp` 来启动 MCP 服务器。
#### 运行方式
**1. 使用 uv run（推荐）**
```bash
uv run autobot-mcp
```
**2. 激活虚拟环境后直接运行**
```bash
# Windows
.venv\Scripts\activate
autobot-mcp
# Linux/Mac
source .venv/bin/activate
autobot-mcp
```
**3. 直接运行 Python 脚本**
```bash
uv run python main.py
```
#### MCP 客户端配置
MCP 服务器通过 stdio 进行通信，需要配置 MCP 客户端来连接。
**Claude Desktop 配置示例：**
在 Claude Desktop 的配置文件中添加：
```json
{
"mcpServers": {
"autobot": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/autobot-mcp",
"autobot-mcp"
],
"env": {
"AUTOBOT_DEVICE_IP": "192.168.1.100",
"AUTOBOT_DEVICE_PORT": "18080"
}
}
}
}
```
**注意：**
- 将 `/path/to/autobot-mcp` 替换为实际的项目路径
- 确保设备 IP 和端口配置正确
## 环境变量
虽然当前版本使用 `config.yaml` 文件进行配置，但你也可以通过环境变量来覆盖配置：
```bash
export AUTOBOT_DEVICE_IP="192.168.1.100"
export AUTOBOT_DEVICE_PORT="18080"
uv run autobot-mcp
```
## 调试
### 启用调试日志
```bash
export AUTOBOT_DEBUG=1
uv run autobot-mcp
```
### 测试连接
```bash
# 测试 Python 导入
uv run python -c "from main import mcp; print('MCP initialized successfully')"
# 测试服务器连接
uv run python -c "from main import hello; print(hello())"
```
### 查看可用工具
MCP 服务器启动后，客户端可以列出所有可用的工具：
- 使用 Claude Desktop 或其他 MCP 客户端
- 通过客户端界面查看可用工具列表
- 每个工具都有详细的参数说明
## 常见问题
### 命令未找到
如果遇到 `autobot-mcp: command not found` 错误：
1. 确保已安装依赖：`uv sync`
2. 使用 `uv run autobot-mcp` 而不是直接 `autobot-mcp`
3. 或者激活虚拟环境后再运行
### 连接失败
1. 检查 `config.yaml` 文件是否存在
2. 确认设备 IP 地址和端口正确
3. 确保设备和电脑在同一网络
4. 验证 AutoBot 服务在设备上运行
### 权限问题
某些操作可能需要特殊权限：
- 联系人管理、短信功能需要运行时权限
- 文件操作需要相应的存储权限
- ADB 命令可能需要调试权限
## 最佳实践
1. **使用百分比坐标**：提高跨设备兼容性
2. **检查设备状态**：操作前确保设备亮屏和解锁
3. **错误处理**：所有工具都返回错误信息，注意检查
4. **性能优化**：避免频繁调用截图等耗时操作
5. **安全操作**：谨慎使用删除和清除数据操作
## 屏幕常亮功能
AutoBot MCP 现在支持智能屏幕常亮功能，在 AI 操作手机时自动保持屏幕常亮。
### 自动启用
MCP 服务器启动时会自动启用屏幕常亮功能：
- 将屏幕超时时间设置为 30 分钟（最大值）
- 保存原始的屏幕超时设置
- 在每次工具调用前执行轻量级心跳操作
### 自动恢复
当 MCP 服务器关闭时（正常退出或异常终止）：
- 自动恢复原始的屏幕超时设置
- 确保不影响设备的正常使用
### 手动控制
如果需要手动控制屏幕常亮功能，可以使用以下工具：
#### 1. 启用屏幕常亮
```python
# 将屏幕超时设置为 30 分钟
enable_screen_keep_alive()
```
#### 2. 禁用屏幕常亮
```python
# 恢复原始屏幕超时设置
disable_screen_keep_alive()
```
#### 3. 获取当前屏幕超时
```python
# 查看当前屏幕超时时间（秒）
get_screen_timeout()
```
#### 4. 设置屏幕超时
```python
# 自定义屏幕超时时间
# 参数：超时时间（秒）
# - 0: 永不熄屏（部分设备可能不支持）
# - 15-1800: 15秒到30分钟
set_screen_timeout(300) # 设置为 5 分钟
```
### 工作原理
1. **超时设置**：通过修改系统设置 `screen_off_timeout` 来控制屏幕熄灭时间
2. **心跳机制**：在每次工具调用前执行轻量级操作（模拟轻微触摸）保持屏幕活跃
3. **自动恢复**：保存原始设置，在服务器关闭时自动恢复
### 注意事项
- 部分设备可能限制最大超时时间为 30 分钟
- 如果设备进入深度睡眠，可能需要先唤醒才能操作
- 心跳操作使用屏幕边缘的轻微触摸，通常不会影响正常操作
- 如果手动修改了屏幕超时设置，服务器关闭时会恢复到服务器启动时的值
## 更多信息
- [README.md](README.md) - 项目概览
- [CLAUDE.md](CLAUDE.md) - 开发指南
- [docs/autobot_http_api.md](docs/autobot_http_api.md) - API 文档
