Skip to content
Back to search

js-reverse-mcp

AI Agent-first JS 逆向 MCP Server:有头 Chrome 调试、断点、网络/WebSocket 分析、Patchright 反检测,可选 CloakBrowser。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhizhuodemao--js-reverse-mcp/badge.svg)](/listings/zhizhuodemao--js-reverse-mcp)

HTML

<a href="/listings/zhizhuodemao--js-reverse-mcp"><img src="/api/listings/zhizhuodemao--js-reverse-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 426 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # JS Reverse MCP
  2. [English](README_en.md) | 中文
  3. AI-first / AI-native 的 JavaScript 逆向工程 MCP Server,让你的 AI 编码助手(如 Claude、Cursor、Copilot)能够像分析师一样持续调试、定位、保存和复盘网页中的 JavaScript 行为。
  4. 它不是把 Chrome DevTools API 原样搬给模型,而是把脚本、断点、网络、WebSocket、浏览器状态和本地文件 I/O 重新组织成适合 AI Agent 连续推理和操作的工具。反检测是其中一部分能力:默认使用为本 MCP 重新编译发布、独立维护的 [Patchright fork](https://github.com/zhizhuodemao/patchright-mcp) 提供协议层 stealth,对强反爬站点可选启用 [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) 源码层指纹模式。
  5. ## ☁️ 赞助 · Sponsored by IPWO
  6. <p align="center">
  7. <a href="https://www.ipwo.net/?ref=githubmcp">
  8. <img src="images/ipwo-residential-proxy.png" alt="IPWO 住宅代理:稳定连接、全球节点、多协议支持" width="100%">
  9. </a>
  10. </p>
  11. IPWO 住宅代理支持灵活的代理配置,开发者可以根据不同任务选择相应的网络环境,用于网页访问、请求测试、地区化内容分析及自动化工作流。
  12. 对于涉及 JS 逆向、浏览器调试和 Web 网络分析的项目,住宅代理也可以作为网络环境的一种补充选择,帮助开发者更灵活地满足不同地区的访问与测试需求。
  13. 👉 [免费测试入口](https://www.ipwo.net/?ref=githubmcp),9 折优惠码:`0204`
  14. ## ☁️ 赞助 · Sponsored by Infistar.cc 无限星河
  15. <p align="center">
  16. <a href="https://www.infistar.cc/register?aff=JJXMRC86&amp;ref_source=link">
  17. <img src="images/infistar-model-api.png" alt="Infistar.cc 无限星河:一站式全球大模型 API 服务平台" width="100%">
  18. </a>
  19. </p>
  20. **js-reverse-mcp × Infistar.cc 无限星河|全模型 API · 稳定驱动 AI 辅助调试**
  21. 感谢 Infistar.cc 无限星河赞助并为 js-reverse-mcp 提供模型服务支持!
  22. - ⚡ **稳定承载复杂调试任务**:提供企业级高并发通道与多节点冗余,价格低至官方渠道 1 折,减少限流、429 和长任务断连问题。
  23. - 🧠 **一个 API Key 接入主流模型**:支持 ChatGPT、Claude、Gemini、Kimi、GLM、DeepSeek 等模型,适配 Claude Code、Codex、Cursor 等 AI 编程工具。
  24. - 🔎 **助力授权调试与安全研究**:适用于脚本检索、断点分析、网络请求追踪、调用栈检查和代码逻辑理解等多步骤任务。
  25. - 📦 **项目用户专属福利**:通过 [专属推广链接](https://www.infistar.cc/register?aff=JJXMRC86&ref_source=link) 注册并完成首次调用,即可领取 5 美元等值测试额度 / 首充专属优惠。
  26. 定位:Claude Code / Codex 模型 API 配置支持。
  27. ## 功能特点
  28. - **AI-native 工具设计**:工具粒度、输出边界和错误提示都围绕 Agent 决策设计,避免把模型推向无效下一步
  29. - **可复盘工作流**:脚本源码、网络原始数据、二进制结果都能导出到本地文件,再作为后续分析输入
  30. - **断点上下文执行**:暂停时可直接在 call frame 中求值,检查作用域变量,单步执行并返回源码上下文
  31. - **脚本分析**:列出所有加载的 JS,搜索代码,获取/保存源码,自动格式化大型压缩脚本
  32. - **网络与 WebSocket 分析**:请求调用栈、XHR 断点、Set-Cookie 识别、原始 body/header 导出、WebSocket 消息分组
  33. - **浏览器状态重放**:清理当前站点 cookies / cache / storage / sessionStorage,配合 reload 复现 cookie 和风控流程
  34. - **默认有头 + 持久化登录态**:看得到浏览器,cookies / localStorage 跨会话保留
  35. - **专用 Patchright 内核**:默认依赖本项目独立维护的 Patchright fork,持续修复上游已知的共享实现特征
  36. - **可选反检测层**:专用 Patchright 协议层 stealth 默认启用;强反爬站点可加 `--cloak` 使用 CloakBrowser 二进制
  37. ## 专用 Patchright fork
  38. js-reverse-mcp 不再直接依赖 Patchright 的大众发行包,而是使用专门为本 MCP 编译发布的 [`@zhizhuodemao/patchright`](https://www.npmjs.com/package/@zhizhuodemao/patchright)。这个 fork 会在独立仓库持续维护,并随本 MCP 的实际检测样本演进。
  39. - 不再直接依赖 Patchright 大众发行包
  40. - 针对已确认的上游共享实现特征进行协议层调整并重新编译发布
  41. - 反检测调整不依赖页面级 JS 注入
  42. - 保留 evaluate、locator 和页面控制等原始能力
  43. - fork 在面向本 MCP 的专用仓库中持续维护
  44. 公开文档仅说明设计边界,不展开内部检测样本与实现细节。专用 fork 的目标是减少已确认的共享实现特征,而不是承诺浏览器自动化绝对不可检测。
  45. ## 系统要求
  46. - [Node.js](https://nodejs.org/) v20.19 或更新版本
  47. - [Chrome](https://www.google.com/chrome/) 稳定版
  48. ## 快速开始(npx)
  49. 无需安装,直接在 MCP 客户端配置中添加:
  50. ```json
  51. {
  52. "mcpServers": {
  53. "js-reverse": {
  54. "command": "npx",
  55. "args": ["js-reverse-mcp"]
  56. }
  57. }
  58. }
  59. ```
  60. ### Claude Code
  61. ```bash
  62. claude mcp add js-reverse npx js-reverse-mcp
  63. ```
  64. 如果你还没有可用的模型 API,或者需要配置自定义 API 地址,可以参考:[Claude Code / Codex 第三方模型 API 配置教程](docs/model-api-setup.md)。
  65. ### Codex
  66. ```bash
  67. codex mcp add js-reverse -- npx js-reverse-mcp
  68. ```
  69. 如果你还没有可用的模型 API,或者需要配置自定义 API 地址,可以参考:[Claude Code / Codex 第三方模型 API 配置教程](docs/model-api-setup.md)。
  70. ### Cursor
  71. 进入 `Cursor Settings` -> `MCP` -> `New MCP Server`,使用上面的配置。
  72. ### VS Code Copilot
  73. ```bash
  74. code --add-mcp '{"name":"js-reverse","command":"npx","args":["js-reverse-mcp"]}'
  75. ```
  76. ## 本地安装(可选)
  77. ```bash
  78. git clone https://github.com/zhizhuodemao/js-reverse-mcp.git
  79. cd js-reverse-mcp
  80. npm install
  81. npm run build
  82. ```
  83. 然后在 MCP 配置中使用本地路径:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "js-reverse": {
  88. "command": "node",
  89. "args": ["/你的路径/js-reverse-mcp/build/src/index.js"]
  90. }
  91. }
  92. }
  93. ```
  94. ## AI-first 设计
  95. 这个项目的核心目标不是“能操作浏览器”,而是让 AI Agent 能稳定完成一轮真实 JS 逆向任务:打开页面、过风控、定位脚本、保存源码、设置断点、触发行为、检查运行时、导出网络材料、复现状态,然后继续推理。
  96. 几个设计取向贯穿在代码里:
  97. - **工具是 Agent primitives,不是 DevTools 菜单映射**:`list_network_requests` 既能列索引,也能按 `reqid` 查详情,还能用 `outputFile` 导出精确材料;`evaluate_script` 既能在页面执行,也能在断点 call frame 执行,还能接收 `localFilePath` 输入。
  98. - **输出要能指导下一步**:列表输出保持短而可扫描;详情输出有边界;长结果提示导出;pending 请求会明确提示先恢复执行,避免 Agent 等一个永远不会完成的 response。
  99. - **本地文件是分析工作台**:`save_script_source`、`list_network_requests(..., outputFile)`、`evaluate_script(..., localFilePath)` 让 Agent 能在浏览器、网络和本地文件之间往返,而不是把大段代码或二进制数据塞进聊天上下文。
  100. - **状态可清理、流程可重放**:默认 profile 保留登录态;`--isolated` 提供一次性干净环境;`clear_site_data` 只清当前站点相关状态,用来反复复现 cookie 生成、风控初始化和请求链路。
  101. - **反检测服务于调试链路**:CDP 静默导航、真实视口、Google referer、专用 Patchright fork 和 CloakBrowser 的目标都是让 Agent 能进入目标页面继续分析,而不是把项目变成一个泛用爬虫框架。
  102. ## 反检测机制(支撑能力)
  103. 反检测是 js-reverse-mcp 的底层支撑能力之一。包装层(这个 MCP 自己)**零 JS 注入**、不做 `Object.defineProperty` hack(那本身就是检测信号)。所有反检测都在两个互不重叠的层:
  104. | 层 | 默认模式 | `--cloak` 模式 |
  105. | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
  106. | **协议层**(CDP) | 专用 Patchright fork:不调 `Runtime.enable` / `Console.enable`,在 isolated world 里执行 evaluate,移除自动化 launch flag,并持续修复已知共享实现特征 | 同 |
  107. | **源码层**(C++ 二进制 patch) | 无 —— 直接用系统 Google Chrome | CloakBrowser 二进制(按平台提供源码层指纹 patch,覆盖 `navigator.webdriver`、canvas、WebGL、audio、GPU、字体、屏幕、WebRTC、TLS) |
  108. | **Profile 目录** | `~/.cache/chrome-devtools-mcp/chrome-profile`(持久化登录态) | `~/.cache/chrome-devtools-mcp/cloak-profile`(与默认物理隔离) |
  109. | **实际浏览器** | 你装的 Google Chrome(带 Web Store、扩展、sync) | 定制 Chromium 编译版(无 Google 服务、无 Web Store) |
  110. 另外几个导航级措施(两种模式都生效):
  111. - **CDP 静默导航** —— 页面加载时不激活 `Network.enable` / `Debugger.enable`,请求/控制台收集只走 Playwright 监听器,直到某个工具显式需要 CDP 才激活
  112. - **Google Referer** —— `new_page` 默认带 `referer: https://www.google.com/`
  113. - **真实视口** —— 关掉 Playwright 默认的 1280×720 假视口,浏览器展示真实屏幕尺寸
  114. **何时开 `--cloak`**:只在以上还不够、被站点指纹拦截时才用。详见 [docs/cloak.md](docs/cloak.md)。
  115. ## 工具列表(24 个)
  116. ### 页面与导航
  117. | 工具 | 描述 |
  118. | ----------------- | ------------------------------------------ |
  119. | `select_page` | 列出打开的页面,或按索引选择调试上下文 |
  120. | `new_page` | 创建新页面并导航到 URL |
  121. | `navigate_page` | 导航、后退、前进或刷新页面 |
  122. | `select_frame` | 列出所有 frame(iframe),或选择执行上下文 |
  123. | `click_element` | 严格匹配并点击当前 frame 中的单个可见元素 |
  124. | `take_screenshot` | 截取页面截图 |
  125. ### 脚本分析
  126. | 工具 | 描述 |
  127. | -------------------- | ------------------------------------------------------ |
  128. | `list_scripts` | 列出页面中所有加载的 JavaScript 脚本 |
  129. | `get_script_source` | 获取脚本源码片段,支持行范围或字符偏移 |
  130. | `save_script_source` | 保存完整脚本源码到本地文件(适用于大型/压缩/WASM文件) |
  131. | `search_in_sources` | 在所有脚本中搜索字符串或正则表达式 |
  132. ### 断点与执行控制
  133. | 工具 | 描述 |
  134. | ------------------------ | ----------------------------------------------- |
  135. | `set_breakpoint_on_text` | 通过搜索代码文本自动设置断点(适用于压缩代码) |
  136. | `break_on_xhr` | 按 URL 模式设置 XHR/Fetch 断点 |
  137. | `remove_breakpoint` | 用显式 action 按 ID、URL 或全部移除断点 |
  138. | `list_breakpoints` | 列出所有活动断点 |
  139. | `get_paused_info` | 获取暂停状态、调用栈和作用域变量 |
  140. | `pause_or_resume` | 用显式 action 暂停或恢复执行 |
  141. | `step` | 单步调试(over/into/out),返回位置和源码上下文 |
  142. ### 网络与 WebSocket
  143. | 工具 | 描述 |
  144. | ------------------------ | ----------------------------------------------------------- |
  145. | `list_network_requests` | 列出网络请求、查看详情,或导出 header/body/query 等原始材料 |
  146. | `clear_network_requests` | 显式确认后清空当前页面已收集的请求和 body cache |
  147. | `get_request_initiator` | 获取网络请求的 JavaScript 调用栈 |
  148. | `get_websocket_messages` | 列出 WebSocket 连接、分析消息模式或获取消息详情 |
  149. ### 浏览器状态
  150. | 工具 | 描述 |
  151. | ----------------- | ----------------------------------------------------------------------------------------- |
  152. | `clear_site_data` | 清理当前站点相关 cookies、origin storage 和 sessionStorage;可显式选择清理全局 HTTP cache |
  153. ### 检查工具
  154. | 工具 | 描述 |
  155. | ----------------------- | ----------------------------------------------------------------------------- |
  156. | `evaluate_script` | 在页面或断点上下文执行 JavaScript,支持主世界、保存结果和读取一个本地输入文件 |
  157. | `list_console_messages` | 列出控制台消息,或按 msgid 获取单条详情 |
  158. ## 使用示例
  159. ### JS 逆向基本流程
  160. 1. **打开目标页面**
  161. ```
  162. 打开 https://example.com 并列出所有加载的 JS 脚本
  163. ```
  164. 2. **查找目标函数**
  165. ```
  166. 在所有脚本中搜索包含 "encrypt" 的代码
  167. ```
  168. 3. **设置断点**
  169. ```
  170. 在加密函数入口处设置断点
  171. ```
  172. 4. **触发并分析**
  173. ```
  174. 在页面上触发操作,断点命中后检查参数、调用栈和作用域变量
  175. ```
  176. ### WebSocket 协议分析
  177. ```
  178. 列出 WebSocket 连接,分析消息模式,查看特定类型的消息内容
  179. ```
  180. ### Agent 推荐的完整捕获流程
  181. 因为导航阶段会刻意保持 CDP 静默,首次进入目标页时不会立即打开 Network / Debugger 域。推荐流程是先过风控,再刷新捕获:
  182. ```
  183. 1. new_page 打开目标页
  184. 2. 调用 list_network_requests 激活 collectors
  185. 3. navigate_page(type="reload") 刷新页面
  186. 4. 再次 list_network_requests 查看完整请求
  187. 5. 对关键 reqid 使用 outputFile 导出原始材料
  188. ```
  189. ### Cookie / 风控重放流程
  190. ```
  191. 1. clear_site_data(confirm=true) 清理当前站点状态
  192. 2. navigate_page(type="reload") 重新触发初始化
  193. 3. list_network_requests 找到设置 cookie 或提交 sensor 的请求
  194. 4. 导出 requestBody / responseHeaders / responseBody
  195. 5. 用 evaluate_script + localFilePath 在页面上下文中复算或验证
  196. ```
  197. ## 配置选项
  198. CLI 保持精简,所有 flag 都是可选项。**99% 场景默认即可**。涉及本地文件时,建议用 `--allowedRoots` 限定 Agent 可读写的目录。
  199. | 选项 | 描述 | 默认值 |
  200. | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
  201. | `--cloak` | 切换到 CloakBrowser 隐身二进制(取代系统 Chrome)。启用按平台提供的 C++ 源码层指纹 patch。首次启动自动下载 ~200MB 二进制;指纹身份按 profile 持久化。详见 [docs/cloak.md](docs/cloak.md)。 | `false` |
  202. | `--isolated` | 使用临时 user-data-dir(cookies/localStorage 不保留,关闭时自动清理) | `false` |
  203. | `--browserUrl, -u` | 连接到已运行的 Chrome 实例(CDP HTTP 端点,如 `http://127.0.0.1:9222`)。MCP 会自动探测出 WebSocket debugger URL。本地 Chrome、AdsPower、BitBrowser 等怎么拿到这个端点详见 [docs/cdp-endpoint.md](docs/cdp-endpoint.md)。 | – |
  204. | `--logFile` | 写入 `0600` 普通文件的 MCP 调试日志;详细日志仅使用 `DEBUG=mcp:*`。不要使用 `DEBUG=*`,浏览器协议日志可能泄露页面、Cookie、脚本和凭据。 | – |
  205. | `--allowedRoots` | 可重复指定 Agent 允许读写的本地目录;解析真实路径并拒绝符号链接越界。启用时禁用 `file:`、`view-source:file:` 和 `filesystem:file:` 浏览器页面。未指定时本地文件访问不受目录限制,启动时会打印安全警告。 | – |
  206. ### 示例配置
  207. **默认 —— 系统 Chrome + 持久化登录态**(绝大多数调试场景推荐):
  208. ```json
  209. {
  210. "mcpServers": {
  211. "js-reverse": {
  212. "command": "npx",
  213. "args": ["js-reverse-mcp"]
  214. }
  215. }
  216. }
  217. ```
  218. **`--cloak` —— 强反爬站点**(Cloudflare Turnstile / DataDome / FingerprintJS 防护):
  219. > **强烈推荐:先把二进制预下载好**(一次性,~30–60 秒)。**不做这一步**的话,首次启动带 `--cloak` 的 MCP 会**静默下载 ~200MB**,看起来像 MCP 卡住了:
  220. >
  221. > ```bash
  222. > npx cloakbrowser install
  223. > ```
  224. >
  225. > (`cloakbrowser` 包已经通过 `optionalDependencies` 一起装好,这条命令只是触发它自带的二进制下载逻辑,有进度条)
  226. ```json
  227. {
  228. "mcpServers": {
  229. "js-reverse-cloak": {
  230. "command": "npx",
  231. "args": ["js-reverse-mcp", "--cloak"]
  232. }
  233. }
  234. }
  235. ```
  236. **两套并行** —— 两个 MCP 实例 profile 物理隔离,根据目标站点切换:
  237. ```json
  238. {
  239. "mcpServers": {
  240. "js-reverse": {
  241. "command": "npx",
  242. "args": ["js-reverse-mcp"]
  243. },
  244. "js-reverse-cloak": {
  245. "command": "npx",
  246. "args": ["js-reverse-mcp", "--cloak"]
  247. }
  248. }
  249. }
  250. ```
  251. **`--isolated` —— 每次全新 profile**(不保留 cookies/localStorage):
  252. ```json
  253. {
  254. "mcpServers": {
  255. "js-reverse": {
  256. "command": "npx",
  257. "args": ["js-reverse-mcp", "--isolated"]
  258. }
  259. }
  260. }
  261. ```
  262. ### 连接到已运行的 Chrome / 第三方指纹浏览器
  263. `--browserUrl` 只接受 **CDP endpoint**(能响应 `/json/version` 的 HTTP 端点),不接受厂商私有 Local API。本地 Chrome、AdsPower、BitBrowser 等场景下怎么拿到 CDP 端口,详见专门的文档:
  264. 📖 **[docs/cdp-endpoint.md —— 如何拿到 CDP 调试端口](docs/cdp-endpoint.md)**
  265. 最短路径(本地 Chrome):
  266. ```bash
  267. # 先关掉所有 Chrome 窗口,然后
  268. /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  269. --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
  270. ```
  271. ```json
  272. {
  273. "mcpServers": {
  274. "js-reverse": {
  275. "command": "npx",
  276. "args": ["js-reverse-mcp", "--browserUrl", "http://127.0.0.1:9222"]
  277. }
  278. }
  279. }
  280. ```
  281. 指纹浏览器(AdsPower、BitBrowser 等)的 CDP 端口是**每次启动随机变化**的,必须通过厂商 Local API 启动浏览器后再提取,操作步骤和示例脚本都在上面那篇文档里。
  282. ## 故障排除
  283. ### 被反爬系统拦截
  284. 如果访问某些站点被拦截(如知乎返回 40362、Cloudflare 挑战死循环):
  285. 1. **先试 `--isolated`** —— 用全新 profile 排除残留状态污染:
  286. ```json
  287. "args": ["js-reverse-mcp", "--isolated"]
  288. ```
  289. 2. **还不行就开 `--cloak`** —— 启用按平台提供的源码层指纹 patch:
  290. ```json
  291. "args": ["js-reverse-mcp", "--cloak"]
  292. ```
  293. 3. **最后再考虑手动清持久化 profile**(会丢登录态):
  294. ```bash
  295. rm -rf ~/.cache/chrome-devtools-mcp/chrome-profile
  296. ```
  297. 什么时候该开 `--cloak`、什么时候不该开,详见 [docs/cloak.md](docs/cloak.md)。
  298. ## Agent 路由评测(维护者)
  299. `npm run eval:routing:validate` 会离线校验实际 MCP `tools/list`、server instructions 与 `evals/tool-routing.json` 的 30 条工具选择契约;该命令不会访问模型端点,并已纳入 presubmit。
  300. 真实模型评测是显式 opt-in,会逐条调用 OpenAI-compatible Chat Completions 端点并可能产生费用:
  301. ```bash
  302. MCP_ROUTING_EVAL_ENDPOINT=https://api.example.com/v1/chat/completions \
  303. MCP_ROUTING_EVAL_MODEL=model-name \
  304. MCP_ROUTING_EVAL_API_KEY=secret \
  305. npm run eval:routing
  306. ```
  307. `MCP_ROUTING_EVAL_API_KEY` 对无需认证的本地端点可省略;带凭据的远程端点必须使用 HTTPS,HTTP 仅允许 loopback。可用 `MCP_ROUTING_EVAL_TIMEOUT_MS` 调整单条请求超时。默认要求 100% 通过,跨模型对比时可用 `MCP_ROUTING_EVAL_MIN_PASS_RATE` 设置 `(0, 1]` 阈值。评测不会输出 API key、endpoint 或端点错误响应正文。
  308. ## 安全提示
  309. 此工具会将浏览器内容暴露给 MCP 客户端,允许检查、调试和修改浏览器中的任何数据。请勿在包含敏感信息的页面上使用。
  310. `evaluate_script.localFilePath`、各类 `outputFile`/`filePath` 会让 MCP 进程读取或写入宿主机文件。生产或共享环境应使用一个或多个 `--allowedRoots` 收窄到专用工作目录;未配置时访问范围不受限制。启用 `--allowedRoots` 后,`file:`、`view-source:file:` 和 `filesystem:file:` 浏览器页面也会被拒绝,避免通过浏览器导航绕过目录边界;需要调试本地页面时,只能在明确接受本地文件暴露风险的会话中不配置该选项。
  311. ## 许可证
  312. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.