最佳实践

面向初次配置 jshookmcp 的用户，帮你快速上手并避免常见坑。

配置方式

jshookmcp 的所有参数都有内建默认值，大多数用户无需任何配置即可直接使用。如需覆盖默认值，根据安装方式选择对应配置方式：

npx / MCP 用户（推荐）

通过 npx 或 MCP 客户端安装的用户，在 MCP 配置的 env 字段中传入环境变量即可，不需要创建 .env 文件：

{
  "mcpServers": {
    "jshook": {
      "command": "npx",
      "args": ["-y", "@jshookmcp/jshook@latest"],
      "env": {
        "MCP_TOOL_PROFILE": "workflow"
      }
    }
  }
}

需要更多参数时，直接在 env 对象里添加键值对：

"env": {
  "MCP_TOOL_PROFILE": "workflow",
  "PUPPETEER_HEADLESS": "true",
  "ENABLE_CACHE": "true",
  "EXTENSION_REGISTRY_BASE_URL": "https://raw.githubusercontent.com/vmoranv/jshookmcpextension/master/registry"
}

源码开发者

Clone 仓库进行开发的用户，在项目根目录创建 .env 文件（参考 .env.example 模板）。运行时自动从 src/utils/config.ts 读取，未设置的变量回退到代码默认值。

# .env — 项目根目录
PUPPETEER_HEADLESS=true
MCP_TOOL_PROFILE=workflow

注意：两种方式传入的变量名和效果完全相同，只是传入途径不同。所有可用变量见 配置项参考。

---

Profile 选择建议

场景	推荐 Profile	理由
日常逆向	workflow	浏览器、网络、调试、Hook 常驻，token 开销适中
只做搜索/探索	search	极简模式，仅暴露元工具，token 最省
深度分析（WASM/进程/内存）	full	全域预载，适合重型任务

切换方式（任选一种）：

# 方式一：MCP 配置 env 字段
"MCP_TOOL_PROFILE": "workflow"

# 方式二：.env 文件（仅源码开发者）
MCP_TOOL_PROFILE=workflow

---

推荐安装的 Extension

通过 install_extension 工具安装官方扩展：

Workflow（任务流）

Workflow	用途	安装命令
signature_hunter	签名算法定位：自动抓请求、识别加密参数、Hook 签名路径	install_extension("workflow:signature_hunter")
ws_protocol_lifter	WebSocket 协议逆向：消息聚类、编码识别、handler 关联	install_extension("workflow:ws_protocol_lifter")
bundle_recovery	Bundle 恢复：webpack 枚举、source map 恢复、模块结构还原	install_extension("workflow:bundle_recovery")
anti_bot_diagnoser	反检测诊断：对比 stealth/normal 指纹差异	install_extension("workflow:anti_bot_diagnoser")
evidence_pack	证据打包：一键收集请求、Cookie、快照为可回放包	install_extension("workflow:evidence_pack")

Plugin（工具插件）

Plugin	用途	安装命令
pl-auth-extract	从页面提取 token/device-id 等鉴权要素	install_extension("plugin:pl-auth-extract")
pl-qwen-mail-open-latest	打开最新 QQ 邮件并提取正文	install_extension("plugin:pl-qwen-mail-open-latest")
pl-temp-mail-open-latest	打开临时邮箱最新邮件	install_extension("plugin:pl-temp-mail-open-latest")

安装后通过 list_extension_workflows() / run_extension_workflow() 调用。

---

环境调优

以下示例以 .env 语法展示。npx 用户请将等号改为 JSON 键值对放入 MCP 配置的 env 字段。

浏览器配置

# 指定 Chrome 路径（自动检测失败时）
PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome
# 或
CHROME_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe

性能调优

# Token 预算（防止上下文爆炸）
TOKEN_BUDGET_MAX_TOKENS=200000

# 并发控制
jshook_IO_CONCURRENCY=4       # I/O 并发上限
jshook_CDP_CONCURRENCY=2       # CDP 操作并发上限
MAX_CONCURRENT_ANALYSIS=3      # 分析任务并发上限

# 缓存（推荐开启，减少重复采集）
ENABLE_CACHE=true
CACHE_TTL=3600

超时设置

# 浏览器操作超时
PUPPETEER_TIMEOUT=30000

# 外部工具超时
EXTERNAL_TOOL_TIMEOUT_MS=30000

# Workflow 批处理超时
WORKFLOW_BATCH_MAX_TIMEOUT_MS=300000

---

常见问题

搜索不到工具

原因：当前 profile 未包含目标域。

解决：

1. 切到更高档位：MCP_TOOL_PROFILE=workflow
2. 或运行时调用 activate_tools(["debugger", "hooks"])

Extension 安装失败

检查：

1. 确认 registry URL 已配置：EXTENSION_REGISTRY_BASE_URL=https://...
2. 确认网络可达（需要访问 GitHub raw 内容）
3. 运行 doctor_environment() 诊断环境

Hook 注入后无数据

可能原因：

• 目标函数在 iframe/worker 内，需要切换上下文
• 页面启用了 CSP，阻止注入脚本
• Hook 路径不正确（如 window.fetch vs globalThis.fetch）

排查：调用 manage_hooks({ action: "list" }) 确认状态。

浏览器启动失败

排查顺序：

1. 运行 doctor_environment() 检查依赖
2. 显式指定浏览器路径：PUPPETEER_EXECUTABLE_PATH=...
3. 检查浏览器远程调试端口是否被占用

---

下一步

• 配置项参考 — 完整配置项参考
• 工具路由 — Profile 与路由机制详解
• 域矩阵 — 所有域的完整工具清单
• Workflow 开发 — 编写自己的 workflow
• 环境诊断 — 检查 bridge 健康状态