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

静态索引 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 客户端

{
  "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 个工具

返回契约（每个工具都保证）

• 成功：{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 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 重建才能拿回正确的组件与安全面。

命令行

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 的入参：

{ "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 传进来。

自测

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 的客户端）

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。