android-decompile-mcp 0.0.0-stage → 1.0.0

package/README.vi.md

@@ -0,0 +1,226 @@
+# DexAndroid
+
+[English](./README.md) · [简体中文](./README.zh-CN.md) · [繁體中文](./README.zh-TW.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Español](./README.es.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md) · [Português](./README.pt-BR.md) · [Русский](./README.ru.md) · [العربية](./README.ar.md) · [हिन्दी](./README.hi.md) · [Bahasa Indonesia](./README.id.md) · **Tiếng Việt** · [ไทย](./README.th.md) · [Italiano](./README.it.md) · [Türkçe](./README.tr.md)
+
+> ⚠️ **Chỉ dùng cho học tập và giảng dạy.** Không dùng cho hành vi bất hợp pháp, crack trái phép, xâm phạm bản quyền hay vượt bảo vệ của bên thứ ba. Tuân thủ pháp luật địa phương và điều khoản ứng dụng. Người dùng chịu trách nhiệm nếu lạm dụng.
+
+**MCP Server** giải nén Android + phân tích smali. Trong Cursor / Claude: quản lý thiết bị, phát hiện packer, unpack tĩnh / BlackDex / Frida, dex→smali, tìm chuỗi API.
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## Tính năng
+
+| Khả năng | Công cụ MCP | Ghi chú |
+| --- | --- | --- |
+| Devices | `list_devices` | Connected ADB devices |
+| Packages | `list_packages` | Optional keyword filter |
+| Packer detect | `detect_packer` | 360 / Tencent / Bangcle / ijiami / Alibaba, etc. |
+| Pull APK | `pull_apk` | Installed app (+ splits) |
+| Static unpack | `static_unpack` | Extract `classes*.dex` |
+| No-Root unpack | `blackdex_prepare` / `blackdex_pull` | BlackDex memory dump |
+| Root unpack | `frida_prepare` / `frida_unpack` | frida-server + frida-dexdump |
+| Decompile | `dex_to_smali` | baksmali → smali |
+| Analyze | `smali_list_classes` / `smali_read_class` / `smali_search` | List / read / regex |
+
+### Các phương pháp unpack
+
+| Phương pháp | Root? | Khi nào |
+| --- | --- | --- |
+| Static | No | Unpacked apps or shell/resources only |
+| BlackDex | No | Most protected apps |
+| Frida | **Yes** | Strong packers / fuller dumps |
+
+---
+
+## Yêu cầu
+
+- **Windows / macOS / Linux** (docs use Windows examples)
+- **Node.js** ≥ 18
+- **ADB** on PATH, or set `ADB_PATH`
+- **Java 8+** (for baksmali via `dex_to_smali`)
+- Optional: [BlackDex](https://github.com/CodingGay/BlackDex/releases); rooted device + `frida-server`; `pip install frida-tools frida-dexdump`
+
+Place baksmali fat jar / frida-server / BlackDex under local `tools/` (large binaries are gitignored).
+
+---
+
+## Cài đặt & build
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+```
+
+Khởi động MCP (stdio):
+
+```bash
+npm start
+# node dist/index.js
+```
+
+Chế độ dev:
+
+```bash
+npm run dev
+```
+
+---
+
+## Thiết lập Cursor (MCP)
+
+Thêm vào `.cursor/mcp.json` (**đổi đường dẫn**):
+
+```json
+{
+  "mcpServers": {
+    "dex-android-unpack": {
+      "command": "node",
+      "args": ["E:/DexAndroid/dist/index.js"],
+      "env": {
+        "ADB_PATH": "E:/Android/Sdk/platform-tools/adb.exe",
+        "DEX_OUT_DIR": "E:/DexAndroid/unpack-output"
+      }
+    }
+  }
+}
+```
+
+Khởi động lại Cursor / tải lại MCP.
+
+---
+
+## Biến môi trường
+
+| Biến | Ý nghĩa | Mặc định |
+| --- | --- | --- |
+| `ADB_PATH` | adb executable | `adb` |
+| `DEX_OUT_DIR` | Default output dir | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali jar | auto-discover under `tools/` |
+
+---
+
+## Quy trình điển hình
+
+### 1. Unpack tĩnh (nhanh nhất)
+
+1. `list_devices` or prepare local `apkPath`.
+2. `detect_packer`.
+3. `static_unpack` → `classes*.dex`.
+4. `dex_to_smali` → smali folder.
+5. `smali_search` / `smali_read_class`.
+
+**Note:** Protected apps often yield only the shell via static unpack—use BlackDex / Frida for business code.
+
+### 2. Không Root (BlackDex)
+
+1. `list_devices`.
+2. `blackdex_prepare` with `blackdexApkPath`.
+3. Unpack the target app in BlackDex UI.
+4. `blackdex_pull` with `targetPkg`.
+5. `dex_to_smali` then `smali_*`.
+
+### 3. Có Root (Frida)
+
+1. Rooted device (e.g. Magisk), `adb` ready.
+2. `frida_prepare` to push/start `tools/frida-server`.
+3. Matching `frida` / `frida-dexdump` locally (prefer 16.x).
+4. `frida_unpack` with `pkg`, prefer `spawn: true`, `deepSearch: true`.
+5. `dex_to_smali` on output, then analyze.
+
+If Frida 17 attach fails, align tools to 16.x; some devices need temporary `setenforce 0`.
+
+### 4. Ví dụ smali
+
+```text
+smali_list_classes  smaliDir=.../smali  keyword=login
+smali_search        smaliDir=.../smali  pattern=https?://|/api/|publicClient/
+smali_read_class    smaliDir=.../smali  className=com.example.api.ApiService
+```
+
+---
+
+## Cấu trúc
+
+```text
+DexAndroid/
+├── src/                 # MCP server (TypeScript)
+│   ├── index.ts
+│   ├── adb.ts
+│   ├── detect.ts
+│   ├── smali.ts
+│   └── unpack/
+├── dist/
+├── examples/            # Damai / Huaxi sample smali.zip + docs
+├── tools/               # baksmali / frida-server / BlackDex (local)
+├── unpack-output/       # local dumps (gitignored)
+├── package.json
+└── README.md
+```
+
+---
+
+## Ví dụ decompile
+
+Xem [`examples/`](./examples/) (smali dạng zip):
+
+| Ví dụ | Đường dẫn | Nội dung |
+| --- | --- | --- |
+| Damai | [`examples/damai/`](./examples/damai/) | Frida smali.zip + API docs |
+| Huaxi Maternity | [`examples/huaxi/`](./examples/huaxi/) | Static smali.zip (`info.cd120.two`) |
+
+Sau khi giải nén, dùng `smali_*`.
+
+---
+
+## Bảng tra MCP
+
+| Tool | Params |
+| --- | --- |
+| `detect_packer` | `apkPath` or `pkg`, optional `serial` |
+| `pull_apk` | `pkg`, optional `outDir` / `serial` |
+| `static_unpack` | `apkPath` or `pkg`, optional `outDir` |
+| `blackdex_prepare` | `blackdexApkPath`, optional `serial` |
+| `blackdex_pull` | `targetPkg`, optional `outDir` / `serial` |
+| `frida_prepare` | optional `serial` / `serverLocalPath` |
+| `frida_unpack` | `pkg`, optional `spawn` / `deepSearch` / `outDir` |
+| `dex_to_smali` | `dexInput`, optional `outDir` |
+| `smali_list_classes` | `smaliDir`, optional `keyword` |
+| `smali_read_class` | `smaliDir`, `className` |
+| `smali_search` | `smaliDir`, `pattern`, optional `flags` / `maxResults` |
+
+---
+
+## FAQ
+
+**Q: Empty `list_devices`?**  
+Check USB debugging, `adb devices`, pass `serial` if multiple.
+
+**Q: No business classes after static unpack?**  
+Likely packed—use BlackDex or Frida.
+
+**Q: `dex_to_smali` failed?**  
+Install Java; put baksmali jar in `tools/` or set `BAKSMALI_JAR`.
+
+**Q: Frida jailed / version mismatch?**  
+Keep `frida-server` and host `frida` major versions aligned; try 16.x.
+
+**Q: Where is output?**  
+Default `unpack-output/` (or `DEX_OUT_DIR`). **Do not commit dumps.**
+
+---
+
+## Tuyên bố pháp lý
+
+Dự án này **chỉ dành cho học tập, giảng dạy và nghiên cứu bảo mật được ủy quyền**. Nghiêm cấm dùng cho tội phạm/bất hợp pháp (truy cập trái phép, crack, đạo nhái, tấn công, xâm phạm IP). Tác giả không chịu trách nhiệm về lạm dụng. Việc sử dụng đồng nghĩa chấp nhận điều khoản.
+
+> ⚠️ **Chỉ dùng cho học tập và giảng dạy.** Không dùng cho hành vi bất hợp pháp, crack trái phép, xâm phạm bản quyền hay vượt bảo vệ của bên thứ ba. Tuân thủ pháp luật địa phương và điều khoản ứng dụng. Người dùng chịu trách nhiệm nếu lạm dụng.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,252 @@
+# DexAndroid
+
+[English](./README.md) · **简体中文** · [繁體中文](./README.zh-TW.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Español](./README.es.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md) · [Português](./README.pt-BR.md) · [Русский](./README.ru.md) · [العربية](./README.ar.md) · [हिन्दी](./README.hi.md) · [Bahasa Indonesia](./README.id.md) · [Tiếng Việt](./README.vi.md) · [ไทย](./README.th.md) · [Italiano](./README.it.md) · [Türkçe](./README.tr.md)
+
+> ⚠️ **仅用于学习与教学目的。** 禁止用于任何违法犯罪、未授权破解、侵权或绕过他人防护的行为。使用者须遵守所在国家/地区法律法规与目标应用服务条款；因滥用造成的后果由使用者自行承担。
+
+安卓脱壳 + smali 分析 **MCP Server**。在 Cursor / Claude 等客户端中通过工具调用完成：设备管理、加固检测、静态/免 Root/Root 脱壳、dex→smali、接口字符串检索。
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## 功能概览
+
+| 能力 | MCP 工具 | 说明 |
+| --- | --- | --- |
+| 设备列表 | `list_devices` | ADB 已连接设备 |
+| 包名列表 | `list_packages` | 可按关键字过滤 |
+| 加固识别 | `detect_packer` | 360 / 腾讯 / 梆梆 / 爱加密 / 阿里聚安全等 |
+| 拉 APK | `pull_apk` | 从设备拉取已安装应用（含 split） |
+| 静态解包 | `static_unpack` | 解压 APK 提取 `classes*.dex` |
+| 免 Root 脱壳 | `blackdex_prepare` / `blackdex_pull` | BlackDex 内存 dump 后拉取 |
+| Root 脱壳 | `frida_prepare` / `frida_unpack` | 推送 frida-server + frida-dexdump |
+| 反编译 | `dex_to_smali` | baksmali 转 smali |
+| 分析 | `smali_list_classes` / `smali_read_class` / `smali_search` | 列类、读类、正则搜索 |
+| 入口定位 | `find_app_entry` | MAIN/LAUNCHER + smali onCreate（只读） |
+| 解码/重打包 | `apk_decode` / `apk_repack` | apktool 解码 + 重建签名 |
+
+### 三种脱壳方案对比
+
+| 方案 | 是否需要 Root | 适用场景 |
+| --- | --- | --- |
+| 静态解包 | 否 | 未加固，或只要壳/资源 |
+| BlackDex | 否 | 多数加固 App |
+| Frida | **是** | 强加固 / 壳对抗，内存 dump 更完整 |
+
+---
+
+## 环境要求
+
+- **Windows / macOS / Linux**（文档以 Windows 为例）
+- **Node.js** ≥ 18
+- **ADB**：加入 PATH，或设置 `ADB_PATH`
+- **Java 8+**（`dex_to_smali` 调用 baksmali）
+- 可选：[BlackDex](https://github.com/CodingGay/BlackDex/releases) APK；设备 Root + `frida-server`；本机 `pip install frida-tools frida-dexdump`
+
+将 baksmali fat jar / frida-server / BlackDex 放到本地 `tools/`（大文件默认不进 Git，见 `.gitignore`）。
+
+---
+
+## 安装（推荐）
+
+无需 clone，通过 npx 自动从 npm 下载并启动：
+
+```bash
+npx -y android-decompile-mcp
+```
+
+或全局安装：
+
+```bash
+npm i -g android-decompile-mcp
+android-decompile-mcp
+```
+
+### 本地开发构建
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+npm start
+```
+
+---
+
+## 接入 Cursor（MCP）
+
+在项目 `.cursor/mcp.json` 或 Cursor 全局 MCP 配置中增加：
+
+```json
+{
+  "mcpServers": {
+    "android-decompile-mcp": {
+      "command": "npx",
+      "args": ["-y", "android-decompile-mcp"],
+      "env": {
+        "ADB_PATH": "adb",
+        "DEX_OUT_DIR": "./unpack-output"
+      }
+    }
+  }
+}
+```
+
+保存后重启 Cursor / 重载 MCP。例如：「列出设备并检测加固」「对本地 apk 做 static_unpack，再 dex_to_smali，搜索登录接口」。
+
+---
+
+## 环境变量
+
+| 变量 | 说明 | 默认 |
+| --- | --- | --- |
+| `ADB_PATH` | adb 可执行文件 | `adb` |
+| `DEX_OUT_DIR` | 脱壳/拉取默认输出目录 | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali 可执行 jar | 自动在 `tools/` 下查找 |
+
+---
+
+## 使用说明（典型流程）
+
+### 1. 静态解包（最快）
+
+1. `list_devices` 确认设备（若用 `pkg` 拉取）或准备本地 `apkPath`。
+2. `detect_packer` 看是否加固。
+3. `static_unpack` → 得到 `classes*.dex`。
+4. `dex_to_smali` → smali 目录。
+5. `smali_search` / `smali_read_class` 分析接口、字符串、加解密等。
+
+**注意：** 加固 App 的静态 dex 往往只有壳，业务代码需 BlackDex / Frida。
+
+### 2. 免 Root（BlackDex）
+
+1. `list_devices`。
+2. `blackdex_prepare`，传入 `blackdexApkPath`。
+3. 在手机 BlackDex 界面选择目标应用并脱壳。
+4. `blackdex_pull`，传入 `targetPkg`。
+5. `dex_to_smali` → 再 `smali_*` 分析。
+
+### 3. Root（Frida）
+
+1. 设备已 Root（如 Magisk），`adb` 可用。
+2. `frida_prepare`：推送并启动 `tools/frida-server`。
+3. 本机已安装匹配版本的 `frida` / `frida-dexdump`（建议 16.x）。
+4. `frida_unpack`：传 `pkg`，建议 `spawn: true`、`deepSearch: true`。
+5. 对输出目录 `dex_to_smali` 后分析。
+
+若 Frida 17 附加失败，可降级到同一 16.x；部分机型需临时 `setenforce 0`。
+
+### 4. smali 分析示例
+
+```text
+smali_list_classes  smaliDir=.../smali  keyword=login
+smali_search        smaliDir=.../smali  pattern=https?://|/api/|publicClient/
+smali_read_class    smaliDir=.../smali  className=com.example.api.ApiService
+```
+
+---
+
+## 目录结构
+
+```text
+DexAndroid/
+├── src/                 # MCP server (TypeScript)
+│   ├── index.ts
+│   ├── adb.ts
+│   ├── detect.ts
+│   ├── smali.ts
+│   └── unpack/
+├── dist/
+├── examples/            # Damai / Huaxi sample smali.zip + docs
+├── skills/              # 规范 skill 源（改这里再 sync）
+├── .cursor/skills/      # Cursor
+├── .agents/skills/      # Codex
+├── .claude/skills/      # Claude Code
+├── tools/               # baksmali / frida-server / BlackDex (local)
+├── unpack-output/       # local dumps (gitignored)
+├── package.json
+└── README.md
+```
+
+### Agent Skill（多客户端）
+
+脱壳后使用 **`android-api-smali-analysis`**，强制还原请求头 / Body / 加解密与密钥（smali / `.so` / 服务端下发），禁止只写 path。
+
+| 客户端 | 路径 |
+| --- | --- |
+| 规范源 | [`skills/android-api-smali-analysis/SKILL.md`](./skills/android-api-smali-analysis/SKILL.md) |
+| Cursor | [`.cursor/skills/`](./.cursor/skills/android-api-smali-analysis/) |
+| Codex | [`.agents/skills/`](./.agents/skills/android-api-smali-analysis/) |
+| Claude Code | [`.claude/skills/`](./.claude/skills/android-api-smali-analysis/)（可 `/android-api-smali-analysis`） |
+
+修改规范源后执行：`node tools/sync-skills.mjs`。详见 [`skills/README.md`](./skills/README.md)。
+
+---
+
+## 反编译示例
+
+仓库 [`examples/`](./examples/) 提供两套可下载示例（smali 为 zip）：
+
+| 示例 | 路径 | 内容 |
+| --- | --- | --- |
+| 大麦 | [`examples/damai/`](./examples/damai/) | Frida smali 压缩包 + API / 选座 / 登录文档 |
+| 华西妇幼 | [`examples/huaxi/`](./examples/huaxi/) | 静态解包 smali 压缩包（`info.cd120.two`） |
+
+解压后即可对目录执行 `smali_list_classes` / `smali_search` / `smali_read_class`。
+
+---
+
+## MCP 工具参数速查
+
+| Tool | Params |
+| --- | --- |
+| `detect_packer` | `apkPath` or `pkg`, optional `serial` |
+| `pull_apk` | `pkg`, optional `outDir` / `serial` |
+| `static_unpack` | `apkPath` or `pkg`, optional `outDir` |
+| `blackdex_prepare` | `blackdexApkPath`, optional `serial` |
+| `blackdex_pull` | `targetPkg`, optional `outDir` / `serial` |
+| `frida_prepare` | optional `serial` / `serverLocalPath` |
+| `frida_unpack` | `pkg`, optional `spawn` / `deepSearch` / `outDir` |
+| `dex_to_smali` | `dexInput`, optional `outDir` |
+| `smali_list_classes` | `smaliDir`, optional `keyword` |
+| `smali_read_class` | `smaliDir`, `className` |
+| `smali_search` | `smaliDir`, `pattern`, optional `flags` / `maxResults` |
+| `find_app_entry` | `projectDir` / `manifestPath` / `apkPath`，可选 `smaliDir` |
+| `apk_decode` | `apkPath`，可选 `outDir` |
+| `apk_repack` | `projectDir`，可选 `outApk` / keystore 参数 |
+| `smali_patch` | `mode` + `smaliPath`/`projectDir`；自备 `content` 或 `insert_verify_log` |
+
+---
+
+## 常见问题
+
+**Q: `list_devices` 为空？**  
+检查 USB 调试、`adb devices`、多设备时传 `serial`。
+
+**Q: 静态解包后找不到业务类？**  
+多半是加固壳，请改用 BlackDex 或 Frida。
+
+**Q: `dex_to_smali` 失败？**  
+确认已安装 Java，并在 `tools/` 放置 baksmali jar，或设置 `BAKSMALI_JAR`。
+
+**Q: Frida 报 jailed / 版本不匹配？**  
+保持 `frida-server` 与本机 `frida` 主版本一致；必要时用 16.x。
+
+**Q: 输出目录在哪？**  
+默认 `unpack-output/`（或 `DEX_OUT_DIR`）。**请勿提交到 Git**。
+
+---
+
+## 合规与免责声明
+
+本项目**仅用于学习、教学与已授权的安全研究**。严禁将本工具用于任何违法犯罪活动，包括但不限于未授权访问、破解、盗版、攻击他人系统或侵犯知识产权。作者与贡献者不对任何滥用行为负责。使用即表示你已阅读并同意上述条款。
+
+> ⚠️ **仅用于学习与教学目的。** 禁止用于任何违法犯罪、未授权破解、侵权或绕过他人防护的行为。使用者须遵守所在国家/地区法律法规与目标应用服务条款；因滥用造成的后果由使用者自行承担。
+
+---
+
+## License
+
+MIT，见仓库根目录 [`LICENSE`](./LICENSE)。

package/README.zh-TW.md

@@ -0,0 +1,226 @@
+# DexAndroid
+
+[English](./README.md) · [简体中文](./README.zh-CN.md) · **繁體中文** · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [Español](./README.es.md) · [Français](./README.fr.md) · [Deutsch](./README.de.md) · [Português](./README.pt-BR.md) · [Русский](./README.ru.md) · [العربية](./README.ar.md) · [हिन्दी](./README.hi.md) · [Bahasa Indonesia](./README.id.md) · [Tiếng Việt](./README.vi.md) · [ไทย](./README.th.md) · [Italiano](./README.it.md) · [Türkçe](./README.tr.md)
+
+> ⚠️ **僅供學習與教學用途。** 禁止用於任何違法犯罪、未授權破解、侵權或規避他人防護之行為。使用者須遵守當地法律與目標應用服務條款；濫用後果自負。
+
+安卓脫殼 + smali 分析 **MCP Server**。可在 Cursor / Claude 等客戶端透過工具呼叫完成：裝置管理、加固偵測、靜態/免 Root/Root 脫殼、dex→smali、介面字串檢索。
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## 功能概覽
+
+| 能力 | MCP 工具 | 說明 |
+| --- | --- | --- |
+| 设备列表 | `list_devices` | ADB 已连接设备 |
+| 包名列表 | `list_packages` | 可按关键字过滤 |
+| 加固识别 | `detect_packer` | 360 / 腾讯 / 梆梆 / 爱加密 / 阿里聚安全等 |
+| 拉 APK | `pull_apk` | 从设备拉取已安装应用（含 split） |
+| 静态解包 | `static_unpack` | 解压 APK 提取 `classes*.dex` |
+| 免 Root 脱壳 | `blackdex_prepare` / `blackdex_pull` | BlackDex 内存 dump 后拉取 |
+| Root 脱壳 | `frida_prepare` / `frida_unpack` | 推送 frida-server + frida-dexdump |
+| 反编译 | `dex_to_smali` | baksmali 转 smali |
+| 分析 | `smali_list_classes` / `smali_read_class` / `smali_search` | 列类、读类、正则搜索 |
+
+### 三種脫殼方案比較
+
+| 方案 | 是否需要 Root | 適用場景 |
+| --- | --- | --- |
+| 静态解包 | 否 | 未加固，或只要壳/资源 |
+| BlackDex | 否 | 多数加固 App |
+| Frida | **是** | 强加固 / 壳对抗，内存 dump 更完整 |
+
+---
+
+## 環境需求
+
+- **Windows / macOS / Linux**（文件以 Windows 為例）
+- **Node.js** ≥ 18
+- **ADB**：加入 PATH，或設定 `ADB_PATH`
+- **Java 8+**（`dex_to_smali` 呼叫 baksmali）
+- 可選：[BlackDex](https://github.com/CodingGay/BlackDex/releases)；裝置 Root + `frida-server`；本機 `pip install frida-tools frida-dexdump`
+
+請將 baksmali fat jar / frida-server / BlackDex 放於本機 `tools/`（大型檔案預設不進 Git）。
+
+---
+
+## 安裝與建置
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+```
+
+啟動 MCP（stdio）:
+
+```bash
+npm start
+# node dist/index.js
+```
+
+開發模式:
+
+```bash
+npm run dev
+```
+
+---
+
+## 接入 Cursor（MCP）
+
+於 `.cursor/mcp.json` 或全域 MCP 設定新增（**路徑請改為本機**）：
+
+```json
+{
+  "mcpServers": {
+    "dex-android-unpack": {
+      "command": "node",
+      "args": ["E:/DexAndroid/dist/index.js"],
+      "env": {
+        "ADB_PATH": "E:/Android/Sdk/platform-tools/adb.exe",
+        "DEX_OUT_DIR": "E:/DexAndroid/unpack-output"
+      }
+    }
+  }
+}
+```
+
+儲存後重啟 Cursor / 重載 MCP。
+
+---
+
+## 環境變數
+
+| 變數 | 說明 | 預設 |
+| --- | --- | --- |
+| `ADB_PATH` | adb 可执行文件 | `adb` |
+| `DEX_OUT_DIR` | 脱壳/拉取默认输出目录 | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali 可执行 jar | 自动在 `tools/` 下查找 |
+
+---
+
+## 使用說明（典型流程）
+
+### 1. 靜態解包（最快）
+
+1. `list_devices` 或準備本機 `apkPath`。
+2. `detect_packer`。
+3. `static_unpack` → `classes*.dex`。
+4. `dex_to_smali` → smali 目錄。
+5. `smali_search` / `smali_read_class`。
+
+**注意：** 加固 App 靜態 dex 常只有殼，業務程式碼需 BlackDex / Frida。
+
+### 2. 免 Root（BlackDex）
+
+1. `list_devices`。
+2. `blackdex_prepare`（`blackdexApkPath`）。
+3. 於手機 BlackDex 介面選擇目標 App 並脫殼。
+4. `blackdex_pull`（`targetPkg`）。
+5. `dex_to_smali` 後再 `smali_*`。
+
+### 3. Root（Frida）
+
+1. 裝置已 Root，`adb` 可用。
+2. `frida_prepare` 推送並啟動 `frida-server`。
+3. 本機安裝相符版本 `frida` / `frida-dexdump`（建議 16.x）。
+4. `frida_unpack`（建議 `spawn: true`、`deepSearch: true`）。
+5. `dex_to_smali` 後分析。
+
+若 Frida 17 附加失敗，可對齊至 16.x；部分機型需暫時 `setenforce 0`。
+
+### 4. smali 分析範例
+
+```text
+smali_list_classes  smaliDir=.../smali  keyword=login
+smali_search        smaliDir=.../smali  pattern=https?://|/api/|publicClient/
+smali_read_class    smaliDir=.../smali  className=com.example.api.ApiService
+```
+
+---
+
+## 目錄結構
+
+```text
+DexAndroid/
+├── src/                 # MCP server (TypeScript)
+│   ├── index.ts
+│   ├── adb.ts
+│   ├── detect.ts
+│   ├── smali.ts
+│   └── unpack/
+├── dist/
+├── examples/            # Damai / Huaxi sample smali.zip + docs
+├── tools/               # baksmali / frida-server / BlackDex (local)
+├── unpack-output/       # local dumps (gitignored)
+├── package.json
+└── README.md
+```
+
+---
+
+## 反編譯範例
+
+見 [`examples/`](./examples/)（smali 以 zip 提供）：
+
+| 範例 | 路徑 | 內容 |
+| --- | --- | --- |
+| 大麥 | [`examples/damai/`](./examples/damai/) | Frida smali 壓縮包 + API 文件 |
+| 華西婦幼 | [`examples/huaxi/`](./examples/huaxi/) | 靜態解包 smali 壓縮包（`info.cd120.two`） |
+
+解壓後即可執行 `smali_*` 工具。
+
+---
+
+## MCP 工具參數速查
+
+| Tool | Params |
+| --- | --- |
+| `detect_packer` | `apkPath` or `pkg`, optional `serial` |
+| `pull_apk` | `pkg`, optional `outDir` / `serial` |
+| `static_unpack` | `apkPath` or `pkg`, optional `outDir` |
+| `blackdex_prepare` | `blackdexApkPath`, optional `serial` |
+| `blackdex_pull` | `targetPkg`, optional `outDir` / `serial` |
+| `frida_prepare` | optional `serial` / `serverLocalPath` |
+| `frida_unpack` | `pkg`, optional `spawn` / `deepSearch` / `outDir` |
+| `dex_to_smali` | `dexInput`, optional `outDir` |
+| `smali_list_classes` | `smaliDir`, optional `keyword` |
+| `smali_read_class` | `smaliDir`, `className` |
+| `smali_search` | `smaliDir`, `pattern`, optional `flags` / `maxResults` |
+
+---
+
+## 常見問題
+
+**Q: `list_devices` 為空？**  
+檢查 USB 偵錯、`adb devices`，多裝置時傳 `serial`。
+
+**Q: 靜態解包後找不到業務類？**  
+多半是加固殼，請改用 BlackDex 或 Frida。
+
+**Q: `dex_to_smali` 失敗？**  
+確認已安裝 Java，並放置 baksmali jar 或設定 `BAKSMALI_JAR`。
+
+**Q: Frida jailed / 版本不符？**  
+保持 `frida-server` 與本機 `frida` 主版本一致；必要時用 16.x。
+
+**Q: 輸出目錄在哪？**  
+預設 `unpack-output/`。**請勿提交至 Git**。
+
+---
+
+## 合規與免責聲明
+
+本專案**僅供學習、教學與已授權安全研究**。嚴禁用於任何違法犯罪行為，包括未授權存取、破解、盜版、攻擊系統或侵害智慧財產權。作者與貢獻者不對濫用負責。使用即表示同意上述條款。
+
+> ⚠️ **僅供學習與教學用途。** 禁止用於任何違法犯罪、未授權破解、侵權或規避他人防護之行為。使用者須遵守當地法律與目標應用服務條款；濫用後果自負。
+
+---
+
+## License
+
+MIT，見倉庫根目錄 [`LICENSE`](./LICENSE)。