System Architecture¶

Deep dive into JADX-AI-MCP technical design.

High-Level Design¶

The system follows a 3-Tier Architecture:

1. Presentation Tier: LLM Client (Claude, Cherry Studio)
2. Application Tier: MCP Server (Python)
3. Data Tier: JADX Plugin (Java) + JADX Core

block-beta
  columns 3
  LLM_Client(("LLM Client"))
  block:MCP
    MCPServer["MCP Server (Python)"]
    FastMCP["FastMCP Lib"]
  end
  block:Plugin
    Javalin["Javalin Server"]
    JADXAPI["JADX API"]
    GUI["JADX GUI"]
  end

  LLM_Client --> MCPServer
  MCPServer --> Javalin
  Javalin --> JADXAPI
  JADXAPI --> GUI

Threading Model¶

Python Server (AsyncIO)¶

• Single-threaded Event Loop: Uses asyncio for non-blocking I/O
• HTTP Client: httpx.AsyncClient handles concurrent requests
• Concurrency: Can handle multiple MCP tool calls simultaneously

Java Plugin (Multi-threaded)¶

• HTTP Server: Jetty (via Javalin) uses a thread pool (default: 200 threads)
• Request Handling: Each request runs on a worker thread
• UI Interaction: CRITICAL - All JADX API calls accessing UI/Data must run on Event Dispatch Thread (EDT)

EDT Pattern:

// Wrong: Direct access from worker thread
String code = javaClass.getCode(); // ConcurrentModificationException

// Correct: Wrap in invokeLater
SwingUtilities.invokeLater(() -> {
    String code = javaClass.getCode(); // Safe
});

State Management¶

Plugin State (Persistent)¶

• Port Configuration: Stored in Java Preferences node com.zin.jadxaimcp
• Session State: JADX project state (loaded APK, decompilation cache)

Server State (Transient)¶

• Configuration: Loaded from CLI args at startup
• Connections: No persistent connections (HTTP is stateless)

🔒 Security Model¶

Network Security¶

• Localhost Binding: Plugin binds ONLY to 127.0.0.1. Remote access blocked.
• No Auth: Relies on OS-level user isolation.

Input Validation¶

• Path Traversal: Resource paths validated against APK root.
• SQL Injection: Not applicable (no SQL database).
• Code Injection: Refactoring inputs validated for Java naming rules.

Transport Security¶

• Proxy Isolation: Python httpx client uses trust_env=False to prevent OS-level HTTP/HTTPS proxies from intercepting 127.0.0.1 traffic or routing internal API calls externally.
• Stdio Integrity: When running as an MCP stdio server, all internal logging, health checks, and application banners write to stderr. The stdout stream is strictly reserved for JSON-RPC communication to prevent protocol corruption.

Performance Optimization¶

Pagination Strategy¶

Large APKs can have 10,000+ classes. Returning all at once causes: 1. JSON Serialization Overhead: 10MB+ responses 2. Network Latency: Slow transfer 3. Client Timeout: LLM clients timeout after 60s

Solution: - All list endpoints support offset and count - Default page size: 100 items - Maximum page size: 10,000 items

Caching¶

• JADX Core: Caches decompiled source automatically
• Plugin: Does NOT cache responses (to support real-time refactoring)

Protocol Specifications¶

MCP Protocol (JSON-RPC 2.0)¶

• Tools: Exposed as MCP tools
• Resources: Not currently used (everything is a tool)
• Prompts: Not currently used

HTTP Protocol (Internal)¶

• Method: GET (mostly)
• Format: JSON
• Status Codes:
  • 200 OK: Success
  • 400 Bad Request: Invalid params
  • 404 Not Found: Class/Method missing
  • 500 Server Error: Internal failure

Tech Stack¶