mcp-server-github-trend

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

English | 中文

---

简介

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

核心能力

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

---

快速开始

安装

pip install -e ".[all]"

配置

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

OSS_AGENT_GITHUB_TOKEN=ghp_xxxxxxxx

作为 MCP 服务器使用

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

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

CLI 使用

# 查看帮助
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 速率限制

---

架构

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

Loading

---

项目结构

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

---

开发

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

# 运行测试
pytest tests/ -q

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

# 构建
python -m build

---

许可证

MIT