ReaPlus

<div align="center">

<img src="assets/icon.svg" width="110" height="110" alt="rea-plus logo">

# Reverse Engine Anything Plus

**One MCP server for reverse engineering — live Windows debugging plus a 157-tool static-analysis suite for PE/ELF, Mach-O, .NET, APK, IL2CPP, WASM/EVM, firmware, and the web.**

Your agent asks questions; rea-plus inspects the binary and answers with evidence, not guesses.

[![CI](https://github.com/Alyhnte/ReaPlus/actions/workflows/ci.yml/badge.svg)](https://github.com/Alyhnte/ReaPlus/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/Alyhnte/ReaPlus?style=flat-square)](https://github.com/Alyhnte/ReaPlus/releases)
[![Tools](https://img.shields.io/badge/MCP%20tools-191-blue?style=flat-square)](#-features)
[![Tests](https://img.shields.io/badge/tests-912%20its%20%2B%20e2e-green?style=flat-square)](#-tests)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)

[Install](#-install) · [Clients](#-client-setup) · [Docker](#-docker) · [Features](#-features) · [Tools](docs/TOOLS.md) · [How it works](#-how-it-works) · [Security](#-security-model) · [Roadmap](docs/ROADMAP.md) · [FAQ](#-faq)

</div>

---

## ✨ Why rea-plus?

- 🐞 **Real debugging, not screenshots** — x64dbg, cdb (WinDbg), and Frida engines behind one frozen 30-tool core: breakpoints, stepping, registers, memory, call stacks, time-travel checkpoints.
- 🧰 **157 static tools** — Ghidra headless, rizin/radare2, .NET CIL (dnfile) and ILSpy, jadx/apktool/adb, WASM + EVM, firmware, browser/HAR, UPX, PE/ELF/Mach-O readers, and more.
- 🤝 **Honest by design** — a missing backend answers `capability_unsupported` with an install hint. Nothing fakes a result, errors come back as proper MCP `isError`, and mutating live-debug calls require `confirm:true`.
- 🧩 **191 tools, 2 resources, 3 prompts** — the full generated catalog lives in [`docs/TOOLS.md`](docs/TOOLS.md); `REA_TOOLSETS` lets small-context clients load only a profile slice (see [Configuration](#-configuration)). Without an HTTP token, only a 44-tool read-only allowlist is registered instead of the full surface.
- 🔌 **Two transports** — stdio for local agents, streamable HTTP (`/mcp` + `/health`, bearer token, localhost Host/Origin validation) for shared setups.
- 🧪 **Proven, not promised** — a 91-file default test lane, Ubuntu CI for the released line, and protocol tests that drive the real compiled server.

```console
$ rea-plus-cli doctor            # what is installed on this machine, what is missing
$ rea-plus-cli analyze-evm "transfer(address,uint256)"
transfer(address,uint256) -> 0xa9059cbb
```

```jsonc
// One MCP call your agent makes:
{ "name": "rea_investigate", "arguments": { "path": "sample.exe" } }
// -> sniff + confidence + provider plan + evidence bundle, in one answer
```

## 🚀 Install

> **Requirements:** Node.js ≥ 20. Everything else (Ghidra, rizin, jadx, Frida tooling, …) is optional — tools light up as backends appear; run `doctor` to see your machine's map. Windows is required for the live debuggers (x64dbg/cdb/Frida attach); static analysis runs anywhere.

### One-click (Cursor / VS Code)

[![Add to Cursor](https://img.shields.io/badge/Add%20to%20Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=rea-plus&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInJlYS1wbHVzIl19)
[![Install in VS Code](https://img.shields.io/badge/Install%20in%20VS%20Code-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=rea-plus&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22rea-plus%22%5D%7D)

### Setup wizard (standalone download)

No npm? Download [`setup.mjs`](https://github.com/Alyhnte/ReaPlus/releases/latest/download/setup.mjs) (+ Windows [`setup.ps1`](https://github.com/Alyhnte/ReaPlus/releases/latest/download/setup.ps1)) from the [latest release](https://github.com/Alyhnte/ReaPlus/releases/latest) — needs only Node.js 20+:

```bash
node setup.mjs --list        # detect installed clients
node setup.mjs --dry-run     # preview without writing
node setup.mjs --yes         # write MCP config (asks unless --yes)
```

```powershell
.\setup.ps1 --list
.\setup.ps1 --yes
```

Or inside the package: `npx -y rea-plus rea-plus-cli setup` (same wizard).

### npx (no clone)

Any stdio MCP client can launch it straight from the npm registry:

```json
{
  "mcpServers": {
    "rea-plus": {
      "command": "npx",
      "args": ["-y", "rea-plus"]
    }
  }
}
```

> **Publishing status:** `rea-plus@0.8.2` is live on the [npm registry](https://www.npmjs.com/package/rea-plus) and [`io.github.Alyhnte/rea-plus`](https://registry.modelcontextprotocol.io) is published on the MCP Registry. The supported installs are `npx -y rea-plus` (above) and GHCR (see [Docker](#-docker)).

### Clone & build

```bash
git clone https://github.com/Alyhnte/ReaPlus.git
cd ReaPlus
npm ci
npm run build        # tsc + runtime assets (frida-agent.js, Ghidra scripts) -> dist/
npm start            # stdio server (dist/server.js)

# Optional HTTP transport:
node dist/server.js --transport http --port 3848
# -> GET  http://127.0.0.1:3848/health
# -> POST http://127.0.0.1:3848/mcp
```

### Optional extras

```bash
# Browser tools (Playwright is an optional dependency, loaded lazily):
npm i playwright && npx playwright install chromium
```

Then point your agent at it and ask it to inspect something.

## 🔌 Client setup

Every client below gets the same server. Ready-made files live in [`configs/`](configs/).

<details>
<summary><strong>Claude Desktop</strong></summary>

Add to `claude_desktop_config.json` (see [`configs/claude-desktop/`](configs/claude-desktop/claude_desktop_config.stdio.json)):

```json
{
  "mcpServers": {
    "rea-plus": { "command": "npx", "args": ["-y", "rea-plus"] }
  }
}
```

</details>

<details>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add rea-plus -- npx -y rea-plus
```

Or drop [`configs/claude-code/.mcp.json`](configs/claude-code/.mcp.json) into your project root.

</details>

<details>
<summary><strong>Cursor</strong></summary>

Click **Add to Cursor** above, or use [`configs/cursor/mcp.stdio.json`](configs/cursor/mcp.stdio.json) (clone path form) / [`mcp.http.json`](configs/cursor/mcp.http.json) (HTTP form).

</details>

<details>
<summary><strong>VS Code</strong></summary>

Click **Install in VS Code** above, or copy [`configs/vscode/mcp.json`](configs/vscode/mcp.json) to `.vscode/mcp.json` in your workspace.

</details>

<details>
<summary><strong>Windsurf</strong></summary>

Use [`configs/windsurf/mcp_config.json`](configs/windsurf/mcp_config.json) as your `mcp_config.json`.

</details>

<details>
<summary><strong>Codex</strong></summary>

Append [`configs/codex/config.toml`](configs/codex/config.toml) to `~/.codex/config.toml`:

```toml
[mcp_servers.rea-plus]
command = "npx"
args = ["-y", "rea-plus"]
```

</details>

<details>
<summary><strong>opencode / generic HTTP</strong></summary>

```bash
DBG_BRIDGE_TOKEN=your-secret node dist/server.js --transport http --port 3848
# clients connect to http://127.0.0.1:3848/mcp with Authorization: Bearer <token>
```

See [`configs/opencode/`](configs/opencode/opencode.stdio.json) for stdio and HTTP variants.

</details>

## 🐳 Docker

```bash
# Build locally (works today):
docker build -t rea-plus .

# stdio (for MCP clients that spawn containers):
docker run -i --rm rea-plus

# HTTP:
docker run -p 3848:3848 -e DBG_BRIDGE_TOKEN=your-secret rea-plus --transport http --port 3848 --host 0.0.0.0
```

Images are published to GHCR on each release (`ghcr.io/alyhnte/reaplus`). Windows-only
debuggers (x64dbg/cdb) report `capability_unsupported` inside a Linux container; static
analysis, the CLI, and both transports work.

## 🧰 Features

The complete, generated reference — **191 tools + 2 resources (`rea-plus://server-info`, `rea-plus://capabilities-safety`) + 3 prompts (`packer-triage`, `dotnet-malware-triage`, `android-triage`)** — is in [`docs/TOOLS.md`](docs/TOOLS.md). The table below is only a domain summary.

| Domain | What you get | Engine / backend |
|---|---|---|
| Live debugging | Breakpoints, step/continue, registers, memory, call stacks, checkpoints & rewind | x64dbg · cdb · Frida · radare2 (conduit core, 30 frozen tools) |
| Native static (PE/ELF) | Disassembly, CFG, xrefs, strings, imports, PDB/DWARF, decompile | Ghidra headless · rizin/Cutter |
| .NET | Real CLR detection, CIL dump via dnfile, ILSpy decompile | dnfile · ilspycmd |
| Android | APK decode/build, framework info, adb bridge | jadx · apktool · aapt2 · adb |
| Dynamic instrumentation | Attach/spawn, API tracing, conditional breakpoints, process pause | Frida 17 |
| Behavior | Process runs with SHA-256 records, network capture (HAR), event timelines | mitmproxy · process capture |
| Web / browsers | Navigation, clicks, screenshots, storage & console capture | Playwright (optional extra) |
| WASM / EVM | Validation (wabt), disassembly, function selectors, opcode work | wabt · offline keccak |
| Firmware & exotic | Firmware triage, DOS/MIPS/AOT/Go pre-scans, packer hunt (UPX→.NET→dump recipe) | Static inspection · UPX |
| Mach-O / Apple | Header + load commands, otool output, bundle/plist reading (honest errors without backends) | Built-in reader · otool |
| Unity IL2CPP | Il2CppDumper dump + global-metadata class/method counts (honest error when missing) | Il2CppDumper · metadata reader |
| Binary diff | Function lists (name/address + hash) and version-to-version diff | Built-in |
| PCAP / TLS | Stream reassembly + keylog-based TLS decryption | tshark · keylog |
| Android dynamic | Dynamic-analysis recipe generation + dry-run recipe validation | Built-in recipe |
| Scale | Parallel repo scan (pool of 4, cancellable) | Built-in |
| Investi