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.

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

Группа	Инструменты
Репозитории	`listRepositories` · `getRepository`
Pull request'ы	`getPullRequests` · `createPullRequest` · `createDraftPullRequest` · `getPullRequest` · `updatePullRequest` · `getPullRequestActivity` · `getPullRequestCommits` · `getPullRequestDiff`
Вердикты ревью	`approvePullRequest` · `unapprovePullRequest` · `requestChanges` · `removeChangeRequest` · `declinePullRequest`
Комментарии	`getPullRequestComments` · `addPullRequestComment` · `updatePullRequestComment` · `deletePullRequestComment`
CI (Actions)	`listPipelineRuns` · `getPipelineRun` · `runPipeline` · `getPipelineSteps` · `getPipelineStep` · `getPipelineStepLogs`

Установка

Через 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_TOKEN`	Персональный токен GitVerse (см. ниже)	Да
`GITVERSE_BASE_URL`	База API. По умолчанию `https://api.gitverse.ru`	Нет
`GITVERSE_API_VERSION`	Версия вендорного media type. По умолчанию `1`	Нет

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

Войдите в ваш аккаунт на gitverse.ru
Откройте Настройки → Управление токенами
Создайте новый токен с правами:
- Репозитории: чтение, запись
- Issues / Pull requests: чтение, запись
- CI/CD (Actions): чтение, запись — нужно для тулов *Pipeline*
Скопируйте сгенерированный токен и используйте его как 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

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

"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

Проверьте токен: убедитесь, что используете персональный токен из «Управление токенами», а не пароль аккаунта
Проверьте права токена: для базовых операций нужно «Репозитории: чтение»; для вердиктов и комментариев — запись
Проверьте токен вручную через 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): причина отклонения — публикуется комментарием в обсуждение перед закрытием

// Общий комментарий
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.

Name		Name	Last commit message	Last commit date
src		src
test		test
.gitignore		.gitignore
.nvmrc		.nvmrc
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

GitVerse MCP Server

Обзор

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

Установка

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

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

Настройка

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

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

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

ZCode

Claude Desktop

Cursor

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

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

Ошибки 401 Unauthorized

Ошибки 429 Too Many Requests

Ошибки 400 VALIDATION_ERROR

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

Репозитории

listRepositories

getRepository

Pull request'ы

getPullRequests

createPullRequest

createDraftPullRequest

getPullRequest

updatePullRequest

getPullRequestActivity

getPullRequestCommits

getPullRequestDiff

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

approvePullRequest

unapprovePullRequest

requestChanges

removeChangeRequest

declinePullRequest

Комментарии

getPullRequestComments

addPullRequestComment

updatePullRequestComment

deletePullRequestComment

CI (GitVerse Actions)

listPipelineRuns

getPipelineRun

runPipeline

getPipelineSteps

getPipelineStep

getPipelineStepLogs

Ограничения

Разработка

Требования

Настройка

Структура

Лицензия

Ссылки

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`listRepositories`

`getRepository`

`getPullRequests`

`createPullRequest`

`createDraftPullRequest`

`getPullRequest`

`updatePullRequest`

`getPullRequestActivity`

`getPullRequestCommits`

`getPullRequestDiff`

`approvePullRequest`

`unapprovePullRequest`

`requestChanges`

`removeChangeRequest`

`declinePullRequest`

`getPullRequestComments`

`addPullRequestComment`

`updatePullRequestComment`

`deletePullRequestComment`

`listPipelineRuns`

`getPipelineRun`

`runPipeline`

`getPipelineSteps`

`getPipelineStep`

`getPipelineStepLogs`