jsreverser-mcp

JS Reverse MCP provides a comprehensive suite of tools for JavaScript reverse engineering, categorized by the reverse engineering lifecycle:

1. Page Observation & Script Locating

Establish the scope of scripts and find target code.

• list_scripts: List all loaded scripts on the current page.
• get_script_source: View the source code of a specific script.
• find_in_script: Locate strings, variable names, or patterns within a single script.
• search_in_scripts: Batch search across cached scripts to narrow down candidates.

2. Hooking & Runtime Sampling

Perform non-intrusive observation of runtime behavior.

• create_hook: Define reusable hooks for later injection.
• inject_hook: Inject existing hooks into the current page.
• get_hook_data: Retrieve hook call records and summaries.
• hook_function: Directly hook global functions or object methods to record arguments and return values.
• trace_function: Trace function calls by source name to follow call chains.

3. Breakpoints & Debugging Control

Use pause-based debugging when hooks are insufficient.

• set_breakpoint: Set a breakpoint by script URL and line number.
• set_breakpoint_on_text: Automatically locate and set a breakpoint based on code text.
• resume: Continue execution to the next breakpoint or end.
• pause: Manually pause JavaScript execution.
• step_over / step_into / step_out: Single-step execution control.

4. Network Analysis

Identify requests and their origins.

• list_network_requests: List all current network requests.
• get_network_request: View detailed request info (headers, response, payload).
• get_request_initiator: Trace which entity triggered a specific request.
• break_on_xhr: Interrupt execution when a target XHR request is sent.

5. Page State & Environment Checks

Verify browser health and local dependencies.

• check_browser_health: Verify browser connection and page controllability.
• diagnose_environment: Output Node, browser, path, and dependency status.
• recommend_next_step: Get suggested actions based on current evidence.
• explain_reverse_stage: Explain the current stage, requirements, and exit conditions.
• list_console_messages: View console output (useful for hook/trace logs).
• get_storage: Read cookies, localStorage, and sessionStorage.
• evaluate_script: Execute code within the selected frame for runtime validation.
• search_in_sources: Search all loaded source code for keywords.

6. WebSocket Observation

Handle long connections and binary frames.

• list_websocket_connections: List active WebSocket connections (returns wsid).
• analyze_websocket_messages: Group messages by frame characteristics.
• get_websocket_messages: View message summaries or content for a connection/group.

7. Local Rebuild & Environment Patching

Bring page evidence to a local environment.

• export_rebuild_bundle: Export entry points, environment patches, and evidence for local reproduction.
• diff_env_requirements: Compare current environment capabilities against missing requirements based on errors.
• record_reverse_evidence: Save key observations to a task artifact.

8. Page Automation

Automate interactions to reproduce conditions.

• navigate_page: Navigate, go back, or refresh.
• query_dom: Query elements via selectors.
• click_element: Trigger clicks.
• hover_element / select_option: Handle menus and dropdowns.
• type_text: Input text into fields.
• press_key / upload_file: Handle keyboard and file uploads.
• scroll_page / wait_for_network_idle: Handle lazy loading and request completion.
• set_viewport / emulate_device: Emulate mobile or specific viewports.
• get_all_links: List all links on the page.
• take_screenshot: Capture the current page state.

9. Deep Analysis

Understand code structure and deobfuscate.

• collect_code: Collect page code with controlled sampling.
• understand_code: Use static analysis and AI to understand business logic and structure.
• deobfuscate_code: Clean and restore obfuscated code.
• risk_panel: Aggregate code analysis, crypto detection, and hook signals.

10. Session Management

• save_session_state: Snapshot cookies and storage to memory.
• restore_session_state: Restore a session snapshot to the current page.
• dump_session_state: Export session snapshot to JSON.
• load_session_state: Load session from JSON or string.

11. Task Orchestration & Agent Consumption

• start_reverse_task / create_reverse_task_from_request: Create task artifacts.
• manage_reverse_task: Entry point for get, summarize, archive, restore, search, tag, prune, and compare.
• orchestrate_reverse_task: Advance through stages (observation, sampling, reconstruction, etc.).
• run_reverse_agent: One-stop entry point for agent-driven tasks.
• query_reverse_task: Read task summaries, suggestions, and artifacts.
• get_rebuild_health_report: Summarize local rebuild health.

The JS Reverse Workflow is a structured model execution protocol designed to transform frontend reverse engineering tasks into stable, repeatable stages. This prevents skipping steps or attempting algorithm extraction before environment replication is stable.

The six stages are:

1. Observe: Identify target requests, scripts, and trigger conditions.
2. Capture: Use hooks to collect runtime samples, parameters, and call sequences.
3. Rebuild: Export page evidence into a local Node.js reproduction project.
4. Patch: Drive environment patching using proxy logs and first divergence analysis until the local link matches browser truth.
5. PureExtraction: Separate 'environment noise' from 'algorithm input' to create a pure Node.js implementation.
6. Port: Migrate the pure implementation to Python or other target hosts.

Core Principles:

• Observe-first, Hook-preferred, Breakpoint-last.
• Rebuild-oriented, Evidence-first, Browser-truth-first.
• Pure-extraction-after-pass (only extract algorithms after the environment rebuild passes).

When calling tools like manage_reverse_task, orchestrate_reverse_task, run_reverse_agent, or get_rebuild_health_report, parse the response in this specific order to determine the next action:

1. responseSummary: Get the high-level overview.
2. outcome / status: Check the current state of the task.
3. errorType / retryable / blockedBy: Identify if the task failed, if it can be retried, or what is blocking progress.
4. routeGuard: Check for routing constraints.
5. continuation.invoke: If continuation.ready=true, this is your primary next step.

Decision Logic:

• If blocked: Resolve the issue identified in blockedBy before proceeding.
• If partial and retryable=true: You can attempt to resume/run again.
• If shouldSwitchStrategy=true: Prioritize switching the execution strategy.
• If compactDelivery is ready: Prompt the user to export or use the portable product.

A complete site mapping document must include the following seven sections to ensure site-specific nuances are captured:

1. Site Information: Identifies the site name, parameter name, entry functions/classes, script URL patterns, and entry URLs or API hosts (using Base64 encoding for URLs).
2. Request Mapping: Defines the target interface pattern (method, URL pattern, optional functionId/operation) and where parameters reside (query, body, or header).
3. Field Mapping: Lists required and optional fields, and identifies dependency seed types such as specific cookie keys, storage keys, or fingerprinting capabilities (e.g., canvas, webgl).
4. Site-Specific Risk Points: Notes regarding initialization timing (first screen vs. async vs. lazy loading), high-change points (version fields, dynamic algorithms, token issuance), and common misjudgments.
5. Verification Criteria (Site Version): Defines structural criteria (segment count, charset, length), behavioral criteria (status + business code), and tolerance for differences.
6. Regression Checklist: A list of checks to perform after script version changes, including output contract compliance, requiredInputs changes, proxy env log exception paths, and first divergence shifts.
7. Related Documentation: Links to the methodology template, safety policy, and tool I/O contracts.