droidasc-mcp

A small, defensive MCP server for Droid ASC, the fast
on-demand Android APK decompiler.

droidasc-mcp exposes ASC's public CLI as typed, read-only MCP tools. Every analysis runs in an
isolated subprocess group, accepts only input paths under configured roots, and returns paginated
structured data instead of unbounded terminal output.

Community project. Not affiliated with or endorsed by the Droid ASC maintainers.

中文文档

Tools

Install

Version 0.4.0 adds class search/outline/hierarchy, constant use sites, decoded instruction
search/disassembly and source-token links through the existing DEX query tools. It also adds
strict DEX 041 imports, first-level JVM JAR inventory/diffs, resumable archive byte pages,
manifest/class resource templates, compare_versions and opt-in secret candidate values.
The complete competitor source map records all 25 tools,
two resources, three prompts and 87 parameters, including intentional interface differences.
Functional parity does not establish universal performance superiority.

Container, signing and review workflows and their support boundaries are described in
REVERSE_WORKFLOW.md. Release gates cover cross-platform,
transport and clean-package execution.

Python 3.10 or newer is required. CI checks Linux and native Windows runners on Python 3.10-3.13, including
all 18 tools over stdio/HTTP against a source-built
acceptance APK
and package installation. macOS remains unverified.

Install the version-pinned GitHub release on Linux:

python -m venv .venv
.venv/bin/python -m pip install https://github.com/cnlnn/droidasc-mcp/releases/download/v0.4.0/droidasc_mcp-0.4.0-py3-none-any.whl

Windows (PowerShell):

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install https://github.com/cnlnn/droidasc-mcp/releases/download/v0.4.0/droidasc_mcp-0.4.0-py3-none-any.whl

Windows uses .venv\Scripts\droidasc-mcp.exe for the server command. For development,
clone this repository and run uv sync --locked --extra dev instead.

Connect

The default transport is stdio. Limit the server to directories that contain APKs:

export DROIDASC_MCP_ALLOWED_ROOTS=/absolute/path/to/apks
.venv/bin/droidasc-mcp

Codex

codex mcp add droidasc \
  --env DROIDASC_MCP_ALLOWED_ROOTS=/absolute/path/to/apks \
  -- /absolute/path/to/droidasc-mcp/.venv/bin/droidasc-mcp

Claude Desktop and compatible hosts

{
  "mcpServers": {
    "droidasc": {
      "command": "/absolute/path/to/droidasc-mcp/.venv/bin/droidasc-mcp",
      "env": {
        "DROIDASC_MCP_ALLOWED_ROOTS": "/absolute/path/to/apks"
      }
    }
  }
}

Streamable HTTP

DROIDASC_MCP_ALLOWED_ROOTS=/absolute/path/to/apks \
  .venv/bin/droidasc-mcp --transport streamable-http --host 127.0.0.1 --port 8000

The endpoint is http://127.0.0.1:8000/mcp. Keep it on loopback unless you add an authenticated,
TLS-terminating reverse proxy.

Examples

Ask an MCP host to call:

asc_apk_info(apk_path="/samples/app.apk")
asc_manifest_summary(apk_path="/samples/app.apk", limit=20)
asc_list_apk_entries(apk_path="/samples/app.apk", kind="resource", limit=100)
asc_read_apk_entry(apk_path="/samples/app.apk", entry_path="res/xml/config.xml")
asc_list_classes(apk_path="/samples/app.apk", prefix="com.example", limit=100)
asc_find_refs(apk_path="/samples/app.apk", kind="string", value="Authorization")
asc_find_refs(apk_path="/samples/app.apk", kind="extends", value="android.app.Activity")
asc_find_refs(apk_path="/samples/app.apk", kind="impl", value="java.lang.Runnable")
asc_get_class_source(apk_path="/samples/app.apk", class_name="com.example.MainActivity")

APK contents and manifest triage

The three archive tools bind every successful result to apk_sha256. Match hashes before
correlating resources, components and code. Inventory supports a category and a literal,
case-sensitive path prefix; its CRC values are ZIP metadata, not integrity verification.
Native rows report archive paths and ABI directories, not ELF analysis.

asc_read_apk_entry streams a bounded prefix without filesystem extraction. max_bytes
defaults to 16 KiB, with a 128 KiB maximum before UTF-8/base64 encoding. XML decoding reads
only complete inputs up to 4 MiB. decoded, decoding_status, decoding_warnings,
truncated, content_complete and crc_verified distinguish successful decoding, decoder
warnings, output truncation and incomplete raw reads. Resource-table values remain unresolved.

