Asc

asc-mcp

asc-mcp is a read-only Model Context Protocol server for agent-driven static analysis of Android artifacts. It gives MCP clients structured access to APK metadata, DEX declarations and instructions, targeted decompilation, cross-references, resources, signing data, and artifact comparison. There is no manual decompilation CLI; running asc-mcp starts the server.

This project is an MCP-focused continuation of Droid ASC, created by MG1937. The original author designed and implemented ASC's direct DEX querying, cross-reference engine, minimal-DEX reconstruction, and on-demand decompilation architecture. The MCP server and its structured analysis interface are built on that work.

The original ASC project was presented at Black Hat Europe Arsenal as "R8 Compiler Optimization as a DeCompiler Primitive." Its published 352 MB benchmark reported global cross-reference search in 1.79 seconds and class decompilation in 177 milliseconds using 141 MB of RAM. Those figures describe the original benchmark, not a guarantee for every artifact or MCP client.

Features

• Structured manifest, package, SDK, and component analysis with effective provider read/write permissions
• Class listing, outlines, on-demand Java source, and Dalvik disassembly
• Descriptor-aware string, type, method, and field cross-reference search
• Reference evidence with opcode, method-relative offset, access type, and exact target
• Method and field discovery, DEX string search, and method-body search
• Class hierarchy and bounded caller/callee graphs
• Resource inventory, binary XML decoding, and native-library discovery
• APK signing schemes, certificate fingerprints, and embedded-secret scanning
• Class-inventory comparison between artifact versions
• MCP resources for decoded manifests and decompiled class source
• Isolated analysis workers that protect the MCP process from decompiler globals
• Bounded worker caches for repeated class, DEX, and identical reference queries

All analysis tools are read-only. The server does not install, modify, rebuild, or sign APK files.

Supported inputs

load_artifact reports a capability list for each file. Operations that require an unavailable structure, such as requesting signing data from a DEX file, fail with a clear MCP tool error. JVM bytecode decompilation is not currently included; ordinary JAR files expose their class and archive inventories.

Install

Python 3.10 or newer is required.

python -m pip install .

The Python distribution and installed executable are both named asc-mcp:

asc-mcp

asc-mcp starts an MCP server over stdio. It does not provide manual decompilation subcommands.

MCP client configuration

Configure an MCP host to launch the installed command:

{
  "mcpServers": {
    "asc-mcp": {
      "command": "asc-mcp",
      "env": {
        "ASC_MCP_ALLOWED_ROOTS": "/home/user/apks:/work/mobile"
      }
    }
  }
}

On Windows, separate multiple allowed roots with ; instead of :. If ASC_MCP_ALLOWED_ROOTS is omitted, only the server's working directory is accessible.

Typical agent workflow:

1. Call load_artifact with an allowed artifact path.
2. Reuse the returned analysis_id with the analysis tools.
3. Use descriptors returned by apk_get_class_outline unchanged when selecting overloaded methods or fields.
4. Call close_artifact when the analysis is no longer needed.

MCP tools

List and search results are paginated and capped. Tool results use MCP structured output schemas rather than human-formatted CLI text.

The server publishes routing instructions, tool descriptions, and descriptions for every input parameter so MCP clients can choose calls without relying on this README. The most important search distinctions are:

apk_find_type_instructions covers type operands such as new-instance, check-cast, and const-class; it does not include method calls, field accesses, signatures, or declarations. Empty reference results include a hint explaining their scope and the next appropriate tool. Every reference hit includes evidence for each matching instruction: its byte offset within the caller, opcode, read/write/invoke/load classification, and structured target metadata.

Repeated work on the same unchanged artifact reuses bounded per-worker caches. The cache covers inflated DEX buffers, parsed lightweight and Androguard DEX objects, class inventories, call-graph indexes, and identical reference queries. Cache keys include file size and modification time, so replacing an artifact does not reuse stale analysis data.

Resources and prompts

The server exposes these resource templates:

• artifact://{analysis_id}/manifest.xml
• artifact://{analysis_id}/class/{class_name}

It also includes artifact_triage, trace_behavior, and compare_artifacts prompts.

Configuration

Do not expose Streamable HTTP to untrusted networks without an authenticated deployment boundary. The stdio transport is recommended for local analysis.

Development

python -m pip install -r requirements.txt
python tests/run_tests.py --require-decompiler --suite unit
python tests/run_tests.py --require-decompiler --suite integration
python tests/benchmark_startup.py --samples 9
python tests/benchmark_reference.py --samples 9

The integration suite starts an in-process MCP client and exercises a spawned analysis worker. The release test also validates the deterministic source archive outside the checkout.

Original ASC sponsors

These sponsors are credited by the original Droid ASC project:

Acknowledgements

Primary credit goes to MG1937 for creating Droid ASC and its core analysis engine. Thanks also to Androguard for the Android reverse-engineering and DEX analysis foundation, and to the Model Context Protocol Python SDK for the server runtime.

Licensed under Apache-2.0.