# REA MCP Analysis Orchestrator (FastAPI)

## PURPOSE
The video covers **REA — "reverse engineer anything"**, the GitHub repo by Moruto that blew
up to 150K+ stars after the viral "software is done" post. REA is not a magic wand: it ships
a set of **MCP and CLI tools one can hand to an agent** to analyze software apps and browser
websites. The server exposes the exact toolset the video names — `inspect`, `search`, `trace`,
`compare`, `workflow`, `observe`, `capture` — and hides the messy backend (Hopper, Ghidra,
Playwright, its own JavaScript parsers) behind one clean HTTP contract.

## WHY THIS MATTERS
This teaches the real REA loop the creator walks through in Hermes Agent: *the agent asks a
question → the agent calls REA's tools over MCP → REA sends a request to the local analysis
provider → the provider runs locally → REA turns the output into a standard result → the agent
asks follow-up questions.* Students implement the middle of that chain as real code instead of
treating it as a black box.

## HOW TO BUILD
1. `pip install fastapi uvicorn pydantic httpx`.
2. Define a `ToolName` enum for the seven REA tools and a `ToolRequest`/`ToolResult` pair of
   Pydantic models — one normalized shape for *every* tool, mirroring REA's "standard result".
3. Add `POST /analyze` that validates the request, picks the provider route (decompiler vs.
   browser vs. JS), and returns a `ToolResult`.
4. Add `POST /followup/{session_id}` so an agent can read prior evidence and ask a tighter
   question — the learning loop.
5. Enforce REA's **target size ceiling** before dispatch (the video shows the 532 MB Loom app
   being rejected while "Loom's own app code" analyzed fine).

```python
@app.post("/analyze", response_model=ToolResult)
async def analyze(req: ToolRequest) -> ToolResult:
    if req.target.size_mb > settings.max_target_mb:
        raise HTTPException(413, f"target exceeds REA limit ({settings.max_target_mb} MB)")
    return await provider.dispatch(req, session_store)
```

## WHEN TO USE IN PRODUCTION
Use it when an internal agent must drive decompiler/browser analysis behind a controlled,
auditable boundary — size limits, allow-listed tools, and a uniform result schema. Do **not**
use a server like this for open, unauthenticated analysis of third-party binaries; the video is
explicit that reverse engineering carries legal weight and should stay personal/experimental,
not commercial.

## HOW IT HELPS STUDENTS
They learn MCP-style tool contracts, async FastAPI, Pydantic validation, provider abstraction,
and guardrails (size caps) — the glue layer that turns a pile of decompilers into one agent tool.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI skeleton with all seven tool routes, the size
guard, and a deterministic stub standing in for the local analysis provider.