asc_manifest_summary preserves raw namespaced declarations and component order, intent
filters, metadata, provider path/URI-grant rules, and permission inheritance sources. Explicit
empty permissions clear inherited requirements; an alias without its own permission requires
none, rather than inheriting its target/application permission. Absent exported defaults and
resource-dependent values remain unresolved. These are static declarations, not proof of
runtime accessibility. Follow next_offset; reduce page size on an explicit response_limit.
See archive workflow boundaries and acceptance.

Results include total, offset, limit, truncated, and next_offset. Use next_offset for the
next request (null means done): the response budget can shorten a page. A single line
that exceeds the budget produces an explicit error rather than silent truncation.

Reference fields are best-effort parsing of ASC CLI text. Embedded newlines can split records;
total counts output lines, not semantic references. Reference lines are sorted before pagination.
Values such as --help are query data, not CLI options. ASC's matching semantics still apply:
string/type queries accept regular expressions, and invalid patterns return errors. The exact
value --gui returns an explicit error because ASC reserves it before parsing CLI arguments.
Exact method/field class names accept
Java names or Dalvik descriptors; fuzzy class patterns retain their original meaning.

The extends and impl kinds query direct superclass/interface declarations,
including interface-to-interface declarations. They require Droid ASC 0.1.2.post2 or newer
(installed by the updated dependency requirement). Supply a Java name or Dalvik descriptor in
value; class filters are rejected for these kinds. Records contain dex, class_name,
relation, target, and raw, with relation_scope="direct". They are not transitive
subclass searches or runtime dispatch graphs. Unrecognized text remains a raw-only record.
The same queries work with asc_analyze_dex(operation="find_refs", ...).

Snapshots are decoded and sorted once, then cached for 60 seconds (up to 8 entries). The cache
budget accounts for Python strings and tuple pointers, not just original output bytes. Identical
concurrent queries share a single computation; unrelated queries and cache hits do not wait on
a global computation lock. Snapshots are
keyed by query and file identity/size/timestamps. Cache misses rerun ASC; this is not an immutable
content-addressed evidence store. Do not modify APK files between pages.

Bare DEX analysis

Available in v0.3.0 and newer.
It accepts 1-64 explicit .dex paths under the allowed roots, with a combined size bounded by
DROIDASC_MCP_MAX_APK_BYTES. Directories, APKs, CompactDex and DEX 041 containers are not accepted.

asc_analyze_dex(dex_paths=["/samples/classes.dex", "/samples/classes2.dex"])
asc_analyze_dex(dex_paths=["/samples/classes.dex"], operation="list_classes", prefix="com.example")
asc_analyze_dex(dex_paths=["/samples/classes.dex"], operation="get_class_source", class_name="com.example.Main")
asc_analyze_dex(dex_paths=["/samples/classes.dex"], operation="find_refs", kind="string", value="Authorization")

operation defaults to info. Successful responses have status="ok" and a sources array
mapping internal dex_entry names to original paths, SHA-256 hashes, sizes and class counts.
Class/source results retain dex_entry; reference results retain ASC's best-effort dex field.
Input order determines entry names. Keep both the order and file bytes stable between pages and
compare the returned hashes. Each call imports and analyzes afresh; APK cross-request caching
does not apply to this tool.

Standard little-endian DEX headers (035/037/038/039/040), fixed ID-table bounds, file size, SHA-1
signature and Adler-32 checksum are checked before analysis. Checksum validation does not prove
method bodies or runtime coverage are complete. The tool preserves input bytes, creates private
temporary analysis containers, and invokes ASC's public module entry point in the supervised worker.
Containers are not installable APKs and are removed after success, failure, timeout or cancellation.
Temporary disk usage can approach twice the combined input size, plus ZIP overhead.

Duplicate class definitions are rejected with status="error", code="duplicate_class" rather
than selecting one silently (up to 20 conflicts are returned). get_manifest returns
status="not_applicable", code="no_manifest". Invalid input/query and engine failures return
diagnostic codes; a successful empty reference search is status="ok", total=0.
Path policy, worker startup, timeout, memory and stream-limit failures remain MCP tool errors.
Clients must inspect both MCP errors and the structured status.

This is post-export static analysis, not automatic unpacking or DEX repair. It does not recover
missing code, decrypt runtime-only method bodies, or reconstruct the original manifest/resources.
Every result is limited to supplied files (coverage="supplied_files_only"), with runtime
completeness marked unknown. Untrusted dumps still require an isolated analysis environment.

Immutable sessions

