MCP 子域查找器服务器

<p align="center"> <img src="assets/logo.png" alt="MCP 子域查找器标志" width="400"> </p>

这是一个模型上下文协议（MCP）服务器，它封装了 ProjectDiscovery 的子域查找器，通过 JSON-RPC API 提供强大的子域枚举功能。

架构

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

致谢

所有子域枚举的繁重工作都是由 ProjectDiscovery 的子域查找器 完成的。这个项目只是在其优秀工具周围提供了一个 MCP 服务器封装。

概览

MCP 子域查找器服务器提供了：

• 用于给定域名枚举子域的 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

# 运行实时子域查找器测试
make live-test

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

# 格式化代码
make fmt

# 为 Linux 构建
make build-linux

# 清理项目
make clean

配置

为了获得最佳效果，请在 provider-config.yaml 文件中添加您的 API 密钥。这允许子域查找器使用高级来源以更好地发现子域。

当使用 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	字符串	要枚举其子域的域名（必需）	-
timeout	整数	枚举过程的超时时间（秒）	120
recursive	布尔值	是否递归检查发现的子域	false
maxDepth	整数	递归枚举的最大深度	2
sourcesFilter	字符串	要使用的来源的逗号分隔列表	-
excludeSourcesFilter	字符串	要排除的来源的逗号分隔列表	-

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