GitHub Analytics MCP Server

GitHub Analytics MCP服务器——架构参考项目

从命令行、浏览器或AI代理查询、分析和可视化任何公共GitHub存储库。

______________________________________________________________________

概述

GitHub Analytics MCP Server是一个可用于生产的微服务，它将GitHub API变成一个简单的自托管分析端点。将其指向任何公共存储库，即可立即获取有关star、fork、贡献者、提交历史和语言分布的结构化数据。

它公开了两个接口：a RESTful API （带有自动生成Swagger文档的FastAPI）用于直接HTTP访问，以及 模型上下文协议（MCP）服务器 它允许像Claude Desktop这样的人工智能代理作为原生工具查询GitHub数据。

整个堆栈—API网关、MCP服务器、容器编排、基础设施配置和CI/CD—都包含在一个命令中并可通过单个命令进行部署。

该项目还作为 架构参考实现：每一层都附有设计决策文件，解释 *为什么* 它的结构是这样的，而不仅仅是 *什么* 确实如此。

特性

• 🔍 查询任何公共GitHub存储库 按所有者/姓名
• 📊 存储库统计信息 --星星、叉子、问题、观察者
• 👥 贡献者分析 --提交次数最多的贡献者
• 📝 提交历史记录 --最近提交的包含作者和消息详细信息的提交
• 🌐 RESTful API 使用自动生成的OpenAPI/Swagger文档
• 🤖 MCP协议支持 用于AI代理集成（Claude Desktop等）
• 🐳 生产就绪 使用Docker多阶段构建和Docker Compose
• ☸️ Kubernetes部署 包括部署、服务、入口和HPA
• 📈 自动缩放 --水平Pod自动缩放器（2-5个副本，70%CPU目标）
• 🔄 完整的CI/CD管道 --通过GitHub Actions进行lint、测试、构建和部署
• 🏗️ 基础设施即代码 --Terraform提供了整个K8s堆栈

为什么是这个项目？

这不仅仅是一个工具，它是一个 参考实现 专为研究架构模式而设计。每一层都包含设计决策文档，解释其结构背后的推理。

建筑

graph TB
    subgraph "User Interface"
        A[Web Browser / CLI]
    end

    subgraph "API Layer"
        B[FastAPI Gateway
Port 8080]
        C[MCP Server
stdio mode]
    end

    subgraph "Container Orchestration"
        D[Kubernetes Cluster]
        E[Docker Containers]
        F[Auto-scaling HPA]
    end

    subgraph "External Services"
        G[GitHub API]
    end

    subgraph "Infrastructure"
        H[Terraform IaC]
        I[CI/CD Pipeline]
    end

    A -->|HTTP/REST| B
    A -->|MCP Protocol| C
    B -->|GitHub Token| G
    C -->|GitHub Token| G
    B -.->|Deployed in| D
    C -.->|Deployed in| D
    D -->|Manages| E
    D -->|Auto-scales| F
    H -.->|Provisions| D
    I -.->|Deploys to| D

设计理念

一个域，两个接口，共享核心

GitHubClient 是单个业务逻辑层。MCP服务器和FastAPI网关都是瘦适配器，它们在各自的协议和共享核心之间进行转换。两者都不包含业务逻辑，也不重复另一个。

为什么有两个接口： MCP通过stdio为AI代理提供服务；REST通过HTTP为人类和程序提供服务。两个协议，两个适配器，零重复逻辑。

错误处理策略

自定义异常层次结构(RepositoryNotFoundError, AuthenticationError, RateLimitError)将GitHub HTTP状态代码转换为语义域错误。MCP服务器将这些转换为用户友好的文本消息；FastAPI网关将它们转换为相应的HTTP状态码（404/401/429/502）。调用方不需要知道GitHub API内部是如何工作的。

基础设施：三层用于三个用例

• Docker Compose --地方发展。一个命令(docker-compose up)开始一切。
• Kubernetes清单(k8s/) --直接 kubectl apply非常适合学习K8s和快速测试。
• 地形(terraform/) --状态管理、漂移检测、多环境支持。用于生产。

