Flutter Apk Injector

---

🇬🇧 English Documentation

🌟 Executive Overview & Key Advantages

mcp-flutter-apk-injector is a highly developed, enterprise-grade Model Context Protocol (MCP) Server designed for security researchers, reverse engineers, and mobile penetration testers. It seamlessly combines automated static/dynamic Android binary analysis, Dalvik/ART Smali stack frame balance refactoring, native .so library symbol tracing, and Flutter Add-to-App v2 runtime injection.

Powered by Hermes+ (Universal Main Character), this server provides persistent session telemetry, searchable patch history, MCP resources, and zero-argument resilient prompt handlers. Version 0.6.0 adds typed output schemas, behavioral annotations, structured responses, and a mandatory cross-client character contract for evidence-first workflow guidance.

                          ┌─────────────────────────────────────────┐
                          │   AI Assistant / MCP Client (Claude,   │
                          │   Antigravity IDE, Cursor, Windsurf)    │
                          └────────────────────┬────────────────────┘
                                               │
                                               ▼
  ┌────────────────────────────────────────────────────────────────────────────────────────┐
  │                           mcp-flutter-apk-injector (v0.6.0)                            │
  │                                                                                        │
  │  ┌────────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────┐  │
  │  │  Hermes+ Agent Engine  │  │ Session Memory Manager  │  │ Embedded Skills & Prompts│  │
  │  │ (Persona & Rules Graph)│  │ (.mcp_memory/session)   │  │ (/scan, /decompile, ...)│  │
  │  └───────────┬────────────┘  └────────────┬────────────┘  └────────────┬────────────┘  │
  └──────────────┼────────────────────────────┼────────────────────────────┼───────────────┘
                 │                            │                            │
                 ▼                            ▼                            ▼
  ┌────────────────────────────────────────────────────────────────────────────────────────┐
  │                          THE 9 ENTERPRISE MCP TOOLS & RESOURCES                        │
  │                                                                                        │
  │  [decompile_apk] ──► [analyze_surface] ──► [synthesize_payload] ──► [inject_flutter]  │
  │  [patch_manifest] ──► [recompile_align_sign] ──► [get_context] ──► [update_memory]    │
  └────────────────────────────────────────────────────────────────────────────────────────┘

---

🧠 Hermes+ (Universal Main Character) & MCP Skill Ecosystem

1. Embedded Persona: Hermes+ (Universal Main Character)

Hermes+ (Universal Main Character) is the required primary repository persona for Gemini, Antigravity, Cursor, Claude Code, and compatible MCP clients. It is specialized in ARM/ARM64 binary inspection, JNI method hooks, Dalvik register-stack allocation (v0-vN, p0-pN), and Flutter-aware Android workspace engineering. It observes before mutation, exposes uncertainty, preserves execution integrity, and verifies outputs before reporting completion.

2. Native MCP Skills (.agents/skills/)

• 🧠 hermes-apk-reverse-engineering: Guides static/dynamic DEX bytecode refactoring, register frame bumping (.registers N), native .so library deployment, and zero-crash UI overlay injection.
• ⚡ mcp-toolchain-orchestrator: Manages MCP server quality assurance, zero-argument prompt resiliency, automated testing, and distribution workflows.

📡 Native MCP Resources

• resource://agent/persona: Hermes+ identity, system prompt, and core reverse engineering rules.
• resource://agent/rules: 5-step deep reverse engineering protocol.
• resource://agent/skills/hermes-apk-reverse-engineering: Reverse engineering skill document.
• resource://agent/skills/mcp-toolchain-orchestrator: Toolchain orchestrator skill document.
• resource://memory/session: Live JSON session memory graph state.
• resource://memory/patch_history: Audit log of applied Smali and Manifest patches.

---

