jadx-mcp-multisession

JADX-MCP 改良版：多会话管理 + 插件版本兼容 + 错误降级

基于 zinja-coder/jadx-mcp-server v3.3.5（Apache-2.0）深度改良，让 AI（如 Kimi Code CLI）能像使用 IDA-MCP 一样自主管理多个 jadx-gui 窗口：无窗口时自动拉起、多窗口间切换、按需关闭，并对上游插件在 Windows 上的多个缺陷做了兼容与降级处理。

┌─────────────┐   MCP(stdio/http)   ┌───────────────────┐   HTTP    ┌──────────────┐
│ AI 客户端     │ ─────────────────► │ jadx-mcp-server    │ ────────► │ jadx-gui 实例 │
│ (Kimi Code)  │ ◄───────────────── │ (Python FastMCP)  │ ◄──────── │  (每窗口一个, │
└─────────────┘                     └───────────────────┘           │   独立端口)   │
        会话管理工具: jadx_open_session / jadx_list_sessions /        └──────────────┘
        jadx_switch_session / jadx_close_session / jadx_get_session_info

---

✨ 核心特性

特性	说明
🪟 多会话管理	AI 可自行启动 / 列出 / 切换 / 关闭 jadx-gui 窗口（对齐 IDA-MCP 模式）
🚀 自动拉起	jadx-gui 未打开时，jadx_open_session(apk) 自动启动独立窗口并加载 APK
🔌 插件版本兼容	自动适配 jadx-ai-mcp 插件 3.3.x（legacy 参数名）/ 6.x（新参数名），并探测缺失端点
🛡️ 错误降级	get_main_activity_class 对非标准 LAUNCHER 应用本地解析 Manifest 降级；get_strings 尽力降级并输出诊断
🔄 向后兼容	不带 --jadx-sessions-dir 启动时行为与上游 v3.3.5 完全一致
🔍 能力探测	会话启动后自动检测插件参数风格与端点覆盖，异常插件明确告警

📦 目录结构

jadx-mcp-multisession/
├── jadx_mcp_server.py              # MCP server 入口（29 个上游工具 + 5 个会话工具）
├── requirements.txt                # Python 依赖（fastmcp>=3.0.2, httpx, requests）
├── LICENSE                         # Apache-2.0（上游同款）
├── MULTI_SESSION.md                # 多会话改造细节与实测问题修复记录
├── AGENTS.md                       # 开发者/后续 AI 的项目文档（先读这个）
├── src/
│   ├── session_manager.py          # [新增] 会话注册表/端口分配/进程管理/能力探测
│   ├── session_tools.py            # [新增] 5 个 jadx_* MCP 工具的 async 包装
│   ├── PaginationUtils.py          # 分页框架（上游）
│   ├── banner.py                   # 启动横幅（上游）
│   └── server/
│       ├── config.py               # [改造] active 会话路由 + 参数风格自适应
│       └── tools/                  # class/search/resource/refactor/debug/xrefs 工具
├── session-prefs-factory/          # [新增] Java Preferences 文件化实现（多实例端口隔离）
│   ├── src/com/jadxmcp/session/FilePrefsFactory.java
│   └── build.sh                    # 构建脚本（需要 JDK，产出 lib/file-prefs-factory.jar）
├── lib/
│   └── file-prefs-factory.jar      # [新增] 构建产物（Preferences 文件化，端口隔离关键）
└── tests/                          # 集成测试脚本（HTTP stream 模式 + stdio 模式）

🚀 快速开始

前置依赖

组件	说明
jadx-gui 1.5.3+	含 JRE 的发行包，目录含 jre/ 与 lib/jadx-gui-1.5.3-all.jar
jadx-ai-mcp 插件 6.x	放任意 plugins/ 目录（自动探测），6.x 参数与端点最全
Python 3.10+ & uv	server 运行环境
JDK（可选）	仅重新构建 file-prefs-factory.jar 时需要

1. 准备环境

# 构建 Preferences 文件化 jar（仓库已带构建产物，可跳过）
bash session-prefs-factory/build.sh
# 输出: <jadx根>/lib/file-prefs-factory.jar

