GitHub Analytics MCP Server

Production-grade сервер Model Context Protocol (MCP) 2.x для аналитики GitHub.

Этот проект выходит за рамки простого учебного примера MCP и демонстрирует, как построить MCP-сервер с инженерными паттернами, которые действительно нужны для реального использования:

• Асинхронный HTTP

• Пул соединений

• Явные тайм-ауты

• TTL-кэширование

• Учёт rate-limit GitHub

• Повторные попытки с экспоненциальной задержкой

• Структурированное логирование

• Валидация входных данных

• Параллельные API-запросы

• Чистое управление жизненным циклом MCP

• Реальное сквозное тестирование MCP-протокола

Создан в рамках серии Production AI Engineering на канале Agentic Data Lab.

🎥 YouTube: Agentic Data Lab

Что делает этот MCP-сервер?

Сервер предоставляет аналитку GitHub-репозиториев в виде MCP-инструментов.

MCP-совместимый ИИ-клиент может использовать его, чтобы:

• просматривать метаданные репозитория

• получать последние коммиты

• аналізировать контрибьюторов

• просматривать открытые issues

• аналізировать активность коммитов

• сранивать два репозитория

• просматривать rate-limit GitHub API

Пример:

User:
Compare pallets/flask and django/django.

Which repository looks more active?

ИИ-клиент можт вызвать:

compare_repos

и получать живые данные GitHub через этот MCP-сервер.

Архитектура

                ┌─────────────────────┐
                │   MCP Client / AI   │
                │ Claude / MCP Client │
                └──────────┬──────────┘
                           │
                           │ MCP stdio
                           ▼
                ┌─────────────────────┐
                │ GitHub Analytics    │
                │     MCP Server      │
                └──────────┬──────────┘
                           │
                 ┌─────────┴─────────┐
                 │                   │
                 ▼                   ▼
          Input Validation       TTL Cache
                                     │
                           ┌─────────┴─────────┐
                           │                   │
                      CACHE HIT          CACHE MISS
                           │                   │
                           │                   ▼
                           │          Async HTTP Client
                           │                   │
                           │          Retry + Backoff
                           │                   │
                           │                   ▼
                           │            GitHub REST API
                           │                   │
                           └───────────◄───────┘
                                       │
                                       ▼
                               Structured MCP Result

7 производственных паттернов

1. Асинхронный HTTP + пул соединений

Сервер использует:

httpx.AsyncClient

вместо синхронных HTTP-запросов.

HTTP-клиент создаётся один раз за время жизненного цикла MCP-сервера и переиспользуется при вызовах инструментов.

Это обеспечивает:

• неблокирующий ввод/вывод

• переиспользование соединений

• лучшую конкуренть

• явный контрол тайм-аутов

Сервер настравает отдельные тайм-ауты для:

connect
read
write
pool

Related MCP server: ship-it-mcp

2. TTL-кэширование

ИИ-клиенты могут вызывать один и тот же MCP-инструмент несколько раз за время одного разговора.

Вместо обращения к GitHub каждый раз сервер кэширует ответы в памяти.

Пример:

First request

MCP Client
    │
    ▼
MCP Server
    │
    ▼
GitHub API
    │
    ▼
Cache

Второй запрос:

MCP Client
    │
    ▼
MCP Server
    │
    ▼
CACHE HIT

Дополнительный запрос к GitHub не требуется.

Разные инструменты используют разные TTL в зависимости от того, насколько быстро меняются их данные.

3. Учёт rate-limit GitHub

GitHub передаёт информацию о rate-limit в загоовках ответов.

Сервер отслеживает:

X-RateLimit-Limit
X-RateLimit-Used
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After

Сервер может определить, когда GitHub действительно ограничивает запросы, и вернуть полезную ошибку MCP-инструмента вместо вывода сырого исключения.

4. Повторные попытки + экспоненциальная задержка

Временные сбои сети и ответы 5xx от вышестоящего сервера автоматически повторяются.

Последовательность повторов:

Attempt 1
   │
   └── failure
        │
        ▼
      wait 1s

Attempt 2
   │
   └── failure
        │
        ▼
      wait 2s

Attempt 3
   │
   └── final result

Формула задержки:

2 ** (attempt - 1)

Сервер не повторяет вслепую обычные клиентские ошибки 4xx.

5. Структурированное логирование

MCP stdio использует stdout для протокольной коммуникации.

Поэтому операционные логи записываются отдельно через Python logging.

Пример:

