REA MCP Lite

An on-demand MCP proxy for REA that keeps all 207 reverse-engineering tools available while cutting their context cost from ~193,000 tokens to ~415.

If you have ever mounted REA's MCP server and watched every turn fail with CONTEXT_WINDOW_EXCEEDED before you typed anything — this is the fix.

The problem

MCP clients inline every tool's input schema into every request. REA's catalogue is enormous:

Measured on a real session against a 90,112-token local model:

direct mount : 243 tools, 787.6 KB header, ~201,638 tok  ->  hard failure
               "Message too long: 266784 tokens exceeds the 90112-token context window"
with proxy   :  39 tools,  32.4 KB header,   ~8,305 tok  ->  works

Two things make this unrecoverable without a proxy:

1. Auto-compaction cannot help. Compaction prunes messages; the bloat is 96% tool schemas, which it never touches. Compaction ran and also blew the window.

2. Only one tool needs to kill you. compare_web_captures alone is 162.7 KB (~41,000 tokens). Its schema is bigger than most context windows' entire working budget.

Related MCP server: sor-mcp-server

How it works

The proxy exposes three tiny tools and holds the full 207-tool catalogue out of band, in its own process memory.

agent ──rea_find_tools{query}────▶ proxy ──▶ matching names + one-line summaries
      ──rea_tool_schema{name}────▶ proxy ──▶ that ONE tool's schema (≤24 KB)
      ──rea_call{name,arguments}─▶ proxy ──▶ REA backend ──▶ result verbatim

Nothing about REA is removed or reimplemented. Every tool stays callable; the schemas are simply fetched on demand instead of paid for up front.

Cost per call

Worst-case single schema is ~6,000 tokens — versus 41,000 for the same tool mounted directly.

Requirements

• Node.js 18+

• REA — rea-agents ≥ 6.7.0, either already installed or resolvable by npx

• macOS or Linux (Windows untested)

Install

git clone https://github.com/shivanshtalwar0/REA-mcp-lite.git
cd REA-mcp-lite
node scripts/doctor.mjs

doctor verifies the backend resolves, counts the catalogue, and confirms the proxy surface. Expected output:

rea-mcp-lite doctor

  node            v24.15.0  (/path/to/node)
  proxy           /path/to/rea-proxy.mjs
  backend         cached rea-agents 6.7.0 (/path/.npm/_npx/.../scripts/rea.mjs)
  ✓ backend answered: 207 tools
  catalogue       207 tools
  schemas         3084 KB raw / 755 KB model-facing
  if mounted      ~193,289 tokens of every request
  ✓ proxy answered: 3 tools
  tool surface    rea_find_tools, rea_tool_schema, rea_call
  wire size       1,657 bytes (~415 tokens)

PASS — ready to mount.

Quickstart — DeepSeek Harness (DSH)

This is the client it was built for. DSH prices tool schemas into every request via dsh-token-meter:

Math.ceil(JSON.stringify(header.tools).length / 4) + 4

A 755 KB catalogue therefore costs ~193K tokens per turn, forever.

1. Add the mount

Edit ~/.dsh/cordis.patch.yml (the home-level user layer, applied to every profile):

- insert:
    - id: rea-proxy
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: rea
        transport: stdio
        command: /Users/you/.nvm/versions/node/v22.14.0/bin/node
        args:
          - /Users/you/REA-mcp-lite/rea-proxy.mjs
        env:
          HOPPER_LAUNCHER_PATH: /Applications/Hopper Disassembler.app/Contents/MacOS/hopper

2. The two things people get wrong

command must be an absolute node path. DSH is a desktop app; launched from Finder it inherits a minimal PATH that does not include nvm or Homebrew bins. command: node fails with ENOENT. Do not use the app's bundled runtime/bin/node either — that is a wrapper script requiring $DSH_DESKTOP_NODE_EXECUTABLE, which env scrubbing strips.

The file must stay a YAML array. A patch file with only comments parses as null and DSH fails to boot it. Keep at least [] or a real entry.

3. Restart and confirm

Restart DSH, then check the context meter in the composer. Tool definitions should read ~400–500 tokens, not ~194,000. Your REA tools appear as:

mcp__rea__rea_find_tools
mcp__rea__rea_tool_schema
mcp__rea__rea_call

4. Verify against the real payload (optional)

DSH logs each request envelope. This prints the tool count and size per request:

S=~/.dsh/sessions/$(ls ~/.dsh/sessions | head -1)
zstd -d -c "$S"/session*.zstd | node -e '
let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{
for(const l of d.split("\n")){if(!l)continue;let o;try{o=JSON.parse(l)}catch{continue}
if(o.type==="request/header"&&o.data?.header?.tools){const t=o.data.header.tools;
console.log(o.seq, t.length, "tools", (JSON.stringify(t).length/1024).toFixed(1)+"KB");}}})'

