MCP 服务器

mcp-flutter-apk-injector

Enables Android APK reverse engineering and Flutter runtime injection through a six-step pipeline of decompile, analyze, synthesize, inject, patch, and repackage. Provides MCP tools for authorized security research and penetration testing.

README

mcp-flutter-apk-injector

Model Context Protocol (MCP) server for Android APK reverse engineering and Flutter runtime injection — an automated, enterprise-grade white-hat security research & penetration testing toolkit exposing a complete Decompile ➔ Analyze ➔ Synthesize ➔ Inject ➔ Patch ➔ Repackage pipeline as six modular MCP tools and agent prompt triggers.

🔒 Scope & Compliance Statement
This project is designed exclusively for security researchers, mobile auditors, and application owners auditing their own binaries or authorized targets. Repackaging third-party applications without explicit authorization is prohibited. You are responsible for using this tool lawfully.

🚀 Quick Start & Installation

You can run mcp-flutter-apk-injector directly via npx (no manual build required), or install it globally:

📦 Global NPM Install

npm install -g mcp-flutter-apk-injector

⚡ Running via `npx`

npx -y mcp-flutter-apk-injector@latest

🛠️ MCP Client Setup

Claude Desktop Configuration

Add the following block to your claude_desktop_config.json:

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

Antigravity IDE / Generic MCP Client (`stdio`)

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

⚡ Agent Prompts & Slash Commands

mcp-flutter-apk-injector registers native MCP Prompts for AI desktop agents (Antigravity IDE, Claude Desktop, Cursor):

/scan: Diagnostic audit scan of decompiled APK workspace, entry points, Smali structure, and native ABIs.
/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.

🧠 How it Works & Injection Modes

The pipeline supports four flexible injection strategies aligning with Flutter's "Add-to-App" v2 architecture:

activity_overlay: Generates a dedicated FlutterOverlayActivity extending FlutterActivity that reuses the pre-warmed cached engine.
view_tree_injection: Programmatically attaches a FlutterView into the decor view layout tree of the target Activity's onCreate().
headless_engine: Initializes a background FlutterEngine without UI for headless Dart execution, channel routing, and telemetry.
direct_application_hook: Directly instruments existing Application.onCreate() or attachBaseContext() methods in decompiled Smali without altering android:name in AndroidManifest.xml.

🛠️ The 6 Core MCP Tools

Tool Name	Detailed Function & Output
`decompile_apk`	Disassemble a target Android APK into Smali bytecode, native library trees (`lib/`), resources (`res/`), and a decoded `AndroidManifest.xml` using `apktool`. Returns package name, main Activity, Application class, min/target SDKs, native ABIs, and file manifest.
`analyze_injection_surface`	Scan a decompiled APK workspace to identify optimal injection hooks for Flutter runtime initialization: Application class presence (`android:name`), entry Activity, JNI loading sites, pre-existing Flutter classes, native ABIs, and recommended Smali patch points.
`synthesize_flutter_payload`	Compile a source Flutter project and extract the runtime artifacts required for injection: `libflutter.so` (Flutter engine), `libapp.so` (Dart AOT snapshot), the `flutter_assets` bundle, and ICU data. Produces a payload directory ready to merge into a decompiled APK workspace.
`inject_flutter_runtime_and_smali`	Inject Flutter engine assets, native libraries, and Smali glue code into a decompiled APK tree. Generates an `InjectedApplication` (`FlutterEngine` init + `libflutter`/`libapp` loading with try-catch fallback), a cached-engine bootstrap, an optional `FlutterOverlayActivity` (`activity_overlay` mode), and an optional two-way Smali<->Dart `MethodChannel` bridge. Returns a detailed patch report.
`patch_manifest_and_config`	Patch the decoded `AndroidManifest.xml` with Flutter runtime requirements: `INTERNET`/`WAKE_LOCK` permissions, custom Application class override, `FlutterActivity` entry (`activity_overlay`), `engine-id` metadata, `extractNativeLibs`, `hardwareAccelerated`, and optional `usesCleartextTraffic`. Returns a validation status for the patched manifest.
`recompile_align_and_sign`	Repack the decompiled APK workspace with `apktool`, run `zipalign` for 4-byte alignment, and sign with `apksigner` using V1/V2/V3 schemes. Uses an auto-generated debug keystore unless a custom `keystoreConfig` is provided. Returns the verified, aligned, installable APK path.

💻 System Requirements

Node.js >= 18.0.0
Java Runtime / JDK (required by apktool and apksigner)
Android SDK Build-Tools (zipalign, apksigner — auto-discovered from ANDROID_HOME or system PATH)
apktool installed on system PATH
Flutter SDK (required only when executing synthesize_flutter_payload)

🧪 Development & Testing

# Install local dependencies
npm install

# Build TypeScript to dist/
npm run build

# Typecheck without emitting
npm run typecheck

# Code formatting & lint check
npm run lint

# Execute Vitest suite (35 unit tests)
npm test