2026-08-27T14:14:03 | INFO | Starting GitHub Analytics MCP server
2026-08-27T14:14:04 | INFO | GET /repos/facebook/react → 200
2026-08-27T14:14:04 | INFO | CACHE HIT /repos/facebook/react

Это позволяет легко просматривать:

• API-запросы

• HTTP-статусы

• задержки

• попытки повторов

• попадания в кэш

• ошибки валидации

• предупреждения о rate-limit

6. Валидация входных данных

Владелец репозитория и имя репозитория проверяются до выполнения любого сетевого запроса.

Допустимые имена могут содержать:

letters
numbers
.
-
_

Например:

face../../book

отклоняется локально, прежде чем сможет стать частью запроса к GitHub API.

7. Параллельные API-запросы

MCP-инструмент compare_repos требует информацию о двух независимых репозиториях.

Вместо последовательного получения:

repo_a = await get_repo_a()
repo_b = await get_repo_b()

сервер выполняет оба запроса одновременно:

repo_a, repo_b = await asyncio.gather(
    get_repo_a(),
    get_repo_b(),
)

Концептуально:

Sequential

Repo A ───────────────► Done
                        Repo B ───────────────► Done


Parallel

Repo A ───────────────► Done
Repo B ───────────────────► Done

Это сокращает общее время ожидания, когда запросы независимы.

Доступные MCP-инструменты

В настоящее время сервер предоставляет 7 MCP-инструментов.

get_repo_overview

Возвращает:

• звёзды

• форки

• открытые issues

• наблюдателей

• язык

• темы

• лицензию

• дату последнего пуша

• домашнюю страницу

• размер репозитория

Пример:

get_repo_overview(
    owner="facebook",
    repo="react"
)

list_recent_commits

Возвращает недавние коммиты репозитория.

Пример:

list_recent_commits(
    owner="vuejs",
    repo="core",
    limit=5
)

get_contributors

Возвращает топ-контрибьюторов репозитория.

Пример:

get_contributors(
    owner="django",
    repo="django",
    limit=10
)

list_open_issues

Возвращает открытые issues GitHub, исключая pull request'ы.

Пример:

list_open_issues(
    owner="pallets",
    repo="flask",
    limit=10
)

get_commit_activity

Возвращает активность коммитов в репозитории, включая:

• общее количество коммитов

• среднее количество коммитов в неделю

• пиковую активность

• недавнюю недельную активность

compare_repos

Сравнивает два репозитория бок о бок.

Пример:

compare_repos(
    owner1="pallets",
    repo1="flask",
    owner2="django",
    repo2="django"
)

Возвращаемые поля включают:

stars
forks
open issues
language
last push

get_rate_limit_status

Возвращает информацию о rate-limit GitHub API, а также локальные счётчики MCP-сервера.

Пример:

{
  "limit": 60,
  "used": 4,
  "remaining": 56,
  "resets_in_seconds": 3599,
  "server_outbound_http_requests": 4,
  "server_cache_hits": 1
}

Фактические значения зависят от вашего текущего использования GitHub API.

Структура проекта

mcp-github-analytics/
│
├── server.py
│   └── Main MCP server and GitHub tools
│
├── demo_mcp.py
│   └── Real end-to-end MCP client demo
│
├── requirements.txt
│   └── Python dependencies
│
├── .env.example
│   └── Environment variable template
│
└── .gitignore

Установка

1. Клонирование репозитория

git clone https://github.com/sweta2503/mcp-github-analytics.git

Перейдите в проект:

cd mcp-github-analytics

2. Создание виртуального окружения

python -m venv .venv

macOS / Linux

source .venv/bin/activate

Windows

.venv\Scripts\activate

3. Установка зависимостей

pip install -r requirements.txt

Проект использует:

mcp[cli]==2.1.1
httpx==0.28.1
python-dotenv==1.2.3

Настройка GitHub-токена

Токен GitHub необязателен при работе только с публичными репозиториями, но рекомендуется.

Скопируйте пример файла окружения:

cp .env.example .env

Добавте свой GitHub-токен:

GITHUB_TOKEN=your_github_token_here

Не коммитьте ваш настоящий файл .env или токен.

Запуск реальной MCP-демонстрации

Запустите:

python demo_mcp.py

Это настоящий сквозной MCP-тест.

demo_mcp.py не просто импортирует функции из server.py.

Вместо этого он:

1. Starts server.py as an MCP subprocess
2. Connects using MCP stdio
3. Negotiates the MCP protocol
4. Discovers the MCP tools
5. Calls the tools through MCP
6. Receives structured MCP responses

