GitVerse MCP README

GitVerse MCP Server

MCP-сервер (Model Context Protocol) для работы с GitVerse — российским сервисом хостинга репозиториев. Сервер даёт AI-ассистентам (Cursor, Claude Desktop, ZCode и любым MCP-клиентам) доступ к вашим репозиториям, pull request'ам и CI: можно листать и создавать PR, проводить code review — оставлять инлайн-комментарии к диффу, ставить вердикты approve / request changes / decline, назначать исполнителей и лейблы, запускать и разбирать CI-раны вплоть до логов джоб.

Набор из 25 инструментов повторяет семантику популярного bitbucket-mcp: привычные имена (getPullRequests, approvePullRequest, addPullRequestComment…), но поверх REST API GitVerse.

Обзор

Сервер реализует стандарт Model Context Protocol и предоставляет инструменты для:

• Репозитории — список своих или репозиториев организации, карточка репозитория
• Pull request'ы — список с фильтром по состоянию, создание (включая черновики), правка заголовка/описания/состояния/базовой ветки, коммиты и изменённые файлы PR, таймлайн активности
• Code review — инлайн-комментарии к конкретным строкам диффа, комментарии обсуждения (создание/правка/удаление), вердикты: одобрить, запросить изменения, заклонить, снять своё одобрение
• Назначения — assignees и labels на PR (PR в GitVerse является issue)
• CI — ран-ы GitVerse Actions (аналог Bitbucket Pipelines): список с фильтрами, карточка рана, запуск workflow, джобы и их логи

Все операции выполняются через официальный публичный REST API GitVerse: заголовки Authorization: Bearer и вендорный Accept: application/vnd.gitverse.object+json; version=1 выставляются автоматически, ответы 429 автоматически повторяются с учётом Retry-After.

Инструменты на одном экране

Установка

Через NPX (рекомендуется)

Запуск без глобальной установки:

GITVERSE_TOKEN="ваш-токен" npx -y @grigoriy-grisha/gitverse-mcp@latest

Ручная установка

Либо установите глобально или в проект:

# Глобально
npm install -g @grigoriy-grisha/gitverse-mcp

# Или в проект
npm install @grigoriy-grisha/gitverse-mcp

Затем запускайте:

# Глобальная установка
GITVERSE_TOKEN="ваш-токен" gitverse-mcp

# Установка в проект
GITVERSE_TOKEN="ваш-токен" npx @grigoriy-grisha/gitverse-mcp

Требуется Node.js 20 или выше.

Настройка

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

Создание токена GitVerse

1. Войдите в ваш аккаунт на gitverse.ru
2. Откройте Настройки → Управление токенами
3. Создайте новый токен с правами:
   • Репозитории: чтение, запись
   • Issues / Pull requests: чтение, запись
   • CI/CD (Actions): чтение, запись — нужно для тулов *Pipeline*
4. Скопируйте сгенерированный токен и используйте его как GITVERSE_TOKEN

Подробности — в документации по токенам.

Интеграция с клиентами

ZCode

Добавьте в конфигурацию MCP (~/.zcode/mcp.json или настройка проекта):

{
  "mcpServers": {
    "gitverse": {
      "command": "npx",
      "args": ["-y", "@grigoriy-grisha/gitverse-mcp@latest"],
      "env": {
        "GITVERSE_TOKEN": "ваш-токен"
      }
    }
  }
}

Claude Desktop

В файле claude_desktop_config.json:

{
  "mcpServers": {
    "gitverse": {
      "command": "npx",
      "args": ["-y", "@grigoriy-grisha/gitverse-mcp@latest"],
      "env": {
        "GITVERSE_TOKEN": "ваш-токен"
      }
    }
  }
}

Cursor

1. Откройте Settings → Extensions → Model Context Protocol
2. Добавьте конфигурацию:

"gitverse": {
  "command": "npx",
  "env": {
    "GITVERSE_TOKEN": "ваш-токен"
  },
  "args": ["-y", "@grigoriy-grisha/gitverse-mcp@latest"]
}

Локальная сборка для разработки

Если правите сервер локально и хотите проверить изменения:

"gitverse-local": {
  "command": "node",
  "env": {
    "GITVERSE_TOKEN": "ваш-токен"
  },
  "args": ["/путь/к/gitverse-mcp/dist/index.js"]
}

Устранение неполадок

Ошибки 401 Unauthorized

1. Проверьте токен: убедитесь, что используете персональный токен из «Управление токенами», а не пароль аккаунта
2. Проверьте права токена: для базовых операций нужно «Репозитории: чтение»; для вердиктов и комментариев — запись
3. Проверьте токен вручную через curl:

