内容
# 📱 Mobile App Testing MCP
一个面向 Android 安全测试场景的 MCP Server，聚焦以下能力：
- ADB 设备与应用操作自动化
- AAPT APK 信息分析
- JADX 反编译与代码审计支撑
- 静态安全扫描（密钥泄露、弱加密、调试泄露）
项目遵循标准 `stdio` MCP 协议，可接入 Claude、Codex 及其他 MCP 客户端。
## ✨ 核心特性
- 开箱即用启动脚本：`npm start` 会先做依赖探测再启动服务
- 首次运行可自动下载 JADX（默认 `v1.5.5`）
- 支持 `.env`、Android SDK 路径、系统 PATH 多层回退
- 内置健康检查链路：`check` + `smoke` + `verify`
- 综合静态分析可直接导出统一审计报告（`json` / `md` / `sarif`）
- 新增会话预检与一键复现流水线（含证据包 `manifest.json`）
## 📌 能力边界
- 当前定位为 **Android App 测试 MCP**
- 已移除 Frida / Gadget 动态注入能力
- 动态 Hook 类测试不在当前工具范围内
## 🚀 启动流程（最简）
```bash
# 1) 克隆并进入目录
git clone https://github.com/your-username/mobile-app-testing-mcp.git
cd mobile-app-testing-mcp
# 2) 安装并构建
npm run setup
# 3) 启动 MCP
npm start
```
就这三步，其他配置都可以后补。
## 🔌 一键安装到客户端
```bash
# 同时安装到 Codex + Claude
npm run install:mcp
# 仅安装到 Codex
npm run install:mcp:codex
# 仅安装到 Claude
npm run install:mcp:claude
```
安装脚本会：
1. 自动定位客户端配置文件（`~/.codex/config.toml`、Claude Desktop 配置）
2. 写入 `mobile-app-testing` MCP Server 条目（指向 `scripts/start.js`）
3. 变更前自动备份原文件（`.bak.<timestamp>`）
## 🧭 `npm start` 会自动做什么
`npm start` 实际执行 `node scripts/start.js`，启动前会自动：
1. 探测 `adb` / `aapt` / `jadx` 本地路径（`.env`、Android SDK、PATH）
2. 若缺少 `jadx` 且 `AUTO_DOWNLOAD_JADX=true`，自动下载并解压
3. 打印缺失依赖修复建议后，再启动服务
默认 JADX 下载地址：
`https://github.com/skylot/jadx/releases/download/v1.5.5/jadx-1.5.5.zip`
## 🛠 环境要求
- Node.js `>= 18`
- Android SDK（至少包含 `platform-tools`，推荐包含 `build-tools`）
- JADX（可选，可由启动脚本自动下载）
## ⚙️ 常用命令
```bash
npm run setup # 安装依赖 + 构建
npm start # 启动（含依赖探测与JADX自动下载）
npm run verify # 完整验证（build + check + smoke）
npm run check # 仅检查本机依赖
npm run smoke # 仅做 MCP 冒烟测试
npm run build # 清理 dist 后重新编译
npm run dev # 构建后启动（同 start）
```
## 🔧 `.env` 配置
复制 `.env.example` 为 `.env` 后，常用配置如下：
- `ANDROID_HOME` / `ANDROID_SDK_ROOT`：Android SDK 路径（推荐设置）
- `ADB_PATH`：adb 可执行文件绝对路径（可选）
- `AAPT_PATH`：aapt 可执行文件绝对路径（可选）
- `JADX_PATH`：jadx 可执行文件绝对路径（可选）
- `EMULATOR_PATH`：Android emulator 可执行文件路径（可选，支持 AVD 列表/启动/关闭）
- `AUTO_DOWNLOAD_JADX`：是否自动下载 JADX（默认 `true`）
- `JADX_VERSION`：自动下载版本（默认 `1.5.5`）
- `JADX_DOWNLOAD_URL`：JADX 下载 URL（可覆盖默认地址）
- `SCREENSHOTS_DIR` / `RECORDINGS_DIR` / `DECOMPILED_DIR` / `LOGS_DIR`：工作目录
## 🔌 MCP 客户端接入
项目是标准 `stdio` MCP Server，通用配置如下：
```json
{
"mcpServers": {
"mobile-app-testing": {
"command": "node",
"args": ["/path/to/your/project/scripts/start.js"],
"cwd": "/path/to/your/project",
"env": {}
}
}
}
```
说明：
- `args` 推荐指向 `scripts/start.js`（而不是 `dist/index.js`），才能保留自动依赖检查与 JADX 首启下载
- `cwd` 建议为项目根目录
- 客户端不继承系统环境时，请在 `env` 明确传入 `ANDROID_HOME`、`PATH`
示例文件：[`mcp-config.example.json`](./mcp-config.example.json)
## 🧰 工具能力清单
当前总计 `46` 个工具：
- ADB 工具 `25`：设备、模拟器（AVD 列表/启动/关闭）、应用、文件、输入模拟、截屏录屏
- AAPT 工具 `4`：badging、permissions、xmltree、完整分析
- JADX 工具 `3`：反编译、输出信息、APK 验证
- 静态分析工具 `4`：secrets/debug/weak-crypto/comprehensive（含统一报告导出）
- 工作流工具 `9`：模板、上下文、智能建议、执行记录、会话预检、证据包导出、一键复现流水线
- 文件工具 `1`：`sha256` 指纹
## 💡 使用示例
在任意 MCP 客户端可直接提出：
```text
分析这个 APK 的基础信息：/path/to/app.apk
反编译这个 APK 并输出关键目录：/path/to/app.apk
对当前连接设备截图并保存到默认目录
查看可启动模拟器并启动：adb_list_emulators / adb_start_emulator
关闭模拟器：adb_stop_emulator（或指定 emulator_id）
对反编译目录做全面静态分析，并导出 json/md/sarif 报告到 /tmp/reports
先做会话预检：workflow_session_precheck
执行一键复现流水线并导出证据包：workflow_run_repro_pipeline
```
`static_comprehensive_analysis` 支持可选参数：
- `output_formats`: `["json","md","sarif"]` 中的任意组合
- `output_dir`: 报告输出目录（默认 `./reports`）
- `report_name`: 报告文件名前缀
- `include_third_party`: 是否包含第三方库目录（默认 `false`）
- `third_party_prefixes`: 自定义第三方路径前缀
`static_scan_secrets` / `static_scan_debug_leaks` / `static_scan_weak_crypto` / `static_comprehensive_analysis` 均输出统一字段模型：
- `severity` / `cwe` / `masvs` / `evidence` / `repro` / `impact` / `fix`
`adb_start_app` / `adb_screenshot` / `adb_shell_command` 支持稳定性参数：
- `timeout_ms`: 超时控制
- `retry_count`: 重试次数
- `retry_delay_ms`: 重试间隔
`adb_start_emulator` 支持启动等待参数：
- `wait_for_ready`: 是否等待模拟器就绪（默认 `true`）
- `wait_for_boot_completed`: 是否等待 `sys.boot_completed=1`（默认 `true`）
- `timeout_ms` / `poll_interval_ms`: 启动等待超时与轮询间隔
`adb_install_app` 支持安装等待参数：
- `timeout_ms` / `retry_count` / `retry_delay_ms`: 安装执行的超时与重试
- `wait_after_install_ms`: 安装成功后额外等待（默认 `3000`）
## 📚 Prompt 示例
参考 [`prompt-examples`](./prompt-examples/)：
- [SECURITY_TESTING_PROMPT](./prompt-examples/SECURITY_TESTING_PROMPT.md)
- [静态代码安全分析](./prompt-examples/静态代码安全分析.md)
- [网络通信加密分析](./prompt-examples/网络通信加密分析.md)
- [Root检测绕过分析](./prompt-examples/Root检测绕过分析.md)
- [SSL证书固定绕过](./prompt-examples/SSL证书固定绕过.md)
- [应用加壳脱壳分析](./prompt-examples/应用加壳脱壳分析.md)
- [恶意软件行为分析](./prompt-examples/恶意软件行为分析.md)
## 🆘 常见问题
### 1) 想要最省事启动
```bash
npm run setup
npm start
```
如果能启动，就不需要先跑 `check/smoke/verify`。
### 2) `npm start` 提示缺少 `adb` / `aapt`
先执行：
```bash
npm run check
```
然后按输出提示设置 `ANDROID_HOME` 或 `ADB_PATH` / `AAPT_PATH`。
### 3) `jadx` 缺失
- 保持 `AUTO_DOWNLOAD_JADX=true`，首次启动会自动下载
- 或手动安装后设置 `JADX_PATH`
- 如需固定下载源，设置 `JADX_DOWNLOAD_URL`
### 4) 客户端连不上 MCP
- 确认 `args` 是绝对路径且指向 `scripts/start.js`
- 确认 `cwd` 指向项目根目录
- 先运行 `npm run verify` 排除服务端问题
- 可重新执行 `npm run install:mcp` 覆盖更新客户端配置
### 5) 设备显示 `unauthorized`
```bash
adb devices
```
在手机上确认 USB 调试授权后重试。
## 🔐 合规说明
- 仅用于合法授权的安全测试与研究
- 请遵守所在地法律法规与组织合规要求
- 禁止用于未授权目标或恶意用途
MCP 市场