Open with asc_open_dex_session(dex_paths=[...]), retain its session_id, then call
asc_query_dex_session(session_id="...", operation="list_classes"). Query parameters match
asc_analyze_dex. Close with asc_close_dex_session(session_id="...").

The input_id binds ordered DEX SHA-256 hashes, schema and ASC version. The UUID session ID
identifies one private snapshot, not a global current sample. Changing/deleting original files
does not mutate that snapshot. Cache keys include complete query options and backend identity,
not merely the input ID; distinct queries cannot share a cached page.
Reuse skips reimport, integrity checks and the duplicate-class scan; it does not retain a
resident decompiler or promise warm engine latency. Method results identify the optional backend
version separately. Sessions are local to this server process, not shared across hosts/restarts.

Idle sessions expire (swept at most every 30 seconds), and least-recently-used idle sessions can
be evicted at capacity. Active queries pin storage. Closing an active session prevents new queries
and returns cleanup_pending=true; the last active query releases the files. Normal MCP lifespan
shutdown cleans sessions; abrupt host termination may leave OS temporary files. A lost handle
returns session_not_found, never silently reloads changed evidence. Cancellation or failed opens
release their reservations. Concurrent preparation has reserved disk/count capacity before starting.

Exact methods and Smali

Optional: install the official JADX 1.5.5 distribution
and a JDK 17 or newer. Set DROIDASC_MCP_JADX_HOME to its extracted directory (containing lib/).
Set DROIDASC_MCP_JAVA to the JDK's java executable, or put it on PATH. A JRE alone cannot run
the source bridge. The Python package does not bundle/download JADX or require Java for ASC tools.
Explicit source_format=smali uses ASC 0.1.2.post3 directly and needs no JVM or JADX configuration.
Set debug_info=true with that format to include upstream debug directives.

asc_query_dex_session(session_id="...", operation="list_methods", class_name="com.example.Main")
asc_query_dex_session(session_id="...", operation="get_method_source", method_descriptor="Lcom/example/Main;->check(I)Z")
asc_analyze_dex(dex_paths=["/samples/classes.dex"], operation="get_method_source", method_descriptor="Lcom/example/Main;->check(I)Z", source_format="smali")

list_methods reads raw DEX definitions through dexlib2, including constructors, synthetic/bridge
methods, native/abstract declarations, complete parameter types and return types. It sorts full
descriptors before pagination. No method name, partial prototype, or overload index selects a body.
get_method_source requires the exact full descriptor; an absent overload returns method_not_found.
Class mismatches are rejected rather than choosing another owner.

source_format=auto uses JADX's exact short-ID lookup and public method-code API. If Java is absent
(for example an elided default constructor) or reports a decompilation error, it disassembles the
same dexlib2 method object, not a name-matched slice of class Smali. Results carry format,
fell_back, fallback_reason, backend version, original hashes and dex_entry. java returns
java_unavailable instead of falling back; smali always returns exact-method disassembly.
Java error/warning counts are engine diagnostics, not proof of semantic correctness. Reference
tools named find_refs still use ASC's best-effort name-level text.

find_field_refs requires field_descriptor, for example Lcom/example/Config;->enabled:Z.
Set field_access to all (default), read or write. Rows contain the exact caller and field
descriptors, access, storage (static/instance), opcode, DEX provenance and code-unit offset.
Filtering occurs before pagination, so totals and page cursors refer to the selected access kind.
Same-name fields with different types are distinct; an unused or absent field returns zero matches,
while references to external fields retain target_dex_entry=null. Definition lookup is literal:
inherited field resolution is not performed. Reflection, JNI, method-handle targets and encoded
initial values are not direct instruction accesses and are not claimed as reads or writes.
This operation uses the optional JADX/dexlib2 backend and works on one-shot inputs and sessions.

asc_query_dex_session(
    session_id="...",
    operation="find_field_refs",
    field_descriptor="Lcom/example/Config;->enabled:Z",
    field_access="write",
)

find_method_refs and get_method_calls are separate descriptor-exact operations on DEX inputs
and sessions, using the optional pinned backend. Each result row carries full caller/callee
descriptors, caller dex_entry, opcode, and instruction_offset in 16-bit code units from
the method's first instruction, not a file offset. target_dex_entry and target_resolution
describe whether the declared operand has a definition in the supplied files. Incoming queries
may target external methods; outgoing queries require a definition. Rows sort by DEX entry,
class, caller descriptor and instruction position before pagination.

