mcp-flutter-apk-injector

The World's Most Advanced Memory-Aware Model Context Protocol (MCP) Server for Android APK Reverse Engineering, Dalvik/Smali Bytecode Refactoring, Native JNI Tracing, and Flutter Runtime Overlay Injection.

🇬🇧 English Documentation   |   🇸🇦 التوثيق باللغة العربية

🇬🇧 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

🎮 The 4 Dynamic Injection Modes

⚡ 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.

🚀 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.

Related MCP server: Flutter MCP

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

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

خادم 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

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

⚡ أوامر 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)