MCP Server Registry

MCP服务器注册表参与者

一个Apify actor，用于在GitHub、NPM和PyPI上发现、编目和删除模型上下文协议（MCP）服务器。

特性

• 多源报废：从GitHub、NPM注册表和PyPI发现MCP服务器
• 智能重复数据删除：合并多个源中发现的重复服务器
• 自动分类：根据功能将服务器分配到9+个类别
• 兼容性检测：确定AI客户端兼容性（Claude、OpenAI、Kiro等）
• 安装说明：生成安装命令和配置示例
• 费率限制处理：指数退避和自动重试逻辑
• 数据验证：具有详细错误记录的全面验证
• 增量更新：支持完整和增量数据收集模式

输入参数

源配置

来源 （字符串数组）

• 违约： ["github", "npm", "pypi"]
• 选项： "github", "npm", "pypi"
• 控制要抓取的数据源

更新模式

下载中 （枚举）

• 违约： "full"
• 选项： "full" （替换所有数据）或 "incremental" （与现有合并）
• 影响服务器与以前运行的合并方式

过滤

最大服务器数 （整数，可选）

• 限制要收集的服务器总数
• 适用于测试或部分运行

minStars （整数，可选，仅限GitHub）

• GitHub最低星数
• 过滤低参与度项目

内容选项

包括广告 （布尔值）

• 违约： true
• 控制是否获取和包含README内容

github代币 （字符串，可选，机密）

• GitHub API的个人访问令牌
• 将速率限制从每小时60个请求增加到5000个请求
• 建议用于生产运行

执行模式

运行模式 （枚举）

• 违约： "production"
• 选项： "test" （仅限于5台服务器）或 "production" （全程）

输出格式

参与者输出一个包含重复数据消除服务器记录的数据集：

{
  "name": "server-name",
  "description": "Server description",
  "version": "1.0.0",
  "sourceUrl": "https://npm.example.com/package/server-name",
  "sourceUrls": {
    "npm": "https://www.npmjs.com/package/server-name",
    "github": "https://github.com/user/server-name"
  },
  "stars": 150,
  "forks": 20,
  "downloads": {
    "npm": 5000,
    "pypi": 200
  },
  "license": "MIT",
  "author": "Author Name",
  "repository": "user/server-name",
  "keywords": ["mcp", "llm", "ai"],
  "readme": "# Server Name\nLong README content...",
  "lastUpdated": "2024-01-15T10:30:00Z",
  "isActive": true,
  "categories": ["AI & ML", "Integration & Orchestration"],
  "compatibility": [
    {
      "client": "Claude",
      "status": "likely",
      "notes": "Mentioned in documentation"
    }
  ],
  "installationInstructions": {
    "npm": {
      "command": "npm install server-name@1.0.0",
      "package": "server-name",
      "version": "1.0.0"
    },
    "pypi": [
      {
        "command": "pip install server-name==1.0.0",
        "package": "server-name",
        "version": "1.0.0"
      }
    ],
    "configExample": "{...}"
  },
  "normalizedName": "server-name"
}

元数据输出

运行元数据与密钥一起存储在键值存储中 run-metadata-{runId}:

{
  "runId": "uuid",
  "startedAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:30:00Z",
  "duration": 1800000,
  "totalServersFound": 250,
  "serversBySource": {
    "github": 120,
    "npm": 80,
    "pypi": 50
  },
  "duplicatesRemoved": 30,
  "serversByCategory": {
    "Database": 45,
    "File System": 30,
    "Web & API": 50
  },
  "rateLimitEvents": [
    {
      "source": "github",
      "timestamp": "2024-01-15T10:15:00Z",
      "message": "Rate limited...",
      "retryAfter": 60
    }
  ],
  "validationFailures": [],
  "errors": [],
  "updateMode": "full"
}

分类

参与者将服务器分为9类：

1. 数据库 -SQL、NoSQL、数据存储系统
2. 文件系统 -云存储、S3、blob存储
3. Web和API -HTTP、REST、fetch、URL处理
4. 代码与开发 -Git、GitHub、CI/CD、测试
5. AI和ML -机器学习、LLM、嵌入
6. 沟通 -Slack、电子邮件、webhooks、消息传递
7. 数据与分析 -分析、度量、可观察性
8. 云和基础设施 -AWS、Azure、GCP、Kubernetes
9. 集成与编排 -工作流程、自动化、流水线

