android-decompile-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TimeCyber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ar.md

@@ -0,0 +1,228 @@
+dir="rtl"
+
+# 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.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)
+
+> ⚠️ **للتعلّم والتعليم فقط.** يُحظر الاستخدام في أي نشاط غير قانوني أو اختراق غير مصرّح أو انتهاك حقوق أو تجاوز حماية الغير. التزم بالقوانين المحلية وشروط التطبيق. المسؤولية عن إساءة الاستخدام على المستخدم.
+
+**خادم MCP** لفك حزم أندرويد وتحليل smali. من Cursor / Claude: إدارة الأجهزة، كشف الحماية، فك ثابت / BlackDex / Frida، dex→smali، والبحث عن واجهات API.
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## الميزات
+
+| القدرة | أداة MCP | ملاحظات |
+| --- | --- | --- |
+| 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 |
+
+### طرق فك الحماية
+
+| الطريقة | Root؟ | متى |
+| --- | --- | --- |
+| Static | No | Unpacked apps or shell/resources only |
+| BlackDex | No | Most protected apps |
+| Frida | **Yes** | Strong packers / fuller dumps |
+
+---
+
+## المتطلبات
+
+- **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).
+
+---
+
+## التثبيت والبناء
+
+```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` (**عدّل المسارات**):
+
+```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 executable | `adb` |
+| `DEX_OUT_DIR` | Default output dir | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali jar | auto-discover under `tools/` |
+
+---
+
+## مسارات العمل النموذجية
+
+### 1. فك ثابت (الأسرع)
+
+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. بدون 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. مع 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. أمثلة 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):
+
+| مثال | المسار | المحتوى |
+| --- | --- | --- |
+| Damai | [`examples/damai/`](./examples/damai/) | Frida smali.zip + API docs |
+| Huaxi Maternity | [`examples/huaxi/`](./examples/huaxi/) | Static smali.zip (`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: 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.**
+
+---
+
+## إخلاء المسؤولية القانوني
+
+هذا المشروع **للتعلّم والتعليم والبحث الأمني المصرّح به فقط**. يُحظر استخدامه في أي جريمة أو نشاط غير قانوني (وصول غير مصرّح، اختراق، قرصنة، هجمات، انتهاك الملكية الفكرية). المؤلفون غير مسؤولين عن إساءة الاستخدام. باستخدامك توافق على هذه الشروط.
+
+> ⚠️ **للتعلّم والتعليم فقط.** يُحظر الاستخدام في أي نشاط غير قانوني أو اختراق غير مصرّح أو انتهاك حقوق أو تجاوز حماية الغير. التزم بالقوانين المحلية وشروط التطبيق. المسؤولية عن إساءة الاستخدام على المستخدم.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/README.de.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** · [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)
+
+> ⚠️ **Nur für Lern- und Lehrzwecke.** Nicht für illegale Aktivitäten, unautorisiertes Cracken, Urheberrechtsverletzung oder das Umgehen fremder Schutzmaßnahmen verwenden. Beachten Sie lokale Gesetze und die Nutzungsbedingungen der App. Missbrauch liegt in Ihrer Verantwortung.
+
+Android-Unpacking + Smali-Analyse **MCP Server**. Über Cursor / Claude: Geräte, Packer-Erkennung, statisches / BlackDex / Frida-Unpacking, dex→smali, API-String-Suche.
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## Funktionen
+
+| Fähigkeit | MCP-Tool | Hinweise |
+| --- | --- | --- |
+| 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 |
+
+### Unpack-Methoden
+
+| Methode | Root? | Einsatz |
+| --- | --- | --- |
+| Static | No | Unpacked apps or shell/resources only |
+| BlackDex | No | Most protected apps |
+| Frida | **Yes** | Strong packers / fuller dumps |
+
+---
+
+## Voraussetzungen
+
+- **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).
+
+---
+
+## Installation & Build
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+```
+
+MCP starten (stdio):
+
+```bash
+npm start
+# node dist/index.js
+```
+
+Entwicklungsmodus:
+
+```bash
+npm run dev
+```
+
+---
+
+## Cursor-MCP einrichten
+
+In `.cursor/mcp.json` eintragen (**Pfade anpassen**):
+
+```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 neu starten / MCP neu laden.
+
+---
+
+## Umgebungsvariablen
+
+| Variable | Bedeutung | Standard |
+| --- | --- | --- |
+| `ADB_PATH` | adb executable | `adb` |
+| `DEX_OUT_DIR` | Default output dir | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali jar | auto-discover under `tools/` |
+
+---
+
+## Typische Abläufe
+
+### 1. Statisches Unpack (schnellste)
+
+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. Ohne 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. Mit 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. Smali-Beispiele
+
+```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
+```
+
+---
+
+## Struktur
+
+```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
+```
+
+---
+
+## Decompile-Beispiele
+
+Siehe [`examples/`](./examples/) (Smali als Zip):
+
+| Beispiel | Pfad | Inhalt |
+| --- | --- | --- |
+| Damai | [`examples/damai/`](./examples/damai/) | Frida smali.zip + API docs |
+| Huaxi Maternity | [`examples/huaxi/`](./examples/huaxi/) | Static smali.zip (`info.cd120.two`) |
+
+Nach dem Entpacken `smali_*` nutzen.
+
+---
+
+## MCP-Kurzreferenz
+
+| 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.**
+
+---
+
+## Rechtlicher Hinweis
+
+Dieses Projekt dient **ausschließlich dem Lernen, der Lehre und autorisierter Sicherheitsforschung**. Die Nutzung für Straftaten oder illegale Handlungen (unautorisierter Zugriff, Cracking, Piraterie, Angriffe, IP-Verletzung) ist streng untersagt. Autoren und Mitwirkende haften nicht für Missbrauch. Nutzung gilt als Zustimmung.
+
+> ⚠️ **Nur für Lern- und Lehrzwecke.** Nicht für illegale Aktivitäten, unautorisiertes Cracken, Urheberrechtsverletzung oder das Umgehen fremder Schutzmaßnahmen verwenden. Beachten Sie lokale Gesetze und die Nutzungsbedingungen der App. Missbrauch liegt in Ihrer Verantwortung.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/README.es.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** · [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)
+
+> ⚠️ **Solo para aprendizaje y enseñanza.** No lo use para actividades ilegales, cracking no autorizado, infracción de derechos ni elusión de protecciones de terceros. Cumpla las leyes locales y los términos de la app. Usted es responsable del mal uso.
+
+**MCP Server** de desempaquetado Android + análisis smali. Desde Cursor / Claude: dispositivos, detección de protectores, unpack estático / BlackDex / Frida, dex→smali y búsqueda de APIs.
+
+Repo: [https://github.com/TimeCyber/DexAndroid](https://github.com/TimeCyber/DexAndroid)
+
+---
+
+## Funciones
+
+| Capacidad | Herramienta MCP | Notas |
+| --- | --- | --- |
+| 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 |
+
+### Métodos de unpack
+
+| Método | ¿Root? | Cuándo |
+| --- | --- | --- |
+| Static | No | Unpacked apps or shell/resources only |
+| BlackDex | No | Most protected apps |
+| Frida | **Yes** | Strong packers / fuller dumps |
+
+---
+
+## Requisitos
+
+- **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).
+
+---
+
+## Instalación y compilación
+
+```bash
+git clone https://github.com/TimeCyber/DexAndroid.git
+cd DexAndroid
+npm install
+npm run build
+```
+
+Iniciar MCP (stdio):
+
+```bash
+npm start
+# node dist/index.js
+```
+
+Modo desarrollo:
+
+```bash
+npm run dev
+```
+
+---
+
+## Integración Cursor (MCP)
+
+Añada a `.cursor/mcp.json` (**ajuste las rutas**):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+Reinicie Cursor / recargue MCP.
+
+---
+
+## Variables de entorno
+
+| Variable | Significado | Por defecto |
+| --- | --- | --- |
+| `ADB_PATH` | adb executable | `adb` |
+| `DEX_OUT_DIR` | Default output dir | `<cwd>/unpack-output` |
+| `BAKSMALI_JAR` | baksmali jar | auto-discover under `tools/` |
+
+---
+
+## Flujos típicos
+
+### 1. Unpack estático (más rápido)
+
+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. Sin 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. Con 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. Ejemplos 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
+```
+
+---
+
+## Estructura
+
+```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
+```
+
+---
+
+## Ejemplos de decompilación
+
+Vea [`examples/`](./examples/) (smali en zip):
+
+| Ejemplo | Ruta | Contenido |
+| --- | --- | --- |
+| Damai | [`examples/damai/`](./examples/damai/) | Frida smali.zip + API docs |
+| Huaxi Maternity | [`examples/huaxi/`](./examples/huaxi/) | Static smali.zip (`info.cd120.two`) |
+
+Tras descomprimir, use `smali_*`.
+
+---
+
+## Referencia rápida 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` |
+
+---
+
+## Preguntas frecuentes
+
+**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.**
+
+---
+
+## Aviso legal
+
+Este proyecto es **solo para aprendizaje, enseñanza e investigación de seguridad autorizada**. Queda prohibido usarlo para delitos o ilegalidades (acceso no autorizado, cracking, piratería, ataques o infracción de PI). Autores y contribuidores no responden por abusos. Al usarlo acepta estos términos.
+
+> ⚠️ **Solo para aprendizaje y enseñanza.** No lo use para actividades ilegales, cracking no autorizado, infracción de derechos ni elusión de protecciones de terceros. Cumpla las leyes locales y los términos de la app. Usted es responsable del mal uso.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).