三者有意共存。每个服务于部署生命周期的不同阶段。

为什么这些数字

• HPA 2-5副本： 2保证可用性（一个吊舱可以在不停机的情况下发生故障）；5是成本上限。
• 70%CPU阈值： 留下30%的缓冲区，以便现有的Pod在新Pod启动时吸收流量峰值（10-30s调度窗口）。
• 资源限制（100m/500m CPU，128Mi/256Mi内存）： FastAPI+uvicorn在约30m CPU/~50MB RAM下空闲。限制可以防止失控进程饿死其他Pod。

故意遗漏

• 无数据库 --这是一个无状态代理。每个请求都会从GitHub获取新数据。添加数据库会掩盖核心架构模式。
• Redis是可选的 --可通过 docker-compose --profile with-cache up 演示Docker Compose配置文件，但不连接到应用程序中。
• 无身份验证中间件 --身份验证与所演示的架构正交。包括它会分散人们对分层设计的注意力。

架构文档

深入了解具体决策：

• 建筑.md --带层次图的完整架构概述
• 架构决策记录（ADR）：

- ADR-001：双MCP+REST接口 - ADR-002：自定义异常层次结构 - - ADR-004：地形和kubectl共存 - ADR-005:HPA配置值

快速开始

选项1:Docker编写（最快）

# 1. Clone and configure
git clone https://github.com/Pyroxyl/github-analytics-mcp.git
cd github-analytics-mcp
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN

# 2. Start services
docker-compose up -d

# 3. Test the API
curl http://localhost:8080/health
curl http://localhost:8080/api/v1/repo/facebook/react/stats | jq

选项2:Kubernetes（生产）

# 1. Build and deploy
make build
make k8s-deploy

# 2. Access the API (LoadBalancer on port 80)
curl http://localhost/health
curl http://localhost/api/v1/repo/facebook/react/stats | jq

选项3：地形（全IaC）

cd terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars

terraform init
terraform plan
terraform apply

用法示例

存储库统计信息

curl "http://localhost/api/v1/repo/facebook/react/stats" | jq

{
  "repository": "facebook/react",
  "stars": 242591,
  "forks": 50472,
  "open_issues": 1138,
  "watchers": 6690,
  "description": "The library for web and native user interfaces.",
  "language": "JavaScript"
}

最近的承诺

curl "http://localhost/api/v1/repo/anthropics/anthropic-sdk-python/commits?limit=3" | jq

顶级贡献者

curl "http://localhost/api/v1/repo/kubernetes/kubernetes/contributors?top_n=5" | jq

语言的分布

curl "http://localhost/api/v1/repo/microsoft/vscode/languages" | jq

{
  "repository": "microsoft/vscode",
  "languages": {
    "TypeScript": 95.54,
    "CSS": 1.49,
    "JavaScript": 1.0,
    "Rust": 0.61
  }
}

比较项目

# Compare stars across projects
curl -s "http://localhost/api/v1/repo/facebook/react/stats" | jq '.stars'
curl -s "http://localhost/api/v1/repo/vuejs/vue/stats" | jq '.stars'

交互式API文档

🌐 实时API文档: http://localhost/docs（或 http://localhost:8080/docs Docker Compose）

FastAPI自动生成交互式Swagger UI，您可以在其中：

• 📖 浏览所有可用端点
• 🎮 直接在浏览器中使用“试用”测试API
• 📊 查看请求/响应模式
• 💡 请参阅所有参数的示例值
• ✨ 执行真正的API调用并查看实时响应

MCP客户端配置

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "github-analytics": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/github-analytics-mcp",
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

或者使用Docker：

{
  "mcpServers": {
    "github-analytics": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", ".env", "github-analytics-mcp"],
      "cwd": "/path/to/github-analytics-mcp"
    }
  }
}

技术栈

DevOps亮点

• 多级Docker构建，实现最小映像大小
• Kubernetes自动扩展（基于CPU的2-5个副本）
• 自我修复的活力和准备状态探头
• 零停机滚动更新
• 自动化的lint、测试、构建和部署管道

