Android-RE/docs/mcp-tool-reference.md

MCP Tool Reference

Auto-generated reference for every tool exposed by every Android-RE MCP server. Source of truth is the mcp_servers/<server>/src/.../server.py FastMCP registration. If this page drifts from the code, the code wins.

Output convention

Every file-producing MCP tool accepts an output_path (single file) or output_dir (directory) parameter. When omitted, the path is derived from android_re_core.paths.output_dir_for(apk_path):

Output/<apk-basename>-<short-sha>/<subdir>/<file>

Override the base with the ANDROID_RE_OUTPUT_DIR env var (read once at import time of android_re_core.paths). The default base is <repo-root>/Output/; the directory is git-ignored. The full convention is documented in output-convention.md.

Tool	Default subdir	Default filename
finalize_triage	Output/<apk>-<sha>/<triage_id>/	triage-<id>.{md,json,sarif}
get_masvs_coverage	Output/<apk>-<sha>/masvs/	coverage.json
build_sarif_report	Output/<apk>-<sha>/masvs/	report.sarif
scan_secrets	Output/<apk>-<sha>/secrets/	secrets-findings.json
scan_with_quark	Output/<apk>-<sha>/secrets/quark/	(quark's native layout)
run_androwarn	Output/<apk>-<sha>/secrets/	androwarn.json
build_native_report	Output/<apk>-<sha>/native/	native-report.json
build_session_report	Output/<apk>-<sha>/dynamic/	session-report.json
rebuild_apk	Output/<apk>-<sha>/repackage/	rebuilt.apk
create_gradle_project	(required)	n/a
take_screenshot	Output/<apk>-<sha>/dynamic/	screenshot-<ts>.png
screenrecord	Output/<apk>-<sha>/dynamic/	screenrecord-<ts>.mp4
dump_heap	(required)	n/a
setup_mitm	Output/<apk>-<sha>/network/	n/a

Servers

Server	Module
android-re-static	mcp_servers.static.android_re_mcp_static
android-re-native	mcp_servers.native.android_re_mcp_native
android-re-dynamic	mcp_servers.dynamic.android_re_mcp_dynamic
android-re-triage	mcp_servers.triage.android_re_mcp_triage
mcp_bridge	mcp_bridge (TypeScript)

android-re-static

26 tools (Phase 1 + 2 + 3 + Decompilation pipeline).

Project lifecycle:

• open_project(apk_path, project_id?, max_size?) -> {project_id, sha256, size, ...}
• close_project(project_id) -> {ok}
• list_projects() -> [ProjectSummary]

Manifest:

• read_manifest(project_id, formatted?) -> manifest XML or structured
• list_components(project_id, component_type?) -> [Component]
• get_permissions(project_id, classification?) -> [Permission]

DEX:

• find_classes(project_id, query, limit?, exact?) -> [Class]
• find_methods(project_id, class_name?, name_substring?, native_only?, limit?) -> [Method]

Decompilation (jadx):

• decompile_class(project_id, class_name, deobfuscate=False, threads=None, output_format="java") -> {source, found, workdir, deobfuscated, output_format}
• decompile_method(project_id, class_name, method_name, descriptor, deobfuscate=False, output_format="java") -> {source, found, start_line, end_line, full_class_source, workdir, reason} — slices the decompiled class by method signature; start_line / end_line are 1-indexed.
• decompile_apk(project_id, force=False, deobfuscate=False, threads=None, output_format="java", limit=500, offset=0) -> {class_count, files, total_files, truncated, jadx_duration_s} — enumerates the decompiled tree.
• read_source(project_id, path, deobfuscate=False, output_format="java") -> {content, found, line_count, byte_size, reason} — reads a file by path; refuses .. and files > 10 MB.

Smali / repackage:

• get_smali(project_id, class_name) -> {smali, found, workdir}
• decode_apk(project_id, force=False) -> {workdir, class_count, smali_dirs, manifest_path}
• rebuild_apk(project_id, output_path?, confirm=False) -> {output_path, size} — requires confirm=true.
• patch_manifest(project_id, patch, confirm=False) -> {applied, changes, ...} — dry-run by default.

Signing:

• verify_signature(project_id) -> {signed, versions, signers, ...}
• get_certificate_info(project_id, signer_index?) -> {subject, issuer, ..., fingerprint_sha256}

Native (delegated from android-re-native):

• list_native_libs(project_id) -> [lib_path]
• analyze_elf(project_id, lib_name) -> {format, architecture, security, sections, imports, exports}
• disassemble_native(project_id, lib_name, symbol?, offset?, length?, max_instructions?) -> [instruction]

Secrets / reports:

• scan_secrets(project_id, rules="default", limit=500) -> [SecretFinding]
• scan_with_quark(project_id, timeout_s=300) -> {matched_rules}
• run_androwarn(project_id, timeout_s=300) -> [Warning]
• build_sarif_report(project_id) -> SARIF log
• get_masvs_coverage(project_id) -> {by_group, controls, findings}

Each decompile tool caches its workdir under /tmp/android-re/<project_id>-jadx-{deobf,plain}-{java,kotlin}/. deobfuscate and output_format are part of the cache key.

android-re-native

(Phase 2) 19 tools — see mcp_servers/native/src/.../server.py.

android-re-dynamic

(Phase 3) 30+ tools — see mcp_servers/dynamic/src/.../server.py.

install_apk (SDK-34+ aware)

install_apk(serial, apk_path, replace=True, allow_downgrade=False, confirm=false, output_path=None) -> InstallResult

The dynamic server's install_apk tool delegates to android_re_core.device.adb_install.install_apk, which runs a 3-strategy install ladder:

1. adb_install — one-shot adb -s <serial> install [-r] [-d] <apk>. Pre-34 fast path; tried first on every API level.
2. push_then_pm_install — push the APK to /data/local/tmp/ on the device, then pm install [-r] [-d] <tmp_path>. Primary escalation on API 34+.
3. staged_install — pm install-create / -write / -commit. Last-resort fallback on API 34+ when (2) also fails.

Returns a structured InstallResult:

{
  "status": "success" | "failure" | "partial",
  "api_level": 34,
  "strategy": "adb_install" | "push_then_pm_install" | "staged_install",
  "output": "Success\n",
  "package": "com.example",
  "elapsed_s": 1.23
}

confirm=false (the default) does not call adb. It writes a structured dry-run summary to Output/<apk>-<short-sha>/dynamic/install-attempt.dry-run.json listing the strategy ladder, then returns the confirm_required error envelope. Override the path with output_path=....

Failure modes the ladder handles explicitly:

• INSTALL_FAILED_OWNER_BLOCKED, INSTALL_FAILED_USER_RESTRICTED, INSTALL_FAILED_VERSION_DOWNGRADE → strategy 2.
• INSTALL_FAILED_INSUFFICIENT_STORAGE, INSTALL_FAILED_NO_INSTALL, INSTALL_FAILED_INTERNAL_ERROR → strategy 3.
• An unknown 4th mode surfaces in output for triage; the implementer can extend the ladder with a 5-line PR.

The ANDROID_RE_FORCE_STAGED=1 env var forces strategy 1 only (for testing the override path; not the staged path itself).

TS bridge parity gap — the TypeScript mcp_bridge adb_install tool still uses adbkit's install() and does not support the SDK-34+ fix. Callers using the TS bridge on an API 34+ device should use the Python dynamic server's install_apk instead.

android-re-triage

(Phase 4) 12 tools — orchestrator; composes the other three.

mcp_bridge (TypeScript)

(Phase 3) 18 tools — ADB / screencap / logcat / frida-ps.

MCP resources

Resource URI	Provided by
apk://<project_id>/manifest	android-re-static
apk://<project_id>/smali/<fqcn>	android-re-static
apk://<project_id>/source/<fqcn>	android-re-static
native://<project_id>/lib/<lib_name>/...	android-re-native
device://<serial>/<topic>	mcp_bridge

Peer MCP servers

Android-RE's .mcp.json can register peer MCP servers alongside the 5 in-workspace ones. Peers are external projects that live outside this repo; they're opt-in and have no destructive tools.

re-library (MIT)

Wrapper around the RE-Library corpus — 8 categories (android, ios, native, anti-analysis, drm, packers, tools, web-hybrid) of generic RE knowledge. Used by 5 Android-RE skills as a "Background reading (peer MCP)" step before writing Frida hooks or MASVS reports.

5 tools, all read-only:

• mcp__re-library__list_categories() — enumerate the 8 categories with entry counts.
• mcp__re-library__list_entries(category) — lightweight summary of one category (titles + summaries + difficulty).
• mcp__re-library__search_re(query, category?, platform?, max_results?) — free-text search with snippet + score. Returns up to max_results hits (default 5, max 50).
• mcp__re-library__get_entry(slug) — full body of one entry, indexed by <category>/<NN>-<slug>.
• mcp__re-library__get_anti_analysis_techniques(platform?) — convenience aggregator over the anti-analysis category.

Install once with just install-re-library (the .mcp.json entry uses uv tool run --from re-library-mcp … as a fallback if the package is not pre-warmed).