GitHub MCP Server

Проект, который позволяет ИИ-ассистенту общаться с GitHub с помощью безопасных структурированных инструментов.

Простыми словами: вместо того, чтобы ИИ угадывал, как устроен GitHub, этот проект даёт ему понятное меню действий — например, «показать мои репозитории», «показать открытые issues» или «прочитать файл». ИИ выбирает нужное действие, сервер обращается к GitHub, и ответ возвращается в аккуратном виде, который ИИ понимает.

Какую проблему это решает?

Чат-боты хорошо работают с языком, но у них нет автоматического живого доступа к вашему аккаунту GitHub.

Этот проект создаёт мост:

1. Вы задаёте запрос обычным языком («Покажи открытые issues в microsoft/vscode»).

2. Модель ИИ (через Groq) решает, какой инструмент GitHub использовать.

3. MCP-сервер выполняет этот инструмент через реальный API GitHub.

4. Результаты нормализуются и возвращаются ИИ.

5. ИИ объясняет результат вам простым языком.

MCP расшифровывается как Model Context Protocol. Представьте его как стандартный разъём: любой совместимый ИИ-клиент может подключиться к серверу и использовать его инструменты.

Related MCP server: GitHub MCP Server

Общая картина (архитектура)

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

Правило проектирования (важно)

Инструменты остаются тонкими:

1. Проверить входные данные (корректно ли имя репозитория).

2. Вызвать GitHub-клиента.

3. Нормализовать ответ до стабильной формы.

4. Вернуть эти чистые данные агенту.

Все «грязные» детали GitHub остаются внутри клиентского слоя, а не разбросаны по инструментам.

Папки проекта (что где находится и зачем)

Что можно делать с помощью инструментов

Сервер предоставляет множество действий с GitHub. Простая группировка:

Чтение (безопасно для explorации)

• Список ваших репозиториев

• Детали репозитория

• Списки и получение issues и pull request

• Диффы PR

• Списки веток, коммитов, меток

• Поиск кода в репозитории

• Чтение содержимого файлов

• Список прогонов GitHub Actions workflow

Запись (изменяет GitHub)

• Создание issues, комментариев, PR, веток, меток

• Обновление issues, добавление/удаление меток

• Переоткрытие issues

Деструктивные (могут навредить — защищено)

По умолчанию требуют дополнительное подтверждение:

• merge_pull_request

• delete_file

• create_repository

• create_or_update_file

• close_issue

Для таких инструментов агенту обычно нужно:

1. Вызвать с dry_run=true → только просмотр

2. Вызвать снова с confirm=true → реально выполнить

Ужесточить или ослабить можно настройками окружения (см. ниже).

Нормализованные ответы (почему это нравится агентам)

Сырые ответы GitHub огромны и часто меняются. Проект возвращает стабильные форма.

Списковые инструменты всегда выглядят так:

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

Чтобы получить следующую страницу, вызовите тот же инструмент снова с page=2 (или page=next_page).

Пример issue:

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

Также get_issues отфильтровывает pull requests (API issues GitHub подмешивает их).

Функции безопасности

Опционально переменные окружения:

GITHUB_MCP_DESTRUCTIVE_MODE=confirm
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST=merge_pull_request,delete_file

Логирование (для отладки)

Сервер пишет JSON-логи только в stderr.

Почему stderr? Протокол MCP использует stdout. Если логи печатать потуда, соединение с ИИ сломается.

Логи могут включать:

• метод и путь запроса

• HTTP-статус

• длительность

• оставшийся лимит запросов

Они никогда не логируют:

• ваш GitHub-токен

• заголовки Authorization

• секретные на вид поля (PAT, bearer-токены и т. п.)

Пример строки лога:

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

ИИ-агент (client/agent.py)

Агент:

1. Запускает MCP-сервер как подпроцесс (notebooks/server.py).

2. Запрашивает у сервера список инструментов.

3. Отправляет ваш запрос и список инструментов в Groq.

4. Если Groq выбирает инструмент, агент вызывает его через MCP.

5. Отправляет результат обратно в Groq для финального ответа.

Полезные команды (из папки проекта, при активном виртуальном окружении):

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

Ограничения циклов (опционально):

python client/agent.py --max-rounds 5 --once "..."

Или в .env:

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

Переменные окружения

Требуется для MCP-сервера

Требуется для агента (чат / выбор инструментов)

Опциональные

Скопируйте .env.example → .env и заполните реальные значения. Полный пошаговыхаемся в SETUP.md.

Технологический стек (для интересующихся)

• Python 3.13+ (проект разрабатывался на 3.13)

• MCP (Python-пакет mcp) — протокол сервера инструментов

• httpx — HTTP-клиентстечение для GitHub

• Pydantic — схемы / валидация

• python-dotenv — загрузка .env

• OpenAI-совместимый клиент → Groq для агента

• Jupyter (опционально) — обучающий ноутбук

Как установить и запустить

Следуйте одному из пошаговой инструкции:

👉 SETUP.md — установите Python, создайте ключи, настройте .env и запустите первые команды.

Короткая инструкция (если вы уже знаете Python):

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

Путь обучения (рекомендуется)

1. Прочтите этот README (вы уже здесь).

2. Пройдите SETUP.md, пока не заработает --list-tools.

3. Изучите docs/ARCHITECTURE_HLD_LLD.md — сценарии HLD + LLD.

4. Попробуйте --dry-run и --once с простыми чтениюскими вопросами.

5. Выполните ручный тест-план на 50 сценариев: tests/MANUAL_TESTING_50_SCENARIOS.md

   • Автовыбор: python client/run_manual_scenarios.py

6. Откройте notebooks/01_github_mcp_server.ipynb, чтобы увидеть, как построен за слой.

7. И только потом пробуйте инструменты записи/удаление с dry_run + confirm.

Решение проблем (быстро)

Напоминания о качестве

• Никогда не коммитьте .env.

• Никогда не вставляйте свои GitHub- или Groq-токены в чат, скриншоты или заявки.

• Старайтесь брать GitHub-токен только с теми правами, которые нужны.

• Оставляйте GITHUB_MCP_DESTRUCTIVE_MODE=confirm (или deny), если не полностью доверяете окружению.

• Не делитесь отладочным выводом server_1.py, если он печатал токены в старых экспериментах — используйте server.py.

Лицензия / владельца

Это личный/учебный Gen-AI проект: GitHub MCP-сервер и агент. Перед публикацией при необходимости измените owner’а и лицензию.