# GitHub Stars MCP Server

一个用于分析 GitHub 用户 Star 项目的 MCP (Model Context Protocol) 服务器。

## 功能特性

这个 MCP 服务器提供了以下工具来分析 GitHub 用户的 starred 项目：

### 1. `get_starred_repos` - 获取 Star 项目列表
获取指定 GitHub 用户的 starred 项目列表，包含详细信息。

**参数：**
- `username` (必需): GitHub 用户名
- `limit` (可选): 返回的最大项目数量

**示例：**
```json
{
  "username": "torvalds",
  "limit": 10
}
```

### 2. `analyze_starred_repos` - 分析 Star 项目
对用户的 starred 项目进行全面分析，生成统计信息。

**参数：**
- `username` (必需): GitHub 用户名

**分析包括：**
- 总 star 数量统计
- 编程语言分布
- 主题（topics）分析
- 最多 star 的项目
- 最多 fork 的项目
- 最近 star 的项目
- 归档项目数量
- 平均 star 和 fork 数

**示例：**
```json
{
  "username": "octocat"
}
```

### 3. `search_starred_repos` - 搜索 Star 项目
在用户的 starred 项目中搜索，支持在项目名称、描述和主题中搜索。

**参数：**
- `username` (必需): GitHub 用户名
- `query` (必需): 搜索关键词

**示例：**
```json
{
  "username": "octocat",
  "query": "machine learning"
}
```

### 4. `filter_starred_repos` - 过滤 Star 项目
根据各种条件过滤 starred 项目。

**参数：**
- `username` (必需): GitHub 用户名
- `language` (可选): 按编程语言过滤
- `topic` (可选): 按主题过滤
- `min_stars` (可选): 最小 star 数量
- `archived` (可选): 按归档状态过滤 (true/false)

**示例：**
```json
{
  "username": "octocat",
  "language": "Python",
  "min_stars": 1000,
  "archived": false
}
```

## 安装

### 依赖要求
- Python 3.10 或更高版本
- uv (推荐) 或 pip

### 使用 uv 安装（推荐）

```bash
# 克隆仓库
git clone <repository-url>
cd mcp_agent

# 使用 uv 安装依赖
uv pip install -e .
```

### 使用 pip 安装

```bash
# 克隆仓库
git clone <repository-url>
cd mcp_agent

# 安装依赖
pip install -e .
```

## 配置

### GitHub Token（可选但推荐）

为了避免 GitHub API 速率限制，建议配置 GitHub Personal Access Token：

1. 在 GitHub 上创建 Personal Access Token：
   - 访问 https://github.com/settings/tokens
   - 点击 "Generate new token (classic)"
   - 选择权限：`public_repo` (用于访问公开仓库信息)
   - 生成并复制 token

2. 设置环境变量：

```bash
export GITHUB_TOKEN="your_token_here"
```

或者在使用 MCP 客户端时配置环境变量。

**注意：** 不使用 token 时，API 调用会受到速率限制（每小时 60 次请求）。使用 token 后限制提高到每小时 5000 次。

## 使用方法

### 作为 MCP 服务器运行

在 Claude Desktop 或其他 MCP 客户端中配置：

```json
{
  "mcpServers": {
    "github-stars": {
      "command": "python",
      "args": ["-m", "github_stars_mcp"],
      "cwd": "/path/to/mcp_agent",
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}
```

或者使用 uv：

```json
{
  "mcpServers": {
    "github-stars": {
      "command": "uv",
      "args": ["run", "python", "-m", "github_stars_mcp"],
      "cwd": "/path/to/mcp_agent",
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}
```

### 直接运行

```bash
# 设置 GitHub token（可选）
export GITHUB_TOKEN="your_token_here"

# 运行服务器
python -m github_stars_mcp

# 或使用 uv
uv run python -m github_stars_mcp
```

## 使用示例

### 示例 1：获取用户的 Star 项目

```
使用 get_starred_repos 工具获取 torvalds 的前 20 个 starred 项目
```

### 示例 2：分析 Star 项目统计

```
使用 analyze_starred_repos 工具分析 octocat 的 starred 项目
```

### 示例 3：搜索特定主题的项目

```
使用 search_starred_repos 工具在 octocat 的 starred 项目中搜索 "rust"
```

### 示例 4：过滤 Python 项目

```
使用 filter_starred_repos 工具过滤 octocat 的 starred 项目，
只显示 Python 语言且 star 数超过 1000 的项目
```

## API 参考

### GitHub API

本工具使用 GitHub REST API v3：
- 端点：`GET https://api.github.com/users/{username}/starred`
- 文档：https://docs.github.com/en/rest/activity/starring

### 速率限制

- **未认证请求**：每小时 60 次
- **已认证请求**：每小时 5000 次

## 开发

### 运行测试

```bash
# 安装开发依赖
uv pip install -e ".[dev]"

# 运行测试
pytest
```

### 项目结构

```
mcp_agent/
├── src/
│   └── github_stars_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # MCP 服务器实现
│       └── github_client.py   # GitHub API 客户端
├── pyproject.toml
├── README.md
└── .gitignore
```

## 故障排除

### 常见问题

1. **API 速率限制错误**
   - 解决方案：配置 GitHub Personal Access Token

2. **用户名不存在**
   - 检查用户名是否正确
   - 确保用户的 starred 项目是公开的

3. **网络连接错误**
   - 检查网络连接
   - 确认可以访问 api.github.com

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 相关资源

- [MCP 协议文档](https://modelcontextprotocol.io/)
- [GitHub REST API 文档](https://docs.github.com/en/rest)
- [Claude Code 文档](https://docs.claude.com/en/docs/claude-code)