curl -H "Authorization: Bearer ваш-токен" \
     -H "Accept: application/vnd.gitverse.object+json; version=1" \
     "https://api.gitverse.ru/user"

Ошибки 429 Too Many Requests

API GitVerse ограничивает 2000 запросов в час на пользователя. Сервер автоматически повторяет такие запросы с учётом заголовка Retry-After (до 3 попыток). Если лимиты всё равно исчерпываются — снизьте частоту вызовов в сценарии ассистента.

Ошибки 400 VALIDATION_ERROR

Проверьте, что токен передаётся вместе с вендорным заголовком Accept: application/vnd.gitverse.object+json; version=1 — без него шлюз GitVerse отвечает 400. При работе через этот MCP-сервер заголовок ставится автоматически, ошибка возникает только при ручных curl-проверках.

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

Сервер предоставляет 25 инструментов для работы с репозиториями, PR и CI. Полный список по группам:

• Репозитории
• Pull request'ы
• Вердикты ревью
• Комментарии
• CI (GitVerse Actions)

Если не указано иное, листинги (listRepositories, getPullRequests, getPullRequestCommits, listPipelineRuns) принимают опциональные параметры пагинации:

• page (optional): номер страницы, начиная с 1. По умолчанию возвращается первая страница.
• per_page (optional): количество элементов на странице.

Репозитории

listRepositories

Возвращает список репозиториев.

Параметры:

• org (optional): имя организации — если указано, возвращаются репозитории организации; иначе — репозитории текущего пользователя
• page (optional), per_page (optional): пагинация

getRepository

Возвращает карточку репозитория.

Параметры:

• owner: владелец репозитория (пользователь или организация)
• repo: имя репозитория

Pull request'ы

getPullRequests

Возвращает pull request'ы репозитория.

Параметры:

• owner: владелец
• repo: имя репозитория
• state (optional): состояние PR — open или closed
• page (optional), per_page (optional): пагинация

createPullRequest

Создаёт pull request из ветки head в ветку base.

Параметры:

• owner: владелец
• repo: имя репозитория
• title: заголовок PR
• head: исходная ветка
• base: целевая ветка
• body (optional): описание PR (markdown)
• draft (optional): создать как черновик
• assignees (optional): список username для назначения
• labels (optional): список лейблов

Примечание: запрос ревьюеров (reviewers) в API GitVerse отсутствует — используйте assignees.

createDraftPullRequest

Создаёт pull request в статусе черновика.

Параметры:

• owner, repo, title, head, base — как у createPullRequest
• body (optional): описание PR

Примечание: эквивалентно createPullRequest с draft: true.

getPullRequest

Возвращает карточку конкретного pull request'а.

Параметры:

• owner: владелец
• repo: имя репозитория
• pull_number: номер PR

updatePullRequest

Обновляет pull request: заголовок, описание, состояние, целевую ветку; дополнительно может заменить assignees и labels (через issue-эндпоинт — PR в GitVerse является issue).

Параметры:

• owner: владелец
• repo: имя репозитория
• pull_number: номер PR
• title (optional): новый заголовок
• body (optional): новое описание
• state (optional): новое состояние — open или closed
• base (optional): новая целевая ветка
• assignees (optional): заменить исполнителей
• labels (optional): заменить лейблы

getPullRequestActivity

Возвращает таймлайн активности pull request'а.

Параметры:

• owner, repo, pull_number

getPullRequestCommits

Возвращает коммиты pull request'а.

Параметры:

• owner, repo, pull_number
• page (optional), per_page (optional): пагинация

getPullRequestDiff

Возвращает изменённые файлы pull request'а с построчными патчами.

Параметры:

• owner, repo, pull_number

Вердикты ревью

approvePullRequest

Одобряет pull request — создаёт ревью с вердиктом APPROVED.

Параметры:

• owner, repo, pull_number
• body (optional): комментарий к одобрению

unapprovePullRequest

Снимает ваше одобрение: находит ваше последнее APPROVED-ревью и удаляет его.

Параметры:

• owner, repo, pull_number

requestChanges

Запрашивает изменения — создаёт ревью с вердиктом REQUEST_CHANGES.

Параметры:

• owner, repo, pull_number
• body (optional): что нужно изменить

removeChangeRequest

Снимает ваш change request — перекрывает его новым ревью с вердиктом APPROVED (отдельного эндпоинта в API GitVerse нет).

Параметры:

• owner, repo, pull_number
• body (optional): комментарий

