# asc-mcp

MCP server for **[ASC](https://github.com/MG1937/ASC)** — the "APK-as-database" Android analysis engine presented as *Droid ASC: R8 Compiler Optimization as a DeCompiler Primitive* at **Black Hat Europe 2026 Arsenal** (credit: WeiMin Cheng / MG1937 & Zhihan Lin).

ASC treats an APK as a read-only database instead of fully decompiling it: zero preprocessing, zero disk cache, sub-second to ~2s global cross-reference searches even on 300MB+ APKs (see the upstream benchmark in the ASC repo). **asc-mcp exposes that engine as MCP tools** so AI clients (kimi-code / ksec, Claude, any MCP host) can drive it directly, side by side with [jadx-mcp](https://github.com/zinja-coder/jadx-ai-mcp).

```
MCP client ──MCP──▶ asc-mcp ──imports──▶ ASC engine (external clone, ASC_PATH)
```

- **Use asc-mcp for**: locating — cross-references, string recon, class/member peek, manifest/components, fleet-wide batch queries.
- **Use jadx-mcp for**: deep reading, rename/annotation, resources, smali, debugger.

## Tools

| Tool | What it does |
|---|---|
| `asc_find_refs` | Global xref search across all DEX entries: `kind` = `string` / `type` / `method` / `field`, fuzzy or exact-class matching, structured sorted hits, progress events |
| `asc_batch_find_refs` | Same query across many APKs in parallel (per-APK fault isolation) |
| `asc_dump_strings` | Dump DEX string tables with regex filter (URLs, api keys, secrets recon) |
| `asc_list_classes` | Enumerate class descriptors straight from class_defs (no decompile) |
| `asc_get_class_members` | Methods/fields with signatures and access flags from class_data |
| `asc_get_class_source` | Rebuild a minimal DEX in memory and decompile one class (subprocess-isolated) |
| `asc_get_manifest` | Decode binary AndroidManifest.xml to XML |
| `asc_get_components` | Activities/services/receivers/providers with exported resolution, deeplinks, permissions, main activity |
| `asc_apk_info` | File size, package/version/SDK, DEX entry list |
| `asc_ping` | Health check |

All tools are stateless and re-entrant: every call takes an explicit `apk_path`, spawns isolated worker processes, and shares no memory, files, or ports — multiple MCP clients (harnesses) can use one or several server instances concurrently without conflicts.

## Install

```bash
# 1. the engine (external dependency, NOT vendored — see Legal notes)
git clone https://github.com/MG1937/ASC.git ../ASC   # or set ASC_PATH later

# 2. this server
git clone https://github.com/NitrogenT7/asc-mcp.git asc-mcp && cd asc-mcp
python -m venv .venv
# Windows: .venv\Scripts\python -m pip install -r requirements.txt
.venv/bin/python -m pip install -r requirements.txt
```

`asc_path.py` resolves the engine in this order: `$ASC_PATH` → `./ASC/` → `../ASC/`.

### Register with an MCP host (example: kimi-code / ksec `~/.kimi-code/mcp.json`)

```json
"asc": {
  "command": "C:/path/to/asc-mcp/.venv/Scripts/python.exe",
  "args": ["C:/path/to/asc-mcp/asc_mcp_server.py"],
  "startupTimeoutMs": 60000,
  "toolTimeoutMs": 180000
}
```

Stdio is the default transport; `--http --host 127.0.0.1 --port 9001` serves streamable-http instead.

## Test

Fully fixture-driven; no paths are hardcoded:

```bash
# Windows: set ASC_TEST_APK=C:\path\to\app.apk
export ASC_TEST_APK=/path/to/app.apk            # any non-trivial APK
export ASC_TEST_APK_2=/path/to/second.apk       # optional
export ASC_TEST_APK_UNSIGNED=/path/to/edge.apk  # optional

.venv/bin/python tests/test_asc_mcp.py           # in-process
.venv/bin/python tests/test_asc_mcp.py --stdio   # stdio + progress + multi-harness
```

The suite covers all 10 tools, structured-output shape, error paths, determinism, a 6-way concurrent mix, and two concurrent stdio server instances (multi-harness).

## Benchmark

```bash
.venv/bin/python tests/benchmark_asc.py /path/one.apk /path/two.apk
# optional jadx comparison when a jadx-ai-mcp plugin is reachable:
set JADX_MCP_URL=http://127.0.0.1:8650
```

## Compatibility notes

- asc-mcp imports ASC internals (including private helpers such as `_parse_cd_dex_entries`). Upstream has no stable API or releases yet; pin your ASC clone by commit and re-run the test suite after pulling.
- The decompiler backend (Androguard DAD, patched by ASC) poisons `sys.modules` with dummy modules, so `asc_get_class_source` deliberately runs in a subprocess. Don't import it in-process.

## Legal notes

- **asc-mcp's own code is MIT** (see `LICENSE`).
- **ASC itself currently ships without a LICENSE file.** Until upstream adds one, this repository does not vendor or redistribute ASC; users clone it themselves. All ASC credit goes to its author — this is only an MCP wrapper.
- Test APKs are never committed (`.gitignore`); fixtures are supplied locally via environment variables.