rea-python(rea-mcp)

Reverse engineer anything from your terminal or agent — one CLI and one MCP server.

Attribution and disclaimer

This is an unofficial Python port of morluto/rea. The original project is a TypeScript implementation. This port exists because our Python-based AI agent products (aacode, fastclaw) need a native Python integration. Not affiliated with or endorsed by the original authors. Licensed under MIT.

See DISCLAIMER.md for responsible-use guidance and THIRD_PARTY_NOTICES.md for dependency and tool notices.

Lawful use

The project's position on illegal or unauthorized use covers all REA versions, distribution channels, and platforms; each copy retains its applicable licenses.

REA is for lawful research, education, interoperability, software preservation, and analysis of software you own or are authorized to examine.

Commercial tools

You must legally obtain and be authorized to use commercial tools, including IDA Pro / Hex-Rays decompilers, Hopper, and JEB, under their applicable licenses. REA grants no tool license, key, or activation entitlement. Trials and demos remain subject to vendor terms, including user, feature, automation, and output sharing restrictions. Cracked copies, stolen keys, unauthorized key sharing, and bypassing license restrictions are not authorized. This guidance does not amend MIT or third-party licenses.

Deep-engine configuration

rea-python is a provider-neutral reverse-engineering engine that returns traceable, evidence-carrying, reusable results, exposed through a shared CLI and MCP (Model Context Protocol) server. Its design follows the ideas behind morluto/rea, including the Evidence model: every result carries its identity, confidence, authority, limitations, and unresolved unknowns, so an AI agent (or a person) can reason honestly instead of trusting a bare answer.

Status: alpha (0.1.52) — the original 169 upstream MCP tool names and 153 CLI commands, plus compatibility/extras (265 MCP tools, 289 CLI commands) with built-in static providers, the Evidence model, snapshot caching, deep-engine adapters, workflow/evidence tools, and gated runtime observation.

Upstream sync

rea-python tracks morluto/rea. As of 0.1.52 it matches the 6.7.0 upstream tool surface (169 MCP tools, 153 CLI commands) and adopts these 6.6/6.7 behaviors:

• Apktool localized string tables: repeatable --locales, --locale, --string-tables-only
• JADX whole-operation deadline: REA_JADX_OPERATION_TIMEOUT_MS
• Setup merges into existing JSON/JSONC client configs instead of overwriting unrelated servers
• Ghidra bridge auto-selection: pyhidra (Ghidra ≤11.3) or pyghidra (Ghidra ≥11.4), with --language/--compiler
• Kuna multi-operation provider: procedures, strings, xrefs, pseudocode, callers/callees, assembly via project export, with inventory/string caching
• Retained analysis views: environment-manifest, javascript-facts, javascript
• Prompt process cancellation with partial output; ASAR integrity observations; DMG inspection and read-only extraction
• Universal (fat) Mach-O inspection, code-signature metadata, and address-mapped byte tools

Known depth gaps vs upstream: full Kuna project-export reuse and Electron inspector/listener-ownership refinements.

What you can analyze

Engine tools can live on an external volume. Kuna is auto-detected under vendor/tools/kuna-*/kuna-*/kuna, or set REA_KUNA_COMMAND to the absolute binary. Raw images are selected with raw_image/--raw-image plus target/base/entry:

rea list-procedures firmware.bin --raw-image --target x86:LE:64:default --base 0x100000000 --entry 0x100000010
rea kuna-decompile firmware.bin --raw-image --target x86:LE:64:default --base 0x100000000 --entry 0x100000010 --function sub_100000010

An Electron runtime is auto-detected under vendor/tools/electron/node_modules/.bin/electron (or REA_ELECTRON_EXECUTABLE). capture-electron-scenario --app DIR launches the app, discovers a free CDP port, runs the scenario, and terminates the process:

rea capture-electron-scenario --app ./electron-app --steps-json '[{"action":"screenshot","path":"shot.png"}]'

External-tool providers are caller-supplied: rea-mcp never installs them and reports an actionable reason when one is missing (rea-mcp doctor). Cross-cutting tools: compare / compare-network-captures / compare-web-captures / compare-managed-members (target and Evidence diffs), build-reconstruction-obligation-ledger / evaluate-reconstruction-coverage (reconstruction), capture-process (bounded runtime capture), doctor (readiness), setup (client registration, plus --write-all and --install-skill), update, and evidence-export / evidence-import / inspect-analysis-view (portable Evidence).

Agent environments are an extension beyond the 6.7.0 upstream surface. From an environment-manifest Evidence record and its parent capture:

rea environment-compare manifest.json capture.json --probe probe.json
rea environment-export manifest.json capture.json ./bundle
rea environment-serve manifest.json capture.json --port 18765

The exporter derives item/list/document state, writes a Dockerfile and verifier, and the server exposes manifest tools plus replay/state/compare tools and /agentenv/data/{get,list,add,merge,delete,document,reset}.

