Content
# Tool List
Repository: `zhizhuodemao/js-reverse-mcp`
This is a practical documentation for actual use, focusing on:
- Overview of all tool methods
- Parameters for each method
- Meaning and precautions for each parameter
- Typical usage sequence for reverse analysis
- Special considerations for this project compared to regular browser MCP
## 1. Project Positioning
`js-reverse-mcp` is an MCP Server biased towards **JavaScript reverse analysis** scenarios, not just a regular browser automation tool.
Its core capabilities are mainly concentrated in:
- Page and frame switching
- Script enumeration and source code extraction
- Script content search
- Text breakpoints and XHR breakpoints
- Viewing call stacks and scope variables when paused
- Single-step debugging
- Function tracing
- Request initiator backtracking
- WebSocket message analysis
- Page injection and pre-hook
- Console logs and script execution
This repository is more suitable for tasks such as:
- Finding a signature function or encryption function in which script
- Setting breakpoints on a piece of code to observe parameters and return values
- Tracing which API request is initiated by
- Observing WebSocket send and receive content and grouping patterns
- Hooking key objects before page loading
## 2. Overview of All Methods
There are 23 tool methods in total:
### Page and Navigation
1. `select_page`
2. `new_page`
3. `navigate_page`
4. `select_frame`
5. `take_screenshot`
### Script Analysis
6. `list_scripts`
7. `get_script_source`
8. `save_script_source`
9. `search_in_sources`
### Breakpoints and Execution Control
10. `set_breakpoint_on_text`
11. `break_on_xhr`
12. `remove_breakpoint`
13. `list_breakpoints`
14. `get_paused_info`
15. `pause_or_resume`
16. `step`
### Tracing and Injection
17. `trace_function`
18. `inject_before_load`
### Network and WebSocket
19. `list_network_requests`
20. `get_request_initiator`
21. `get_websocket_messages`
### Script Execution and Console
22. `evaluate_script`
23. `list_console_messages`
## 3. Method-by-Method Organization
## 3.1 `select_page`
### Function
- List all pages of the current browser
- Or switch the active page context of the current MCP
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `pageIdx` | `number` | No | Page index. Omitting it lists pages; passing it switches to the corresponding page |
### Description
- Many tools depend on the "currently selected page"
- If no page is selected, debugging tools may report errors
## 3.2 `new_page`
### Function
- Create a new page and navigate to the specified URL
- Wait for `DOMContentLoaded`
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `url` | `string` | Yes | URL to open |
| `timeout` | `number` | No | Timeout in milliseconds. Default is around 10000; passing `0` or less than `0` usually falls back to the default value |
### Description
- Suitable for establishing an analysis environment from scratch
- Does not wait for all resources on the entire page to load, but returns when the DOM is available
## 3.3 `navigate_page`
### Function
Perform navigation actions on the current page:
- Jump to URL
- Go back
- Go forward
- Refresh
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `type` | `'url' \| 'back' \| 'forward' \| 'reload'` | No | Navigation type |
| `url` | `string` | No | Used when `type='url'` |
| `ignoreCache` | `boolean` | No | Whether to ignore cache when refreshing |
| `timeout` | `number` | No | Timeout in milliseconds |
### Description
- After page navigation, the old `scriptId` often becomes invalid
- Script URL is more stable than `scriptId`, and subsequent analysis prioritizes URL
- Some breakpoints attempt to retain or restore
## 3.4 `select_frame`
### Function
- List frames/iframes of the current page
- Switch the current execution context to a frame
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `frameIdx` | `number` | No | Frame index, `0` is usually the main frame |
### Description
- If the target logic is in an iframe, you must switch to the corresponding frame first
- Affects the execution context of tools like `evaluate_script`
## 3.5 `take_screenshot`
### Function
- Take a screenshot of the current page
- Can return results or save as a file
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `format` | `'png' \| 'jpeg'` | No | Screenshot format, default is usually `png` |
| `quality` | `number` | No | JPEG quality, `0-100`, usually invalid for PNG |
| `fullPage` | `boolean` | No | Whether to capture the entire page |
| `filePath` | `string` | No | Save path |
### Description
- Useful for debugging page state and verifying if hook is effective
- If `filePath` is not passed, the tool usually returns the result directly
## 3.6 `list_scripts`
### Function
List loaded scripts of the current page.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `filter` | `string` | No | Fuzzy filter by script URL |
### Returned Content Usually Includes
- `scriptId`
- `url`
- Source map related information
### Description
- This is one of the entry tools for script analysis
- If part of the script URL is known, filtering first is more efficient
## 3.7 `get_script_source`
### Function
Read script source code snippets.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `url` | `string` | No | Script URL, recommended to use first |
| `scriptId` | `string` | No | Script ID from `list_scripts` |
| `startLine` | `number` | No | Starting line number, usually 1-based |
| `endLine` | `number` | No | Ending line number, usually 1-based |
| `offset` | `number` | No | Character offset, usually 0-based |
| `length` | `number` | No | Number of characters to take from `offset` |
### Description
- **Must** pass either "line range" or "offset range", not suitable for directly reading large scripts
- `startLine/endLine` suitable for normal multi-line source code
- `offset/length` more suitable for single-line compressed code
- Page navigation may invalidate `scriptId`, so prioritize using `url`
## 3.8 `save_script_source`
### Function
Save complete script source code to a local file.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `url` | `string` | No | Script URL, recommended |
| `scriptId` | `string` | No | Script ID |
| `filePath` | `string` | Yes | Path to save locally |
### Description
- Suitable for offline analysis of large scripts
- Useful for compressed JS and large bundles
- Similarly, prioritize using `url` for better stability
## 3.9 `search_in_sources`
### Function
Search for strings or regular expressions in all loaded scripts.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `query` | `string` | Yes | Search keyword or regular expression |
| `caseSensitive` | `boolean` | No | Whether to distinguish case, default is usually `false` |
| `isRegex` | `boolean` | No | Whether to treat `query` as a regular expression |
| `maxResults` | `number` | No | Maximum number of results to return, default is usually around `30` |
| `maxLineLength` | `number` | No | Maximum line length for single match result display |
| `excludeMinified` | `boolean` | No | Whether to exclude compressed scripts, default is usually `true` |
| `urlFilter` | `string` | No | Search scripts with matching URL only |
### Description
- Suitable for searching: function names, key field names, API paths, encryption fields, key strings
- After searching, use `get_script_source` to view context
- If suspecting key logic in compressed code, can set `excludeMinified` to `false`
## 3.10 `set_breakpoint_on_text`
### Function
Automatically set breakpoints based on code text search results.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `text` | `string` | Yes | Code text to locate and set breakpoint |
| `urlFilter` | `string` | No | Search in scripts with specified URL only |
| `occurrence` | `number` | No | Which occurrence, default is usually `1` |
| `condition` | `string` | No | Conditional breakpoint expression |
### Description
- Very suitable for compressed code scenarios
- Does not require knowing exact line numbers, as long as text can be located
- Can be used for signature functions, key field assignment points, request parameter concatenation points, etc.
## 3.11 `break_on_xhr`
### Function
Set breakpoints on XHR/Fetch requests by URL pattern.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `url` | `string` | Yes | Matching string for request URL |
### Description
- Suitable for "first locking interface, then deducing who is calling"
- When a request hits, it pauses, and you can use `get_paused_info` to view the call stack
## 3.12 `remove_breakpoint`
### Function
Remove breakpoints.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `breakpointId` | `string` | No | Code breakpoint ID |
| `url` | `string` | No | URL pattern corresponding to XHR breakpoint |
### Description
- Passing `breakpointId`: delete specified code breakpoint
- Passing `url`: delete specified XHR breakpoint
- Passing neither: usually means deleting all breakpoints
- If currently paused, the tool may automatically resume execution
## 3.13 `list_breakpoints`
### Function
List all active breakpoints.
### Parameters
None.
### Description
- Used to confirm if breakpoints are set
- Certain breakpoints may be restored after reload or navigation
## 3.14 `get_paused_info`
### Function
Get paused context after breakpoint hit.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `includeScopes` | `boolean` | No | Whether to include scope variables, default is usually `true` |
| `maxScopeDepth` | `number` | No | Scope expansion depth |
| `frameIndex` | `number` | No | Choose which call stack frame |
### Returned Information Usually Includes
- Hit breakpoint information
- Current execution position
- Call stack
- Scope variables
### Description
- This is one of the most critical tools for breakpoint analysis
- `frameIndex=0` is usually the current execution frame
- If you want to view closure variables or outer scope, can increase `maxScopeDepth`
## 3.15 `pause_or_resume`
### Function
Switch execution state:
- When running, initiate pause
- When paused, resume execution
### Parameters
None.
### Description
- Simple and crude way to interrupt current JS execution
- But on complex pages, may not always stop at the most valuable position
## 3.16 `step`
### Function
Single-step execution.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `direction` | `'over' \| 'into' \| 'out'` | Yes | Single-step direction |
### Direction Meaning
- `over`: Step over
- `into`: Step into
- `out`: Step out
### Description
- Only available when currently paused
- Cooperate with `get_paused_info` to form a complete debugging loop
## 3.17 `trace_function`
### Function
Trace a specified function, usually by logpoint or conditional breakpoint to record call situations.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `functionName` | `string` | Yes | Function name to trace |
| `urlFilter` | `string` | No | Search within specified script URL range only |
| `logArgs` | `boolean` | No | Whether to record function arguments, default is usually `true` |
| `logThis` | `boolean` | No | Whether to record `this` |
| `pause` | `boolean` | No | Whether to pause on hit, default is usually `false` |
| `traceId` | `string` | No | Custom trace identifier for easy distinction |
### Description
- Very suitable for scenarios where "I know the function name but don't want to stop every time"
- Defaults to recording logs, not necessarily triggering real pause
- Tracing results are usually written to the console, and you need to cooperate with `list_console_messages` to view logs
## 3.18 `inject_before_load`
### Function
Inject JS before page script runs.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `script` | `string` | No | Script to inject |
| `identifier` | `string` | No | Identifier for injected script, also used to delete injected content |
### Description
- At least one of `script` and `identifier` should be provided
- After successful injection, usually returns an identifier
- Can remove injection through identifier later
- Very suitable for:
- Pre-emptive hook global variables
- Hook setter/getter
- Hook signature object initialization
- Hook a critical function hung on `window`
## 3.19 `list_network_requests`
### Function
List network requests or view details of a single request.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `reqid` | `number` | No | Specify request ID to view details |
| `pageSize` | `number` | No | Number of items per page |
| `pageIdx` | `number` | No | Page index, usually 0-based |
| `resourceTypes` | `string[]` | No | Filter by resource type |
| `urlFilter` | `string` | No | Filter by URL substring |
| `includePreservedRequests` | `boolean` | No | Whether to include requests preserved from last few navigations |
### Common `resourceTypes`
- `document`
- `stylesheet`
- `image`
- `media`
- `font`
- `script`
- `xhr`
- `fetch`
- `websocket`
- `manifest`
- `preflight`
- `other`
### Description
- Suitable for first filtering interface requests, then analyzing call chain
- `reqid` often used with `get_request_initiator`
## 3.20 `get_request_initiator`
### Function
Backtrack which one initiated a request based on request ID.
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `requestId` | `number` | Yes | Request ID from `list_network_requests` |
### Returned Information Usually Includes
- Initiator type
- Script URL that triggered the request
- Line number, column number
- Call stack
- Async parent stack in certain cases
### Description
- Very suitable for locating:
- Which function actually initiated the API request
- Which logic started assembling parameters
- Which script triggered the target request
## 3.21 `get_websocket_messages`
### Function
- List WebSocket connections
- View messages of a specified connection
- Analyze message patterns and group
- View details of a frame
### Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `wsid` | `number` | No | WebSocket connection ID; omitting it usually lists all connections |
| `analyze` | `boolean` | No | Whether to analyze message patterns and group automatically |
| `frameIndex` | `number` | No | View details of a frame, usually 0-based |
| `direction` | `'sent' \| 'received'` | No | View sent or received direction only |
| `groupId` | `string` | No | View a group of messages only |
| `pageSize` | `number` | No | Page size |
| `pageIdx` | `number` | No | Page index |
| `show_content` | `boolean` | No | Whether to show complete message content |
| `urlFilter` | `string` | No | Filter connections by URL when listing only |
| `includePreservedConnections` | `boolean` | No | Whether to include connections preserved from last few navigations |
### Description
- If just finding connections, omit `wsid`
- If analyzing protocol patterns, can set `analyze=true` first
- If messages are many and contain binary frames, suggest not opening `show_content` initially
## 3.22 `evaluate_script`
### Function
Execute a JS function on the current page and return a JSON-serializable result.
## 3.23 `list_console_messages`
### Function
List console messages.
### Input Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `function` | `string` | Yes | The JS function string to be executed |
| `mainWorld` | `boolean` | No | Whether to execute in the main world of the page |
| `frameIndex` | `number` | No | The call frame index when paused |
### Description
- Examples:
- `() => document.title`
- `() => window.someVar`
- `async () => { ... }`
- Default execution in an isolated world
- If you need to access global variables defined by the page, such as `window.xxx`, often requires `mainWorld=true`
- When the page is paused at a breakpoint, this tool can directly evaluate in the current call frame, very suitable for looking at local variables or temporarily executing expressions
---
## 3.23 `list_console_messages`
### Function
List page console messages or view detailed messages.
### Input Parameters
| Parameter Name | Type | Required | Description |
|---|---|---:|---|
| `msgid` | `number` | No | View detailed message by ID |
| `pageSize` | `number` | No | Number of messages per page |
| `pageIdx` | `number` | No | Page index |
| `types` | `string[]` | No | Filter by message type |
| `includePreservedMessages` | `boolean` | No | Whether to include preserved messages |
### Common `types`
- `log`
- `debug`
- `info`
- `error`
- `warn`
- `trace`
- `table`
- `assert`
- `verbose`
- `issue`
### Description
- `trace_function` logs usually appear here
- Often used to verify if injected scripts or hooked code is effective
---
## 4. Important Considerations
## 4.1 `scriptId` is not stable, prioritize `url`
This is a crucial point in this project.
- After page refresh, jump, or forward/backward
- Previously obtained `scriptId` may become invalid
So, in these tools, prioritize using script `url`:
- `get_script_source`
- `save_script_source`
- Other analysis processes related to script location
---
## 4.2 Debugging tools usually require a current page
Tools like these typically require:
- A page has been selected
- Debugger is available in some cases
Typical examples include:
- `list_scripts`
- `set_breakpoint_on_text`
- `get_paused_info`
- `step`
- `trace_function`
- `evaluate_script`
So, the recommended order is usually:
1. `new_page` or `select_page`
2. Then perform script analysis or breakpoint debugging
---
## 4.3 For minified code, prioritize "text location" over "line number location"
For modern sites, many core logics are in minified bundles.
In this case, it's more recommended to use:
- `search_in_sources`
- `set_breakpoint_on_text`
- `get_script_source(offset/length)`
Rather than relying on "line number and column" location like ordinary source code.
---
## 4.4 `trace_function` is more like "lightweight tracing", not always forced to pause
The value of `trace_function` lies in:
- Observing who calls the target function
- Seeing the input parameters
- Not necessarily interrupting the page execution flow
If you want to pause and deeply inspect the context, use:
- `set_breakpoint_on_text`
- Or configure `pause=true` for tracing
---
## 4.5 `inject_before_load` is suitable for hooking before page initialization
Many critical objects are initialized only once in the early stage of the page.
For example:
- The signature function is hung on `window` when the page starts
- Some getters/setters are triggered only during initialization
- Some encryption objects are generated and immediately referenced by closures
In this case, ordinary "evaluate after page load" is too late.
Prioritize:
- `inject_before_load`
- Then `navigate_page reload`
---
## 4.6 `evaluate_script`'s `mainWorld` is crucial
The default execution environment is more inclined to isolate contexts.
If you find:
- `document` is accessible
- But `window.xxx` is not accessible
- Or page-defined global objects are not accessible
Consider:
- `mainWorld=true`
But also note:
- The return value must be JSON serializable
- In certain modes, it's more suitable for synchronous functions to return simple objects
---
## 4.7 This repository is not suitable for direct use on sensitive account pages
Because it essentially exposes browser content to MCP client analysis.
So:
- Do not directly use it on high-sensitivity account pages for an extended period
- Do not arbitrarily perform capturing and injection on pages containing real privacy data
- It's best to clarify the boundary between test and formal environments before use
---
## 5. Recommended Reverse Analysis Process
Here's a practical process.
### Scenario 1: Find a signature function
1. `new_page`
2. `list_scripts`
3. `search_in_sources(query='sign' or key fields)`
4. `get_script_source`
5. `trace_function` or `set_breakpoint_on_text`
6. `list_console_messages` / `get_paused_info`
---
### Scenario 2: Know an interface and want to find who initiated it
1. `new_page`
2. `list_network_requests(resourceTypes=['xhr','fetch'])`
3. Find the target request's `reqid`
4. `get_request_initiator(requestId=...)`
5. Then `get_script_source` / `set_breakpoint_on_text`
---
### Scenario 3: Want to see how parameters are constructed before interface sending
1. `break_on_xhr(url='target interface keyword')`
2. Trigger page operation
3. Hit and then `get_paused_info`
4. `step(direction='into')` or `step(direction='over')`
5. Cooperate with `evaluate_script` to see local variables
---
### Scenario 4: Target function initializes too early, cannot be captured by ordinary means
1. `inject_before_load(script='hook code')`
2. `navigate_page(type='reload')`
3. `list_console_messages`
4. Cooperate with `trace_function` / `set_breakpoint_on_text` if necessary
---
### Scenario 5: WebSocket Protocol Analysis
1. `new_page`
2. `get_websocket_messages()` to list connections
3. Select `wsid`
4. `get_websocket_messages(wsid=..., analyze=true)`
5. Specify `groupId`, `direction`, `frameIndex` if needed
---
## 6. Method Quick Reference Table
| Method Name | Core Purpose | Common Parameters |
|---|---|---|
| `select_page` | Switch page | `pageIdx` |
| `new_page` | Open a new page and navigate | `url`, `timeout` |
| `navigate_page` | Navigate/refresh/go back | `type`, `url`, `ignoreCache`, `timeout` |
| `select_frame` | Switch iframe | `frameIdx` |
| `take_screenshot` | Take a screenshot | `format`, `fullPage`, `filePath` |
| `list_scripts` | List scripts | `filter` |
| `get_script_source` | Get source code fragment | `url`, `scriptId`, `startLine/endLine`, `offset/length` |
| `save_script_source` | Save complete source code | `url`, `scriptId`, `filePath` |
| `search_in_sources` | Search in scripts | `query`, `isRegex`, `urlFilter` |
| `set_breakpoint_on_text` | Text breakpoint | `text`, `urlFilter`, `occurrence`, `condition` |
| `break_on_xhr` | Request breakpoint | `url` |
| `remove_breakpoint` | Remove breakpoint | `breakpointId`, `url` |
| `list_breakpoints` | List current breakpoints | None |
| `get_paused_info` | Get paused context | `includeScopes`, `maxScopeDepth`, `frameIndex` |
| `pause_or_resume` | Pause/resume | None |
| `step` | Step execution | `direction` |
| `trace_function` | Function tracing | `functionName`, `urlFilter`, `logArgs`, `pause` |
| `inject_before_load` | Inject before load | `script`, `identifier` |
| `list_network_requests` | Request list | `reqid`, `resourceTypes`, `urlFilter` |
| `get_request_initiator` | Request call chain backtrace | `requestId` |
| `get_websocket_messages` | WebSocket analysis | `wsid`, `analyze`, `direction`, `groupId` |
| `evaluate_script` | Execute JS | `function`, `mainWorld`, `frameIndex` |
| `list_console_messages` | View console | `msgid`, `types`, `pageSize` |
---
## 7. Final Summary
If you only remember the core ideas of this project, keep these points:
1. It's not ordinary browser automation MCP, but more inclined to **JS reverse debugging tools**.
2. The commonly used core process is usually:
`list_scripts -> search_in_sources -> get_script_source -> set_breakpoint_on_text / trace_function -> get_paused_info / evaluate_script`
3. After page navigation, **prioritize script URL, don't overly rely on scriptId**.
4. For minified code, prioritize "text search + text breakpoint + offset/length to get source code".
5. For logics initialized very early, prioritize `inject_before_load`.
6. For request analysis, the key combination is:
`list_network_requests + get_request_initiator + break_on_xhr`
7. For WebSocket analysis, the key combination is:
`get_websocket_messages(wsid, analyze, groupId, frameIndex)`
