vmoranv/jshookmcp

📦 What is @jshookmcp/jshook?

A search‑first, profile‑aware reverse‑engineering workspace that runs as an MCP (Model‑Context‑Protocol) server. It lets AI agents (e.g., Claude Desktop, Cursor) interact with a rich toolbox for front‑end and binary analysis – from browser automation to WASM disassembly – without having to load thousands of tool schemas up‑front.

---

🎯 Core idea

• MCP server – exposes a uniform JSON‑RPC‑like interface that AI agents can call.
• Profiles – three token‑light tool sets (search ≈ 3 K tokens, workflow, full ≈ 40 K tokens). Agents start with a tiny profile and “promote” as the task grows, keeping LLM token usage low.
• Runtime recovery – streamable HTTP sessions restore browser attach state, coverage data, and activated domains after a disconnect, while keeping each client’s state isolated.

---

🔧 Main capabilities (high‑level)

Area	What you can do
Browser automation	Drive Chromium or Camoufox via CDP, anti‑detection presets, explicit‑input CAPTCHA solving, HTTPS‑MITM, HTTP/2 frame building, pop‑up/download/permission interception.
Network interception	Auto‑generated HTTPS CA, WebSocket capture, GraphQL introspection, Burp Suite bridge.
JS analysis	LLM‑assisted deobfuscation, crypto routine detection, AST transforms, source‑map reconstruction, script extraction/replay.
WASM RE	wabt‑based disassembly (wasm2wat, wasm‑decompile, wasm‑objdump), Binaryen optimisation, section parsing, diff, obfuscation detection, instrumentation.
Binary & process forensics	Frida/Ghidra/IDA bridges, hardware breakpoints, PE introspection, memory read/write, cross‑reference graphs.
Android/APK	Static triage, manifest dump, apktool decode/build, jadx decompilation, DEX scanning, native lib listing, unidbg emulation.
Coordination	Task queue with progress/cancel, multi‑agent session handling, coverage reports.
Extensibility	Hot‑reload plugins, declarative YAML workflows, auto‑discovered domains (36 built‑in).

---

📚 Typical use‑cases

Scenario	How you would use jshook
Skim a minified bundle	search_tools → deobfuscate → search_in_scripts → understand_code (uses the core domain).
Solve a CAPTCHA	Launch Camoufox, take a screenshot, feed the image to an LLM for manual input, replay the solution.
Capture & replay an OAuth flow	Start the MITM proxy (proxy_start), collect requests, introspect GraphQL, replay the sequence.
Reverse a WASM crypto routine	Dump the module, disassemble, generate hooks, set a memory breakpoint.
Audit a suspicious APK	Run static triage, dump the manifest, decompile with jadx, scan DEX for suspicious patterns.
Recover a dropped browser session	Re‑connect via the streamable HTTP transport; the server restores the previous CDP attach and coverage state.
Build a custom workflow	List available extension workflows, run one as a single tool (run_extension_workflow).
Hook a live process	Use the Frida bridge to spawn/attach, install an interceptor, and enumerate functions.

---

🚀 Quick start for an AI‑agent client

Add the server to your MCP client config (example for Claude Desktop / Cursor):

{
  "mcpServers": {
    "jshook": {
      "command": "npx",
      "args": ["-y", "@jshookmcp/jshook@latest"],
      "env": {
        "MCP_TOOL_PROFILE": "search",
        "npm_config_omit": "optional"
      }
    }
  }
}

The search profile loads only the minimal 3 K token metadata.

If you want several agents to share the heavy runtimes (browser, embeddings, etc.), start a shared daemon:

pnpm build
pnpm daemon   # runs the Streamable HTTP server on 127.0.0.1:3000

Then point each client to http://127.0.0.1:3000/mcp. Each client still gets an isolated MCP session.

---

🏗️ Architecture at a glance

• Runtime registry – domains are discovered from manifest.ts; adding a file creates a new domain automatically.
• Lazy init – tool handlers are instantiated only on first call, keeping startup fast.
• Hybrid search – search_tools uses BM25 + optional vector ranking to find the right tool without loading the whole schema.
• Tool annotations – every tool declares readOnlyHint, destructiveHint, idempotentHint, openWorldHint for safer agent orchestration.
• Transport symmetry – both stdio and Streamable HTTP expose the exact same tool surface; the latter multiplexes sessions and restores state after reconnects.

---

📦 Building / running from source

# prerequisites
#   Node 22.22.2+   pnpm 10.x
pnpm install          # install deps (optional runtimes are omitted unless needed)
pnpm build            # compile TypeScript
pnpm start            # run the server (stdio mode)
# or
pnpm daemon           # run the HTTP daemon

Additional scripts:

• pnpm dev – watch‑mode development.
• pnpm check – lint, format, type‑check, and verify generated metadata.
• pnpm test / pnpm test:e2e – unit and end‑to‑end test suites.

---

📄 License

AGPL‑v3 (see LICENSE).

---

Bottom line: @jshookmcp/jshook is a full‑stack, extensible reverse‑engineering platform that can be driven by LLM agents through a lightweight MCP interface, offering everything from browser automation to low‑level binary analysis while keeping token usage under control.