GitHub MCP Server

MCP-сервер на Node.js и TypeScript, который позволяет совместимому агенту выполнять операции с GitHub на естественном языке.

Архитектура

Usuario -> Antigravity (Host) -> MCP Client -> MCP Server -> Octokit -> GitHub API

Чат-бот в основном поддерживает разговор. AI-ассистент помогает, используя дополнительные возможности. AI-агент интерпретирует цель, решает, какие действия ему нужны, и использует tools для её достижения.

MCP (Model Context Protocol) стандартизирует взаимодействие между AI-хостом, MCP-клиентом и серверами, которые предоставляют tools или источники данных. В этом проекте транспортом является stdio: сообщения протокола используют stdin/stdout, а логи — stderr.

Related MCP server: GitHub MCP Server

Технологии

• Node.js 18 или выше

• TypeScript с strict: true

• @modelcontextprotocol/sdk

• @octokit/rest

• zod

• dotenv

• Vitest

Установка

npm install
npm run build

Конфигурация

Скопируйте .env.example как .env и заполните токен локально:

GITHUB_TOKEN=tu_token_de_github

.env исключён через .gitignore и никогда не должен коммититься.

Токен должен иметь только необходимые разрешения. Для приватных репозиториев fine-grained токены должны разрешать доступ к репозиторию и содержимому/issues в зависимости от операции. Классический PAT может требовать repo. Разрешение user необходимо только для дополнительных операций с пользователем, а admin:org не требуется для текущих пяти tools, если только организация не навязывает такой сценарий. Токены не включаются в примеры, тесты, логи или ответы MCP.

Скрипты

npm run dev       # Ejecuta TypeScript directamente
npm run build     # Compila a dist/
npm start         # Ejecuta el JavaScript compilado
npm test          # Ejecuta los tests unitarios

Tools MCP

create_repository

Создаёт новый репозиторий в аутентифицированной учётной записи.

Входные данные: name, description.

Возвращает полное имя и URL репозитория.

create_issue

Создаёт issue в существующем репозитории.

Входные данные: owner, repo, title, body.

Возвращает номер, заголовок и URL issue.

list_repositories

Перечисляет репозитории аутентифицированного пользователя.

Необязательные входные данные: page, per_page.

Возвращает краткий список с полным именем и URL.

create_commit

Создаёт или обновляет файл и формирует коммит через Contents API.

Входные данные: owner, repo, path, message, content; branch необязателен.

Tool сначала запрашивает файл. Если он существует, используется его SHA; если GitHub отвечает 404, файл создаётся без SHA.

list_issues

Перечисляет открытые issues репозитория и исключает pull requests.

Входные данные: owner, repo; page и per_page необязательны.

Обработка ошибок

Ошибки классифицируются как ValidationError, AuthenticationError, GitHubAPIError или NetworkError. Ответы MCP содержат практические сообщения и не пересылают технические сообщения, которые могут раскрыть учётные данные.

Операции повторяются до трёх раз только при rate limiting, ошибках 5xx или устранимых сетевых ошибках. Ошибки валидации, аутентификации и несуществующих ресурсов не повторяются.

Тесты

Тесты не обращаются к реальному GitHub. Они используют имитированные клиенты Octokit и покрывают:

• Допустимые и недопустимые схемы репозиториев и issues.

• Создание репозиториев и issues.

• Перечисление репозиториев и открытых issues.

• Создание новых файлов.

• Обновление существующих файлов с использованием SHA.

• Преобразование ошибок.

• Повторные попытки с backoff.

Выполните npm test, чтобы запустить полный набор тестов.

MCP Inspector

Скомпилируйте проект и запустите сервер через Inspector:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Настройте GITHUB_TOKEN в окружении перед запуском Inspector. Убедитесь, что отображаются пять tools, их описания и схемы. Для реального теста используйте тестовый репозиторий и избегайте деструктивных операций.

Antigravity и VS Code

Файл .vscode/mcp.json содержит конфигурацию stdio без версионируемых учётных данных. Используйте npm run build перед запуском сервера из Host. Конфигурация выполняет dist/index.js и берёт GITHUB_TOKEN из локального окружения.

Для другого Host, совместимого с MCP, зарегистрируйте эквивалентную команду:

{
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"],
  "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}

Проверьте, что Host обнаруживает create_repository, create_issue, list_repositories, create_commit и list_issues.

Структура

src/
  errors/       Errores clasificados y sanitizacion
  github/       Cliente Octokit y operaciones GitHub
  schemas/      Schemas Zod y tipos inferidos
  tools/        Handlers MCP individuales
  utils/        Retry, logging, respuestas y ensamblado del servidor
  index.ts      Entrada y transporte stdio
tests/          Tests unitarios con mocks

Безопасность

• Не хардкодить токены.

• Не коммитить .env.

• Не выводить токены и заголовки авторизации.

• Держать логи в stderr, чтобы не загрязнять протокол.

• Применять принцип минимальных привилегий к PAT.

• Проверять изменения перед выполнением tools, которые пишут в GitHub.