@yuanhuakk/js-reverse-mcp

v3.0.0

Published

a day ago

MCP server for JavaScript reverse engineering and debugging

Downloads

1,340

0High
0Medium
0Low

yuanhuakk

JS Reverse MCP

English README

一个把前端 JavaScript 逆向流程标准化的 MCP 服务。
目标不是只做页面调试，而是把页面观察、运行时采样、本地复现、补环境和证据沉淀串成一套可复用工作流。

项目来源与二次开发说明

本项目参考并基于 zhizhuodemao/js-reverse-mcp 的 MCP 前端逆向工具方向继续演进。当前仓库不是简单换名或少量修补版本，而是围绕工程化、可维护性和完整逆向工作流进行了深度二次开发。

主要二开范围包括：

工程栈升级到 Node.js（运行要求 >=22）、pnpm、TypeScript、Oxc lint / format 约束。
源码目录、模块命名、入口结构、构建脚本和发布流程重整。
浏览器控制层迁移到 Patchright 运行模型，并保留必要的 CDP 能力边界。
新增运行时采样、目标参数追踪、高级动态分析报告和目标参数明文证据输出。
强化 Hook、Network、WebSocket、Storage、Console、Session、Rebuild、Evidence 等逆向链路能力。
建立 docs/reference/*、skills/js-reverse-playbook/* 和 scripts/cases/* 的方法论、任务产物与案例分层。
补充测试、格式检查、源码结构检查、文档生成和发布前校验流程。

因此，更准确的定位是：这是一个基于原始方向进行深度二次开发、由当前仓库独立维护的 JS 逆向 MCP 服务。保留上游来源说明不影响当前仓库新增代码、架构改造和文档体系的独立贡献归属。

核心方法论

本项目默认遵循以下方法论：

Observe-first
Hook-preferred
Breakpoint-last
Rebuild-oriented
Evidence-first
Pure-extraction-after-pass

这意味着：

先在浏览器里确认请求、脚本、函数和依赖来源
再做最小化 Hook 采样
再导出 local rebuild
再在 Node 里逐项补环境
每一步都沉淀为 task artifact，而不是只留在对话里

已沉淀链路

以下参数链路已有公开索引，可作为仓库内复用入口：

某东 h5st 参数
- 索引：scripts/cases/README.md
- Case：scripts/cases/jd-h5st-pure-node.mjs
某手 falcon 风控参数
- 索引：scripts/cases/README.md
- Case：scripts/cases/ks-hxfalcon-pure-node.mjs
某音 a-bogus 参数
- 索引：scripts/cases/README.md
- Case：scripts/cases/douyin-a-bogus-pure-node.mjs

说明：

README 首页只展示脱敏后的参数类型和公开入口
真实 artifacts/tasks/<task-id>/ 默认视为本地私有任务目录
Git 默认只提交 artifacts/tasks/_TEMPLATE/

支持的能力

页面观察与脚本定位

先回答“页面里有哪些脚本、目标代码大概在哪”。

list_scripts：列出当前页面已加载的脚本，先建立脚本范围。
get_script_source：查看指定脚本源码，适合继续阅读具体实现。
find_in_script：在单个脚本里定位字符串、变量名或特征片段。
search_in_scripts：在已采集脚本缓存中批量搜索，适合缩小候选脚本范围。

Hook 与运行时采样

先做最小侵入式观测，确认运行时到底调用了什么。

create_hook：创建可复用的 hook 定义，用于后续注入页面。
inject_hook：把已有 hook 注入当前页面，开始采样目标行为。
get_hook_data：读取 hook 采集到的调用记录和摘要结果。
hook_function：直接 hook 全局函数或对象方法，记录参数和返回值。
trace_function：按源码函数名做调用追踪，适合跟调用链。

断点与调试控制

当 hook 不够时，再进入暂停式调试。

set_breakpoint：按脚本 URL 和行号设置断点。
set_breakpoint_on_text：按代码文本自动定位并设置断点。
resume：继续执行到下一个断点或执行结束。
pause：手动暂停当前页面的 JavaScript 执行。
step_over / step_into / step_out：单步控制执行路径，分别对应跳过、进入、跳出函数。

请求链路与网络分析

定位目标请求，确认是谁发起、带了什么参数。

list_network_requests：列出当前页面的网络请求，先找到目标请求。
get_network_request：查看单个请求的详细内容，包括请求头、响应和载荷。
get_request_initiator：追溯某个请求是谁触发的，帮助定位调用链。
break_on_xhr：在目标请求发出时中断，适合抓参数生成前的现场。

页面状态与运行前检查

补看页面运行状态、控制台输出和本地状态依赖。

check_browser_health：检查浏览器连接和当前页是否可控，适合作为起手验证。
list_console_messages：查看当前页面 console 输出，适合回看 hook 和 trace 日志。
get_storage：读取 cookie、localStorage、sessionStorage，确认状态依赖。
evaluate_script：在当前选中 frame 内执行一段函数，做小范围运行时验证。
search_in_sources：在所有已加载源码中搜索关键字，快速缩小可疑代码范围。

WebSocket 观察与消息分组

处理长连接、直播流或二进制帧时，用这组工具先分流再细看。

list_websocket_connections：列出当前页面的 WebSocket 连接，先拿到目标 wsid。
analyze_websocket_messages：按帧特征做消息分组，适合先识别不同消息类型。
get_websocket_messages：查看某个连接或某个分组下的消息摘要和内容。

本地复现与补环境

把页面证据带回本地，逐步补齐 Node 运行环境。

export_rebuild_bundle：导出本地复现工程所需的入口、补环境和证据材料。
diff_env_requirements：根据报错和观测能力比对当前缺失的环境能力。
record_reverse_evidence：把关键观察结果写入 task artifact，避免证据只留在对话里。

页面自动化

做最小必要的页面操作，复现触发条件并辅助取证。

navigate_page：跳转、回退、刷新当前页面。
query_dom：查询页面元素，确认选择器和节点状态。
click_element：按选择器触发点击，复现页面动作。
type_text：向输入框写入文本，驱动表单交互。
take_screenshot：截取页面当前状态，保留可视化证据。

深度分析

在拿到代码和运行时证据后，继续做结构理解与去混淆。

collect_code：采集页面代码，支持按优先级或范围控制采样量；传入 enableRuntimeSampler、enableAdvancedDynamicAnalysis、targetParams 后可生成动态分析证据。
understand_code：结合静态分析和 AI 做代码结构、业务逻辑与风险理解。
deobfuscate_code：对混淆代码做清理、还原和辅助分析。
risk_panel：聚合代码分析、加密检测和 hook 信号，输出综合风险视图。

会话与登录态复用

save_session_state：保存当前页面的 cookie 和存储状态到内存快照。
restore_session_state：把快照恢复到当前页面，复用登录态和现场。
dump_session_state：把会话快照导出为 JSON 文件，便于持久化。
load_session_state：从已有 JSON 或字符串重新载入会话快照。

完整参数说明见 docs/reference/tool-reference.md。按逆向流程选工具可继续看 docs/reference/reverse-workflow.md。动态分析的启用条件、输出结构和安全边界见 docs/reference/dynamic-analysis.md。

外部 AI 怎么配置

这个项目支持把外部 LLM 作为“分析增强层”接进来，当前支持：

openai
anthropic
gemini

配置入口本质上是进程环境变量。
通过 MCP 客户端启动时，优先在 MCP server 配置里的 env 传入；.env 只适合你直接本地运行 node build/src/entry/index.js 或 pnpm run start 的场景。

推荐方式示例：

[mcp_servers.js-reverse]
command = "node"
args = ["/ABSOLUTE/PATH/JSReverser-MCP/build/src/entry/index.js"]

[mcp_servers.js-reverse.env]
DEFAULT_LLM_PROVIDER = "anthropic"
ANTHROPIC_API_KEY = "your_key"
ANTHROPIC_MODEL = "claude-3-5-sonnet-20241022"

如果你是直接在项目目录本地启动，也可以使用 .env：

# 三选一：openai / anthropic / gemini
DEFAULT_LLM_PROVIDER=gemini

# OpenAI
OPENAI_API_KEY=your_key
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=

# Anthropic / Claude
ANTHROPIC_API_KEY=your_key
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
ANTHROPIC_BASE_URL=

# Gemini
GEMINI_API_KEY=your_key
GEMINI_BASE_URL=
GEMINI_MODEL=gemini-2.0-flash-exp

# 如果不用 API，也可以走本地 CLI
GEMINI_CLI_PATH=gemini-cli

说明：

DEFAULT_LLM_PROVIDER 决定默认走哪个 provider
gemini 支持两种模式：有 GEMINI_API_KEY 时走 Gemini API；没有时会尝试走 GEMINI_CLI_PATH
openai 和 anthropic 需要对应 API key
如果你配了多个 provider，实际使用哪个，仍由 DEFAULT_LLM_PROVIDER 决定
配置后可以先调用 check_llm_health；默认只检查配置，传 liveCheck=true 时会发起一次最小 LLM 请求

哪些功能依赖外部 AI

强依赖外部 AI 的功能：

understand_code
- 默认会调用 LLM 做代码语义理解、业务逻辑提取、安全风险补充；传 useAI=false 时只走本地静态分析降级路径

可选启用外部 AI 的功能：

detect_crypto
- 只有传 useAI=true 时才会额外调用 LLM；不传时主要依赖本地规则和 AST 分析
analyze_target
- 传 useAI=true 时会在一站式分析里启用更深的 AI 辅助分析
risk_panel
- 传 useAI=true 时会把 AI 开关透传到代码理解和加密检测；不传时以本地分析与 hook 信号为主
deobfuscate_code
- 传 useAI=true 时会在本地反混淆管线后追加 LLM 辅助分析

有 AI 时效果更好，但不配也能运行的功能：

deobfuscate_code
- 本地规则、AST 优化、专项反混淆管线始终可用；配置外部 AI 并显式传 useAI=true 后，复杂语义清理、VM 结构理解、部分编码型混淆降级分析会更完整

完全不依赖外部 AI 的功能：

浏览器接管
Hook / 断点 / Console / Storage / Network / WebSocket
collect_code
export_rebuild_bundle
diff_env_requirements
record_reverse_evidence

如果没配外部 AI，典型影响是：

understand_code 默认会尝试 LLM；没配 provider 时会降级输出本地静态分析结果
detect_crypto(useAI=true) 会退回本地分析或忽略 AI 增强
deobfuscate_code 仍可跑，但某些高难度混淆的解释和清理质量会下降

标准任务结构

任务目录统一使用：

artifacts/tasks/_TEMPLATE/
artifacts/tasks/<task-id>/

推荐目录结构：

task.json
runtime-evidence.jsonl
network.jsonl
scripts.jsonl
env/env.js
env/polyfills.js
env/entry.js
env/capture.json
run/
report.md

职责边界：

env.js
- 基础宿主对象和最小 shim
polyfills.js
- 代理诊断层、watch、safeFunction、makeFunction
entry.js
- 运行入口、目标脚本加载、first divergence 输出

标准执行流程

推荐流程：

页面观察
运行时采样
证据入库
local rebuild
逐项补环境
first divergence 定位
env-pass 后再进入纯算法 / 风控逻辑提纯

默认原则：

不要跳过页面证据直接猜环境
不要一次性全量模拟浏览器
不要把真实任务目录直接提交 Git

参数沉淀与安全边界

参数链路沉淀遵循以下规则：

先读本地 task artifact

artifacts/tasks/<task-id>/

本地没有时再读抽象 case

scripts/cases/*

仍不足时按模板新建

docs/reference/parameter-methodology-template.md
docs/reference/parameter-site-mapping-template.md

安全边界：

case 只保留抽象方法和流程
真实任务目录默认本地保留
敏感值必须脱敏后才允许共享
Git 默认只提交 _TEMPLATE

详见：

3 分钟快速开始

环境要求

Node.js >=22
已安装 Google Chrome（稳定版）。默认以系统 Chrome 启动；也可用 --executablePath 指定自定义 Chrome，或 npx patchright install chromium 后使用下载的 Chromium，或 --browserUrl / --wsEndpoint 接管已运行的浏览器。
仅参与源码开发时还需 pnpm 10.x

通过 npx 直接使用（推荐）

无需克隆仓库，直接运行已发布的包：

npx @yuanhuakk/js-reverse-mcp@latest

在 MCP 客户端中配置，最简：

{
  "mcpServers": {
    "js-reverse": {
      "command": "npx",
      "args": ["-y", "@yuanhuakk/js-reverse-mcp@latest"]
    }
  }
}

功能可用性（重要）

最简配置即可注册全部工具，但要全功能需注意：

前提：Node ≥ 22 + 系统已装 Google Chrome（默认 channel=stable 自启动系统 Chrome）。不满足则浏览器类工具不可用。
默认有界面：默认 headless=false，会弹出 Chrome 窗口；不想弹窗在 args 加 --headless。
AI 增强需配 LLM：understand_code（强依赖）、以及 detect_crypto/analyze_target/risk_panel/deobfuscate_code（传 useAI=true 时）需要在 env 配置 LLM provider + key；不配则自动降级为本地静态分析。

全功能配置（headless + AI）

{
  "mcpServers": {
    "js-reverse": {
      "command": "npx",
      "args": ["-y", "@yuanhuakk/js-reverse-mcp@latest", "--headless"],
      "env": {
        "DEFAULT_LLM_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "your_key",
        "ANTHROPIC_MODEL": "claude-3-5-sonnet-20241022"
      }
    }
  }
}

LLM 三选一：openai / anthropic / gemini（详见下方「外部 AI 怎么配置」）。

Codex config.toml：

[mcp_servers.js-reverse]
command = "npx"
args = ["-y", "@yuanhuakk/js-reverse-mcp@latest", "--headless"]

[mcp_servers.js-reverse.env]
DEFAULT_LLM_PROVIDER = "anthropic"
ANTHROPIC_API_KEY = "your_key"

常用启动参数：--headless（无界面）、--isolated（临时用户目录）、--channel beta|dev|canary（指定 Chrome 渠道）、--executablePath <path>（自定义 Chrome）、--browserUrl <url> / --wsEndpoint <ws>（接管已运行浏览器）。完整参数见 npx @yuanhuakk/js-reverse-mcp@latest --help。

配套方法论 Skill（可选）

MCP 提供工具，配套 skill 提供「怎么用这些工具做逆向」的五阶段流程。单独安装：

npx skills add YuanHuakk/js-reverse-playbook-skill

从源码开发

1) 安装依赖并构建

corepack enable
pnpm install
pnpm run build

构建入口：

build/src/entry/index.js

2) 最简单启动方式

pnpm run start

3) 配置客户端

最小配置示例：

Claude Code

claude mcp add js-reverse node /ABSOLUTE/PATH/JSReverser-MCP/build/src/entry/index.js

Cursor

Command: node
Args: [/ABSOLUTE/PATH/JSReverser-MCP/build/src/entry/index.js]

Codex

[mcp_servers.js-reverse]
command = "node"
args = ["/ABSOLUTE/PATH/JSReverser-MCP/build/src/entry/index.js"]

如果你需要接管已经打开的浏览器，请继续看：

浏览器运行时

项目默认使用 Patchright 作为浏览器运行时。通常不需要额外配置；如果要显式声明，可以在 MCP server 的 env 中传入：

[mcp_servers.js-reverse.env]
JS_REVERSER_BROWSER_RUNTIME = "patchright"

本地直接运行时也可以：

JS_REVERSER_BROWSER_RUNTIME=patchright pnpm run start

当前版本默认以 Patchright 作为浏览器后端，已覆盖页面枚举、新页面、CDP session、预注入脚本、UA 覆盖和 networkidle2 映射。业务模块通过 ManagedBrowser / ManagedPage 内部边界访问浏览器能力；只有 CDP/Protocol 相关低层能力保留直接类型依赖。更详细的浏览器连接说明见 docs/guides/browser-connection.md。

Patchright 与页面级 Stealth 的边界

Patchright 是浏览器运行时底座，负责启动或接管浏览器、页面枚举、新页面、CDP session、预注入通道、UA 覆盖和等待策略映射。它降低的是自动化控制层暴露面。

StealthScripts2025 是页面 JavaScript 运行时补丁层，负责在页面上下文里修补或模拟可被业务脚本读取的指纹面，例如 navigator.webdriver、navigator.plugins、navigator.languages、chrome.runtime、Permissions、WebGL、Canvas、AudioContext、screen、connection、battery、mediaDevices 等。

所以 Patchright 不等于替代 StealthScripts2025。默认建议把页面级 stealth 视为可选增强层：

普通调试和页面观察优先只用 Patchright。
遇到风控或反自动化检测时，再启用 USE_STEALTH_SCRIPTS=true 或调用 inject_stealth。
如果目标页面依赖真实浏览器指纹，先记录检测证据，再决定注入哪些补丁，避免过度修改运行时现场。

完整可直接复制的 MCP 配置实例，包括：

mcpServers JSON 结构示例
Codex config.toml 示例
--browserUrl 接管浏览器示例
Gemini / Claude / OpenAI 的 API env 示例

都放在 docs/guides/client-configuration.md。

文档入口

逆向相关任务开场先读：docs/reference/reverse-bootstrap.md。该入口会继续要求模型读取 docs/reference/case-safety-policy.md、docs/reference/reverse-workflow.md；若已进入 env-pass 后的提纯阶段，再读 docs/reference/pure-extraction.md。

Guides

快速开始：docs/guides/getting-started.md
浏览器连接：docs/guides/browser-connection.md
客户端配置：docs/guides/client-configuration.md
逆向工作流：docs/reference/reverse-workflow.md
补环境规范：docs/reference/env-patching.md

Reference

模型首读入口：docs/reference/reverse-bootstrap.md
逆向任务索引：docs/reference/reverse-task-index.md
工具参数总表：docs/reference/tool-reference.md
工具读写契约：docs/reference/tool-io-contract.md
动态分析协议：docs/reference/dynamic-analysis.md
真实 MCP 验收：docs/reference/real-validation.md
任务产物说明：docs/reference/reverse-artifacts.md

Templates And Supporting Docs

开发与测试

pnpm run build
pnpm run check-format
pnpm run typecheck
pnpm run test
pnpm run coverage

真实浏览器和 MCP 链路验收需要先启动 Chrome DevTools endpoint，然后运行：

pnpm run validate:real

能力矩阵、已知边界和分项脚本见 docs/reference/real-validation.md。

故障排查

更多问题排查请看：

docs/guides/browser-connection.md

参考项目

本项目在设计和实现过程中参考了以下项目，具体协议声明（如 MIT 等）以对应上游仓库为准：

License

Apache-2.0