# url-js-finder MCP Server

封装两个开源 URL/JS 信息提取工具为 MCP server，供 AI 全局调用（Reasonix `[[plugins]]` 注册）。

> 授权提醒：两个工具均为主动网络爬取工具，仅可用于**自有或已授权**目标（渗透测试、CTF、SRC）。

## 许可证

- 封装代码（server.py / SKILL.md / test_client.py 等）：MIT，见 [LICENSE](LICENSE)
- 上游工具：`third_party/URLFinder`（[pingc0y/URLFinder](https://github.com/pingc0y/URLFinder)，MIT）与
  `third_party/JSFinder`（[Threezh1/JSFinder](https://github.com/Threezh1/JSFinder)），各自 LICENSE 随源码保留。

## 封装对象

| 工具 | 上游 | 技术栈 | 能力 |
|------|------|--------|------|
| URLFinder | https://github.com/pingc0y/URLFinder | Go（已编译 `bin/URLFinder.exe`） | 页面信息提取：URL / JS / 敏感信息 / 子域名；状态码过滤、深入抓取、404 目录 fuzz |
| JSFinder | https://github.com/Threezh1/JSFinder | Python（`third_party/JSFinder/JSFinder.py`） | 从页面/JS 文件中提取 URL 与子域名；深度爬取 |

## 目录结构

```
url-js-finder/
├── server.py            # MCP server 入口（FastMCP，stdio）
├── requirements.txt     # mcp>=1.26,<2
├── README.md
├── bin/
│   └── URLFinder.exe    # URLFinder 编译产物（Go 1.26，-s -w，Update=dev 禁更新检查）
└── third_party/
    ├── URLFinder/       # 上游源码（git clone --depth 1）
    └── JSFinder/        # 上游源码（单文件 JSFinder.py，依赖 requests+bs4）
```

## MCP 工具

### `urlfinder_scan` — URLFinder 页面信息提取

扫描单个 URL 或批量 URL 文件，返回：域名列表、主域 URL、其他域 URL、JS 链接、敏感信息、fuzz 结果。

关键参数：`url` / `batch_file`（二选一）、`status_codes`（如 `200,403` 或 `all`）、
`mode`（1 正常 / 2 深入 / 3 安全深入）、`domain_regex`、`cookie`、`user_agent`、`proxy`、
`timeout`、`threads`、`max_links`、`fuzz`（1/2/3）、`export_dir`、`run_timeout`。

### `jsfinder_scan` — JSFinder JS 提取

扫描页面 URL 或 URL/JS 列表文件，返回：URL 列表、子域名列表。

关键参数：`url` / `file`（二选一）、`is_js_file`、`deep`（深度爬取）、`cookie`、`run_timeout`。

## 使用注意

- **授权**：两个工具均为主动网络爬取工具，仅可用于自有/已授权目标。
- **速度**：`status_codes` 验证与 `deep` 深度爬取显著耗时；大目标先试 `mode=1`。
- **返回**：所有工具返回 JSON 字符串（UTF-8，`ensure_ascii=False`），可直接结构化解析。
- **超时**：`run_timeout` 控制整个扫描进程超时，超时返回明确 error 信息。

## 自测

```
python test_client.py
```

## 重新编译 URLFinder（可选）

```bash
cd third_party/URLFinder
go build -ldflags "-s -w -X github.com/pingc0y/URLFinder/cmd.Update=dev" -o ../../bin/URLFinder.exe .
```

## 配置注册（Reasonix config.toml）

```toml
[[plugins]]
name    = "url-js-finder"
command = "python"
args    = ["<HOME>\\skills\\mcp\\url-js-finder\\server.py"]
```