# apk-index —— Android 逆向 / Xposed 模块开发用的 APK 索引 MCP Server

[![M8ven Score](https://m8ven.ai/badge/mcp/wlmosv-png/apk-index)](https://m8ven.ai/mcp/wlmosv-png/apk-index)
静态索引 APK / split APK / AAR / 裸 dex / vdex / compact-dex，给 Agent 提供
「查类、查成员、查签名、查字符串、查交叉引用、生成 hook 起手块」的只读能力。
纯 Python 3 标准库（zipfile / sqlite3 / struct / json / hashlib），stdio 上说 MCP JSON-RPC 2.0。

## 运行要求
- Python >= 3.10，无第三方依赖
- 可选：JDK 的 `javac`（AAR fixture）与 `javap`（.class 交叉校验）；缺省时用内置 `tools/classwrite.py` 兜底
- 只读挂载：索引写 `APK_INDEX_CACHE`（默认 `~/.cache/apk-index`），永不写源文件

## 多客户端隔离（0.5.1+）

同时开两个对话 / 两个工作连同一个实例时，会话按 **owner（租户）** 隔离：

- HTTP：客户端 `initialize` 后回传 `MCP-Session-Id` 请求头 → 每个客户端一个
  owner；不带头的老客户端归 `default`（兼容）。
- stdio：每个进程随机 owner（可用环境变量 `APK_INDEX_OWNER` 固定）。
- CLI：`APK_INDEX_OWNER` 或 `cli`。

隔离语义：`sessionList` 只显示本客户端的会话；`unload` 只解除自己的引用，
**索引文件全局共享**（同一包只建一次索引，多客户端 load 命中缓存），
最后一个引用者释放时才删文件。跨进程写索引有文件锁（`<db>.lock`），
两个客户端同时索引同一新包不会互相踩。

## 注册到 MCP 客户端
```json
{
  "mcpServers": {
    "apk-index": {
      "command": "python3",
      "args": ["-m", "apkindex.mcp", "--stdio"],
      "env": {
        "PYTHONPATH": "/data/local/tmp/apk-index/src",
        "APK_INDEX_CACHE": "~/.cache/apk-index",
        "APK_INDEX_ALLOWED_ROOTS": "/sdcard:/data/local/tmp"
      }
    }
  }
}
```
`APK_INDEX_ALLOWED_ROOTS`（冒号分隔）是路径白名单，越界一律 `INVALID_PATH` —— 防止越权读宿主隐私文件。

## 23 个工具
| 分类 | 工具 | 一句话 |
|---|---|---|
| 装载 | `loadApk` | APK(+split 目录) → 会话；返回指纹 / manifest 摘要 / 组件 / 加固探测 |
| 装载 | `loadAar` | classes.jar + R.txt + consumer-rules.pro + jni/\<abi\>/*.so，可 `mergeInto` 并进 App 会话 |
| 装载 | `loadDex` | 裸 classes.dex / vdex / compact-dex，可追加进已有会话 |
| 会话 | `sessionList` / `stats` / `unload` | 忘了 sessionId 先 list；stats 看体量；unload 删登记（`keepFiles` 可选） |
| 查询 | `searchClasses` | exact / prefix / regex，`scope=app|lib|all`，`packageFilter` |
| 查询 | `listMembers` | 类内方法与字段，`include` 走 namePattern |
| 查询 | `getSignature` | 一个类或成员 → smali / reflector / java / helper-ktx 四形态 + hook 起手块 + 注解（含 visibility） |
| 查询 | `searchByString` | 常量字符串反查方法（contains/exact/regex，按命中数聚合排序） |
| 查询 | `findImplementations` | 接口实现 / 父类子类，含传递继承链 |
| 查询 | `xref` | callers / callees，`depth` 控制跳数 |
| 代码 | `decompile` | `outline`（骨架）/ `smali` / `java`，`maxLines` 截断 |
| 生成 | `matchSignature` | 只给结构条件（参数个数/类型/返回值/引用字符串）→ 候选成员 + 可粘 DSL |
| 生成 | `diffSessions` | 两版本差分：exact-structure / structural-similarity / added / removed（入参 `sessionA`/`sessionB`） |
| 综合 | `probe` | 一句人话问题 → 抽字面量/类名/关键词，串起 checkPacker+stats+各查询的证据包 |
| 探测 | `checkPacker` | 识别加固与 dex 加壳证据，只识别不静默脱壳 |
| 清单 | `listManifest` | 会话里的完整 manifest 摘要：包/版本/SDK/权限/四大组件/native 库，可按组件类型与 exported 过滤 |
| 清单 | `findComponent` | 按名字/类型/exported 精确定位一个组件（比 listManifest 窄） |
| 资源 | `searchResources` | resources.arsc 条目枚举（type/name/typeId）；解析失败报 NOT_FOUND 不装可用 |
| 资源 | `resourceRefs` | 找代码里引用某资源的方法：字符串常量 + const-class 真实 xref |
| 安全 | `resourceSecurity` | 一页安全面：exported 组件、危险权限、native 库、资源表可用性 |
| 运维 | `doctor` | 只读缓存体检：逐会话 quick_check / schemaVersion / 体积 / 未登记 db 文件 |

## 返回契约（每个工具都保证）
- 成功：`{ok:true, sessionId, total, items[], truncated, hint, tool, elapsedMs, ...专有字段}`
- 失败：`{ok:false, code, message, suggestion, hint}`
- `items` 上限 100 条、单 item ≤ 32KB；超出置 `truncated:true`，`hint` 说明怎么收窄
- `hint` 在成功与失败两种 envelope 里都恒存在，客户端只看一个字段就能决定下一步
- 错误码：`INVALID_PATH` `NOT_FOUND` `CLASS_NOT_FOUND` `INVALID_REFERENCE` `SESSION_NOT_FOUND`
  `APK_TOO_LARGE` `PACKED_DEX` `ENCRYPTED` `BACKEND_MISSING` `INTERNAL`

## 自测
```bash
bash build.sh                              # 打 tar 分发包
python3 tools/make_fixture.py --out fixtures
APK_INDEX_CACHE=$PWD/.cache python3 tests/test_tools.py
# 真机样本（混淆目标 + 跨版本差分）：
APK_INDEX_TEST_REAL_APK=/sdcard/Download/a.apk,/sdcard/Download/b.apk python3 tests/test_tools.py
```

## 已知边界
- 只读静态索引，不脱壳、不改二进制；加壳 APK 只报证据与 `PACKED_DEX`
- 无 JDK 时 `decompile(java)` 是内置可读伪 java（保留控制流与常量，不做数据流还原）
- dex 解码是 mterp 子集，遇到未覆盖 opcode 标 `partial:true` 而不是猜
- 未修问题清单见 `TESTPLAN.md`（真机 dex 的 mUTF-8 lone surrogate 已修，剩余为错误码与差分阈值）


## 参数与行为速查（对齐 tools/list 实测输出）

23 个工具：`loadApk` `loadAar` `loadDex` `sessionList` `unload` `stats` `checkPacker`
`searchClasses` `listMembers` `getSignature` `searchByString` `findImplementations`
`xref` `decompile` `matchSignature` `diffSessions` `probe`
`listManifest` `findComponent` `searchResources` `resourceRefs` `resourceSecurity` `doctor`。

### 会话与索引

- `loadApk(path, splits?, fromDevice?, packageName?, backend?)`：**按 dex 内容去重**。
  同一个 APK 无论重命名还是重打包，只要 dex 字节集合不变，拿回的是**同一个 `sessionId`**
  和同一份索引。想强制重来用 `unload(keepFiles=false)` 再 load。
- **参数名写错会直接拒收**（`BAD_ARGUMENT` + 有效参数列表），不再静默丢弃。以前把
  `searchClasses` 的 `kind` 写成 `match`，regex 不生效、返回 `total=0`，看着就像
  "这个包里根本没有"——假的空结果比崩溃更害人。注意两个搜索工具的参数名不同：
  `searchClasses(query, kind=exact|prefix|regex)`，`searchByString(text, match=contains|exact|regex)`。
- `loadAar(path, mergeInto?)`：读 `classes.jar` / `R.txt` / `consumer-rules.pro` /
  `jni/**/*.so`。**`mergeInto` 是"并进宿主会话"**，宿主的 `stats` 会多出 library 类；
  需要干净的对照会话时别用 `mergeInto`。
- `unload(sessionId, keepFiles?)` / `sessionList()` / `stats(sessionId)` /
  `checkPacker(sessionId)`：加固包在 `checkPacker` 里给壳特征与真实 dex 位置；
  静态可索引类数为 0 时会明确写"索引不到不等于没有"。

### 查询

- `searchClasses(sessionId, query, kind=exact|prefix|regex, scope=app|library|all, packageFilter, annotatedWith, limit)`
  —— `annotatedWith` 只回类上带该注解的（`@Keep`、`dalvik.annotation.Keep`、`Lkotlin/Metadata;` 三种写法都认），混淆包里挑名字稳定的锚点就用它。
- `listMembers(sessionId, class, include, namePattern, scope, withStrings, limit)`
- `getSignature(sessionId, class, member, scope)`：一个类（或一个成员）的完整外形。注解走 `annotations`：`descriptor / javaName / visibility(build|runtime|system) / values`。
- `searchByString(sessionId, text, match=contains|exact|regex, minLen, scope, methodLimit, limit)`
- `findImplementations(sessionId, interface|superClass, method, transitive, includeAbstract, scope, limit)`
  —— 裸类名可用（等于该类的实现/继承查找）。
- `xref(sessionId, method, direction=callers|callees|both, depth, scope, limit)`
  —— `method` 支持三种写法：`com.a.b.C`（整类全部成员的引用）、`com.a.b.C->m(sig)`、
  `com.a.b.C#m(sig)`；认不出来时报 `NOT_FOUND` 并把**原样入参**带回来，不静默返回空。
- `matchSignature(sessionId, params, returnType, namePattern, packagePrefix, modifiers,
  requireConstructor, invokedMethods, accessedFields, referredStrings, scope, limit)`
  —— `params` 支持 `any` 与具体类型混写；参数个数上限 8（不是 3）；
  `packagePrefix` 同时匹配 `com/example/demo` 与 `com.example.demo` 两种存法。
- `decompile(sessionId, target, format=java|smali, maxLines)`：三档兜底
  SMALI → JAVA+SMALI → SMALI，结果里标 `backend`/`format`/`truncated`；
  JADX 不存在、崩了或导不出源码时**不会**装作成功。

### 差分与聚合

- `diffSessions(sessionA, sessionB, scope, minScore, limit)`：条目按 `kind` 分三种，
  **键不一样** —— `renamed` 有 `from`/`to`/`score`/`how`/`fromDescriptor`/`toDescriptor`/
  `packageFrom`/`packageTo`/`methodsOnlyInA`/`methodsOnlyInB`；`added`/`removed` 只有
  `class`/`descriptor`/`superClass`/`source`/`methodCount`/`sampleMethods`。
  同一个会话自己比是合法的，结果为空差分。
  改名配对是启发式（同外形 + 同常量），`how` 说明依据；库类混进旧会话会搅动候选集，
  所以对照实验要在没被 `mergeInto` 污染过的会话上做。
- `probe(sessionId, question, target?, maxDepth?, limit)`：一句问题跑完整套侦察
  （引号字面量→字符串检索、点号/驼峰→类检索、中文串→UI 文案检索、加固→提示脱壳）。
  **给了 `target` 就连带 `xref` + `getSignature` + `decompile` 深挖**；问"有哪些实现类/
  子类"时给 `implementations` 分节。深挖失败另放 `xrefErrors`，不会把整次 probe 打死。

### 清单、资源与安全面（0.5.0 新增）

- `listManifest(sessionId, componentType?, query?, exported?, limit)` —— 数据在 `loadApk`
  时已写入会话 summary，查询不重新解包。`componentType=component` 看全部四类；
  `exported=true` 只匹配清单里**显式** true 的组件，未声明（None）不算——Android 默认规则
  和显式 false 不是一回事，安全审计上混淆这两者会给出假的干净列表。
- `findComponent(sessionId, name?, componentType?, exported?, limit)` —— `name` 支持短名
  后缀匹配（`.MainActivity` 和 `MainActivity` 都能命中）。
- `searchResources(sessionId, query?, match, resourceType?, limit)` —— best-effort 解析
  resources.arsc（纯 stdlib，条目样本上限 512）。解析不了时**报 `NOT_FOUND` + notes**，
  不返回 ok+空列表冒充"这个包没有资源"。
- `resourceRefs(sessionId, resource?, resourceType?, limit)` —— 两种证据：DEX 字符串常量
  （`app_name` / `R.string.app_name`）与 const-class（`R$string` / `BuildConfig`）。
  0 命中不等于没用到：`getIdentifier`、XML 直接引用、插件化加载都不留这两种痕迹，
  hint 里会说明。
- `resourceSecurity(sessionId)` —— 单条目聚合，适合跨版本 diff：包/SDK/权限/危险权限/
  exported 组件/native 库/资源类型。
- `doctor()` —— 只读：catalog 里每个会话的 db 存在性、`PRAGMA quick_check`、schemaVersion、
  缓存总大小、未登记的 `.db` 文件。它**不修**任何东西；处置是 `unload` + `loadApk` 重建。

注意：`loadAar(mergeInto=...)` 在 0.5.0 前会把库自己的 manifest 顶掉宿主清单；已修，
但**旧的混合会话要 `force=true` 重建**才能拿回正确的组件与安全面。

### 命令行

```bash
PYTHONPATH=src python3 -m apkindex.cli doctor fixtures/demo-v1.apk
PYTHONPATH=src python3 -m apkindex.cli sessions
PYTHONPATH=src python3 -m apkindex.cli tools
PYTHONPATH=src python3 -m apkindex.cli call loadApk '{"path":"fixtures/demo-v1.apk"}'
PYTHONPATH=src python3 -m apkindex.cli call xref '{"sessionId":"ses_xxx","method":"com.example.demo.User","direction":"callers"}'
PYTHONPATH=src python3 -m apkindex.cli pull com.tencent.mm   # adb 在连时才可用
# 子命令只有 tools/call/pull/doctor/sessions；具体查询一律走 call <tool> '<json>'
```

### 从设备取包（adb）

没有独立脚本，走 `loadApk` 的入参：

```jsonc
{ "name": "loadApk",
  "arguments": { "fromDevice": true, "packageName": "com.example.app",
                 "path": "" } }
```

`fromDevice=true` 时依次 `adb shell pm path <pkg>`（拿 base.apk 与 split APK 全部路径）
→ `adb shell dumpsys package <pkg>`（取 versionName/versionCode/minSdk/targetSdk，
和清单里的值互相校正）→ `adb pull` 到缓存目录再索引。`ADB` 环境变量指定 adb 路径
（默认 `adb_bin()` 的探测结果）。找不到 adb、设备没授权或超时都报 `ADB_UNAVAILABLE`
并给出下一步；**不假装能拉到自己拉不动的东西** —— 系统分区或受保护路径请在已 root
的机器上直接把 `/data/app/~~xxxx/.../base.apk` 当 `path` 传进来。

### 自测

```bash
python3 tests/test_tools.py                    # 38 组
APK_INDEX_TEST_REAL_APK=/path/a.apk,/path/b1.apk,/path/b2.apk python3 tests/test_tools.py
```

真机校准样本：TGAutoSign 1.2.1（1131 类，索引 ~1.6 s）、LocusMimic 2.0.0 ↔ 2.0.2
（差分识别 12 组改名候选）。只读校验用 `APK_INDEX_CACHE` + `APK_INDEX_ALLOWED_ROOTS`
把索引和读取范围钉在临时目录里。

`apkindex.cli doctor` 的 `ok:false` 只代表依赖不齐：缺 `aapt2` / `tools/dexlib.jar` / `tools/baksmali.jar` / `tools/apktool.jar` / `jadx/bin/jadx` 时资源与反编译走降级路径，索引与结构化查询不受影响（缺什么会逐项列名，不猜）。

## Streamable HTTP 传输（给只能填 URL 的客户端）

```bash
python3 -m apkindex.cli serve-http --host 127.0.0.1 --port 8732
# 手机上更靠谱的是这个（Android root，服务不会跟着工具环境一起被回收）：
sh tools/httpd-android.sh 8732
```

端点 `http://127.0.0.1:8732/mcp`：POST 一条 JSON-RPC → 200；客户端 `Accept` 里写了
`text/event-stream` 就回 SSE 单帧（`event: message` + `data: <同一份 JSON>`），
只要 `application/json` 就回裸 JSON —— Kotlin/Java 系的 MCP SDK 常常只认 SSE。
通知（无 id）→ 202 空 body；批量 → 200 + 数组；`GET` → 健康检查（`Accept` 要 event-stream
则开常驻流，只发注释帧保活）；`DELETE` → 200（回 501 会被客户端判成服务挂了）。
`initialize` 的应答带 `Mcp-Session-Id` 与 `MCP-Protocol-Version` 头（只发不校验：
拒绝未知会话 id 会让实现松一点的客户端直接卡死，本服务无状态可泄漏）。
与 stdio 版共用同一个 `Server.handle()`，23 个工具、参数校验、响应体积预算完全一致。
默认只绑回环；本机 loopback 与宿主 Android 是同一个 network namespace，
所以手机上的 App（例：LSPilot 的 MCP 拓展 → 本地 → 新建 → Streamable HTTP）
直接填 `http://127.0.0.1:8732/mcp` 就能连。

## 鉴权、状态码与完整部署说明

见 **`docs/HTTP-DEPLOY.md`**：启动器与开机自启、chroot 路径绑定、路由与帧的选择、
JSON-RPC → HTTP 状态码映射表、四个大小上限、token 鉴权（`APK_INDEX_MCP_TOKEN`，
非回环地址无 token 直接拒启）、`decompile` 的 `auto` 降级契约、curl 全流程、排障表。

三条最容易踩的先放在这里：

- 业务错误不占状态码：`tools/call` 成败都回 `200`，看信封里的 `ok` / `code`。
- `tools/call` 的 JSON-RPC `method` 恒为 `tools/call`，工具名在 `params.name`。
  把工具名当 method 发会得到 `404 / -32601`。
- `GET /mcp` 免鉴权，是健康检查；它不含任何包内容。

## HTTP 帧的选择

`Accept` 里同时有 `application/json` 与 `text/event-stream`（ktor/OkHttp 客户端的默认写法）时，
服务端回**裸 JSON**；只有客户端只接受 `text/event-stream` 才回 SSE 单帧（`event: message` + `data: <同一份 JSON>`）。
原因是有些客户端一进 SSE 模式就按"长流"读，单条响应要等流结束才交给上层，白吃一个 request timeout。
`--verbose` 会把每个请求的方法/工具名、字节数和超过 500ms 的耗时打到 stderr，
慢在哪个工具、有没有卡在锁上，看一眼日志就知道。

## 输出：人读文本 + 机器 JSON 双通道

`tools/call` 的结果给两份：

* `content[0].text` —— 给人读的渲染（`src/apkindex/render.py`）：一行结论 + 对齐条目 +
  一句下一步；空结果会解释"为什么可能是空"。descriptor / smali / reflector 这些
  干活要用的字段一个都不省，因为有的客户端只把 text 喂给模型。
* `structuredContent` —— 完整 envelope JSON，字段与早期版本一致，给程序解析。

以前两份内容都是同一坨 JSON，客户端常常重复显示两遍，人读很费劲；现在 text 走渲染，
JSON 只留一份。传输层不变：客户端 Accept 里同时允许 JSON 就回裸 JSON，只要 SSE 才回帧。

要自定义某个工具的样子：`render.RENDERERS["toolName"] = fn`（fn 收 envelope 返回字符串）；
没注册的工具自动走 `_r_generic`，至少是 key 行 + 编号条目，不会退回裸 JSON。