# mcp-server-github-trend

<div align="center">

🚀 **一个基于 Python 的 MCP 超级智能体：自动发现、分析、规划并部署开源项目来解决用户问题。**

[![CI](https://github.com/jankoli/mcp-server-github-trend/actions/workflows/ci.yml/badge.svg)](https://github.com/jankoli/mcp-server-github-trend/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-orange)](https://modelcontextprotocol.io/)

[English](./README.en.md) | 中文

</div>

---

## 简介

本项目是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，它不仅仅是一个 GitHub 趋势查看器，更是一个能够理解用户意图、自动检索开源项目、分析项目健康状况、生成部署方案，并可在沙箱中安全执行的**开源超级智能体**。

### 核心能力

- **意图理解**：从自然语言问题中提取目标、约束、技术栈和紧急程度
- **多源发现**：搜索 GitHub 仓库、话题、用户、Issue
- **仓库智能分析**：多维度健康评分、README 摘要、技术栈检测、风险标记
- **方案规划**：根据用户需求生成可执行的部署/集成计划
- **安全执行**：在受控工作目录中执行允许列表内的命令
- **可观测性**：结构化日志、Prometheus 指标、可选的 FastAPI 仪表盘
- **多级缓存**：支持内存、磁盘、Redis 三种缓存后端
- **中英双语**：所有输出支持中文与英文切换

---

## 快速开始

### 安装

```bash
pip install -e ".[all]"
```

### 配置

创建 `.env` 文件（可选，未配置时部分 GitHub API 调用受速率限制）：

```bash
OSS_AGENT_GITHUB_TOKEN=ghp_xxxxxxxx
```

### 作为 MCP 服务器使用

在 Claude Desktop、Cursor 或其他支持 MCP 的客户端中配置：

```json
{
  "mcpServers": {
    "github-trend": {
      "command": "mcp-oss-agent",
      "args": ["serve"],
      "env": {
        "OSS_AGENT_GITHUB_TOKEN": "ghp_xxxxxxxx"
      }
    }
  }
}
```

### CLI 使用

```bash
# 查看帮助
mcp-oss-agent --help

# 搜索仓库
mcp-oss-agent search "python web framework" --language python --per-page 10

# 分析仓库
mcp-oss-agent analyze jankoli mcp-server-github-trend

# 让智能体帮你解决问题
mcp-oss-agent solve "部署一个 Python 后端服务" --output-lang zh

# 启动 Web 仪表盘
mcp-oss-agent web --host 127.0.0.1 --port 8080
```

---

## MCP 工具清单

| 工具名 | 说明 |
| --- | --- |
| `search_repositories` | 按关键词、语言或话题搜索 GitHub 仓库 |
| `get_repository` | 获取指定仓库的详细元数据 |
| `analyze_repository` | 对仓库进行深度健康与风险评估 |
| `get_readme` | 获取并解码仓库 README |
| `get_trending_repositories` | 发现近期创建的流行仓库 |
| `get_user_repositories` | 列出用户或组织的近期仓库 |
| `search_issues` | 搜索 GitHub Issue 与 Pull Request |
| `solve_problem` | 理解用户问题，发现候选项目并生成方案 |
| `compare_repositories` | 对比多个仓库的健康与风险 |
| `get_rate_limit` | 查看当前 GitHub API 速率限制 |

---

## 架构

```mermaid
flowchart TB
    User[用户请求]
    Intent[意图理解引擎]
    Discovery[GitHub 发现层]
    Analyzer[仓库分析引擎]
    Planner[方案规划器]
    Executor[安全执行器]
    Cache[(多级缓存)]
    Metrics[指标与日志]

    User --> Intent
    Intent --> Discovery
    Discovery --> Cache
    Discovery --> Analyzer
    Analyzer --> Planner
    Planner --> Executor
    Executor --> Metrics
```

---

## 项目结构

```
src/mcp_server_github_trend/
├── __init__.py
├── __main__.py
├── server.py              # MCP 服务器入口
├── cli.py                 # Typer 命令行接口
├── web.py                 # FastAPI 仪表盘
├── config.py              # Pydantic 配置
├── models.py              # Pydantic 领域模型
├── github_client.py       # 异步 GitHub REST 客户端
├── analyzer.py            # 仓库健康分析引擎
├── intent.py              # 意图理解引擎
├── planner.py             # 方案规划引擎
├── executor.py            # 安全命令执行器
├── cache/                 # 内存 / 磁盘 / Redis 缓存
└── utils/                 # 日志、重试、国际化
```

---

## 配置项

所有配置均支持环境变量（前缀 `OSS_AGENT_`）：

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `OSS_AGENT_GITHUB_TOKEN` | - | GitHub Personal Access Token |
| `OSS_AGENT_CACHE_BACKEND` | `memory` | 缓存后端：`memory` / `disk` / `redis` |
| `OSS_AGENT_CACHE_TTL` | `300` | 缓存 TTL（秒） |
| `OSS_AGENT_EXECUTION_ENABLED` | `0` | 是否允许执行命令 |
| `OSS_AGENT_EXECUTION_ALLOWLIST` | `git,python,pip,npm,uv` | 允许执行的命令前缀 |
| `OSS_AGENT_WEB_ENABLED` | `0` | 是否启用 Web 仪表盘 |
| `OSS_AGENT_DEFAULT_LANGUAGE` | `zh` | 默认输出语言：`zh` / `en` |

---

## 开发

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

# 运行测试
pytest tests/ -q

# 代码检查
ruff check src tests
ruff format --check src tests
mypy src

# 构建
python -m build
```

---

## 许可证

[MIT](./LICENSE)