速率限制和重试逻辑

GitHub API

• 速率限制：60个请求/小时（未经身份验证）或5000个/小时（经过身份验证）
• 重试延迟：60秒→ 120s → 300s（指数回退）

NPM注册表

• 速率限制：1000个请求/小时
• 429状态自动重试

PyPI

• 速率限制：1000个请求/小时
• 429状态自动重试

重复数据消除策略

参与者使用两层重复数据删除方法：

1. 标准化名称匹配：不区分大小写，删除特殊字符
2. 存储库URL匹配：首选存储库URL进行规范标识

当发现重复项时，演员：

• 更喜欢GitHub数据中的星型、分叉和最后提交日期
• 从NPM和PyPI下载的总和
• 保留更长/更详细的README
• 合并所有来源的源URL
• 使用最新版本号

用法示例

全扫描（默认）

{
  "sources": ["github", "npm", "pypi"],
  "updateMode": "full",
  "includeReadme": true
}

仅在GitHub上使用星型过滤器

{
  "sources": ["github"],
  "minStars": 50,
  "githubToken": "ghp_xxxxx"
}

测试运行

{
  "sources": ["github", "npm", "pypi"],
  "runMode": "test",
  "maxServers": 5
}

增量更新

{
  "sources": ["npm", "pypi"],
  "updateMode": "incremental",
  "maxServers": 100
}

本地运行

先决条件

• Node.js 16+
• npm或纱线

安装

npm install

构建

npm run build

发展

npm run dev

部署到Apify

npm install -g apify-cli
apify login
apify push

性能注意事项

• 记忆：已分配4 GB（可在中配置 .actor/actor.json)
• 超时：1小时（3600秒）
• 并发：每个来源限制为2-3个同时请求
• 数据集批量大小：每次写入操作100条记录

故障排除

速率限制

如果遇到速率限制错误：

1. 通过以下方式提供GitHub令牌 githubToken 输入
2. 增加超时时间 .actor/actor.json
3. 减少 maxServers 降低请求量

验证失败

检查 run-metadata 验证错误的输出：

• 缺少必填字段
• URL无效
• 畸形数据

缺失数据

• NPM：确保 includeReadme 未筛选预期的服务器
• GitHub：使用更高 maxServers 或删除 minStars 过滤器
• PyPI：受限于公共包搜索可用性

建筑

src/
├── main.ts              # Entry point and orchestration
├── types.ts             # Data models and interfaces
├── processor.ts         # Data validation and normalization
├── categorizer.ts       # Category assignment
├── compatibility.ts     # AI client detection
├── deduplicator.ts      # Duplicate detection and merging
├── installationGenerator.ts  # Instruction generation
└── scrapers/
    ├── github.ts        # GitHub repository scraper
    ├── npm.ts           # NPM registry scraper
    └── pypi.ts          # PyPI package scraper

文档

• 快速入门指南 -几分钟内起床跑步
• 测试指导 -全面的测试文档
• 实施总结 -架构和技术细节
• 故障排除指南 -常见问题和解决方案
• 部署检查表 -部署前验证

发展

设置

npm install
npm run build
npm test

脚本

• npm run build -编译TypeScript
• npm test -运行所有测试
• npm run test:watch -在监视模式下运行测试
• npm run test:coverage -生成测试覆盖率报告
• npm start -在本地运行演员
• npm run dev -以开发模式运行
• npm run lint -Lint源代码

项目结构

src/
├── main.ts                    # Actor entry point
├── types.ts                   # Data models
├── processor.ts               # Data validation
├── categorizer.ts             # Category assignment
├── compatibility.ts           # AI client detection
├── deduplicator.ts            # Duplicate handling
├── installationGenerator.ts   # Installation instructions
└── scrapers/                  # Source scrapers
    ├── github.ts
    ├── npm.ts
    └── pypi.ts

__tests__/                     # Unit tests

许可证

Apache 2.0

支持

对于问题或功能请求：

1. 检查 快速入门指南
2. 查看 测试指导
3. 请参阅 实施总结
4. 检查参与者日志并运行元数据