asc_query_dex_session(session_id="...", operation="find_method_refs", method_descriptor="Lcom/example/Main;->check(I)Z")
asc_query_dex_session(session_id="...", operation="get_method_calls", method_descriptor="Lcom/example/Main;->check(I)Z")

These scan declared method operands, not resolved runtime targets. Counts report scanned methods
and instructions, declarations without code, undefined operands and dynamic sites. Polymorphic
calls preserve their call-site prototype; dynamic sites include at most 20 diagnostic examples.
instruction_scan_complete means the selected scope was decoded, not that a runtime call graph
is complete. Virtual dispatch, reflection, JNI and runtime-loaded code remain unresolved. Unknown
instructions or decoding failures return an error rather than partial results marked complete.

Missing configuration returns backend_unavailable; other JADX versions are rejected. Source and
unindexed optional-backend queries start a JVM (512 MiB maximum heap) inside the worker tree, sharing its
timeout, aggregate memory, output and cancellation limits. This adds startup cost, not a speedup.
Method pages expose total, offset, limit, next_offset, truncated and has_more; oversized
responses fail explicitly. The API currently takes DEX inputs/sessions, not an APK path.

Indexed investigation

operation="get_call_graph" explores an exact method_descriptor with
direction="incoming"|"outgoing"|"both" (default both), depth=1..5 (default 2),
max_nodes=1..500 (default 200) and max_edges=1..1000 (default 500).
It builds/reuses the full static index: first use on a large application can take minutes;
this is not a cold-query speedup. Use sessions to retain that work.
Nodes retain minimum hop distance and definition DEX; edges retain individual call sites
including repeated calls, original opcode, offset and target provenance. Cycles and recursive
calls terminate without duplicate call sites. External method operands can be roots too.
Graph exploration has a 128 KiB content budget, separate from ordinary pagination.
truncation_reasons distinguishes depth, node, edge and byte boundaries;
traversal_complete_within_depth describes only the requested static neighborhood.
Expand boundary descriptors as new roots or raise budgets to investigate further;
node expansion_status identifies expanded, pending and depth/budget-boundary methods.
offset must be zero and ordinary limit does not control graphs. Diagnostics count dynamic
sites only in returned nodes (at most 20 examples), including unresolved invoke-custom targets;
these do not become fabricated call edges. Runtime dispatch remains unresolved.

build_xref_index scans all supplied DEX files once and atomically publishes a bounded SQLite
index. Subsequent exact method/field references need no JVM. find_type_refs builds/reuses it
and separates type_relation=instruction|declaration|annotation|all, including nested annotation
type values. Types and arrays match exactly, not by assignability or array component expansion.
search_members discovers full method/field declarations without knowing their class first:

asc_query_dex_session(session_id="...", operation="search_members", kind="method", value="->check(")
asc_query_dex_session(
    session_id="...",
    operation="find_type_refs",
    type_descriptor="Lcom/example/Main;",
    type_relation="annotation",
)

Search uses a case-sensitive literal substring of the full descriptor, not a regex. An optional
class_name restricts its exact owner. Feed returned descriptors unchanged into exact references
or Smali queries. Searching declarations is not searching DEX string pools or runtime usages.
Member discovery reads declarations only and does not build the full xref index. Use
operation="search_strings", value="https://" for case-sensitive literal DEX string-pool
search with dex_entry, string_index and value provenance; pool presence is not a use site.
Both discovery operations return instruction_scan_complete=false.

Discovery and non-indexed exact reference results reuse identical query pages within a session.
The disk LRU cache holds at most 32 pages / 4 MiB, with a 256 KiB per-page cap, and shares the
index reservation rather than adding unaccounted storage. Full index construction clears it.
Cache identity includes immutable input and backend hashes; different pages may rescan.
query_cache.hit reports reuse. This keeps worker isolation rather than retaining parsed APKs
in a long-lived process.

A separate resident cache holds up to 32 serialized pages / 4 MiB per session (256 KiB per
page). It avoids worker startup for repeated exact pages, and invalidates on implementation,
engine or index-file identity changes. It never retains parsed DEX or worker processes.
All 18 tools expose typed MCP output schemas, including nested result rows and diagnostics.

Index construction costs time/disk upfront. Default per-session index quota is 256 MiB, reserved
from the session storage budget; large applications may need an explicitly larger index quota,
session budget and timeout. Cancellation, malformed input or quota failures do not publish a
partial index. Identity includes input hashes, schema and backend files. Close/expiry/server
shutdown deletes the working copy. By default, one-shot indexes are temporary too.