All analysis runs locally. rea-mcp never uploads your target.

Client schema profiles

Tool schemas can be projected per client to fit hosts with small frame or schema limits. Set REA_MCP_CLIENT to a preset (generic, claude, cursor, opencode, vscode/code, zed, minimal), or override with REA_MCP_INPUT_SCHEMA_PROFILE (full/compact) and REA_MCP_OUTPUT_SCHEMA_PROFILE (full/off). rea-mcp schema-matrix prints the full matrix; REA_MCP_COMPACT_BUDGET_BYTES caps a single compacted schema.

Quick start

pip install rea-mcp             # PyPI distribution name is "rea-mcp"
rea-mcp --help                  # "rea" and "rea-python" are installed as alias commands too
rea-mcp inspect-binary-layout /path/to/program --json

As an MCP server (stdio) — rea-mcp, rea, and rea-python are interchangeable, as are python -m rea_mcp, python -m rea, and python -m rea_python:

rea-mcp mcp     # or: rea mcp   |   rea-python mcp
rea mcp

Output is JSON by default; a bare --json flag is accepted (before or after the command) for compatibility.

Readiness and client setup

rea-mcp doctor          # providers, external tools, effective timeouts
rea-mcp setup           # print the MCP client registration plan
rea-mcp setup --write <client-config.json>   # merge into an existing JSON/JSONC config
rea-mcp setup --install-skill <dir>          # install the bundled agent skill

doctor lists each provider, its operations, and why an optional engine is unavailable. It does not install anything.

Response budgets

MCP results are capped at 512 KiB by default (REA_MCP_MAX_RESPONSE_BYTES). Oversized analysis results are retained as Evidence and returned as a compact summary with an evidence_reference; use evidence-export, inspect-analysis-view --view record --evidence-id <id>, or get-evidence-bundle --full for the complete data. Set a CLI budget with --output-budget <bytes>; an oversized CLI result is written to a UTF-8 JSON file and stdout receives a summary plus output_path. inspect-analysis-view, inspect-artifact, inspect-managed-members, inspect-network-capture, inspect-android-package, inspect-android-class, inspect-android-method, decompile-android-apk, decompile-android-class, and analyze-javascript-application page with --offset/--limit (JavaScript also has --module-offset/--edge-offset). Decompilers return a summary-sized preview by default; --max-bytes changes the limit and the full text remains in Evidence. batch-decompile caps pseudocode at 64 KiB per function (--max-bytes-per-function 0 disables the cap). Captured web response bodies are capped at 32 KiB each and 512 KiB total; observe-web-execution --bodies --retain-bodies keeps the complete bodies in Evidence (up to 8 MiB) while returning bounded previews.

For managed assemblies, inspect-managed-members --type <full-name> --detail summary --evidence-bundle <file> writes the complete parent Evidence and prints identity, selection, counts and coverage. Page individual collections afterwards with inspect-analysis-view <file> --view managed-members --collection types|fields|methods|member_refs|call_edges|field_accesses|field_initializers|user_strings --offset/--limit; inspect-managed-artifact --detail summary exposes module/MVID, assembly, references, resources and attributes. Additional static providers include inspect-elf-notes, inspect-erlang-beam, inspect-pe-certificates, inspect-native-exports, inspect-javascript-routes, inspect-apk-signature, inspect-byte-entropy, inspect-python-pyc, inspect-model-artifact, inspect-desktop-application, inspect-gpu-code-objects, inspect-il2cpp-metadata, read-bytes, search-bytes and address-to-file-offset. compare-managed-members now compares types, fields, methods and nesting by exact type/name/signature identity. Optional C# decompilation is available through decompile-managed-csharp when ilspycmd is on PATH or REA_ILSPY/REA_ILSPY_CMD_PATH points to it. Managed metadata parsing uses a bounded in-process cache (REA_MANAGED_CACHE_ENTRIES, default 8); set it to 0 to disable. doctor --required dotnet,artifacts,sqlite --strict (or --profile powerbi) separates core readiness from optional engines. rea mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp opts into HTTP transport; stdio remains the default.

The optional rea upstream ... command forwards to a caller-installed upstream Node package (REA_UPSTREAM_CLI) for features not yet ported to Python.

Import names

The implementation package is rea_mcp. Compatibility aliases make import rea and import rea_python resolve to the same module objects, so all three import paths are interchangeable:

import rea_mcp  # implementation
import rea  # alias, same objects
import rea_python  # alias, same objects

Design principles

1. Dependencies flow inward: domain → contracts → providers → application → cli/mcp.
2. Evidence first: observations, derivations, inferences, and unknowns are distinguished.
3. Ownership and cleanup: resources are only cleaned by their owner; failures stay explicit.
4. Token-first performance: summaries, paging, and retained evidence keep agent context small.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .
mypy

License

MIT. rea-mcp is an independent, unofficial Python port; it is not affiliated with or endorsed by the authors of REA. See LICENSE and DISCLAIMER.md.