Seep-Reverse-Lab/Tool/docs/MCP-SETUP.md

MCP 配置与验证 (MCP-SETUP)

本工作台靠 3 个 MCP 提供工具能力。本文说明：它们是什么、装到哪、怎么验证、出问题怎么办。

📦 各 MCP 依赖的工具从哪里下载 → 见 Tool/docs/DOWNLOADS.md

---

一、MCP 与 Skill 的关系

Skill（提示词层）       →  告诉 agent「该做什么、走哪条路」
MCP（工具层）           →  给 agent「实际干活的手」

举例：apkseep Skill 说「用 jadx 反编译这个 APK」→ agent 调 seep_apk_decompile → seep MCP 内部驱动 jadx 完成反编译。

Skill 是说明书，MCP 是工具。 两者都装好才能干活。

---

二、3 个已注册 MCP

MCP	工具数	用途	依赖	安装方式
seep ⭐	22	二进制逆向 + APK 逆向 + Frida 生成 + 知识库	radare2 / jadx / apktool	本包自带 + 脚本下载工具
ida	~243	IDA 全套分析链	你自备的 IDA Pro	脚本装 MCP + 你装 IDA
playwright	—	浏览器自动化	npx	自动（npx 按需拉取）

seep MCP 的 22 个工具

分组	工具
状态环境 (2)	seep_status · seep_ida_status
二进制 r2 (8)	seep_r2_info · _cmd · _strings · _functions · _disasm · _decompile · _diff · _asm
Android (5)	seep_apk_info · _decompile · _unpack · _smali_search · _gen_hook
知识库 (4)	seep_kb_search · _read · _checklist · _payloads
流程编排 (3)	seep_task_init · seep_auto_triage · seep_gen_security_report

---

三、安装过程（install-pi.ps1 自动完成）

1. 备份现有 ~/.pi/agent/ 配置
2. 复制 Skill  →  ~/.pi/agent/skills/
3. 复制提示词  →  ~/.pi/agent/SYSTEM.md · AGENTS.md
4. 复制扩展    →  ~/.pi/agent/extensions/
5. 生成 mcp.json：
     · <SEEP_ROOT>  → 本包实际路径
     · <IDA_ROOT>   → 自动探测（D:\Tool\IDA Pro / C:\Program Files\IDA Pro / C:\IDA Pro）
     · <IDA_PYTHON> → 探测到的 IDA Python
     · playwright token → 需你自填（不用浏览器自动化可留空）
6. 写 settings.json（12 个 pi packages）
7. 执行 pi update --extensions

生成的 ~/.pi/agent/mcp.json 结构：

