# mobile-agent

**Repository Path**: tonybearpan/mobile-agent

## Basic Information

- **Project Name**: mobile-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mobile Agent

基于 FastAPI 的移动端自动化 Agent，通过 MCP 协议控制 Android/iOS 设备。

## 功能特性

- 🤖 AI 驱动的手机自动化控制
- 📱 支持 Android 和 iOS 双平台
- 🔄 流式对话接口（SSE）
- 💾 会话管理和历史记录
- 📊 Token 使用量统计
- 🛠️ 通过 MCP 协议与手机交互

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并填写配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# 数据库
DB_URL=sqlite:///./mobile_agent.db

# LLM 配置
LLM_BASE_URL=https://your-llm-api.com/v1
LLM_API_KEY=your-api-key
LLM_MODEL=qwen3-max

# MCP Server 配置
MCP_SERVER_COMMAND=python3
MCP_SERVER_SCRIPT=mobile_mcp/mcp_tools/mcp_server.py
MCP_PROJECT_ROOT=/path/to/mobile-mcp
MCP_CWD=/path/to/your/workdir
MCP_PLATFORM=android
```

### 3. 启动服务

```bash
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

访问 http://localhost:8000/static/index.html 打开聊天界面。

## MCP 依赖

本项目依赖 **mobile-mcp** 来实现手机自动化控制。

### 安装 mobile-mcp

```bash
# 从源码安装
git clone https://gitee.com/tonybearpan/mobile-mcp.git
cd mobile-mcp
pip install -r requirements.txt
```

### mobile-mcp 功能特性

- 🧠 **AI 原生驱动** - 基于 MCP 协议与 Cursor AI 深度集成
- 👁️ **视觉智能识别** - 自动分析截图，精准定位 UI 元素
- ⚡ **零配置启动** - pip install 一行命令，开箱即用
- 🔄 **一键生成脚本** - 操作即录制，自动生成 pytest 测试脚本
- 🎯 **双模式定位** - 元素树 + 视觉坐标双引擎
- 🛡️ **智能验证机制** - 按键操作自动验证生效

### 详细文档

更多 mobile-mcp 的使用方法和配置说明，请参考：

🔗 **https://gitee.com/tonybearpan/mobile-mcp**

## AI 使用指南

### 自然语言控制手机

在聊天界面输入自然语言指令，AI 会自动调用 MCP 工具控制手机：

**基础操作**
- "列出当前页面所有元素"
- "点击'登录'按钮"
- "在用户名输入框输入 test123"
- "截图看看当前页面"

**应用控制**
- "启动微信"
- "打开抖音，向上滑动 3 次"
- "列出手机上所有已安装的应用"

**测试脚本生成**
- "帮我测试登录流程"
- "录制一个下单流程并生成测试脚本"

### 使用示例

1. 打开聊天界面 http://localhost:8000/static/index.html
2. 输入你的指令，例如："打开设置页面"
3. AI 会自动分析并执行相应操作
4. 查看执行结果和生成的测试脚本

## API 接口

### 对话接口

- `POST /agent/chat` - 非流式对话
- `POST /agent/chat/stream` - 流式对话（SSE）

### 管理接口

- `GET /agent/tokens` - 查询 Token 使用统计
- `POST /agent/abort` - 中止会话
- `GET /agent/test-mcp` - 测试 MCP 连接

## 项目结构

```
mobile-agent/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI 入口
│   ├── config.py        # 配置管理
│   ├── db.py            # 数据库连接
│   ├── models.py        # 数据模型
│   ├── schemas.py       # Pydantic 模型
│   ├── agent.py         # Agent 核心逻辑
│   ├── mcp_client.py    # MCP 客户端封装
│   └── routers/
│       ├── __init__.py
│       └── agent.py     # API 路由
├── static/
│   └── index.html       # 前端聊天界面
├── .env.example         # 环境变量示例
├── .gitignore
├── requirements.txt
└── README.md
```

## 技术栈

- **后端**: FastAPI + SQLAlchemy + Pydantic
- **数据库**: SQLite / MySQL
- **MCP 协议**: 与 mobile-mcp 通信
- **前端**: 原生 HTML + JavaScript

## 许可证

MIT License