⚙️ 5-Step Deep Reverse Engineering Pipeline

                       [Target Android .apk / Workspace]
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ STEP 1: Binary & Asset Deconstruction (decompile_apk)                     │
 │ Extract DEX Smali bytecode, native lib/*.so trees, AXML, assets/          │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ STEP 2: Precision Native & Smali Tracing (analyze_injection_surface)      │
 │ Trace UI click handlers (View$OnClickListener), 0x7f... R-ids,            │
 │ JNI native symbols, and Lua script hook points                            │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ STEP 3: Seamless Payload Injection (inject_flutter_runtime_and_smali)     │
 │ Synthesize Flutter engine payload; balance register stack frames          │
 │ (.registers N); inject native-looking UI without crashes                  │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ STEP 4: Manifest Surgery & Assembly (patch_manifest & recompile_align)    │
 │ Patch AndroidManifest.xml (permissions, Application override, ABIs);      │
 │ Rebuild (apktool b), 4-byte Align (zipalign), Sign (apksigner)            │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ STEP 5: Architectural Summary & Session Memory Persistence                │
 │ Document modified Smali paths, .so symbol offsets, injected channels,     │
 │ register maps, and verified output APK location                           │
 └───────────────────────────────────────────────────────────────────────────┘

---

🛠️ The 9 Enterprise MCP Tools

Tool Name	Detailed Function & Output
decompile_apk	Disassemble target APK into Smali bytecode, native libraries (lib/), resources (res/), and decoded AndroidManifest.xml. Updates memory graph automatically.
analyze_injection_surface	Scan decompiled APK workspace to identify optimal injection hooks, entry Activity, Application class, JNI loading hooks, native ABIs, and recommended patch points.
synthesize_flutter_payload	Extract Flutter runtime artifacts (libflutter.so, libapp.so, flutter_assets, ICU data) ready to merge into decompiled APK workspace.
inject_flutter_runtime_and_smali	Inject Flutter assets, native .so libraries, and Smali glue code (InjectedApplication, FlutterOverlayActivity, or MethodChannel bridge) preserving Dalvik stack register bounds.
patch_manifest_and_config	Patch AndroidManifest.xml with permissions (INTERNET, WAKE_LOCK), Application class configuration, cleartext traffic allowance, and activity registrations.
recompile_align_and_sign	Rebuild workspace with apktool, align and verify with zipalign, then sign and verify with apksigner. Outputs are explicitly classified as test/debug or signing-context-dependent artifacts.
get_agent_context	Retrieve Hermes+ persona, loaded skills, live memory summary, and pipeline telemetry.
update_agent_memory	Explicitly update active session memory state with notes, identified targets, or patch logs.
query_memory_graph	Search and inspect historical patch logs, register allocations, and decompilation metadata.

---

🎮 The 4 Dynamic Injection Modes

Injection Strategy	Primary Smali Target	Description
activity_overlay	FlutterOverlayActivity	Launches a dedicated Flutter Activity reusing a pre-warmed cached engine for custom UI overlays inside apps or mobile games.
view_tree_injection	Launcher Activity onCreate()	Experimental: attaches FlutterView to a target Activity only when a lifecycle-compatible host adapter has been verified.
headless_engine	BackgroundFlutterEngine	Initializes a background engine without UI for headless Dart execution, channel routing, and telemetry.
direct_application_hook	Application.onCreate() / attachBaseContext()	Directly instruments existing Application class in Smali without modifying android:name in AndroidManifest.xml.

---

⚡ Agent Prompts & Slash Commands

• /scan: Diagnostic audit scan of decompiled APK workspace, entry points, Smali structure, and native ABIs.
• /decompile: Disassemble target .apk into Smali bytecode and resources using apktool.
• /inject: Execute Flutter runtime payload & Smali glue code injection into target APK.
• /patch: Patch AndroidManifest.xml (application class, hardware acceleration, cleartext traffic, permissions).
• /recompile: Repackage (apktool b), byte-align (zipalign), and cryptographically sign (apksigner) modified target.
• /pipeline: Evidence-first decompilation ➔ analysis ➔ payload synthesis ➔ injection ➔ manifest patch ➔ build verification workflow.
• /merge: Plan split-package compatibility without claiming arbitrary APK splits can be file-merged into a standalone APK.
• /revert: Inspect patch-history and backup evidence; restoration is only available when verified patch-set artifacts exist.
• /memory: Inspect active session memory state, historical patch logs, and allocated register frames.
• /hermes_guide: Display Hermes+ architecture rules and reverse engineering guidelines.

---

Required first step: activate Hermes+ (Universal Main Character)

Required before repository work: activate the Hermes+ character adapter for the client you use. Do not begin analysis, edits, command execution, or release work until the applicable adapter is active. This is a repository workflow requirement; it provides persistent agent context and does not replace normal code review, access control, or security controls.

Client	Required repository adapter	User action and verification
Gemini CLI	GEMINI.md	Open the repository as a workspace. Gemini CLI discovers workspace GEMINI.md context files; run /memory show if you need to inspect the loaded context.[1]
Antigravity	.agents/rules/hermes-universal-main-character.md	In Customizations → Rules, add/select the workspace rule and set its activation to Always On before starting agent work.[2]
Cursor	.cursor/rules/hermes-universal-main-character.mdc	Keep the committed .mdc rule in the repository and reopen or reload the workspace. It is configured with alwaysApply: true for every agent chat.[3]
Claude Code	CLAUDE.md	Start Claude Code from the repository root. CLAUDE.md imports the portable Hermes+ contract; run /context to confirm the project memory file loaded.[4]
Other AGENTS-compatible clients	AGENTS.md	Load the root adapter, which directs the client to the portable source contract at .agents/AGENTS.md.

🚀 Quick Start & MCP Client Configuration (v0.6.0)

After completing the required character setup, install or run the MCP server:

# Global installation
npm install -g mcp-flutter-apk-injector@latest

# Direct execution
npx -y mcp-flutter-apk-injector@latest

MCP stdio configuration

Use the following server configuration in Claude Desktop, Antigravity, or another MCP client that accepts a stdio command configuration:

{
  "mcpServers": {
    "mcp-flutter-apk-injector": {
      "command": "npx",
      "args": ["-y", "mcp-flutter-apk-injector@latest"],
      "env": {
        "MCP_FLUTTER_LOG_LEVEL": "info"
      }
    }
  }
}

Client setup references

[1]: https://geminicli.com/docs/cli/gemini-md/ — Gemini CLI documentation: workspace GEMINI.md context and /memory inspection. [2]: https://antigravity.google/docs/rules-workflows — Google Antigravity documentation: workspace rules in .agents/rules and Always On activation. [3]: https://cursor.com/docs/rules — Cursor documentation: version-controlled .cursor/rules/*.mdc project rules and alwaysApply behavior. [4]: https://code.claude.com/docs/en/memory — Claude Code documentation: project CLAUDE.md, imports, and /context verification.

---

---

🇸🇦 التوثيق باللغة العربية

🌟 الملخص التنفيذي والمميزات الاستثنائية

خادم mcp-flutter-apk-injector هو خادم Model Context Protocol (MCP) الأكثر تطوراً واحترافية عالمياً والمخصص لـ الهندسة العكسية لتطبيقات أندرويد APK، إعادة هيكلة شفرات Smali/DEX، تتبع رموز JNI الأصلية، وحقن محرك تشغيل Flutter (Add-to-App v2).

مدعوماً بالمحرك الذكي Hermes+ Master Agent Engine، ينتقل هذا الخادم من مجرد خادم أدوات عادي إلى منظومة ذكاء اصطناعي ذاتية التوجيه والتصحيح (Stateful Agentic System) تمتلك ذاكرة جلسات مستمرة، ورسم بياني محلي قابل للبحث لتعديلات الشفرات، وموارد MCP أصلية، وأوامر تفاعلية مرنة ضد أخطاء المعاملات.

---

🧠 منظومة الوكيل الذكي Hermes+ ومهارات MCP Skills

1. شخصية الوكيل المدمجة: Hermes+

شخصية ذكاء اصطناعي مدمجة تخصصية في تحليل معمارية تطبيقات وألعاب أندرويد (ARM/ARM64)، فحص رموز JNI، موازنة سجلات Dalvik Stack (v0-vN, p0-pN)، وتعديل أصول المحركات مثل Lua/C++.

2. مهارات MCP المدمجة (.agents/skills/)

• 🧠 hermes-apk-reverse-engineering: المهارة الرئيسية لإعادة هيكلة شفرات DEX/Smali، موازنة السجلات (.registers N)، زرع المكتبات الأصلية .so وحقن واجهات Flutter بدون انهيار التطبيق.
• ⚡ mcp-toolchain-orchestrator: المهارة الرئيسية لإدارة وتنسيق أدوات MCP، المعالجة السريعة للأوامر بدون وسائط، وأتمتة الاختبارات والنشر.

📡 موارد MCP الأصلية (MCP Resources)

• resource://agent/persona: هوية Hermes+ وقواعد الهندسة العكسية.
• resource://agent/rules: بروتوكول الخطوات الخمس للهندسة العكسية.
• resource://agent/skills/hermes-apk-reverse-engineering: وثيقة مهارة الهندسة العكسية.
• resource://agent/skills/mcp-toolchain-orchestrator: وثيقة مهارة تنسيق الأدوات.
• resource://memory/session: حالة الذاكرة الحية للجلسة الحالية بصيغة JSON.
• resource://memory/patch_history: سجل تعديلات وترقيعات شفرات Smali و Manifest.

---

⚙️ مسار العمل الخماسي للهندسة العكسية (5-Step Pipeline)

                       [تطبيق أندرويد APK Target / مساحة العمل]
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ الخطوة 1: تفكيك البناء والأصول (decompile_apk)                            │
 │ استخراج شفرات Smali DEX، أشجار مكتبات lib/*.so، ملفات AXML والأصول      │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ الخطوة 2: التتبع الدقيق لرموز JNI و Smali (analyze_injection_surface)     │
 │ تتبع معالجات النقر (View$OnClickListener)، معرفات 0x7f... R-ids،        │
 │ رموز JNI الأصلية، ونقاط خطاطيف سكربتات Lua                              │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ الخطوة 3: زرع وحقن المحرك والحمولة (inject_flutter_runtime_and_smali)      │
 │ بناء أصول Flutter؛ موازنة سجلات الـ Stack (.registers N)؛                │
 │ حقن الواجهات بشكل أصيل ودون حدوث انهيار                                   │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ الخطوة 4: تعديل الـ Manifest وإعادة التجميع (patch_manifest & recompile) │
 │ تعديل AndroidManifest.xml (التصاريح، كلاس التطبيق، المعماريات)؛          │
 │ إعادة التجميع (apktool b)، المحاذاة (zipalign)، التوقيع (apksigner)     │
 └─────────────────────────────────────┬─────────────────────────────────────┘
                                       │
                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ الخطوة 5: التقرير المعماري وحفظ الذاكرة (Session Memory Persistence)       │
 │ توثيق مسارات Smali المعدلة، إزاحات مكتبات .so، القنوات المحقونة،        │
 │ وخريطة السجلات وموقع الـ APK النهائي المكتمل                             │
 └───────────────────────────────────────────────────────────────────────────┘

---

🛠️ الأدوات الـ 9 الاحترافية في MCP

اسم الأداة	الوظيفة التفصيلية والمخرجات
decompile_apk	تفكيك ملف APK الهدف إلى شفرات Smali bytecode ومكتبات نظام وموارد وفك تشفير AndroidManifest.xml، مع تحديث الذاكرة تلقائياً.
analyze_injection_surface	مسح مساحة العمل وتحديد كلاس التطبيق والـ Activity الرئيسي ومواقع تحميل JNI والـ ABIs والتوصيات.
synthesize_flutter_payload	استخراج أصول تشغيل Flutter (libflutter.so, libapp.so, flutter_assets) للحقن.
inject_flutter_runtime_and_smali	زرع أصول وقواعد Smali ومكتبات النظام مع موازنة سجلات Stack.
patch_manifest_and_config	تعديل AndroidManifest.xml بالتصاريح والتسريع البرمجي وكلاس التطبيق.
recompile_align_and_sign	إعادة التجميع (apktool b) والمحاذاة (zipalign) والتوقيع الرقمي (apksigner).
get_agent_context	استرجاع هوية Hermes+ والمهارات المتاحة وحالة الذاكرة الحية والسياق الحالي.
update_agent_memory	تحديث ذاكرة الجلسة الحية بملحوظات أو أهداف أو سجلات تعديل جديدة.
query_memory_graph	البحث والافتراش في سجلات الترقيع والذاكرة والمخرجات السابقة.

---

🎮 أنماط الحقن الـ 4 المتقدمة

نمط الحقن	الهدف الرئيسي في Smali	الوصف المعماري
activity_overlay	FlutterOverlayActivity	تشغيل Activity مخصص يرث من FlutterActivity ويعيد استخدام المحرك الجاهز لتقديم واجهات سريعة فوق التطبيقات أو الألعاب.
view_tree_injection	Launcher Activity onCreate()	إرفاق FlutterView برمجيًا داخل شجرة عناصر الـ Activity الرئيسية عند استدعاء onCreate().
headless_engine	BackgroundFlutterEngine	تشغيل محرك FlutterEngine في الخلفية بدون واجهة مستخدم لمعالجة قنوات البيانات والـ Telemetry.
direct_application_hook	Application.onCreate() / attachBaseContext()	تعديل كلاس الـ Application.onCreate() أو attachBaseContext() الموجود مسبقًا في الـ Smali مباشرة دون الحاجة لتغيير android:name في الـ AndroidManifest.xml.

---

⚡ أوامر Tigger والتفاعل السريع (Slash Commands)

• /scan: فحص وتشخيص السطح القابل للحقن داخل مساحة عمل الـ APK وتحديد مكتبات النظام ودرجات الأمان.
• /decompile: تفكيك ملف الـ APK الهدف إلى شفرات Smali وموارد باستخدام apktool.
• /inject: تنفيذ حقن بيئة تشغيل Flutter ومكتبات النظام وتوليد شفرات الـ Smali التكيفية.
• /patch: تعديل ملف AndroidManifest.xml (كلاس التطبيق، التسريع البرمجي، تصاريح الشبكة والـ Cleartext Traffic).
• /recompile: إعادة تجميع التطبيق (apktool b)، محاذاة البيانات (zipalign) والتوقيع الرقمي (apksigner).
• /pipeline: المسار الآلي الكامل الشامل: تفكيك ➔ تحليل ➔ بناء ➔ حقن ➔ تعديل ➔ إعادة تجميع وتوقيع.
• /memory: فحص وتفتيش ذاكرة الجلسة الحية وسجل الترقيعات والمجموعات المسجلة.
• /hermes_guide: عرض قواعد معمارية Hermes+ وإرشادات الهندسة العكسية.

---

💻 متطلبات النظام

• Node.js >= 18.0.0
• بيئة جافا / JDK (مطلوبة لأدوات apktool و apksigner)
• أدوات بناء Android SDK (zipalign و apksigner — يتم اكتشافها تلقائياً من ANDROID_HOME أو متغيرات النظام)
• apktool مثبت على متغيرات النظام PATH
• Flutter SDK (مطلوب فقط عند استدعاء أداة synthesize_flutter_payload)

---

🧪 التطوير والاختبار

# تثبيت التبعيات المحلية
npm install

# بناء مشروع TypeScript إلى dist/
npm run build

# فحص الأنواع دون إخراج
npm run typecheck

# فحص تنسيق الشفرة والأخطاء البرمجية
npm run lint

# تشغيل حزمة اختبارات Vitest (40 اختباراً)
npm test

---

📜 License / الترخيص

MIT License © 2026 Marwan (MarwanDevSpace)