🚀 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
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: 命令行部署

npm install
npx wrangler pages deploy public --project-name=github-trending-service

📖 使用指南

1️⃣ REST API 使用

基础请求

# 获取今日热门项目（所有语言）
curl https://cloudflare-mcp1.zx1993.top/api/trending

按语言筛选

# 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"

按时间范围筛选

# 今日热门
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"

组合使用

# 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"

响应示例

{
  "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 中添加：

{
  "mcpServers": {
    "github-trending": {
      "type": "sse",
      "url": "https://cloudflare-mcp1.zx1993.top/mcp/message"
    }
  }
}

注意：虽然 type 设置为 sse，但 Kiro 会自动检测并使用 StreamableHTTP 传输方式。

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "github-trending": {
      "type": "sse",
      "url": "https://cloudflare-mcp1.zx1993.top/mcp/message"
    }
  }
}

配置后，AI 助手可以直接调用 get_trending_repos 工具查询热门项目。

3️⃣ GPT/Gemini Function Calling

获取 OpenAPI 规范

curl https://cloudflare-mcp1.zx1993.top/api/openapi.json

Python 示例（OpenAI GPT）

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 示例

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}`);
});

🛠️ 本地开发

安装依赖

npm install

启动开发服务器

npm run dev

访问 http://localhost:8788 查看效果。

本地测试 API

# 测试 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

快速部署

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 文件

🔗 相关链接

• Cloudflare Pages 文档
• Model Context Protocol (MCP)
• GitHub Trending
• OpenAPI Specification

---

Made with ❤️ | Powered by Cloudflare Pages