MCP Subfinder 服务器

<p align="center"> <img src="assets/logo.png" alt="MCP Subfinder Logo" width="400"> </p>

一个模型上下文协议 (MCP) 服务器，它封装了 ProjectDiscovery 的 subfinder 工具，通过 JSON-RPC API 实现强大的子域名枚举。

架构

flowchart LR
    Client([客户端]) -->|JSON-RPC| MCP[MCP 服务器]
    MCP -->|初始化/工具列表| Client
    MCP -->|处理请求| SF[Subfinder 封装器]
    SF -->|配置| CFG[provider-config.yaml]
    SF -->|调用| PD[ProjectDiscovery Subfinder]
    PD -->|被动源| API1[公共 & 私有 API]
    PD -->|结果| SF
    SF -->|处理后的结果| MCP
    MCP -->|JSON 响应| Client

鸣谢

子域名枚举的所有繁重工作都由 ProjectDiscovery 的 subfinder 完成。 这个项目只是他们优秀工具的 MCP 服务器封装器。

概述

MCP Subfinder 服务器提供：

• 用于枚举给定域名的子域名的 JSON-RPC API
• 支持递归子域名发现
• 源过滤功能
• 可配置的超时和线程
• 用于故障排除的详细日志记录

安装

# 克隆仓库
git clone https://github.com/copyleftdev/mcp-subfinder-server.git
cd mcp-subfinder-server

# 使用 Makefile 构建服务器
make build

用法

可以使用 Makefile 运行服务器，它提供了几个有用的命令：

# 在默认端口 (8080) 上运行服务器
make run

# 在自定义端口上运行服务器
PORT=9090 make run

# 指定不同的提供程序配置文件
PROVIDER_CONFIG=my-custom-config.yaml make run

可用的 Makefile 命令

# 显示所有可用命令
make help

# 运行测试
make test

# 运行集成测试
make integration-test

# 运行实时 subfinder 测试
make live-test

# 生成测试覆盖率报告
make coverage

# 格式化代码
make fmt

# 为 Linux 构建
make build-linux

# 清理项目
make clean

配置

为了获得最佳结果，请将您的 API 密钥添加到 provider-config.yaml 文件中。 这允许 subfinder 使用高级源以获得更好的子域名发现。

使用 make run 运行服务器时，会自动检查 provider-config.yaml 文件。

API 用法

服务器在 http://localhost:8080/mcp 公开一个 JSON-RPC API。

使用 curl 的基本用法示例

1. 初始化连接

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "0.3"
    }
  }'

2. 列出可用工具

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools.list"
  }'

3. 基本子域名枚举

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools.call",
    "params": {
      "name": "enumerateSubdomains",
      "arguments": {
        "domain": "example.com"
      }
    }
  }'

4. 高级子域名枚举

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools.call",
    "params": {
      "name": "enumerateSubdomains",
      "arguments": {
        "domain": "example.com",
        "timeout": 120,
        "recursive": true,
        "maxDepth": 2,
        "sourcesFilter": "github,dnsdumpster,alienvault"
      }
    }
  }'

5. 使用源排除进行枚举

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools.call",
    "params": {
      "name": "enumerateSubdomains",
      "arguments": {
        "domain": "example.com",
        "timeout": 60,
        "excludeSourcesFilter": "waybackarchive,threatcrowd"
      }
    }
  }'

6. 健康检查

curl -X GET http://localhost:8080/health

可用选项

调用 enumerateSubdomains 工具时，可以使用以下选项：

选项	类型	描述	默认值
domain	string	要枚举子域名的域名（必需）	-
timeout	int	枚举过程的超时时间（秒）	120
recursive	bool	是否递归检查发现的子域名	false
maxDepth	int	递归枚举的最大深度	2
sourcesFilter	string	要使用的源的逗号分隔列表	-
excludeSourcesFilter	string	要排除的源的逗号分隔列表	-

Docker 支持

该项目通过 Makefile 包含 Docker 支持：

# 构建 Docker 镜像
make docker

# 在 Docker 中运行服务器
make docker-run

# 使用自定义端口运行
PORT=9090 make docker-run

测试

使用 Makefile 运行测试：

# 运行所有测试
make test

# 运行测试覆盖率
make coverage

docs 文件夹中包含一个 Postman 集合，用于轻松测试所有 API 端点。

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

作者

copyleftdev