OmniRecon: Reverse-Engineering MCP Server for AI Coding Agents

Point your coding agent at any website, API, APK, or codebase. It drives a real browser, captures the evidence, and hands back a rebuild blueprint. Nothing is ever invented.

Reverse-engineering infrastructure for AI coding agents. v2.2.1

One tool call does the whole job.
recon_auto_pilot("https://target.com") crawls routes, inspects pages, captures network traffic, traces how sign= params are computed, and returns a build-ready blueprint — with unknowns and limitations on every response, so the agent always knows what it doesn't know.

Built for Claude Code, Codex, Cursor, Windsurf, Zed, and any other MCP-compatible agent or IDE.

curl -fsSL https://raw.githubusercontent.com/anilkumara9/omnirecon/main/install.sh | bash -s -- --client auto
# one command: clone + venv + deps + Chromium + agent config. Then restart your agent.

Then ask your agent: "Reverse-engineer https://example.com — explain how it works and give me a rebuild plan."

Table of contents

• How it works
• Comparison with alternatives
• See it in action
• The 25 tools
• UI reverse engineering
• Authenticated recon
• Setup
• Agent workflow
• Evidence model
• Measured accuracy
• Security boundaries
• Project layout
• Troubleshooting
• FAQ
• Star history
• License

How it works

1. Point — give it a URL, API doc, repo, or APK. recon_start validates it and does rapid recon in seconds.
2. Run — recon_auto_pilot drives a real headless browser through the whole pipeline: crawl routes, inspect pages, capture network traffic, trace signatures, probe endpoints.
3. Rebuild — you get a blueprint (routes, components, APIs, design tokens, workflows) where every claim cites its evidence and every gap is labeled.

Sessions persist on disk, so the agent can pause, resume, or run long crawls in the background.

Comparison with alternatives

OmniRecon and REA solve different halves of the problem. REA is the authority on deep binary decompilation (Ghidra/IDA providers) and is deliberately passive on the web. OmniRecon autonomously drives a real browser — crawling, clicking, capturing traffic — and hands binary targets to REA through a bridge when it's installed.

See it in action

One call. Full pipeline. Build-ready blueprint:

$ .venv/bin/python -m omnirecon.cli auto-pilot https://example.com --depth quick
{
  "session_id": "a1b2c3d4",
  "depth": "quick",
  "elapsed_s": 87.3,
  "tools_run": ["recon_start", "recon_discover_routes", "recon_inspect_page",
                "recon_capture_network", "recon_analyze_ui",
                "recon_generate_spec"],
  "evidence": {"total": 42, "by_classification": {"OBSERVED": 38}},
  "unknowns": [],
  "limitations": ["browser tools may fail on bot-protected targets"],
  "manifest": {"build_tasks": 8, "research_tasks": 3},
  "next_steps": "Build 8 tasks in manifest['build_tasks'] order..."
}

Every response carries unknowns (what wasn't resolved) and limitations (what can't be guaranteed) — the agent always knows what it doesn't know.

Or hand it to your agent: "Reverse-engineer this platform and give me a rebuild plan." It calls recon_auto_pilot once and gets the blueprint.

Teardown gallery: examples/teardowns/ — complete reverse-engineering blueprints of real targets. Every claim cites its evidence.

Full worked example: examples/teardown-acme-metrics/ — a complete session (evidence ledger, 15-section spec, design tokens, screenshots, dependency graph) against a demo SaaS site, committed as proof.

The 25 tools

UI reverse engineering (designer-grade)

recon_analyze_ui reads the rendered page the way a designer would — not the stylesheets:

• Computed design tokens — real colors, type scale, fonts, spacing, radii, shadows from getComputedStyle.
• Component inventory — buttons/inputs grouped by visual signature ("primary button ×14") with exact values, ready to rebuild.
• Framework detection — Tailwind, MUI, Chakra, Bootstrap, Ant Design; plus layout landmarks with measured dimensions.

Authenticated recon (behind the login)

Most real platforms hide 90% of themselves behind a login. OmniRecon goes there with your own credentials:

recon_authenticate(session_id, login_url, username, password)
→ recon_inspect_page / discover_routes / trace_workflow / capture_network / analyze_ui
→ recon_deauthenticate(session_id)

The password is used transiently for the form fill and never stored — not in the session dir, not in the ledger, not in logs. Cookies are kept 0600.

Setup (about 5 minutes)

You need: Python 3.10+, an internet connection, and ~400MB free disk (mostly Playwright's Chromium). No Node.js.

Step 1 — Install with one command

curl -fsSL https://raw.githubusercontent.com/anilkumara9/omnirecon/main/install.sh \
  | bash -s -- --client auto

That single command does six things, in order:

1. Clones the repo to ~/omnirecon (skipped if you already have a clone — it installs in place instead).
2. Creates an isolated virtualenv (.venv/) and installs the pinned dependencies (mcp<2, playwright, httpx, …).
3. Downloads Playwright's Chromium (~300MB; skipped if already present) — this is the browser OmniRecon drives for screenshots, clicking, and network capture.
4. Verifies the install actually works (imports the package, launches the browser once).
5. Configures your agent — detects Claude Code, Codex, Cursor, Windsurf, and Zed, and registers OmniRecon in each one's MCP config automatically. Existing configs are merged, never duplicated; a config file it can't parse is backed up (.omnirecon.bak) instead of overwritten.
6. Safe to re-run — run it again anytime; steps that are already done are skipped.

To configure only specific agents, replace auto with a name: claude-code, codex, cursor, windsurf, zed, or generic.

Step 2 — Restart your agent

Close and reopen your agent/IDE so it picks up the new MCP server. Quick check for Claude Code CLI: claude mcp list should show omnirecon.

Step 3 — Ask it to reverse-engineer something

Reverse-engineer https://example.com — explain how it works and give me a rebuild plan.

Your agent now drives all 25 tools by itself. You never run the server manually — it's a stdio process your agent launches on demand (no ports, no daemons, nothing running in the background).

Check it's healthy (optional)

Without any agent, from a terminal:

~/omnirecon/.venv/bin/python -m omnirecon.cli recon-start https://example.com --mode fast
# → {"session_id": "...", ...} means your install is healthy

git clone https://github.com/anilkumara9/omnirecon.git
cd omnirecon
./install.sh --client auto   # Linux / macOS

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/playwright install chromium   # the driven browser
.venv/bin/python -m omnirecon.cli setup auto   # write agent configs

claude mcp add omnirecon -- /path/to/omnirecon/.venv/bin/python /path/to/omnirecon/omnirecon/server.py
claude mcp list          # verify it shows up

[mcp_servers.omnirecon]
command = "/path/to/omnirecon/.venv/bin/python"
args = ["/path/to/omnirecon/omnirecon/server.py"]

{
  "mcpServers": {
    "omnirecon": {
      "command": "/path/to/omnirecon/.venv/bin/python",
      "args": ["/path/to/omnirecon/omnirecon/server.py"]
    }
  }
}

{
  "context_servers": {
    "omnirecon": {
      "command": "/path/to/omnirecon/.venv/bin/python",
      "args": ["/path/to/omnirecon/omnirecon/server.py"]
    }
  }
}

No MCP support? Use the CLI

All 25 tools are mirrored as CLI commands running the same code — useful for scripts, CI, or agents without MCP:

.venv/bin/python -m omnirecon.cli recon-start https://example.com --mode fast
.venv/bin/python -m omnirecon.cli recon-discover-routes <session-id> https://example.com --max-pages 40
.venv/bin/python -m omnirecon.cli recon-generate-spec <session-id>
.venv/bin/python -m omnirecon.cli --help   # all 25 commands

Sessions persist on disk (sessions/<id>/), so CLI and MCP sessions are interchangeable — start in one, continue in the other.

Agent workflow

Once connected, the agent follows the bundled skill (skills/omnirecon/SKILL.md):

1. recon_start — validate the target, get rapid recon in seconds.
2. Deep engines — crawl routes, inspect pages, trace workflows, capture network, analyze source/artifacts.
3. recon_verify_consistency — cross-check every engine against the others; contradictions get downgraded, never hidden.
4. recon_generate_spec — a 15-section rebuild blueprint where every claim cites its evidence.
5. Build, then recon_compare_build — diff the rebuild against the original and iterate until parity.

Just ask: "Reverse-engineer https://example.com — explain how it works and give me a rebuild plan."

Evidence model

Every finding carries a trust label — the agent (and you) always knows how much to believe it:

Every response also carries unknowns (what couldn't be resolved), limitations (what can't be guaranteed), and truncated (whether the ~30k-token response budget cut anything). The agent always knows what it doesn't know.

Measured accuracy

Measured 2026-10-12/13 on real targets (not estimates):

200 tests green (pytest tests/). Raw benchmark data in benchmarks/results/.

Security boundaries

• Read-only by default — no state-changing requests, no destructive actions, ever.
• No bypasses — CAPTCHAs, paywalls, and bot protection become BLOCKED findings, not workarounds.
• No credential harvesting — authenticated recon only uses credentials you explicitly provide; passwords are never stored.
• Secrets redacted — API keys and tokens are scrubbed before anything is stored; page content is treated as untrusted data.

Project layout

omnirecon/            the 23-module package (server, evidence, session,
                      browser_engine, source_intel, assets, spec, …)
tests/                pytest suite (200 tests)
skills/omnirecon/     agent skill doc: workflow, routing table, hard rules
examples/             committed teardown sessions (proof, not docs)
scripts/proxy_relay.py  dumb TCP relay for sandboxes whose egress proxy
                      breaks Chromium (see Troubleshooting)
benchmarks/           hand-annotated fixture + runner + measured results
install.sh            one-command installer (clone + venv + deps + Chromium + agent config)
install.bat           Windows one-command installer (same steps)
requirements.txt      pinned dependencies (mcp<2)
.github/workflows/    CI: full pytest suite on every push/PR
CHANGELOG.md          version history
CONTRIBUTING.md       contributor guide
SECURITY.md           security policy and §8 boundaries
ARCHITECTURE.md       module map and design decisions
REA_INSPECTION.md     REA teardown and the evidence-based comparison

Troubleshooting

• Agent doesn't see the tools — the usual causes, in order: (1) you used system Python instead of .venv/bin/python — re-run .venv/bin/python -m omnirecon.cli setup <client> and check its output; (2) you forgot to restart the agent/IDE after registering; (3) the JSON has a typo — validate it with python -m json.tool <config-file>.
• setup says python not found — run ./install.sh (or install.bat) first; the venv must exist before the config can point at it.
• Executable doesn't exist … ms-playwright — run .venv/bin/playwright install chromium.
• Browser tunnel/cert errors behind a proxy — export HTTPS_PROXY/ https_proxy; the engine passes it to Playwright. Behind TLS-intercepting proxies the server retries automatically past cert errors (recording an OBSERVED finding); force it with OMNIRECON_IGNORE_HTTPS_ERRORS=1. If Chromium can't use the egress proxy at all (tunnel failures while curl works), run scripts/proxy_relay.py and point HTTPS_PROXY at http://127.0.0.1:8899.
• DNS returns nothing — direct UDP DNS may be blocked; the tool falls back to DNS-over-HTTPS automatically.
• Tool returns {"error", …} — read code and hint; the server never leaks tracebacks.

Frequently asked questions

What can I reverse engineer? Web apps (routes, APIs, design systems, workflows), REST APIs (with OpenAPI export), Android APKs, Electron apps, and source codebases. Anything with an observable surface.

How is this different from REA? REA owns deep binary decompilation (Ghidra/IDA) and is passive on the web. OmniRecon drives a real browser autonomously and hands binaries to REA via a bridge. Comparison table.

Can it do mobile apps? Android APKs: yes (manifest, DEX analysis). iOS: structural only. Native decompilation goes through the REA bridge.

No MCP client? Every tool is mirrored in the CLI: .venv/bin/python -m omnirecon.cli --help.

Safe against production sites? Read-only by default — no state-changing requests, ever. Authenticated recon uses only credentials you provide.

Star history

If OmniRecon is useful in your workflow, consider leaving a ⭐ — it helps other developers find it.

License

MIT — see LICENSE.