To retain reusable indexes across sessions and server restarts, explicitly set
DROIDASC_MCP_XREF_CACHE_DIR to a dedicated private directory (0700 on POSIX; private ACLs on
Windows). This opt-in store retains derived identifiers and relationships, not the original APK.
It is keyed by ordered input hashes, schema, bridge/parser source and backend JAR hashes.
Reopening still validates the supplied DEX files; a matching complete index is copied into the
new session and checksum-verified before use. Exact references and member discovery restore an
available index without rebuilding it. index.durable_cache reports stored, restored,
not_accessed, disabled or too_large; session working copies still have session_lifetime.

The durable store defaults to 1 GiB (DROIDASC_MCP_MAX_XREF_CACHE_BYTES), 64 entries and seven
idle days (DROIDASC_MCP_XREF_CACHE_TTL_SECONDS). These bytes are separate from the session
reservation. Reads/writes serialize across processes; TTL/LRU cleanup runs on cache access.
Checksums, incomplete-write cleanup and atomic publication protect against interrupted writes;
eviction does not invalidate active session copies. Large indexes need sufficient limits in both
stores. Cache misses keep the ordinary streamed discovery/reference path; they do not force a
full build. Stop servers before manually removing the dedicated cache directory.

The server also exposes initialization instructions, droidasc://analysis-guide, and
triage_apk / trace_exact_method prompts. Artifact contents remain untrusted query data.
See the source-backed competitor comparison for remaining gaps.

Optional Rust ASC

Run uv run python scripts/setup_rust.py with Rust installed, then set
DROIDASC_MCP_RUST_ASC to the resulting artifacts/rust_ASC/target/release/rust_ASC
(rust_ASC.exe on Windows). The setup script pins source and radguard revisions.
Select backend="rust_asc" on the manifest, class-list, class-source or APK-reference tool.
Python ASC remains the default; no silent fallback occurs. Rust does not provide our exact DEX
index/Smali queries or extends/impl path. Its upstream reference scanner can discard per-DEX
failures, so results explicitly report unverified coverage: zero hits are not absence proof.
Both engines share scope/concurrency/process-tree budgets. See backend details.

Configuration

Design

• Uses the public droidasc CLI module entry point; it does not import ASC private internals.
• Never invokes a shell and does not expose a generic command tool.
• Drains stdout and stderr concurrently with hard capture caps; no bulk output files are created.
• Caps stderr at 64 KiB and budgets page content conservatively within 256 KiB.
• Runs ZIP inspection and hashing in a supervised worker under the same concurrency budget.
• On POSIX, kills the operation's process group on completion or failure, even if its leader exited.
• On Windows, assigns the worker to a kill-on-close Job Object before starting ASC. Cleanup
  includes descendants even after the worker exits; Job setup failure prevents analysis from starting.
• Propagates MCP request cancellation through queue/snapshot waits and active sync tools; cleanup
  completes before the cancelled server task exits, and the session can continue serving requests.
• Applies the configured worker memory ceiling before importing ASC. Windows limits aggregate
  committed memory for the Job tree. POSIX applies an inherited per-process kernel RLIMIT_AS
  and samples aggregate tree RSS every 50 ms, terminating the tree if it crosses the same budget.
• Resolves symlinks before checking the allowed-root policy.

ASC and its dependencies still parse untrusted binary input. Use a container or disposable VM for
hostile APKs. This adapter is a process boundary, not a malware sandbox.

Native Windows CI checks live-parent and orphan cleanup, including grandchildren, successful
completion, output overflow, reader termination, and repeated-operation handle counts.
Capture buffers, snapshots being built, and active pages can coexist with the cache; this budget
is not a hard MCP-host total-RSS cap. The POSIX aggregate tree check is a sampled watchdog, while
the inherited per-process address-space ceiling is kernel-enforced. Dense outputs may hit the
decoded-memory budget before the wire cap.

Development

See local acceptance checks for real-process tests, optional APK transport
checks, measured outcomes, and the remaining verification limits.

uv sync --locked --extra dev
uv run ruff check .
uv run pytest --cov --cov-report=term-missing
uv run python scripts/validate_corpus.py /path/to/one.apk /path/to/another.apk
uv run python scripts/stability_check.py /path/to/one.apk --duration 300 --workers 2
uv build
# Python 3.12+; use fresh dist outputs matching the current version:
uv run python scripts/verify_dist.py dist/droidasc_mcp-0.4.0.tar.gz dist/droidasc_mcp-0.4.0-py3-none-any.whl

License

Apache License 2.0. Droid ASC is a separate upstream project and retains its own copyright and
license.