android-reserve-mcp

聚焦Android产物、DEX、JS、SO、资源和运行观测的MCP服务。使用本地CLI和静态解析器，复杂查询按需启动REA后端；对模型提供20个分组入口，避免加载整个通用逆向工具集。

当前 GitHub Release 为 v0.5.2：下载 Release，源码仓库：lonnnnnng/android-reserve-mcp。0.5.2尚未发布到 npm registry；可从 GitHub Release 下载 tarball，或按下方说明从源码运行。版本变更及验证边界见变更记录、实施进展和验证记录。

OpenCode 连接名和专用模式名均为 android-reserve，协议服务名与 npm 包名为 android-reserve-mcp。OpenCode 工具前缀为 android-reserve_。各类应用的覆盖范围见 能力与限制。

先准备环境

完整能力依赖与安装检查见 环境与工具依赖。 最小启动需要 Node.js ≥26.12.1；APK 摘要需要 Python ≥3.11。完整静态分析还需要完整 JDK 17+、JADX CLI、apktool、Android SDK、ripgrep、LLVM readelf，以及 REA 6.9.0 和独立的 JADX headless MCP 0.7.1 JAR。动态分析还需要 Frida Node binding 和可连接的 Android 设备环境。

发布后可通过npm install android-reserve-mcp安装CLI；首发前请按下方步骤从源码运行，或从Release候选tarball安装。npm/GitHub首次发布状态见首发待办。

JS分析依赖随npm安装，不需要浏览器。Native函数分析需要配置可用provider；本机已验证Ghidra12.2、macOS ARM64原生decompiler及独立JDK25。Hermes HBC84、Flutter/Dart3.11.5、ILSpy托管程序集、Godot4.3脚本字节码已有自有样本通过；这不等于完整RN/MAUI/游戏恢复。可选环境、固定参数和安装记录见 引擎说明与引擎安装。

安装本项目依赖：

cd /absolute/path/android-reserve-mcp
npm ci --ignore-scripts
node src/cli.js --help

上面跳过依赖安装脚本，可用于基础静态能力与自动测试。java-methods/trace-java还需要frida-compile的Node原生binding；本仓库npm 11配置已锁定允许frida@17.26.3。安装后用npm install-scripts ls确认授权，再执行npm rebuild frida --ignore-scripts=false并验证binding可导入。若作为依赖装入另一个npm项目，项目级授权不会继承；需在那个项目确认锁文件中Frida确为17.26.3后，显式批准该包脚本。设备注入仍由REA的Frida17.23.2完成，勿因此更换设备server版本。安装条件和许可见环境文档。

在 MCP 客户端配置中合并下面的服务器项，替换两个绝对路径，不覆盖原有服务器或模型设置：

{
  "mcp": {
    "android-reserve": {
      "type": "local",
      "command": ["node", "/absolute/path/android-reserve-mcp/src/cli.js", "--allowedRoots", "/absolute/path/apk-projects"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

这是 OpenCode 的格式；通用 stdio 客户端使用相同 command/args，参见 示例。启动命令保持运行等待 MCP 消息是正常现象。先让客户端调用 doctor，再分析 APK。

Related MCP server: OpenAPK

工具入口

一个完整调用流程

工具参数示例（在客户端发起工具调用，并非 shell 命令）：

{"tool":"apk","arguments":{"action":"inspect","path":"/absolute/path/apk-projects/app.apk"}}

长任务立即返回 id。把它作为 jobId 查询：

{"tool":"jobs","arguments":{"action":"status","jobId":"<返回的 id>"}}
{"tool":"artifacts","arguments":{"action":"read","jobId":"<返回的 id>","path":"result.json","offset":0,"limit":12000}}

根据 nextOffset 继续读取。succeeded、partial、failed、canceled、interrupted 是不同终态；失败先看 error 和任务日志，不能仅凭拿到 id 判断成功。

建议：doctor → artifact → apk/decode/dex/script/native/framework → artifacts。artifact的框架指纹是候选；source map、静态引用和运行证据有不同语义，不能相互冒充。Native用法见 引擎说明。

Frida：先明确设备与目标；spawn 创建暂停进程，读取任务结果中的 session_id 后执行 load → resume → status → close。attach 对已运行进程操作，不需要 resume。脚本可能改变目标行为，服务不会自行生成或加载绕过脚本。

Java专项：默认先java-methods读取app loader的真实重载；自定义loader先java-loaders复制唯一selector，再读取真实重载，卸载枚举脚本，再以显式argumentTypes调用trace-java。需要关联JNI时，使用该action的nativeHooks，不要另load一份Native脚本后按时间猜关联。加载成功只说明脚本被接受，spawn须先resume，再从status确认java-hook-installed和实际事件；详见Java/JNI调用示例。

隐藏JNI专项：spawn后先trace-jni并确认ready再resume；匹配注册尝试与成功返回，取得类/方法/签名/模块RVA。卸载观测后，以相同模块RVA进行Native或Java联合追踪。RVA栈为候选地址，不能冒充精确调用链；完整流程、预算与边界见动态JNI说明。

CLI 与数据位置

任务写入 workspace/jobs/<id>/，不会自动删除。允许目录与工作目录使用 realpath 校验；产物读接口限定在对应任务目录。工作目录本身也可作为后续输入。此路径限制不能约束 Frida 脚本在目标进程中的行为，服务也不是执行不可信 APK 解析器的操作系统沙箱。

文档与验证

• 新增能力与调用步骤：分包、Kotlin、自定义loader、WebView、程序集与持久证据。

• 环境与完整依赖：按能力安装、动态设备条件、版本、故障排查。

• 架构：按需后端、队列、进程与产物边界。

• 能力与限制：Java/Kotlin、C/C++、React Native/WebView 的实际覆盖。

• 全技术栈缺口清单：原生、跨平台、Web混合、游戏及Harmony的待补能力与候选引擎。

• 实施进展、引擎说明：本批实际交付、可选环境和调用示例。

• 维护手册：OpenCode 模式、自定义、升级、发布准备。

• 验证记录：实测项目及未验证边界。

• GitHub样本验收：公开样本的固定commit、产物哈希、真机范围与失败边界。

• 参考与许可、第三方说明。

npm run check
npm test
node scripts/smoke.mjs
npm run check:pack
npm run smoke:release

npm test 使用自有样本和模拟后端，不连接设备；smoke:release会在临时目录安装实际npm tarball并验证stdio工具清单。完整静态 smoke 需要静态工具链、Android SDK platform 和headless JAR，生成自有APK/临时签名，不安装或启动APK。

MIT © long。