README.md•9.9 kB
# 🚀 GitHub Trending Service
一个部署在 Cloudflare Pages 上的 GitHub 热门项目服务，提供 REST API 和 MCP 协议支持，让 AI 助手能够实时获取 GitHub 热门项目数据。
## ✨ 功能特性
- 🔥 **REST API** - 标准 HTTP API，获取 GitHub Trending 项目数据
- 🤖 **MCP Server** - 支持 Model Context Protocol，让 AI 助手（Claude Desktop/Kiro）直接查询
- 📄 **OpenAPI Spec** - 完整的 OpenAPI 3.0 规范，支持 GPT/Gemini Function Calling
- ⚡ **KV 缓存** - 使用 Cloudflare KV 缓存数据，减少 GitHub 请求，提升响应速度
- 🌍 **全球 CDN** - 部署在 Cloudflare 边缘网络，全球访问快速
- 🔄 **自动部署** - GitHub 推送自动触发部署，无需手动操作
## 🌐 在线服务
- **主页**: https://cloudflare-mcp1.zx1993.top
- **REST API**: https://cloudflare-mcp1.zx1993.top/api/trending
- **OpenAPI 规范**: https://cloudflare-mcp1.zx1993.top/api/openapi.json
- **MCP 端点**: https://cloudflare-mcp1.zx1993.top/mcp/message
## 项目结构
```
├── functions/
│ ├── api/
│ │ ├── trending.ts # GET /api/trending
│ │ └── openapi.json.ts # GET /api/openapi.json
│ ├── mcp/
│ │ ├── sse.ts # GET /mcp/sse (MCP 连接)
│ │ └── message.ts # POST /mcp/message (MCP 消息)
│ └── _middleware.ts # 全局中间件
├── public/
│ └── index.html # 首页
├── wrangler.toml
└── package.json
```
## 部署方式
### 方式 1: GitHub 自动部署 (推荐)
1. 将代码推送到 GitHub 仓库
2. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com)
3. 进入 **Workers & Pages** → **Create** → **Pages** → **Connect to Git**
4. 选择你的 GitHub 仓库
5. 配置构建设置:
- Build command: `npm run build`
- Build output directory: `public`
6. 点击 **Save and Deploy**
每次 push 到 main 分支会自动部署。
### 方式 2: 命令行部署
```bash
npm install
npx wrangler pages deploy public --project-name=github-trending-service
```
## 📖 使用指南
### 1️⃣ REST API 使用
#### 基础请求
```bash
# 获取今日热门项目（所有语言）
curl https://cloudflare-mcp1.zx1993.top/api/trending
```
#### 按语言筛选
```bash
# Python 项目
curl "https://cloudflare-mcp1.zx1993.top/api/trending?language=python"
# JavaScript 项目
curl "https://cloudflare-mcp1.zx1993.top/api/trending?language=javascript"
# Go 项目
curl "https://cloudflare-mcp1.zx1993.top/api/trending?language=go"
# Rust 项目
curl "https://cloudflare-mcp1.zx1993.top/api/trending?language=rust"
```
#### 按时间范围筛选
```bash
# 今日热门
curl "https://cloudflare-mcp1.zx1993.top/api/trending?since=daily"
# 本周热门
curl "https://cloudflare-mcp1.zx1993.top/api/trending?since=weekly"
# 本月热门
curl "https://cloudflare-mcp1.zx1993.top/api/trending?since=monthly"
```
#### 组合使用
```bash
# Rust 本月热门
curl "https://cloudflare-mcp1.zx1993.top/api/trending?language=rust&since=monthly"
# TypeScript 本周热门
curl "https://cloudflare-mcp1.zx1993.top/api/trending?language=typescript&since=weekly"
```
#### 响应示例
```json
{
"data": [
{
"rank": 1,
"username": "owner",
"reponame": "repo-name",
"url": "https://github.com/owner/repo-name",
"description": "项目描述",
"language": "Python",
"stars": 12345,
"forks": 678,
"starsToday": 1234
}
],
"cached": true,
"language": "python",
"since": "daily"
}
```
### 2️⃣ MCP 配置（AI 客户端使用）
#### Kiro IDE
在 `.kiro/settings/mcp.json` 中添加：
```json
{
"mcpServers": {
"github-trending": {
"type": "sse",
"url": "https://cloudflare-mcp1.zx1993.top/mcp/message"
}
}
}
```
> 注意：虽然 `type` 设置为 `sse`，但 Kiro 会自动检测并使用 StreamableHTTP 传输方式。
#### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"github-trending": {
"type": "sse",
"url": "https://cloudflare-mcp1.zx1993.top/mcp/message"
}
}
}
```
配置后，AI 助手可以直接调用 `get_trending_repos` 工具查询热门项目。
### 3️⃣ GPT/Gemini Function Calling
#### 获取 OpenAPI 规范
```bash
curl https://cloudflare-mcp1.zx1993.top/api/openapi.json
```
#### Python 示例（OpenAI GPT）
```python
import openai
import requests
# 定义工具
tools = [{
"type": "function",
"function": {
"name": "get_trending_repos",
"description": "获取 GitHub 热门项目",
"parameters": {
"type": "object",
"properties": {
"language": {
"type": "string",
"description": "编程语言，如 python, javascript"
},
"since": {
"type": "string",
"enum": ["daily", "weekly", "monthly"],
"description": "时间范围"
}
}
}
}
}]
# 调用 GPT
response = openai.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "最近有什么热门的 Python 项目？"}],
tools=tools
)
# 当 GPT 调用 function 时，请求 API
if response.choices[0].message.tool_calls:
result = requests.get(
"https://cloudflare-mcp1.zx1993.top/api/trending",
params={"language": "python"}
).json()
# 将结果返回给 GPT 继续对话
```
#### JavaScript 示例
```javascript
const response = await fetch(
'https://cloudflare-mcp1.zx1993.top/api/trending?language=python&since=weekly'
);
const data = await response.json();
console.log(`找到 ${data.data.length} 个热门项目`);
data.data.forEach(repo => {
console.log(`${repo.rank}. ${repo.username}/${repo.reponame} - ⭐ ${repo.starsToday}`);
});
```
## 🛠️ 本地开发
### 安装依赖
```bash
npm install
```
### 启动开发服务器
```bash
npm run dev
```
访问 http://localhost:8788 查看效果。
### 本地测试 API
```bash
# 测试 REST API
curl http://localhost:8788/api/trending
# 测试 OpenAPI
curl http://localhost:8788/api/openapi.json
```
## 🔧 技术栈
- **运行时**: Cloudflare Pages Functions
- **语言**: TypeScript
- **协议**: HTTP REST API + MCP (Model Context Protocol)
- **缓存**: Cloudflare KV
- **部署**: GitHub Actions 自动部署
## 📊 API 参数说明
### GET /api/trending
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `language` | string | 否 | all | 编程语言（如 python, javascript, go, rust, typescript 等） |
| `since` | string | 否 | daily | 时间范围：`daily`（今日）、`weekly`（本周）、`monthly`（本月） |
### 响应字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `data` | array | 热门项目列表 |
| `data[].rank` | number | 排名 |
| `data[].username` | string | 项目所有者 |
| `data[].reponame` | string | 项目名称 |
| `data[].url` | string | 项目 URL |
| `data[].description` | string | 项目描述 |
| `data[].language` | string | 主要编程语言 |
| `data[].stars` | number | 总星标数 |
| `data[].forks` | number | 总 Fork 数 |
| `data[].starsToday` | number | 时间段内新增星标数 |
| `cached` | boolean | 是否来自缓存 |
| `language` | string | 筛选的语言 |
| `since` | string | 时间范围 |
## 🎯 MCP 工具说明
配置 MCP 后，AI 助手可以使用以下工具：
### get_trending_repos
获取 GitHub 热门项目。
**参数**:
- `language` (可选): 编程语言筛选
- `since` (可选): 时间范围（daily/weekly/monthly）
**示例对话**:
- "最近有什么热门的 Python 项目？"
- "本周 JavaScript 有哪些热门仓库？"
- "给我看看本月 Rust 的热门项目"
## 🚀 部署到你自己的 Cloudflare
详细部署步骤请查看 [DEPLOY.md](./DEPLOY.md)
### 快速部署
1. Fork 本仓库
2. 在 Cloudflare Dashboard 连接你的 GitHub 仓库
3. 配置构建命令：`npm run build`
4. 部署完成！
## 🔐 可选配置
### KV 缓存（推荐）
启用 KV 缓存可以：
- 减少对 GitHub 的请求频率
- 提升 API 响应速度
- 避免触发 GitHub 速率限制
**配置步骤**:
1. Cloudflare Dashboard → Workers & Pages → KV
2. 创建 Namespace，名称：`TRENDING_CACHE`
3. 进入 Pages 项目 → Settings → Functions → KV namespace bindings
4. 添加绑定：Variable name = `TRENDING_CACHE`
缓存时效：1 小时
### 自定义域名
1. 进入 Pages 项目 → Custom domains
2. 添加你的域名
3. 按提示配置 DNS 记录
## 📝 常见问题
### Q: API 返回空数据或错误？
A: 可能是 GitHub 临时限制了请求。建议配置 KV 缓存，或稍后重试。
### Q: MCP 连接失败？
A: 确认 URL 正确使用 `https://` 协议，路径为 `/mcp/message`。如果遇到 CORS 或超时问题，请检查服务端的 CORS 配置是否正确。
### Q: 如何查看日志？
A: Cloudflare Dashboard → 你的项目 → Functions → Logs
### Q: 支持哪些编程语言？
A: 支持 GitHub 上所有编程语言，常见的如：python, javascript, typescript, go, rust, java, c++, c#, php, ruby, swift, kotlin 等。
### Q: 数据更新频率？
A: 启用缓存后每小时更新一次，未启用缓存则实时获取。
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 📄 License
MIT License - 详见 [LICENSE](./LICENSE) 文件
## 🔗 相关链接
- [Cloudflare Pages 文档](https://developers.cloudflare.com/pages/)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [GitHub Trending](https://github.com/trending)
- [OpenAPI Specification](https://swagger.io/specification/)
---
**Made with ❤️ | Powered by Cloudflare Pages**