# 安装 Python 依赖
uv sync   # 或 pip install -r requirements.txt

2. 配置 kimi-code（mcp.json）

"jadx": {
  "command": "uv",
  "args": [
    "--directory", "D:\\jadx\\jadx-mcp-server",
    "run", "jadx_mcp_server.py",
    "--jadx-host", "127.0.0.1",
    "--jadx-port", "8650",
    "--jadx-sessions-dir", "D:\\jadx\\jadx-sessions"
  ],
  "startupTimeoutMs": 60000,
  "toolTimeoutMs": 180000
}

--jadx-sessions-dir 是会话模式开关：设置即启用多会话，去掉即完全回到旧版单实例行为。 --jadx-home 默认取 server 目录的父目录（即 jadx 根）；--jadx-plugin-jar 可显式指定插件 jar。

3. 使用

AI: 打开这个 APK 分析一下            → jadx_open_session(apk_path)
AI: 现在分析另一个 APK               → jadx_open_session(另一个apk)   （新窗口）
AI: 切回刚才那个窗口                 → jadx_switch_session(session_id)
AI: 有哪些窗口开着？                  → jadx_list_sessions()
AI: 关掉 3 号窗口                     → jadx_close_session(session_id)

🔧 MCP 工具清单

会话管理（新增）

工具	参数	说明
jadx_open_session	apk_path: str, port: int=0	启动新会话并打开 APK；port=0 自动分配空闲端口（8650 起）
jadx_list_sessions	include_external: bool=False	列出会话+存活状态；可探测手动打开的外部实例
jadx_switch_session	session_id: str	切换 active，所有分析工具随后作用于该窗口
jadx_close_session	session_id: str	关闭会话（taskkill），active 自动转移
jadx_get_session_info	—	查看当前 active 会话（含 APK/端口/PID/存活）

分析工具（上游 29 个，路由自动跟随 active 会话）

类/方法：get_class_source get_methods_of_class get_fields_of_class get_smali_of_class get_method_by_name get_main_activity_class get_all_classes 等 搜索：search_classes_by_keyword search_method_by_name 资源：get_android_manifest get_manifest_component get_strings get_resource_file get_all_resource_file_names 引用：get_xrefs_to_class get_xrefs_to_method get_xrefs_to_field 重命名：rename_class rename_method rename_field rename_package rename_variable 调试：debug_get_stack_frames debug_get_threads debug_get_variables

🧪 测试

# 1. 启动 server（HTTP stream 模式，便于 curl/脚本测试）
uv run jadx_mcp_server.py --http --port 9000 --jadx-sessions-dir <会话目录>

# 2. 跑集成测试（需先有测试 APK；脚本内可改路径）
uv run python tests/test_multi_session.py <apk路径>     # 会话开/列/切/关
uv run python tests/test_feedback_fix.py                 # 参数/端点/降级全量验证
uv run python tests/test_stdio_client.py                 # stdio 模式冒烟（kimi-code 同款链路）

测试样本：com.hihonor.id.apk（荣耀账号 86MB/24k 类）、com.heytap.speechassist.apk（OPPO）

⚠️ 已知限制（上游插件缺陷）

限制	表现	对策
Windows 上 get_strings 对字符串在 resources.arsc 内的 APK 不可用	插件按正斜杠精确匹配 arsc 资源名，Windows 实际为反斜杠 → 404	server 尽力降级（分页遍历+读取+校验），失败返回诊断信息与替代方案（如 jadx CLI 反编译资源）
get-resource-file 对 arsc 内部资源存在截胡 bug	遍历到 resources.arsc 时可能返回错误的第一个子文件	server 侧 basename 校验拦截错误数据
get_xrefs_to_method 等业务性 404/400	"Method not found" / "Debugger not attached"	属正常业务响应，非缺陷

📜 许可与致谢

• 上游 server 与插件均为 Apache-2.0，本项目继承该许可（保留 LICENSE 与上游版权声明）
• 上游作者：zinja-coder（https://github.com/zinja-coder/jadx-mcp-server）
• 改良内容：多会话管理、FilePrefsFactory 端口隔离、插件参数/端点兼容、main-activity 与 strings 降级、能力探测