Quickstart — other MCP clients

Any stdio MCP client works. The proxy speaks plain newline-delimited JSON-RPC.

Claude Code

claude mcp add rea-lite -- node /absolute/path/to/rea-proxy.mjs

Generic JSON config (Cursor, VS Code, Windsurf, …)

{
  "mcpServers": {
    "rea": {
      "command": "node",
      "args": ["/absolute/path/to/rea-proxy.mjs"],
      "env": {
        "HOPPER_LAUNCHER_PATH": "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper"
      }
    }
  }
}

These clients launch from a normal shell, so plain node is fine. Only the Finder-launched DSH app needs the absolute path.

Agent workflow

The three tools are designed to be used in order. Prompts that work well:

"Find REA tools for inspecting Electron fuses"
"Get the schema for inspect_binary_layout"
"Call inspect_binary_layout on /path/to/binary with detail=summary"

The intended loop is search → schema → call. rea_tool_schema exists because guessing REA's argument shapes wastes turns; the schema is the contract, and REA validates strictly:

Input validation error: Invalid arguments for tool inspect_binary_layout:
  path: Invalid input: expected string, received undefined, Unrecognized key: "target"

That error is the feedback signal — read it, correct the arguments, retry.

Configuration

All optional.

Troubleshooting

Backend exits with code 1 and an npm EPERM

npm error code EPERM
npm error Your cache folder contains root-owned files

npx -y fails on every cache miss when ~/.npm contains root-owned files (a known npm bug). The proxy sidesteps this two ways, in order:

1. It discovers an existing install under ~/.npm/_npx/*/node_modules/rea-agents/scripts/rea.mjs and spawns it directly with the same node binary — npm never runs.

2. If nothing is cached, it falls back to npx -y <spec>.

If you hit EPERM anyway, either repair the cache or point the proxy at REA explicitly:

sudo chown -R 501:20 ~/.npm
# or
REA_REA_JS=/path/to/real-rea/scripts/rea.mjs  node rea-proxy.mjs

spawn node ENOENT

The client launches without your shell's PATH. Use an absolute path to the node binary in the client config.

Unknown REA tool "foo"

Call rea_find_tools first — tool names must be exact. The error response includes near-miss suggestions.

schema truncated

The tool's real schema exceeds REA_PROXY_MAX_SCHEMA_BYTES (24 KB default). The note tells you so. Either raise the cap (at a token cost) or prefer a narrower tool — the fat ones are usually orchestration wrappers around smaller primitives.

First REA call is slow

Expected. The backend boots in ~0.7–2 s on first use, then stays warm for the life of the process. rea_find_tools and rea_tool_schema then answer in single-digit milliseconds.

Tools disappeared / went stale after upgrading REA

The catalogue is cached per process. Restart the client (or kill the proxy) to re-read it.

Limitations

• Descriptions are truncated at 1,500 characters in rea_tool_schema responses. For REA, descriptions are long design documents; the schema is what you actually need.

• Schemas are capped at 24 KB, trimmed prose-first, structure preserved.

• No forwarding of MCP resources, prompts, or list_changed notifications. Tools only.

• One backend per proxy. Calls share it; REA handles its own concurrency.

• No streaming. rea_call returns when the tool completes.

Security

The proxy gives the agent whatever REA can do — and REA reads local files, binaries, app bundles, databases, and browser profiles. Anything that can talk to this proxy can read your filesystem.

• stdio only; no network listener

• no credentials, no telemetry, no outbound traffic

• run it only in sessions you would trust with full local file access

Files

rea-proxy.mjs              the proxy (dependency-free, ~530 lines)
scripts/doctor.mjs         end-to-end setup verification
examples/dsh-cordis.patch.yml   ready-to-adapt DSH mount
package.json               npm metadata (bin: rea-mcp-lite)

No dependencies. No build step. One file to audit.

Why not just use REA's CLI?

You can, and it costs zero schema tokens:

npx -y rea-agents@6.7.0 <command>

The tradeoff is ergonomics. The CLI gives the model no discoverable contract — it must guess subcommands and flags, then parse --help output. Small local models are bad at this. The proxy gives the same tools with an explicit, verifiable schema per call while keeping the context cost near zero.

Use the CLI for scripted work; use the proxy when an agent needs to choose tools itself.

License

MIT — see LICENSE.

REA itself is a separate project by morluto and is not included or modified here.