Content
# SOMCP
SOMCP is a local SO reverse MCP server running on Android phones. It exposes MCP tools through Streamable HTTP, allowing clients to complete ELF structure analysis, Rizin disassembly/analysis, LIEF ELF repair/rewrite, patch sessions, build export, Cloudflare Tunnel exposure, and optional APK MCP bridging on the phone.
Current version: `1.0.3`
Package name: `com.soreverse.mcp`
Minimum system: Android 8.0 / API 26
License: `GPL-3.0-only`. The SOMCP main project is released under the [GNU General Public License v3.0](LICENSE). Third-party dependencies, submodules, generated resources, and patches in the repository follow their respective upstream licenses, and the GPL-3.0 statement does not replace their original license terms.
## APK Location
Release build output directory:
```text
app/build/outputs/apk/release/
```
Prioritized installation for ordinary arm64 phones:
```text
app/build/outputs/apk/release/app-arm64-v8a-release.apk
```
Installation when ABI is uncertain:
```text
app/build/outputs/apk/release/app-universal-release.apk
```
## GitHub Updates
The app only checks for updates through official Releases of `bilieebiliee1-design/SOMCP` on GitHub. Regular commits, branches, build products, and unpublished tags are not considered updates, and draft and prerelease versions are not included in the automatic update channel.
It is recommended to use the `v<versionName>` format for Release tags and upload APKs named by ABI:
```text
SOMCP-1.0.3-arm64-v8a.apk
SOMCP-1.0.3-armeabi-v7a.apk
SOMCP-1.0.3-x86.apk
SOMCP-1.0.3-x86_64.apk
SOMCP-1.0.3-universal.apk
```
You can also upload `<apk>.sha256` or a unified `SHA256SUMS` file. The detector prioritizes the current device ABI, and if a verification asset exists, it will forcibly verify the SHA-256 before installation.
The current release output size is approximately:
| APK | Size |
| --- | ---: |
| `app-arm64-v8a-release.apk` | 28.76 MB |
| `app-armeabi-v7a-release.apk` | 19.90 MB |
| `app-x86-release.apk` | 20.73 MB |
| `app-x86_64-release.apk` | 20.77 MB |
| `app-universal-release.apk` | 52.19 MB |
## Core Capabilities
- Android native foreground service, independent of Python runtime environment.
- Compose + Material 3 interface.
- Ktor CIO MCP HTTP service, default port `8000`.
- MCP token access control, can bind `127.0.0.1` or `0.0.0.0`.
- Authorize working directory through system file chooser.
- Support independent `.so` and APK internal `lib/<abi>/*.so` workflow.
- Rizin native backend: function analysis, CFG, xref, crypto scan, ESIL, byte search, disassembly, assembly.
- LIEF native backend: ELF parsing, section content read/write, section header rebuild, symbol modification, address patch.
- Editing session: snapshot, rollback, undo, redo, check, audit, persist.
- Build export: automatic renaming/covering, patch report, multi-output variants, mirroring to working directory.
- Cloudflare Tunnel: quick/named tunnel, keepalive, status statistics.
- Optional Unidbg: `emulate_call`, `emulate_dump`.
- Simplified tool list: only exposes core + meta tools by default, and full capabilities are discovered through `meta_info(action=describe)`.
## MCP Tool System
There are currently 29 tools in this directory, and the default lean mode advertises core tools and meta tools, reducing the LLM initialization context cost.
Recommended workflow:
```text
so_open(action=list)
so_open(path=...)
analyze_elf(view=stats)
analyze_functions
read_disasm(locator=...)
session_open
edit_asm(dryRun=true)
session_history(action=check)
build_so
```
Search syntax:
```text
search_bytes(pattern="5F2403D5") # Rizin native byte pattern, compact hex
search_bytes(pattern="5F24..D5") # Rizin nibble wildcard, . represents any half-byte
search_bytes(pattern="5F2403D5:FFFF00FF") # Rizin bytes:mask
search_bytes(pattern="5F 24 ?? D5") # MCP compatible writing method, will be normalized to 5F24..D5 and handed over to Rizin
search_strings(prefix="JNI.*Load", regex=true)
```
AI call precautions:
- `so_open`, `search_bytes`, `analyze_*`, `read_disasm`, and other heavy-duty tools are protected by a global concurrency gate; automated clients should call serially, and if they encounter `SERVER_BUSY`, they should retry the same request after `retryAfterMillis`.
- `search_bytes` prioritizes Rizin search; the returned hit will contain `addr`, `hexAddr`, `fileOffset`, `section`, `sectionOffset`, and can directly connect to `read_hexdump` or patch tools.
- `search_strings(regex=true)` uses Kotlin regular expressions; illegal regular expressions will return structured errors and will not be treated as empty results.
- When directly calling the phone MCP from a computer, you can first execute `adb forward tcp:8000 tcp:8000` and then use `http://127.0.0.1:8000/mcp`.
Tool discovery:
```text
meta_info(action=help)
meta_info(action=tools)
meta_info(action=describe, tools=["edit_asm", "build_so"])
meta_info(action=workflows)
meta_info(action=suggest, workspaceId="...")
meta_info(action=errors)
meta_info(action=report, workspaceId="...", writeToFile=true)
meta_info(action=capabilities)
meta_info(action=health)
```
`meta_info(action=report)` generates a complete analysis report, including ELF statistics, sections, dynamic symbols, strings, Rizin functions, crypto scans, and suggestions, and can be written to the app's private reports directory.
The underlying API exposes through capability registry + 4 aggregation gateways, avoiding MCP tool quantity explosion. `meta_info(action=capabilities)` is the source of real capability surface, which will clearly list supported / partial / missing to avoid reporting unimplemented underlying APIs as covered:
```text
rizin_api(action=capabilities|command|analyze|functions|cfg|xrefs|search_bytes|crypto|esil|diff|asm|disasm)
lief_api(action=capabilities|parse|list|patch_address|add_export|remove_symbol|build|fix_sections|report)
unidbg_api(action=capabilities|status|call|dump)
xanso_api(action=capabilities|status|fix_sections)
```
`rizin_api(action=command)` provides a controlled Rizin raw command channel for covering a large number of Rizin command-line underlying capabilities; for safety, write, file, shell, and other dangerous commands will be blocked.
Batch pipeline supports transaction mode:
```text
meta_info(action=batch, transactional=true, steps=[...])
```
Transaction mode will automatically create a snapshot for editing sessions involving `workspaceId + editSessionId` before execution; if subsequent steps fail, it will automatically rollback to the transaction's previous snapshot.
Paging continuation:
```text
meta_info(action=continue, cursor="page:...")
```
System status:
```text
system_control(action=status)
```
`health/status` returns runtime information, including APK version, device ABI, nativeLibraryDir, `librz_native.so` size, mtime, and SHA-256 short fingerprint, used to confirm whether the latest APK is actually running on the device.
## Settings
- MCP access control: token, binding address, access URL.
- Return quantity: default limit, string limit, disassembly window, hexdump, request body upper limit.
- Export: conflict strategy, patch report, mirroring to working directory, patch byte upper limit, build product list upper limit.
- Editing verification and audit: automatic snapshot, audit log, audit persistence, maximum snapshot number, maximum audit number, diff range number.
- Tool exposure: lean tools, adaptive lean, disabled tool list, tool result character upper limit, tool call frequency limit.
- Performance protection: heavy-duty tool concurrency upper limit, request timeout, tool statistics persistence.
- Native execution: Unidbg simulation execution switch.
- Cloudflare Tunnel: quick/named, target port, protocol, IP version, log level, keepalive, reconnection retreat.
- APK MCP bridging: APK MCP URL, automatic detection, tool merging, forwarding timeout.
## Building from Scratch
Preparation environment:
- Windows 10/11
- JDK 17
- Android SDK 36
- Android NDK `29.0.14206865`
- CMake `3.22.1`
- Gradle `9.6.1`
Build Rizin / LIEF native dependencies:
```powershell
.\build-rizin-all.ps1
.\build-lief-all.ps1
```
Build release:
```powershell
D:\Gradle\gradle-9.6.1\bin\gradle.bat :app:assembleRelease
```
Verify whether the native library still has non-system unresolved symbols that will cause `dlopen` failure:
```powershell
.\verify-native-libs.ps1
```
If the output is all `OK`, it means that Rizin/ZSTD/LIEF and other non-system symbols have been resolved in the APK's own library.
## Installation and Verification
It is recommended to uninstall the old package before installation to avoid Android continuing to load the old native lib:
```powershell
adb uninstall com.soreverse.mcp
adb install -r app\build\outputs\apk\release\app-arm64-v8a-release.apk
```
Call after starting MCP:
```text
meta_info(action=health)
```
Expectation:
```json
{
"nativeBackends": {
"rizin": { "available": true, "loadStatus": "loaded" },
"lief": { "available": true, "loadStatus": "loaded" }
}
}
```
If you still report `dlopen failed: cannot locate symbol ...`, please check whether `runtime.librzNative.sha256_16` is equal to the `librz_native.so` fingerprint in your local latest APK.
## Release Optimization
Release build enables:
- R8 code compression and obfuscation.
- Android resource compression.
- ABI sub-packaging + universal package.
- v1/v2/v3/v4 APK signature.
- Strict native linking: prohibit Rizin/LIEF/zstd unresolved symbols mixed into `.so`.
- JNI keep rules: retain `RizinNativeEngine` / `LiefEngine` class name and native method name.
## Precautions
- This tool is only suitable for analyzing files that you have the right to handle. Reverse engineering, modification, and distribution of third-party binaries may be restricted by laws, agreements, or platform rules.
- Assembly patching is more suitable for equal-length coverage or explicit boundary patching, and will not automatically move subsequent code.
- Mobile phones cannot prove their own accessibility from the public network; public network reachability requires remote clients, Cloudflare Tunnel, or other external detection cooperation.
- APK MCP bridging relies on the MT manager side panel APK MCP function online and requires the MT manager to keep running in the background.
Connection Info
You Might Also Like
No recommendations available