Content
# JS Reverse MCP
An MCP Server for **JavaScript Reverse Engineering**.
Let AI clients like Claude/Codex/Cursor directly call browser debugging capabilities to complete script localization, breakpoint debugging, Hook sampling, network link analysis, deobfuscation, and risk assessment.
## What problem does this project solve?
In traditional reverse engineering workflows, you usually have to switch back and forth between DevTools, script files, and packet capture tools.
`js-reverse-mcp` unifies these capabilities into an MCP tool, allowing AI to execute a complete analysis chain step by step:
1. Open the page and collect scripts
2. Search for target functions/critical strings
3. Automatically inject Hook and sample requests
4. Analyze signature chains, encryption algorithms, and call stacks
5. Output executable next steps (instead of just concepts)
## Core Capabilities
- Script and Source Code Analysis: `list_scripts`, `get_script_source`, `find_in_script`, `search_in_scripts`
- Breakpoint and Execution Control: `set_breakpoint`, `set_breakpoint_on_text`, `resume`, `pause`, `step_over/into/out`
- Hook and Runtime Observation: `create_hook`, `inject_hook`, `get_hook_data`, `hook_function`, `trace_function`
- Network and Request Chain: `list_network_requests`, `get_network_request`, `get_request_initiator`, `break_on_xhr`
- Integrated Reverse Engineering Workflow: `analyze_target`, `collect_code`, `understand_code`, `deobfuscate_code`, `risk_panel`
- Page Automation and DOM: `navigate_page`, `query_dom`, `click_element`, `type_text`, `take_screenshot`
- Login State Management: `save_session_state`, `restore_session_state`, `list_session_states`, `dump_session_state`, `load_session_state`
- Anti-Detection Capabilities: `inject_stealth`, `list_stealth_presets`, `set_user_agent`
See `docs/tool-reference.md` for complete parameter descriptions.
## Quick Start (3 minutes)
### 1) Install dependencies and build
```bash
npm install
npm run build
```
After building, the entry file is: `build/src/index.js`
### 2) Start locally (optional)
```bash
npm run start
```
### 3) Configure MCP client
A typical MCP configuration is as follows:
```json
{
"mcpServers": {
"js-reverse": {
"command": "node",
"args": ["/ABSOLUTE/PATH/js-reverse-mcp-main/build/src/index.js"]
}
}
}
```
Please use **absolute paths** to avoid the client's working directory changing and not being able to find the entry file.
### 4) Connect to an "already open" Chrome (remote debugging)
If you already have a Chrome instance running on your machine and want MCP to directly take control of it, follow the steps below.
#### 4.1 Start Chrome and enable remote debugging
Windows:
```bash
"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\\tmp\\chrome-mcp"
```
macOS:
```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-mcp
```
Linux:
```bash
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-mcp
```
#### 4.2 Connect this browser in MCP (two ways)
Method A: Via `browserUrl` (simplest)
```json
{
"mcpServers": {
"js-reverse": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/js-reverse-mcp-main/build/src/index.js",
"--browserUrl",
"http://127.0.0.1:9222"
]
}
}
}
```
Method B: Via `wsEndpoint` (more precise)
1. First, get the WS address:
```bash
curl http://127.0.0.1:9222/json/version
```
2. Read the `webSocketDebuggerUrl` from the response and put it into MCP:
```json
{
"mcpServers": {
"js-reverse": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/js-reverse-mcp-main/build/src/index.js",
"--wsEndpoint",
"ws://127.0.0.1:9222/devtools/browser/<id>"
]
}
}
}
```
Note:
- Choose either `--browserUrl` or `--wsEndpoint`, do not configure both at the same time.
- If the port is not `9222`, replace all example ports with your actual port.
- When a remote Chrome is already connected, do not force this service to start another browser instance on its own.
## Common Client Integrations
### Claude Code
```bash
claude mcp add js-reverse node /ABSOLUTE/PATH/js-reverse-mcp-main/build/src/index.js
```
### Cursor
`Settings -> MCP -> New MCP Server`, fill in:
- Command: `node`
- Args: `[/ABSOLUTE/PATH/js-reverse-mcp-main/build/src/index.js]`
### Codex / Generic MCP Client
Use the generic JSON above.
Client integration instructions are maintained uniformly in this README and are no longer split into `docs` separately.
## Environment Variable Configuration
Copy the example configuration:
```bash
cp .env.example .env
```
### AI Provider (Optional)
```bash
# openai | anthropic | gemini
DEFAULT_LLM_PROVIDER=gemini
# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
# Anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
# Gemini
GEMINI_API_KEY=...
GEMINI_CLI_PATH=gemini-cli
GEMINI_MODEL=gemini-2.0-flash-exp
```
Explanation:
- You can use non-AI tools (debugging/Hook/network/page control) without configuring AI.
- After configuring AI, you can use enhanced capabilities such as `understand_code`, `deobfuscate_code`, and `risk_panel`.
### Browser and Remote Debugging (Optional)
```bash
BROWSER_HEADLESS=true
BROWSER_ISOLATED=true
BROWSER_EXECUTABLE_PATH=/path/to/chrome
BROWSER_CHANNEL=chrome
USE_STEALTH_SCRIPTS=false
REMOTE_DEBUGGING_URL=http://localhost:9222
REMOTE_DEBUGGING_PORT=9222
```
### Debugging Logs (Optional)
```bash
DEBUG=mcp:*
```
## Recommended Reverse Engineering Workflow
### Workflow A: Quickly Locate Signature Logic
1. `new_page` Open the target site
2. `analyze_target` One-click execution of collection + analysis + association
3. View `priorityTargets` / `requestFingerprints`
4. Call `search_in_scripts` + `understand_code` on high-priority functions
5. Execute `deobfuscate_code` on suspicious code
### Workflow B: Dynamic Tracking of Request Parameters
1. `create_hook` + `inject_hook` (`fetch/xhr/websocket`)
2. Trigger key actions such as placing an order/logging in on the page
3. `get_hook_data` Pull records and compare parameter changes
4. If necessary, `break_on_xhr` + `get_request_initiator` to view the call stack
### Workflow C: Risk Assessment and Reporting
1. `collect_code` Collect high-priority scripts
2. `risk_panel` Summarize security risks and cryptographic risks
3. `export_session_report` Export analysis report (JSON/Markdown)
### Workflow D: Login State Reuse (Log in once, analyze multiple times)
1. After manually logging in to the target website, execute `save_session_state` (it is recommended to specify `sessionId`)
2. Use `dump_session_state` to export to a file (can be placed in your own secure directory)
3. Next session, first `load_session_state` (from file or JSON)
4. Execute `restore_session_state` to rehydrate cookies/storage
5. After confirming that the page is controllable with `check_browser_health`, continue with `analyze_target`
## Development and Testing
```bash
# Build
npm run build
# Unit tests
npm run test:unit
# Property tests
npm run test:property
# Coverage (current default scope: core jshook + services)
npm run coverqge
# Full coverage scope
npm run coverage:full
```
## Document Index
- Reverse Task Index (Tools by Target): `docs/reverse-task-index.md`
- Tool Parameter Summary: `docs/tool-reference.md`
- JSHook Usage Examples: `docs/jshook-examples.md`
- Common Problem Troubleshooting: `docs/jshook-troubleshooting.md`
- Gemini Provider Instructions: `docs/gemini-provider-implementation.md`
## Troubleshooting
- `Cannot find module ... build/src/index.js`
- First execute `npm run build`
- Confirm the file exists: `build/src/index.js`
- Node version incompatibility
- This project requires: `^20.19.0 || ^22.12.0 || >=23`
- Browser connection failed
- Check Chrome availability and `REMOTE_DEBUGGING_URL/PORT`
- AI call failed
- Check `DEFAULT_LLM_PROVIDER` and corresponding API Key/CLI path
## Reference Projects
- https://github.com/wuji66dde/jshook-skill
- https://github.com/zhizhuodemao/js-reverse-mcp
## License
Apache-2.0
