codingbaby-mobile/README_zh.md

MCP Mobile Agent Server - Node.js implementation for mobile device control via ADB

# Mobile Agent MCP 服务器

**语言**: [English](README.md) | [中文](README_zh.md)

🤖 基于ADB的强大移动设备自动化MCP (Model Context Protocol) 服务器。

[![npm version](https://badge.fury.io/js/codingbaby-mobile.svg)](https://badge.fury.io/js/codingbaby-mobile)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 功能特性

- 📱 **移动设备控制**: 通过ADB远程控制Android设备
- 🖼️ **截图捕获**: 获取和处理设备截图
- 👆 **触摸交互**: 点击、滑动和手势控制
- ⌨️ **文本输入**: 输入文本和发送按键命令
- 🔄 **导航操作**: 返回、主页和应用导航
- 📊 **设备信息**: 获取屏幕分辨率和设备状态

## 快速开始

### MCP配置

在您的MCP客户端配置中添加（例如：`claude_desktop_config.json`、Cursor MCP设置等）：

```json
{
  "mcpServers": {
    "codingbaby-mobile": {
      "command": "npx",
      "args": ["-y", "codingbaby-mobile@latest"],
      "env": {
        "ADB_PATH": "/your/adb/path"
      }
    }
  }
}
```

## 安装和设置

### 1. 安装ADB (Android Debug Bridge)

**macOS:**
```bash
brew install android-platform-tools
```

**Linux (Ubuntu/Debian):**
```bash
sudo apt-get update
sudo apt-get install android-tools-adb android-tools-fastboot
```

**Windows:**
从[Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools)下载

**常见ADB路径:**
- **macOS**: `/usr/local/bin/adb` 或 `~/Library/Android/sdk/platform-tools/adb`
- **Linux**: `/usr/bin/adb` 或 `~/Android/Sdk/platform-tools/adb`
- **Windows**: `C:\Android\sdk\platform-tools\adb.exe`

**注意：** Windows下ADB可执行文件是`adb.exe`，而macOS/Linux下是`adb`。

**设置ADB权限 (macOS/Linux):**
```bash
sudo chmod +x /path/to/adb
```

### 2. 启用Android开发者选项

1. 进入**设置** > **关于手机**
2. 连续点击**版本号** 7次，直到显示"您现在是开发者！"
3. 返回**设置** > **开发者选项**（或**系统** > **开发者选项**）

### 3. 启用USB调试

1. 在**开发者选项**中，启用：
   - ✅ **USB调试**
   - ✅ **保持唤醒状态**（充电时保持屏幕唤醒）
   - ✅ **USB调试（安全设置）**（如果可用）

2. **对于HyperOS/MIUI系统：** 还需要启用：
   - ✅ **USB调试（安全设置）**（HyperOS系统必需）

3. **为了更好的兼容性**，还可以启用：
   - ✅ **OEM解锁**（如果您信任此计算机）
   - ✅ **禁用adb授权超时**

### 4. 连接和授权设备

1. 通过USB连接您的Android设备
2. 设置USB模式为**文件传输(MTP)**或**PTP**（不是"仅充电"）
3. 运行ADB检查连接：
   ```bash
   # 测试连接
   /path/to/adb devices
   
   # 示例：
   # Windows: C:\Android\sdk\platform-tools\adb.exe devices
   # macOS/Linux: /usr/local/bin/adb devices
   ```
4. **首次连接**：设备上会出现弹窗询问"允许USB调试？"
   - ✅ 勾选"始终允许来自此计算机"
   - 点击**确定**
5. **验证连接**：输出应该显示您的设备（不是空的）

### 5. 安装ADB键盘（推荐）

为了更好的文本输入支持，请安装ADB兼容键盘：

1. **下载ADB键盘APK：**
   ```bash
   # 方法1：从GitHub releases下载
   wget https://github.com/senzhk/ADBKeyBoard/releases/download/v2.0/AdbKeyboard.apk
   adb install AdbKeyboard.apk
   
   # 方法2：直接下载链接
   wget https://github.com/senzhk/ADBKeyBoard/raw/master/ADBKeyboard.apk
   adb install ADBKeyboard.apk
   ```

2. **启用ADB键盘：**
   ```bash
   # 启用键盘
   adb shell ime enable com.android.adbkeyboard/.AdbIME
   
   # 设置为默认输入法
   adb shell ime set com.android.adbkeyboard/.AdbIME
   ```

3. **手动设置（备选方案）：**
   - 在设备上安装ADB键盘APK
   - 进入**设置** > **系统** > **语言和输入法** > **虚拟键盘**
   - 将**ADB键盘**添加到已启用的键盘
   - 切换**ADB键盘**为默认输入法

### 6. 验证设置

使用以下命令测试您的设置：

```bash
# 检查设备连接
adb devices

# 测试截图
adb shell screencap -p /sdcard/test.png
adb pull /sdcard/test.png

# 测试输入
adb shell input tap 100 100
adb shell input text "Hello World"
```

## 配置

### ADB路径设置

在MCP服务器配置中设置ADB路径：

```json
{
  "mcpServers": {
    "codingbaby-mobile": {
      "command": "npx",
      "args": ["-y", "codingbaby-mobile@latest"],
      "env": {
        "ADB_PATH": "/your/adb/path"
      }
    }
  }
}
```

**请将 `/your/adb/path` 替换为您系统中ADB的实际路径：**
- **macOS**: `/usr/local/bin/adb` 或 `~/Library/Android/sdk/platform-tools/adb`
- **Linux**: `/usr/bin/adb` 或 `~/Android/Sdk/platform-tools/adb`
- **Windows**: `C:\Android\sdk\platform-tools\adb.exe`

## 可用工具

服务器提供8个强大的移动设备控制工具：

### 1. `mobile_set_adb_path`
设置ADB可执行文件路径
```json
{
  "adbPath": "/path/to/adb"
}
```

### 2. `mobile_screenshot`
获取设备截图
```json
{}
```

### 3. `mobile_tap`
点击指定坐标
```json
{
  "x": 100,
  "y": 200
}
```

### 4. `mobile_swipe`
在两点之间滑动
```json
{
  "x1": 100,
  "y1": 200,
  "x2": 300,
  "y2": 400,
  "duration": 500
}
```

### 5. `mobile_type`
在设备上输入文本
```json
{
  "text": "Hello World"
}
```

### 6. `mobile_back`
返回导航
```json
{}
```

### 7. `mobile_home`
回到主屏幕
```json
{}
```

### 8. `mobile_get_screen_info`
获取屏幕信息和设备状态
```json
{}
```

## 使用示例

### 与MCP兼容的IDE

在您的MCP客户端中配置后，您可以使用自然语言控制您的移动设备：

- "给我的手机截图"
- "点击坐标(100, 200)处的搜索按钮"
- "从左向右滑动以导航"
- "在文本框中输入'Hello World'"
- "返回到上一屏幕"

## 故障排除

### 常见问题

**找不到ADB：**
- 确保ADB已安装并在您的PATH中
- 在配置中设置正确的ADB_PATH

**设备未检测到：**
```bash
# 检查USB调试是否启用
adb devices

# 重启ADB服务器
adb kill-server
adb start-server

# 检查设备授权
adb devices
```

**权限被拒绝：**
```bash
# 在Linux/macOS上，可能需要将用户添加到plugdev组
sudo usermod -a -G plugdev $USER

# 或使用适当权限运行
sudo adb devices
```

**文本输入不工作：**
- 安装并启用ADB键盘（见上面的设置说明）
- 某些Android版本对通过ADB输入文本有限制
- 尝试在设备上手动切换输入法

**截图失败：**
```bash
# 检查设备屏幕是否开启且未锁定
adb shell dumpsys power | grep "Display Power"

# 测试手动截图
adb shell screencap -p /sdcard/test.png
adb pull /sdcard/test.png
```

### 兼容性

- **Android**: 4.4+ (API level 19+)
- **Node.js**: 18.0.0+
- **ADB**: 推荐最新版本

## 系统要求

- Node.js >= 18.0.0
- ADB (Android Debug Bridge)
- 已启用USB调试的Android设备
- MCP兼容客户端（Claude Desktop、Cursor等）

## 贡献

欢迎贡献！请随时提交Pull Request。

## 许可证

MIT许可证 - 详见[LICENSE](LICENSE)文件。

## 支持

- 🐛 **Bug报告**: [GitHub Issues](https://github.com/KellyGong0301/codingbaby_mobile/issues)
- 📚 **文档**: [GitHub Wiki](https://github.com/KellyGong0301/codingbaby_mobile/wiki)
- 💬 **讨论**: [GitHub Discussions](https://github.com/KellyGong0301/codingbaby_mobile/discussions)

---

**注意**: 此项目是CodingBaby移动代理生态系统的一部分。