{
  "mcpServers": {
    "seep": {
      "command": "python",
      "args": ["<本包路径>\\Tool\\mcp\\seep_mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "transport": "stdio"
    },
    "ida": {
      "command": "<IDA Python 路径>",
      "args": ["<IDA 安装目录>\\Lib\\site-packages\\ida_pro_mcp\\server.py"],
      "transport": "stdio",
      "lifecycle": "eager",
      "requestTimeoutMs": 180000
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--extension"],
      "env": { "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<你的token>" },
      "transport": "stdio"
    }
  }
}

---

四、⚠️ 关键约束：Tool/mcp/Tool/ 不可搬动

seep_mcp_server.py 内部硬编码了运行时目录：

BASE_DIR = os.path.dirname(os.path.abspath(__file__))   # = Tool/mcp/
TOOL_DIR = os.path.join(BASE_DIR, "Tool")               # = Tool/mcp/Tool/
SAFE_DIR = os.path.join(TOOL_DIR, "safe")               # = Tool/mcp/Tool/safe/
KB_DIR   = os.path.join(TOOL_DIR, "reverselab", "kb")   # = Tool/mcp/Tool/reverselab/kb

因此：

依赖	必须位于
radare2	Tool/mcp/Tool/safe/radare2/bin/
jadx	Tool/mcp/Tool/safe/jadx/bin/
apktool	Tool/mcp/Tool/safe/apktool/
Hook 模板	Tool/mcp/Tool/safe/hook-mcp/templates/
知识库	Tool/mcp/Tool/reverselab/kb/

搬走任何一个，对应的 MCP 工具就会失效。

---

五、验证 MCP 是否就绪

方法 1：跑自检脚本（推荐）

cd Desktop\Seep\setup
powershell -ExecutionPolicy Bypass -File .\verify.ps1

方法 2：在 pi 里问

你：seep_status 能跑吗？
pi：[返回 radare2 / jadx / apktool / 知识库 的就绪状态]

方法 3：手工检查

# 1. 配置无占位符残留
Select-String -Path "$env:USERPROFILE\.pi\agent\mcp.json" -Pattern "<[A-Z_]+>"

# 2. seep MCP 语法可解析
python -c "import ast; ast.parse(open(r'C:\...\Seep\Tool\mcp\seep_mcp_server.py',encoding='utf-8').read())"

# 3. 知识库在位
(Get-ChildItem "C:\...\Seep\Tool\mcp\Tool\reverselab\kb" -Recurse -Filter *.md).Count   # 期望 ≥289

---

六、工具 → MCP 依赖对照（排障用）

MCP 工具	依赖的目录 / 工具	缺失时的现象
seep_kb_*（4 个）	Tool/mcp/Tool/reverselab/kb/	检索返回空 / 报路径不存在
seep_r2_*（8 个）	Tool/mcp/Tool/safe/radare2/bin/	"radare2 not found"
seep_apk_decompile	Tool/mcp/Tool/safe/jadx/bin/	"jadx not found"
seep_apk_unpack	Tool/mcp/Tool/safe/apktool/	"apktool not found"
seep_apk_gen_hook	Tool/mcp/Tool/safe/hook-mcp/templates/	模板缺失
mcp_ida_*（~243 个）	自备 IDA Pro + Tool/mcp/Tool/safe/ida-pro-mcp/	"IDA not available"
playwright 工具	npx + token	浏览器不可用

排障口诀：工具报错 → 看它读哪个目录 → 检查该目录是否存在且非空。

---

七、IDA Pro 不可用时的降级路线

原则：不阻塞、不报错，直接用 seep_r2_* 继续推进。

需求	seep MCP 替代
架构 / 壳 / 熵 / 字符串	seep_r2_info · seep_r2_strings
反汇编 + 交叉引用	seep_r2_disasm · seep_r2_functions
类 C 伪代码	seep_r2_decompile
二进制差分	seep_r2_diff
汇编 ↔ 机器码	seep_r2_asm

报告中应标注："未使用 IDA 反编译器，伪代码质量受限"。

详见 MANUAL/IDA-PRO.md（含 3 种方案对比）。

---

八、可选注册的 MCP（默认关闭）

reverselab 自带 3 个 MCP，源码在 Tool/mcp/Tool/reverselab/tools/skills/mcp/， 默认不注册。需要时手工加入 mcp.json：

MCP	位置	用途
ReverseLabToolsMCP	.../mcp/ReverseLabToolsMCP/	reverselab 主 MCP（150+ 工具）
JSHookLocal	.../mcp/JSHookLocal/	JS Hook 本地服务
GhidraMCP	.../mcp/GhidraMCP/	Ghidra 桥接

注册示例：

"reverselab": {
  "command": "python",
  "args": ["<本包路径>\\Tool\\mcp\\Tool\\reverselab\\tools\\skills\\mcp\\ReverseLabToolsMCP\\reverse_lab_tools_mcp.py"],
  "cwd": "<本包路径>\\Tool\\mcp\\Tool\\reverselab",
  "transport": "stdio"
}

⚠️ 需先装其 Python 依赖（见该目录 requirements.txt）。

---

九、常见问题

问题	处理
pi 启动后 MCP 没加载	重启 pi（MCP 在启动时注册）
seep 工具全部不可用	检查 mcp.json 的 seep.args[0] 路径是否存在
seep_kb_* 报错	检查 Tool/mcp/Tool/reverselab/kb/ 是否 ≥289 篇
seep_r2_* 报错	重跑 setup\install-tools.ps1
ida 工具报错	确认 IDA 已装 + mcp.json 里 ida 路径正确
MCP 配置文件被我改坏了	重跑 setup\install-pi.ps1（会自动备份旧配置）
想看 MCP 报错日志	pi 启动时的 stderr；或手工 python Tool\mcp\seep_mcp_server.py 看输出

---

十、手工验证 seep MCP（不通过 pi）

cd Desktop\Seep\Tool\mcp
python seep_mcp_server.py
# 正常应挂起等待 stdio 输入（无报错即 OK）
# Ctrl+C 退出

若报 ModuleNotFoundError: mcp → 重跑 setup\install-python.ps1。