# @jshookmcp/jshook: an MCP server for JavaScript hooking and reverse engineering

> @jshookmcp/jshook exposes 723 tools for browser automation, network interception and JS deobfuscation through one Model Context Protocol server. The search-first tool profile is the interesting design choice; the AGPL licence and the unregistered npm name are the parts to check before you build on it.

**vmoranv/jshookmcp** — js hook toolkit that all you need

- Repository: https://github.com/vmoranv/jshookmcp
- Website: https://vmoranv.github.io/jshookmcp/
- Stars: 2,020 · Forks: 459
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/vmoranv-jshookmcp

## The problem: an agent that needs 723 tools without drowning in schemas

Reverse-engineering a front-end bundle is a sequence of small, heterogeneous actions. Attach a debugger. Intercept a WebSocket frame. Reconstruct a source map. Disassemble a WASM module. A general-purpose coding agent can do some of this with shell commands, but every step needs a specific tool with specific arguments, and the agent has to know which one exists.

@jshookmcp/jshook targets that gap. It is a Model Context Protocol server, so an MCP-capable client connects to it and sees its tools as native capabilities. The README describes the project as "a search-first, profile-aware reverse-engineering workspace for AI agents", and the profile part is the actual engineering decision, not the tool count. A server that advertises 723 tools in full costs roughly 40K tokens of metadata before the agent has done any work. The `search` profile is documented at about 3K tokens, using BM25 plus hybrid vector ranking to surface tools on demand rather than up front.

The intended audience is narrow and specific: security analysts and reverse engineers who already drive an MCP client and want browser, network and binary instrumentation available inside the same conversation. It is not a library you import into an application, and it is not a browser automation framework in the Playwright sense.

## How the tool profiles and domain registry fit together

The architecture has three layers the README makes visible. At the bottom, 34 self-discovered domains hold the actual capability: browser automation, network interception, JS hooks, WASM, process and memory forensics, binary instrumentation, encoding, coordination. Domains are auto-discovered and can be hot-reloaded as plugins, which is why the repository ships a `packages/` workspace and a plugin API export (`./plugin-api`) alongside the main entrypoint.

Above that sits the profile layer. `search` exposes a small meta-tool surface; `workflow` exposes composite scripts; `full` exposes everything. The meta tools are `search_tools`, `describe_tool`, `call_tool` and `coverage_report`. The pattern is that the agent searches, describes the tool it found, then calls it with validated arguments. That indirection is what keeps the token cost down, and it is also the main usability cost: every capability is two or three round trips away instead of one.

On top, the transport layer supports stdio and streamable HTTP. The README states that HTTP sessions restore activated domains, browser attach state and coverage state after reconnects, and that per-client browser-side state stays isolated so two agents cannot trample each other's CDP sessions. That isolation claim is the kind of thing worth testing yourself, because it is the difference between a single-user tool and something a team can share.

## Building @jshookmcp/jshook from source and running a first search

There is no published package to install. The README carries a comment in the badge block saying the npm badge will be re-added "once @jshookmcp/jshook is published", and the getting-started page linked from the README is the canonical install path. The repository is a pnpm workspace, so the build route is the one the repository layout implies.

Install dependencies and build the workspace from the repository root:

```bash
pnpm install
pnpm run build
```

The build produces `dist/index.mjs`, which `package.json` declares as both `main` and the `jshook` / `jshookmcp` binaries. If that file is missing after the build, nothing downstream will work.

The runtime reads overrides from a `.env` file. Copy the example and set only what you need:

```bash
cp .env.example .env
```

The defaults in `.env.example` are worth reading before you change anything. `MCP_TRANSPORT` defaults to `stdio`, `MCP_HOST` to `127.0.0.1`, `MCP_PORT` to `3000`, and `MCP_TOOL_PROFILE` to `search`. The browser executable is resolved from `PUPPETEER_EXECUTABLE_PATH`, `CHROME_PATH` or `BROWSER_EXECUTABLE_PATH`, in that order, and all three are empty in the example, so a browser-based tool will fail until you point one of them at a real binary.

For an HTTP deployment, the example file also carries rate limiting defaults (`MCP_RATE_LIMIT_ENABLED=true`, `MCP_RATE_LIMIT_WINDOW_MS=60000`, `MCP_RATE_LIMIT_MAX=60`) and a body size ceiling of `MCP_MAX_BODY_BYTES=10485760`. Those are on by default, which is a sensible posture for a server that can drive a browser.

Once running, the first real use is to ask the server what it has rather than guessing. An MCP client calls `search_tools` with a query, then `describe_tool` on the result, then `call_tool` with the arguments the description specifies. The README gives no worked example of a full search-to-call sequence, so the exact argument shapes have to come from the tool reference in the docs site.

## Where jshookmcp is the wrong tool

The licence is the first hard boundary. `package.json` declares `AGPL-3.0-only`, and the README badge says AGPLv3. If you plan to embed this server in a product you distribute, or to expose a modified version as a network service, the AGPL's source-availability terms apply to your version. That rules it out for a lot of commercial integration work, and no configuration flag changes it.