declinePullRequest

Заклоняет (закрывает) pull request.

Параметры:

• owner, repo, pull_number
• message (optional): причина отклонения — публикуется комментарием в обсуждение перед закрытием

Комментарии

getPullRequestComments

Возвращает комментарии обсуждения pull request'а.

Параметры:

• owner, repo, pull_number
• since (optional): только комментарии, созданные после ISO-времени
• before (optional): только комментарии, созданные до ISO-времени

addPullRequestComment

Создаёт комментарий к pull request — общий или инлайн.

Параметры:

• owner: владелец
• repo: имя репозитория
• pull_number: номер PR
• content: текст комментария (markdown)
• inline (optional): инлайн-комментарий к конкретной строке диффа:

{
  "path": "src/file.ts",
  "to": 15
}

• reply_to (optional): id комментария, на который отвечаем (только для общих комментариев)

Формат инлайн-комментария:

• path: путь к файлу в диффе
• to: номер строки в новой версии (добавленные и изменённые строки)

SHA коммита определяется автоматически — отдельно передавать его не нужно.

Примеры:

// Общий комментарий
addPullRequestComment(owner, repo, 14, "Отличная работа!");

// Инлайн-комментарий к строке 25 файла src/service.ts
addPullRequestComment(owner, repo, 14, "Добавь обработку ошибок", {
  inline: { path: "src/service.ts", to: 25 }
});

updatePullRequestComment

Редактирует комментарий обсуждения.

Параметры:

• owner, repo, pull_number
• comment_id: id комментария
• content: новый текст

deletePullRequestComment

Удаляет комментарий обсуждения.

Параметры:

• owner, repo, pull_number
• comment_id: id комментария

CI (GitVerse Actions)

CI-раны GitVerse Actions — аналог Bitbucket Pipelines.

listPipelineRuns

Возвращает CI-раны репозитория.

Параметры:

• owner, repo
• status (optional): фильтр по статусу — queued, in_progress, success, failure, cancelled, unknown
• branch (optional): фильтр по ветке
• event (optional): фильтр по событию-триггеру
• page (optional), per_page (optional): пагинация

getPipelineRun

Возвращает карточку CI-рана.

Параметры:

• owner, repo
• run_id: id рана

runPipeline

Запускает workflow на ветке или теге.

Параметры:

• owner, repo
• workflow: имя файла workflow (например ci.yml) или id
• ref_type: что передаётся в ref_name — branch или tag
• ref_name: имя ветки или тега
• inputs (optional): входные параметры workflow (строковые значения)

getPipelineSteps

Возвращает джобы (шаги) CI-рана.

Параметры:

• owner, repo
• run_id: id рана

getPipelineStep

Возвращает карточку джобы.

Параметры:

• owner, repo
• job_id: id джобы

getPipelineStepLogs

Возвращает логи джобы.

Параметры:

• owner, repo
• job_id: id джобы

Ограничения

Часть возможностей Bitbucket в публичном API GitVerse отсутствует, поэтому соответствующих тулов нет:

• merge PR — эндпоинта слияния в API нет (только проверка «смержен ли» и обновление ветки из base)
• reviewers при создании PR — есть только assignees
• переключение draft после создания (publishDraftPullRequest / convertTodraft)
• задачи (tasks) на PR
• resolve / reopen тредов комментариев
• остановка CI-рана (cancel отсутствует)
• commit statuses — вместо них используйте listPipelineRuns с фильтром по ветке

Разработка

Требования

• Node.js 20 или выше
• npm

Настройка

# Клонировать репозиторий
git clone <repo-url>
cd gitverse-mcp

# Установить зависимости
npm install

# Собрать проект
npm run build

# Запустить тесты
npm test

# Запустить локально
GITVERSE_TOKEN="ваш-токен" npm start

Структура

src/composite.ts   25 тулов: имена и семантика Bitbucket MCP, вызовы API GitVerse
src/client.ts      HTTP-клиент: Bearer + vendor Accept, 429/Retry-After, ошибки
src/server.ts      MCP-сервер: регистрация тулов, аннотации readOnlyHint
src/index.ts       stdio-транспорт, env-конфигурация
test/              vitest: клиент, тулы, e2e по InMemoryTransport

Лицензия

Проект распространяется по лицензии MIT — подробности в файле LICENSE.

Ссылки

• GitHub-репозиторий
• npm-пакет
• Документация публичного API GitVerse
• Токены GitVerse
• GitVerse MCP (официальный, hosted)
• Model Context Protocol
• bitbucket-mcp — референс набора тулов