项目结构

github-analytics-mcp/
├── src/                        # MCP Server
│   ├── server.py               # MCP protocol entry point
│   ├── github_client.py        # GitHub API client wrapper
│   └── tools/                  # MCP tool implementations
│       ├── repo_stats.py       #   get_repo_stats
│       ├── commits.py          #   list_recent_commits
│       ├── contributors.py     #   analyze_contributors
│       └── languages.py        #   get_language_breakdown
├── api/                        # FastAPI Gateway
│   ├── main.py                 # App entry point
│   ├── routes.py               # API route definitions
│   ├── models.py               # Pydantic models
│   └── dependencies.py         # Dependency injection
├── k8s/                        # Kubernetes manifests
│   ├── namespace.yaml
│   ├── configmap.yaml
│   ├── secret.yaml
│   ├── deployment-api.yaml     # API gateway (2 replicas)
│   ├── deployment-mcp.yaml     # MCP server
│   ├── service-api.yaml        # LoadBalancer service
│   ├── hpa-api.yaml            # Horizontal Pod Autoscaler
│   ├── ingress.yaml
│   └── deploy.sh               # Deployment script
├── terraform/                  # Infrastructure as Code
│   ├── main.tf
│   ├── kubernetes.tf
│   ├── providers.tf
│   ├── variables.tf
│   └── outputs.tf
├── .github/workflows/          # CI/CD pipelines
│   ├── ci.yml                  # Lint & test
│   ├── docker-build.yml        # Build & push image
│   └── cd.yml                  # Deploy to K8s
├── tests/                      # Unit tests
├── Dockerfile                  # Multi-stage container build
├── docker-compose.yml          # Local multi-service setup
├── Makefile                    # Convenience commands
├── requirements.txt
└── .env.example                # Environment template

发展

先决条件

• Python 3.11+
• Docker&Docker编写
• kubectl（用于Kubernetes部署）
• 地形（用于IaC部署）
• GitHub个人访问令牌(在此处创建一个)

本地开发

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run the MCP server
python -m src.server

# Run the API gateway
uvicorn api.main:app --reload --port 8080

# Run tests
pytest tests/

发出命令

CI/CD管道

Push/PR → [CI] Lint + Test → [Docker Build] → ghcr.io → [CD] → Kubernetes

1. 持续集成 --跑步 ruff 棉绒和 pytest 每次推送/PR（Python 3.11和3.12）
2. Docker构建 --构建图像并将其推送到GitHub容器注册表
3. 光盘 --成功构建后通过Terraform部署到Kubernetes

看 了解详情。

生产部署

高可用性

• 2个以上API网关复制副本，带有滚动更新
• 通过活性探针在故障时自动重启吊舱
• 就绪探测可防止流量流向不健康的吊舱

自动缩放

• HPA从2到5个复制品
• 目标：70%的CPU利用率
• 自动处理流量峰值

安全

• 存储为Kubernetes Secrets的GitHub令牌
• 源代码或git历史记录中没有凭据
• Ingress已准备好进行TLS终止

用例

• 📊 项目评估 --在采用GitHub项目之前快速评估它们
• 🔍 趋势研究 --分析流行存储库中的语言趋势
• 🤖 人工智能集成 --允许AI代理通过MCP访问GitHub数据
• 📈 指标仪表板 --使用实时GitHub统计数据构建自定义仪表板
• 🔬 开源研究 --研究贡献者模式和项目健康状况

路线图

• \[\]用于API响应的Redis缓存层
• \[\]普罗米修斯指标和Grafana仪表板
• \[\]速率限制和API密钥验证
• \[\]其他端点（拉取请求、发布、工作流）
• \[\]多云示例（AWS EKS、GCP GKE、Azure AKS）

贡献

看 贡献.md 用于开发工作流程和指南。

许可证

该项目根据MIT许可证获得许可——请参阅 许可证 文件以获取详细信息。

致谢

建于 模型上下文协议 通过Anthropic， 快速API，以及 .

______________________________________________________________________

⭐ 如果你觉得这个项目有用，请在GitHub上加星！