The second boundary is the dependency on a live browser target. The anti-detection presets, the CAPTCHA solver, the CDP attach path and the network interception all assume a Chromium or Camoufox instance you control. If your analysis target is a Node.js process, a mobile binary or a desktop application, most of the browser-facing domains are dead weight. The process and memory forensics domains, the Frida, Ghidra and IDA bridges and the WASM disassembly are the parts that still apply, and they are a minority of the surface.

The third is operational. The README does not document rollback, and there are no retrieved releases, so there is no versioned upgrade path described in the repository. The `.env.example` exposes roughly two dozen tuning keys for HTTP timeouts, in-flight limits and browser session queues. Those exist because the server can be saturated; `MCP_HTTP_MAX_INFLIGHT=64` and `MCP_BROWSER_SESSION_QUEUE_MAX_PENDING=256` are not decorative. A single agent doing exploratory work will not hit them. A shared instance with several clients will.

Finally, the CAPTCHA solver is documented as taking explicit input, with no built-in page or feature probing. That is a deliberate design choice and it means the tool does not identify or solve a challenge on its own.

## How it differs from browser-automation MCP servers

The obvious comparison is an MCP server that wraps a single browser engine and exposes a handful of navigation and screenshot tools. Playwright's MCP server and the various Puppeteer wrappers sit in that category. The difference is scope and indirection. Those servers give an agent a small, flat tool list where every tool maps to one browser action, and the agent calls it directly. jshook gives a much larger list behind a search layer, and the tools are not all browser actions: WASM disassembly through Binaryen, hardware breakpoints, PE introspection, BoringSSL inspection and Mojo IPC analysis have no equivalent in a browser-automation server.

A closer comparison is a scripted toolkit like Frida on its own. Frida is a library and CLI you drive with your own scripts; jshook wraps a Frida bridge as one domain among 34 and lets an MCP client reach it through the same interface as the browser tools. The trade-off is real in both directions. Frida gives you full control over the instrumentation script and no token budget to manage. jshook gives you a uniform interface and a search layer, at the cost of an extra indirection and a much larger dependency surface.

If your task is scraping a page or filling a form, a browser-automation MCP server is the smaller, more predictable choice. jshook's value shows up when the task crosses boundaries: hook a function in the page, capture the request it produces, then disassemble the WASM module that verifies the response.

## Maintenance, upgrades and the AGPL question

The repository is not archived, and the last push was on 2026-09-10, eight days before this writing. That is recent enough to treat the project as under current development, and the presence of `renovate.json`, `lefthook.yml` and a pnpm workspace suggests dependency and hook automation is in place.

Upgrade cost is the open question. There are no retrieved releases, so there is no changelog to read and no semantic versioning history to lean on beyond the `0.3.5` in `package.json`. The README does not document rollback. If you pin to a commit and the tool profiles change shape between commits, the agent prompts that reference specific tool names will break. That is an argument for pinning a commit hash rather than tracking `master`.

On the licence, the practical implication is that AGPL-3.0-only is a copyleft licence with a network clause. Running the server locally for your own analysis is unambiguously fine. Distributing a modified server, or offering it to users over a network, triggers source-availability obligations. Because the plugin API and fleet API are exported entrypoints, a plugin you write is arguably a derivative work, and the repository does not address that question. This is not legal advice; if you are building anything commercial on jshook, have someone read the licence against your distribution model before you write code.

## Conclusion

Adopt it if you already run an MCP client and your work is browser-side JavaScript analysis: the search profile keeps the schema cost low enough to be practical. Do not adopt it if you need a published npm package today, a permissive licence, or a tool that works without a Chromium or Camoufox target. Before committing, verify the dist/index.mjs entrypoint exists after pnpm run build, check whether @jshookmcp/jshook resolves on the npm registry, and read the AGPL-3.0-only terms against how you plan to distribute anything built on top of it.

## FAQ

### How do I install @jshookmcp/jshook?

There is no published npm package yet; the README says the npm badge will be re-added once @jshookmcp/jshook is published. Build it from source with pnpm install and pnpm run build in the repository root, which produces dist/index.mjs. The getting-started page linked from the README is the documented install path.

### What is the difference between the search and full tool profiles in jshookmcp?

The search profile loads about 3K tokens of tool metadata and uses BM25 plus hybrid vector ranking to surface tools on demand. The full profile exposes all 723 tools at around 40K tokens. Agents are meant to move from search to workflow to full as a task grows.

### Why does @jshookmcp/jshook need a browser executable path?

The browser automation domains attach to Chromium or Camoufox over CDP, so the runtime resolves a binary from PUPPETEER_EXECUTABLE_PATH, CHROME_PATH or BROWSER_EXECUTABLE_PATH in that order. All three are empty in .env.example, so browser-based tools fail until you set one to a real binary.

## Sources

- [Issues](https://github.com/vmoranv/jshookmcp/issues)
- [License: AGPL-3.0](https://github.com/vmoranv/jshookmcp/blob/master/LICENSE)
- [Project website](https://vmoranv.github.io/jshookmcp/)
- [README](https://github.com/vmoranv/jshookmcp/blob/master/README.md)
- [vmoranv/jshookmcp on GitHub](https://github.com/vmoranv/jshookmcp)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vmoranv-jshookmcp