MCP Issue Crawlers

MCPC数据管道指南

该存储库承载了我们用来抓取模型上下文协议（MCP）源、规范化收集的存储库以及构建精心策划的问题数据集进行注释的工具。该项目有意采用模块化设计：每个阶段都会写入下一个脚本使用的JSON工件，因此您可以随时暂停/恢复或交换输入。

需求

• Python 3.9或更高版本（建议使用3.11以上版本） asyncio 演出
• 运行依赖Selenium的爬虫（Smithery、MCP Market、Cursor等）时，谷歌Chrome+匹配ChromeDriver
• 依赖关系来自 requirements.txt

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

环境变量

大多数脚本都与GitHub API对话。在运行长作业之前设置一次个人访问令牌：

export GITHUB_TOKEN=ghp_your_token_here  # Windows PowerShell: $env:GITHUB_TOKEN="..."

如果您需要特定于站点的API密钥（例如Smithery），请在调用相关的爬网程序之前以相同的方式设置它们。

存储库布局

engine/                   # Crawler implementations (servers + clients)
scripts/                  # Data-processing utilities
mcp_servers/              # Generated server metadata
分组数据/                  # Issue sampling & grouping outputs
config/                   # YAML configs for crawl targets

端到端工作流

1.抓取原始资源

使用统一的爬虫引擎来访问配置文件中定义的一个或多个数据源。

python -m engine.core.crawler_engine \
  --config config/sites_config.yaml \
  --sources smithery pulse awesome glama \
  --type servers

常见选项：

• --sources：空格分隔的子集。省略对所有已知来源的抓取。
• --type: servers, clients，或 all.
• --download-sources：收集元数据后立即下载每个存储库。
• --download-only：跳过爬行，只下载磁盘上已有的JSON的源代码。
• --categories-only / --categories-source：在不接触元数据的情况下重建类别标签。

每个来源都写 mcp_servers//.json （或 mcp_clients/... 对于客户端爬虫）。

2.汇总到主列表中

在筛选之前，将所有源目录合并到一个重复数据消除列表中：

python scripts/aggregate_servers.py

默认情况下，它会扫描下的每个子目录 mcp_servers/，规范GitHub URL，删除重复项，并写入 mcp_servers/servers_aggregate.json （加上每个来源的计数）。

3.过滤低信号存储库

scripts/filter_servers.py 为每个repo调用GitHub REST API，并强制执行简单的健康规则（最小活动、非模板、有README等）。

python scripts/filter_servers.py \
  --input mcp_servers/servers_aggregate.json \
  --output mcp_servers/servers_filtered.json \
  --resume

关键标志：

• --limit N：停止后 N 保留的存储库（有助于烟雾测试）。
• --resume：继续上一次运行中断的地方，使用 .progress.

排除的原因（例如。， abandoned_project, placeholder_repo)在输出JSON中进行了总结。

4.收集有意义的问题

scripts/collect_meaningful_issues.py 遍历筛选后的列表，对每个GitHub问题进行分页，并存储符合这两个规则的问题：

1. 至少两条评论，以及
2. 多个不同的参与者（问题作者和评论者）。

python scripts/collect_meaningful_issues.py \
  --resume \
  --input mcp_servers/servers_filtered.json \
  --output mcp_servers/servers_issues.json \
  --issues-per-repo 100 \
  --comments-per-issue 40

提示：

• 使用高 --issues-per-repo （最多100个）以减少分页开销。脚本会自动继续请求其他页面，直到页面返回的结果减少。
• --comments-per-issue 控制每期获取的前N条评论。如果您需要更大的参与者集，请增加它。
• 该脚本同时写入完整数据集和 .progress 检查点，这样您就可以在速率限制或网络故障后安全重启。

5.样品和小组问题

之后 servers_issues.json 准备好了，快跑 scripts/group_issues.py （a）划出一个采样子集，（b）可选地将其划分为标记组进行注释。

# Example: sample 663 issues, then create six 100-item groups + one 63-item group
python scripts/group_issues.py \
  --input mcp_servers/servers_issues.json \
  --output-dir 分组数据 \
  --sample-count 663 \
  --group-sizes 100,100,100,100,100,100,63 \
  --seed 42 \
  --sample-output 分组数据/sampled_servers_issues.json \
  --annotated-output 分组数据/annotated_servers_issues.json

您将获得：

• sampled_servers_issues.json：仅包含采样服务器/问题的独立数据集（带 sampled: true).
• annotated_servers_issues.json：原始输入内容丰富 sampled/group_assignment 标记，这样你就可以跟踪使用了什么。
• group_.json：每组一个文件，包含用于快速切换的扁平化问题元数据。

供应 --seed 保证可重复的采样/分组。如果您只需要没有分组的样本，请省略 --group-sizes 和 --groups/--size.

安全地恢复长期工作

• filter_servers.py 和 collect_meaningful_issues.py 两者都发射 .progress。删除进度文件会强制重新启动。
• collect_meaningful_issues.py --resume 还重新加载主输出JSON，以便在崩溃时保留部分结果。
• group_issues.py 除了在指向时添加注释外，不会更改源文件 --annotated-output 在同一条路上。如果你想保持原始的原始状态，请使用不同的路径。

故障排除和最佳实践

许可和贡献

内部项目——如果您计划发布工具包，请更新本节。欢迎添加新MCP源或改进过滤启发式的拉取请求。