@npm_xiyuan/mcp-github-trending 1.1.1

package/README_CN.md

@@ -0,0 +1,527 @@
+[English](./README.md) | 简体中文
+
+# GitHub Trending MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@npm_xiyuan/mcp-github-trending.svg)](https://www.npmjs.com/package/@npm_xiyuan/mcp-github-trending)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-1.0-orange.svg)](https://modelcontextprotocol.io)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+一个基于 Model Context Protocol (MCP) 的服务器，为 AI 应用（如 Claude Code）提供实时访问 GitHub 热门仓库和开发者数据的能力。
+
+## ✨ 核心特性
+
+- 🚀 **实时数据** - 直接从 GitHub 获取最新的热门趋势
+- 🔍 **智能搜索** - 支持关键词模糊匹配和语言过滤
+- 📊 **详细统计** - 获取仓库的 stars、forks、topics 等完整信息
+- 👥 **开发者追踪** - 追踪热门开发者及其代表作品
+- ⚡ **轻量高效** - 基于 cheerio 的快速数据抓取
+- 🔧 **零配置** - 安装即用，无需额外设置
+- 🤖 **AI 原生** - 专为 Claude Code 等 AI 工具设计
+
+## 🚀 快速开始
+
+### 系统要求
+
+- Node.js 18.0.0 或更高版本
+- 可访问 github.com 的网络连接
+
+### 安装
+
+使用 npm 全局安装：
+
+```bash
+npm install -g @npm_xiyuan/mcp-github-trending
+```
+
+或使用 npx 直接运行（推荐）：
+
+```bash
+npx @npm_xiyuan/mcp-github-trending
+```
+
+## ⚙️ Claude Code 配置
+
+### 配置位置
+
+根据你使用的 Claude 客户端，配置文件位置不同：
+
+| 客户端 | 配置文件路径 |
+|--------|-------------|
+| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
+| **Claude Code CLI** | `~/.claude/settings.json` |
+
+### 基础配置
+
+编辑配置文件，添加 MCP 服务器配置：
+
+```json
+{
+  "mcpServers": {
+    "github-trending": {
+      "command": "npx",
+      "args": ["-y", "@npm_xiyuan/mcp-github-trending"]
+    }
+  }
+}
+```
+
+### 配置说明
+
+- **服务器名称**: `github-trending` 可自定义，用于在 Claude 中识别此服务
+- **command**: 使用 `npx` 确保始终运行最新版本
+- **args**: 
+  - `-y`: 自动确认安装，避免交互式提示
+  - 包名: `@npm_xiyuan/mcp-github-trending`
+
+### 验证配置
+
+重启 Claude 客户端后，你可以通过以下方式验证配置是否成功：
+
+1. 在 Claude 中询问：`"帮我查看 GitHub 今日热门项目"`
+2. 如果配置成功，Claude 会自动调用 MCP 工具获取数据
+
+## 📦 MCP 工具能力说明
+
+本服务提供 9 个 MCP 工具，可在 Claude Code 中直接调用：
+
+### 1. get_trending_repos - 获取热门仓库
+
+**功能描述**: 获取 GitHub 上的热门仓库列表，支持按时间范围和编程语言筛选。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `since` | string | 否 | `"weekly"` | 时间范围：`"daily"` (今日)、`"weekly"` (本周)、`"monthly"` (本月) |
+| `language` | string | 否 | - | 编程语言过滤，如 `"python"`, `"javascript"`, `"rust"` |
+| `limit` | number | 否 | `10` | 返回结果数量，建议 1-25 |
+
+**返回数据**:
+```json
+[
+  {
+    "name": "owner/repo-name",
+    "url": "https://github.com/owner/repo-name",
+    "description": "项目描述",
+    "stars": "1,234 stars today"
+  }
+]
+```
+
+**使用场景**:
+- 发现最新的热门开源项目
+- 了解特定编程语言的流行趋势
+- 学习和研究优秀代码库
+
+### 2. get_trending_developers - 获取热门开发者
+
+**功能描述**: 获取 GitHub 上的热门开发者列表及其代表作品。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `since` | string | 否 | `"weekly"` | 时间范围：`"daily"`, `"weekly"`, `"monthly"` |
+| `language` | string | 否 | - | 编程语言过滤 |
+| `limit` | number | 否 | `10` | 返回结果数量 |
+
+**返回数据**:
+```json
+[
+  {
+    "name": "开发者名称",
+    "username": "github-username",
+    "url": "https://github.com/username",
+    "avatar": "头像URL",
+    "popularRepo": {
+      "name": "代表性仓库",
+      "description": "仓库描述",
+      "url": "仓库链接"
+    }
+  }
+]
+```
+
+**使用场景**:
+- 关注活跃的优秀开发者
+- 发现某个领域的技术专家
+- 寻找学习榜样和合作对象
+
+### 3. search_trending - 搜索热门仓库
+
+**功能描述**: 在热门仓库列表中按关键词搜索，支持名称和描述的模糊匹配。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `keyword` | string | **是** | - | 搜索关键词（不区分大小写） |
+| `since` | string | 否 | `"weekly"` | 时间范围 |
+| `language` | string | 否 | - | 编程语言过滤 |
+
+**返回数据**: 与 `get_trending_repos` 相同的格式
+
+**使用场景**:
+- 快速找到特定技术栈的热门项目
+- 搜索特定功能或领域的开源解决方案
+- 精准定位感兴趣的项目类型
+
+### 4. get_repo_details - 获取仓库详情
+
+**功能描述**: 获取指定 GitHub 仓库的详细统计信息和元数据。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `owner` | string | **是** | - | 仓库所有者（用户名或组织名） |
+| `repo` | string | **是** | - | 仓库名称 |
+
+**返回数据**:
+```json
+{
+  "name": "仓库名称",
+  "fullName": "owner/repo",
+  "description": "仓库描述",
+  "url": "https://github.com/owner/repo",
+  "stars": 12345,
+  "forks": 678,
+  "watchers": 890,
+  "language": "JavaScript",
+  "topics": ["react", "typescript", "ui"],
+  "createdAt": "2023-01-01",
+  "updatedAt": "2024-06-05",
+  "license": "MIT"
+}
+```
+
+**使用场景**:
+- 深入了解特定项目的详细信息
+- 评估项目的活跃度和受欢迎程度
+- 获取项目的技术栈和主题标签
+
+### 5. analyze_repo - 项目综合分析
+
+**功能描述**: 一次性获取 GitHub 项目的完整分析报告，包括 README、依赖、目录结构和最近提交。这是最强大的分析工具，适合快速了解陌生项目。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `owner` | string | **是** | 仓库所有者 |
+| `repo` | string | **是** | 仓库名称 |
+
+**返回数据**:
+```json
+{
+  "basic": {
+    "fullName": "owner/repo",
+    "stars": 12345,
+    "language": "TypeScript",
+    "topics": ["react", "typescript"]
+  },
+  "readme": {
+    "content": "# Project Title\n...",
+    "size": 5432
+  },
+  "structure": {
+    "rootFiles": ["package.json", "README.md"],
+    "directories": ["src", "test", "docs"]
+  },
+  "dependencies": {
+    "detected": true,
+    "packageManager": "npm/yarn/pnpm",
+    "file": "package.json",
+    "content": "{...}"
+  },
+  "recentActivity": {
+    "commits": [...],
+    "lastCommitDate": "2024-06-05"
+  }
+}
+```
+
+**使用场景**:
+- 快速了解一个陌生项目的用途和技术栈
+- 评估项目的活跃度和维护状态
+- 获取项目完整的技术背景信息
+
+### 6. get_repo_readme - 获取 README
+
+**功能描述**: 获取 GitHub 仓库的 README.md 原始 Markdown 内容。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `owner` | string | **是** | 仓库所有者 |
+| `repo` | string | **是** | 仓库名称 |
+
+**使用场景**:
+- 阅读项目文档了解使用方法
+- 提取项目介绍和功能说明
+
+### 7. get_repo_file - 获取文件内容
+
+**功能描述**: 获取 GitHub 仓库中指定文件的原始内容。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `owner` | string | **是** | 仓库所有者 |
+| `repo` | string | **是** | 仓库名称 |
+| `path` | string | **是** | 文件路径，如 "package.json" |
+
+**使用场景**:
+- 查看配置文件（package.json, requirements.txt）
+- 读取代码文件了解实现细节
+
+### 8. get_repo_structure - 获取目录结构
+
+**功能描述**: 获取 GitHub 仓库的目录和文件列表。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `owner` | string | **是** | - | 仓库所有者 |
+| `repo` | string | **是** | - | 仓库名称 |
+| `path` | string | 否 | `""` | 目录路径（空为根目录） |
+
+**使用场景**:
+- 了解项目的文件组织结构
+- 浏览特定目录下的文件
+
+### 9. get_repo_commits - 获取提交历史
+
+**功能描述**: 获取 GitHub 仓库的最近提交记录。
+
+**参数说明**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `owner` | string | **是** | - | 仓库所有者 |
+| `repo` | string | **是** | - | 仓库名称 |
+| `limit` | number | 否 | `10` | 返回数量 |
+
+**使用场景**:
+- 了解项目的最近开发动态
+- 查看项目的提交频率和活跃度
+
+## 💡 使用示例
+
+### 示例 1：查看今日热门项目
+
+在 Claude Code 中询问：
+
+```
+帮我查看 GitHub 今日热门项目 top 10
+```
+
+Claude 会自动调用 `get_trending_repos` 工具，返回今日最热门的 10 个项目。
+
+### 示例 2：搜索特定技术栈
+
+```
+帮我找找最近有哪些热门的 Rust 项目
+```
+
+Claude 会使用 `language: "rust"` 参数筛选 Rust 相关的热门项目。
+
+### 示例 3：关键词搜索
+
+```
+搜索 GitHub 热门项目中关于 AI agent 的项目
+```
+
+Claude 会调用 `search_trending` 工具，在热门列表中搜索包含 "AI agent" 关键词的项目。
+
+### 示例 4：获取仓库详情
+
+```
+帮我查看 microsoft/vscode 这个仓库的详细信息
+```
+
+Claude 会调用 `get_repo_details` 获取该仓库的 stars、forks、技术栈等完整信息。
+
+### 示例 5：分析 GitHub 项目
+
+```
+帮我分析一下 https://github.com/microsoft/vscode 这个项目
+```
+
+Claude 会调用 `analyze_repo` 工具，一次性返回项目的完整分析报告，包括：
+- 项目基本信息（stars、语言、主题标签）
+- README 内容
+- 项目结构（根目录文件和主要目录）
+- 依赖管理（package.json 等配置文件）
+- 最近的提交记录
+
+这是最强大和便捷的项目分析方式，适合快速了解陌生项目。
+
+### 示例 6：查看热门开发者
+
+```
+帮我看看本周 GitHub 上的热门 Python 开发者
+```
+
+Claude 会调用 `get_trending_developers` 工具，返回本周最活跃的 Python 开发者列表及其代表作品。
+
+### 示例 7：读取项目 README
+
+```
+帮我读取 facebook/react 的 README 文档
+```
+
+Claude 会调用 `get_repo_readme` 工具，获取 React 项目的完整 README.md 内容，方便了解项目的使用说明和功能介绍。
+
+### 示例 8：查看配置文件
+
+```
+帮我查看 vercel/next.js 项目的 package.json 文件
+```
+
+Claude 会调用 `get_repo_file` 工具，获取 Next.js 项目的 package.json 文件内容，可以了解项目的依赖和脚本配置。
+
+### 示例 9：查看项目结构
+
+```
+帮我看看 nodejs/node 项目的根目录结构
+```
+
+Claude 会调用 `get_repo_structure` 工具，返回 Node.js 项目的根目录文件和文件夹列表，帮助理解项目的组织架构。
+
+### 示例 10：查看提交历史
+
+```
+帮我查看 denoland/deno 项目最近5次提交记录
+```
+
+Claude 会调用 `get_repo_commits` 工具，返回 Deno 项目最近5次提交的详细信息，包括提交者、提交时间和提交说明。
+
+## 🎯 最佳实践
+
+### 性能优化建议
+
+1. **合理使用时间范围**: 
+   - 日常浏览使用 `weekly` (本周)
+   - 快速了解最新动态使用 `daily` (今日)
+   - 长期趋势分析使用 `monthly` (本月)
+
+2. **精准语言过滤**: 
+   - 指定编程语言可大幅减少无关结果
+   - 支持的语言示例: `python`, `javascript`, `typescript`, `rust`, `go`, `java`
+
+3. **控制返回数量**: 
+   - 默认返回 10 条结果，可根据需求调整
+   - 建议不超过 25 条，避免过多数据影响响应速度
+
+### 在 Claude Code 中的应用场景
+
+- **技术选型**: 快速了解某个领域当前最流行的技术方案
+- **学习资源**: 发现高质量的开源项目用于学习
+- **竞品分析**: 追踪同类产品的开源实现
+- **技术趋势**: 观察新兴技术和编程语言的热度变化
+- **开发者关系**: 寻找优秀的开发者和潜在的合作伙伴
+
+## 🔧 故障排除
+
+### 常见问题
+
+**Q: Claude 无法识别 MCP 工具？**
+
+A: 请检查：
+1. 配置文件路径是否正确
+2. JSON 格式是否有效（使用 JSON 验证器检查）
+3. 是否已重启 Claude 客户端
+4. 使用 `npx -y @npm_xiyuan/mcp-github-trending` 确保包可正常运行
+
+**Q: 返回数据为空或不完整？**
+
+A: 可能原因：
+1. GitHub trending 页面结构变化（等待包更新）
+2. 网络连接问题（检查是否能访问 github.com）
+3. 选择的语言或时间范围没有热门项目
+
+**Q: 如何更新到最新版本？**
+
+A: 使用 npx 会自动使用最新版本。如果全局安装，运行：
+```bash
+npm update -g @npm_xiyuan/mcp-github-trending
+```
+
+## 🛠️ 开发指南
+
+### 本地开发
+
+```bash
+# 克隆项目
+git clone https://github.com/jiyi1990118/mcp-github-trending.git
+cd mcp-github-trending
+
+# 安装依赖
+npm install
+
+# 构建项目
+npm run build
+
+# 本地测试
+npm start
+```
+
+### 目录结构
+
+```
+nodejs/
+├── src/
+│   ├── index.ts          # MCP 服务器入口
+│   ├── tools.ts          # 工具定义
+│   └── scraper.ts        # GitHub 数据抓取逻辑
+├── package.json
+└── tsconfig.json
+```
+
+### 技术栈
+
+- **MCP SDK**: `@modelcontextprotocol/sdk` - Model Context Protocol 实现
+- **HTTP 客户端**: `node-fetch` - 发起 HTTP 请求
+- **HTML 解析**: `cheerio` - 轻量级的服务器端 jQuery 实现
+- **TypeScript**: 类型安全的 JavaScript 超集
+
+### 贡献指南
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+## 📄 许可证
+
+本项目基于 MIT 许可证开源 - 查看 [LICENSE](./LICENSE) 文件了解详情。
+
+## 🔗 相关链接
+
+- [GitHub 仓库](https://github.com/jiyi1990118/mcp-github-trending)
+- [npm 包地址](https://www.npmjs.com/package/@npm_xiyuan/mcp-github-trending)
+- [Model Context Protocol 文档](https://modelcontextprotocol.io)
+- [Claude Desktop 下载](https://claude.ai/download)
+- [GitHub Trending 页面](https://github.com/trending)
+
+## 📮 反馈与支持
+
+如有问题或建议，欢迎通过以下方式联系：
+
+- 提交 GitHub Issue
+- 发起 Pull Request
+- 在 npm 页面留言
+
+---
+
+**注意**: 本项目通过爬取 GitHub Trending 页面获取数据，非官方 API。如 GitHub 调整页面结构可能影响功能，请及时更新到最新版本。
+

package/dist/github-api.js

@@ -0,0 +1,83 @@
+import fetch from 'node-fetch';
+export async function fetchRepoReadme(owner, repo) {
+    const url = `https://api.github.com/repos/${owner}/${repo}/readme`;
+    const response = await fetch(url, {
+        headers: { 'Accept': 'application/vnd.github.raw' }
+    });
+    if (!response.ok)
+        throw new Error(`README not found: ${response.status}`);
+    return await response.text();
+}
+export async function fetchRepoFile(owner, repo, path) {
+    const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
+    const response = await fetch(url, {
+        headers: { 'Accept': 'application/vnd.github.raw' }
+    });
+    if (!response.ok)
+        throw new Error(`File not found: ${path}`);
+    return await response.text();
+}
+export async function fetchRepoStructure(owner, repo, path = '') {
+    const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
+    const response = await fetch(url, {
+        headers: { 'Accept': 'application/json' }
+    });
+    if (!response.ok)
+        throw new Error(`Path not found: ${path}`);
+    return await response.json();
+}
+export async function fetchRepoCommits(owner, repo, limit = 10) {
+    const url = `https://api.github.com/repos/${owner}/${repo}/commits?per_page=${limit}`;
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error('Failed to fetch commits');
+    return (await response.json());
+}
+export async function analyzeRepo(owner, repo, fetchRepoDetails) {
+    const [details, readme] = await Promise.all([
+        fetchRepoDetails(owner, repo),
+        fetchRepoReadme(owner, repo).catch(() => null)
+    ]);
+    const structure = await fetchRepoStructure(owner, repo);
+    const rootFiles = structure.filter(item => item.type === 'file').map(item => item.name);
+    const directories = structure.filter(item => item.type === 'dir').map(item => item.name);
+    const depFiles = ['package.json', 'requirements.txt', 'Cargo.toml', 'go.mod', 'pom.xml'];
+    const packageManagerMap = {
+        'package.json': 'npm/yarn/pnpm',
+        'requirements.txt': 'pip',
+        'Cargo.toml': 'cargo',
+        'go.mod': 'go modules',
+        'pom.xml': 'maven'
+    };
+    let dependencies = { detected: false };
+    for (const file of depFiles) {
+        if (rootFiles.includes(file)) {
+            const content = await fetchRepoFile(owner, repo, file).catch(() => null);
+            if (content) {
+                dependencies = {
+                    detected: true,
+                    packageManager: packageManagerMap[file] || 'unknown',
+                    file,
+                    content
+                };
+                break;
+            }
+        }
+    }
+    const commits = await fetchRepoCommits(owner, repo, 10);
+    return {
+        basic: details,
+        readme: readme ? { content: readme, size: readme.length } : null,
+        structure: { rootFiles, directories },
+        dependencies,
+        recentActivity: {
+            commits: commits.map((c) => ({
+                sha: c.sha?.substring(0, 7) || '',
+                message: c.commit?.message?.split('\n')[0] || '',
+                author: c.commit?.author?.name || '',
+                date: c.commit?.author?.date || ''
+            })),
+            lastCommitDate: commits[0]?.commit?.author?.date || null
+        }
+    };
+}