内容
# Android 构建工具 MCP
> **MCP 服务器，用于 [OpenCode](https://opencode.ai)** — 直接在 AI 编程助手上，在 **arm64 设备** (Termux + proot-distro + Ubuntu) 上构建 Android APK。
[](https://github.com/alwansan/android-builder-mcp)
---
## 🚀 快速安装（一条命令）
```bash
curl -fsSL https://raw.githubusercontent.com/alwansan/android-builder-mcp/main/install.sh | bash
```
就这样。安装程序处理所有事情 — 从零到一个可用的 MCP 服务器，约 10 分钟（取决于网速和设备）。
---
## 📋 安装程序执行的操作（8 步）
| 步骤 | 组件 | 安装方式 | 备注 |
|------|-----------|-------------|-------|
| 0 | 系统依赖 | `apt` | curl, unzip, tar, binutils, git |
| 1 | **Node.js** 18+ | `apt` / `pkg` | MCP 服务器运行时所需 |
| 2 | **JDK 17** | `apt` / `pkg` | Android 构建所需 |
| 3 | **Box64** | `apt` 或源码编译 | x86-64 → arm64 翻译，用于 SDK 工具 |
| 4 | **Gradle** 8.10.2 | `apt` 或手动下载 | 构建系统 |
| 5 | **Android SDK** + NDK | sdkmanager + 直接下载 | 平台、构建工具、平台工具、NDK |
| 6 | 环境 | `~/.bashrc` | JAVA_HOME, ANDROID_HOME, PATH |
| 7 | **MCP 服务器** | `git clone` + `npm` | 克隆仓库、安装依赖、编译 TypeScript |
| 8 | 验证 | — | 检查所有 8 个组件 |
### 自动安装的 SDK 组件
- **平台**: android-36
- **构建工具**: 35.0.0（x86-64，通过 Box64 运行）+ 34.0.4（arm64，备用）
- **平台工具**: adb
- **NDK**: 27.3.13750724（用于 Chaquopy / 原生 .so 编译）
---
## 🛠️ 所有 14 个 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `build_apk` | 从 Gradle 项目构建 APK（调试/发布） |
| `create_android_project` | 从模板创建新的 Android 项目（基本） |
| `fix_aapt2` | 修复 arm64 上的 aapt2 架构不匹配 — 用 Box64 包装器替换 AGP 缓存中的 x86-64 二进制文件 |
| `check_environment` | 检查 JDK、SDK、Gradle、构建工具和架构 |
| `install_sdk` | 安装/更新 Android SDK 和构建工具 |
| `doctor` | 完整环境健康检查（8 项检查） |
| `diagnose_build` | 分析 Gradle 构建错误并建议修复 |
| `search_permissions` | 按名称/保护级别/组搜索 Android 权限数据库 |
| `get_manifest_element` | 获取 Android 清单元素要求 |
| `sdk_mapping` | SDK 版本 → API 级别映射 |
| `android_doc_search` | 搜索 developer.android.com |
| `install_apk` | 通过 ADB 在连接的设备上安装 APK |
| `read_logcat` | 读取 Android 系统日志（按应用过滤） |
| `list_devices` | 列出连接的 ADB 设备 |
---
## 🏗️ 架构
```
OpenCode（MCP 客户端）
↓
android-builder-mcp（MCP 服务器）— stdio JSON-RPC
├── build_apk → Gradle 包装器 → AGP → aapt2（Box64）→ APK
├── create_android_project → 模板 → 项目文件
├── fix_aapt2 → 查找 AGP jar → 用 Box64 包装器替换 aapt2
├── doctor → 检查所有 8 个组件
├── diagnose_build → 解析构建日志 → 建议修复
├── search_permissions → SQLite 数据库 → 权限信息
├── get_manifest_element → 硬编码清单规则
├── sdk_mapping → 硬编码 SDK→API 版本映射
├── android_doc_search → curl + 渲染（developer.android.com）
├── install_apk → adb 安装
├── read_logcat → adb logcat
├── list_devices → adb 设备
└── install_sdk → sdkmanager + 直接下载
```
```
文件：
src/index.ts → 工具注册、入口点
src/utils/gradle.ts → 构建逻辑、Box64 包装器补丁、SDK 自动下载
src/utils/sdk.ts → 环境检测
src/utils/aapt.ts → aapt2 修复逻辑
src/tools/project.ts → 项目模板
src/tools/build.ts → 构建 + 环境工具
src/tools/diagnostic.ts → 医生 + 诊断
src/tools/device.ts → ADB 工具
src/tools/knowledge.ts → SDK 映射、权限数据库、清单元素、文档搜索
install.sh → 一键安装程序（8 步）
```
---
## 🔧 为什么使用 Box64？（arm64 Android SDK 问题）
谷歌 **不提供** arm64 原生 Android SDK 构建工具。所有二进制文件（aapt2、zipalign、aidl）仅为 x86-64。
这是该项目解决的核心问题：
```
常见方法（失败）：
Gradle → AGP → aapt2（x86-64）→ ❌ arm64 执行格式错误
我们的方法（有效）：
Gradle → AGP → Box64 → aapt2（x86-64 翻译）→ ✅ 有效
```
### 工作原理
1. **Box64** 已安装（x86-64 → arm64 二进制翻译器，比 QEMU 轻量）
2. 从谷歌下载 x86-64 **构建工具 35.0.0**
3. AGP 在 `aapt2-*-linux.jar` （在 Gradle 缓存中）内提供 aapt2。我们 **修补** 此 jar：
- 提取二进制文件
- 用 shell 包装器替换它：`#!/bin/sh\nexec /usr/bin/box64 /path/to/aapt2 "$@"`
- 重新打包 jar
4. Gradle 提取包装器，Box64 运行真正的 x86-64 aapt2
### 备用：arm64 构建工具 34.0.4
来自 [AndroidIDE](https://github.com/AndroidIDEOfficial/androidide-tools)。仅适用于 `compileSdk ≤ 34`。
### 被拒绝的解决方案
| 方法 | 为什么被拒绝 |
|----------|-------------|
| `binfmt_misc` + QEMU | 需要内核支持 — 在 proot-distro 中不可用 |
| `android.aapt2FromMavenOverride` | 在 AGP 8.0 中已弃用，在 AGP 8.13+ 中被忽略 |
| `aapt2_linux` arm64 来自 AndroidIDE | 仅在 v34.0.4（最大 API 34）之前可用 |
---
## 📋 要求
| 要求 | 最低 | 推荐 |
|------------|---------|-------------|
| 架构 | **arm64**（aarch64） | arm64 |
| 环境 | Termux + proot-distro（Ubuntu） | Termux + proot-distro（Ubuntu 22.04+） |
| RAM | 2 GB | 4 GB+ |
| 存储 | 4 GB 可用 | 8 GB+（SDK + NDK + Gradle 缓存） |
| 网络 | 宽带 | 宽带（约 2 GB 下载用于完整安装） |
> **注意**：此设计适用于 **arm64**。它在 x86-64 上也有效，但 Box64 安装会被跳过。
---
## ⚙️ 手动设置
```bash
# 1. 克隆
git clone https://github.com/alwansan/android-builder-mcp.git
cd android-builder-mcp
# 2. 安装依赖并构建
npm install
npm run build
```
3. 添加到 OpenCode 配置（~/.config/opencode/opencode.jsonc）
```bash
{
"mcp": {
"android-builder": {
"type": "local",
"command": ["node", "/path/to/android-builder-mcp/dist/index.js"],
"enabled": true,
"timeout": 600000
}
}
}
```
或使用 OpenCode CLI：
opencode mcp add android-builder -- node /path/to/android-builder-mcp/dist/index.js
4. 重启 OpenCode 并验证
询问：check_environment
---
## 🔍 故障排除
| 症状 | 原因 | 修复 |
|---------|-------|-----|
| `Exec format error` 与 aapt2 | x86-64 aapt2 直接在 arm64 上运行 | 运行 `fix_aapt2` 工具 — 修补 AGP 缓存 jar |
| `Daemon startup failed` | aapt2 二进制文件与架构不兼容 | 确保 Box64 已安装 + AGP jar 已修补 |
| `resource mipmap/ic_launcher not found` | 模板引用缺少图标 | 从清单中删除 `android:icon` 或添加资源 |
| `android.aapt2FromMavenOverride` 警告 | 已弃用的 Gradle 属性 | 删除此行（AGP 8+ 忽略它） |
| Gradle 未找到 | 不在 PATH 中 | 运行 `source ~/.bashrc` 或安装 Gradle |
| SDK 平台丢失 | 未安装 compileSdk | 运行 `fix_aapt2` → 自动下载缺失组件 |
| `box64: command not found` | Box64 未安装 | `apt-get install -y box64` 或运行 install.sh |
| `/mnt/sdcard` 上的符号链接错误 | FUSE/FAT 文件系统 | MCP 自动将项目复制到 `/tmp` 进行构建 |
| `buildPython FAILED`（Chaquopy） | 错误的 Python 路径 | 设置 `buildPython "/data/data/com.termux/files/usr/bin/python"` |
---
## 📄 许可证
GPL-3.0