Вы должны увидеть вывод, похожий на:

MCP CONNECTED — discover the real server tools

Negotiated protocol: ...
Tools discovered (7):
get_repo_overview
list_recent_commits
get_contributors
list_open_issues
get_commit_activity
compare_repos
get_rate_limit_status

Тест кэша

Демо вызывает:

get_repo_overview(facebook/react)

дважды.

Первый вызов обращается к GitHub.

Второй должен показать:

CACHE HIT

и вернуться значительно быстрее.

Тест параллельного сравнения репозиториев

Демо также запускает:

compare_repos(
    pallets/flask,
    django/django
)

Оба запроса к GitHub отправляются одновременно через:

asyncio.gather(...)

Сохранение вывода демо и логов сервера

Вы можете сохранить вывод MCP-клиента и логи сервера отдельно:

python demo_mcp.py > demo_output.txt 2> server.log

Это создаёт:

demo_output.txt

для ответов MCP-клиента и:

server.log

для логов на стороне сервера.

Лог сервера содержит полезную информацию, такую как:

GET /repos/facebook/react → 200
CACHE HIT /repos/facebook/react
GET /repos/pallets/flask → 200
GET /repos/django/django → 200

Запуск сервера напрямую

Вы можете запустить сам MCP-сервер с помощью:

python server.py

Сервер работает через MCP stdio.

Обычно MCP-совместимый клиент запускает этот процесс автоматически.

Подключение сервера к Claude Desktop

Вам не нужно хранить claude_desktop_config.json, привязанный к конкретной машине, внутри этого репозитория.

Вместо этого добавьте сервер в вашу локальную конфигурацию Claude Desktop.

Пример:

{
  "mcpServers": {
    "github-analytics": {
      "command": "/ABSOLUTE/PATH/TO/mcp-github-analytics/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-github-analytics/server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Замените:

/ABSOLUTE/PATH/TO/mcp-github-analytics

на фактическое расположение проекта на вашем компьютере.

Никогда не коммитьте ваш настоящий GitHub-токен.

После перезапуска Claude Desktop инструменты аналитки GitHub должны стать доступны для Claude.

Пример промпта:

Compare pallets/flask and django/django.

Which repository appears more active?

Use the GitHub MCP tools and explain which data you used.

Сквозной поток запроса

User
 │
 ▼
Claude / MCP Client
 │
 │ MCP tool call
 ▼
GitHub Analytics MCP Server
 │
 ├── Validate input
 │
 ├── Check TTL cache
 │
 ├── Cache hit ──────────────► Return result
 │
 └── Cache miss
          │
          ▼
     Async HTTP
          │
     Retry / Backoff
          │
          ▼
     GitHub REST API
          │
          ▼
       Response
          │
          ▼
       TTL Cache
          │
          ▼
 Structured MCP Response
          │
          ▼
     AI / MCP Client

Локальный и распределённый MCP в продакшене

Этот проект намеренно использует кэш в памяти с TTL, потому что он задуман как понятный локальный/stdio пример MCP.

Для многокземплярного удалённого развёртывания MCP обычно заменяют состояние, локальное для процесса, на инфраструктуру вроде:

Redis
PostgreSQL
distributed rate limiting
centralized observability
authentication
tracing

Паттерны, продемонстрированные в этом репозитории, являются строительными блоками для этого следующего этапа.

Смотрите полную сборку

Я объясняю архитектуру, код, кэширование, логику повторов, валидацию, параллельные запросы и реальную MCP-демонстрацию на своём YouTube-канале:

Agentic Data Lab

https://www.youtube.com/@agenticdatalab

На канале я рассматриваю:

• Production AI Engineering

• MCP

• AI-агенты

• LangGraph

• RAG

• AI-оценки

• Наблюдаемость агентов

• Проектирование AI-систем

• Инженерия данных + AI

• Продакшен-бенчмарки и эксперименты

Если вам интересно создавать AI-системы, выходящие за рамки учебных демо, подумайте о подписке.

👉 YouTube: Agentic Data Lab

Вклад в проект

Приветствуются issues, улучшения и pull request'ы.

Если вы расширите MCP-сервер ещё одним полезным инструментом аналитки GitHub, смело открывайте PR.

Поддержка проекта

Если этот репозиторий вам помог:

• ⭐ Поставьте звёзду репозиторию

• Сделайте форк и создайте свои MCP-инструменты

• ▶️ Подпишитесь на Agentic Data Lab

Скоро появится больше проектов по production AI engineering.