ЭТОТ ПРОЕКТ АРХИВИРОВАН

Рассмотрите возможность использования официального glab mcp

{
  "mcpServers": {
    "glab": {
      "type": "stdio",
      "command": "glab",
      "args": ["mcp", "serve"]
    }
  }
}

GitLab MCP Server

Готовый к промышленной эксплуатации сервер протокола контекста модели (MCP) для GitLab, который интегрируется с GitHub Copilot в IntelliJ IDEA. Автоматически обнаруживает ваш проект GitLab из удаленного git-репозитория, отслеживает статусы конвейеров и заданий с помощью интеллектуального опроса и обеспечивает надежную интеграцию с API с логикой повторных попыток.

Статус: ✅ Полностью проверено (35 тестов, 100% успешных)

Быстрый старт

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

# Runtime dependencies
pip install -r requirements.txt

# Development/test dependencies (optional)
pip install -r requirements-dev.txt

2. Настройка окружения

# Copy the example configuration
cp .env.example .env

# Edit .env with your GitLab credentials
# GITLAB_URL=https://your-gitlab-instance.com
# GITLAB_TOKEN=glpat-xxx

Как получить токен GitLab:

1. Настройки GitLab → Персональные токены доступа (Personal Access Tokens)

2. Создайте токен с областями видимости (scopes): api, read_api, read_repository

3. Скопируйте значение токена в файл .env

3. Запуск сервера

# Using the startup script
./run.sh

# Or directly
python -m src.server

Ожидаемый вывод:

2026-02-10 13:15:30,123 - src.server - INFO - Initializing GitLab MCP server for https://...
2026-02-10 13:15:30,456 - src.server - INFO - GitLab authentication successful
2026-02-10 13:15:30,789 - src.server - INFO - Tools registered successfully
2026-02-10 13:15:30,900 - src.server - INFO - GitLab MCP server started, listening on stdio

4. Настройка в IntelliJ IDEA

1. Установите плагин GitHub Copilot (если еще не установлен)

2. Настройки → Инструменты → GitHub Copilot → MCP Servers

3. Добавьте MCP-сервер:

   • Тип: stdio

   • Команда: python -m src.server

   • Окружение: Укажите путь к вашему файлу .env

Related MCP server: GitLab MCP Server

Функции

✅ Автоматическое обнаружение проекта

• Нет необходимости указывать путь к проекту

• Автоматически определяется из удаленного git-репозитория (remote origin)

• Работает с SSH и HTTPS URL

• Поддерживает вложенные группы GitLab

✅ Мониторинг статуса конвейера

• Статус конвейера в реальном времени

• Все детали и статусы заданий

• Автоматическое обнаружение ветки и коммита

• Удобный для чтения текстовый вывод

✅ Статус задания с интеллектуальным опросом

• Опрос каждые 2 секунды до завершения задания

• Настраиваемый тайм-аут (по умолчанию 30 секунд)

• Возвращает промежуточные состояния

• Метаданные опроса включены в ответ

✅ Надежная интеграция с API

• 3 повторные попытки с экспоненциальной задержкой (1с, 5с, 9с)

• Корректная обработка временных сетевых сбоев

• Кэширование ID проекта на уровне сессии

• Понятные сообщения об ошибках для отладки

✅ Поддержка self-hosted GitLab

• Работает с любым экземпляром GitLab, размещенным на собственных серверах

• Нет зависимости от gitlab.com

• Полная совместимость с API

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

check_pipeline_status

Получение статуса конвейера для текущего проекта и ветки

Input:  working_directory (string)
        Optional: branch (string), commit (string)
Output: Pipeline status report with all jobs

Что он делает:

• Автоматически определяет: проект, ветку, коммит из git-репозитория

• Возвращает: ID конвейера, статус, задания с индивидуальными статусами

• Формат: Текстовый отчет, удобный для чтения

• Включает: время выполнения, веб-ссылки, информацию об этапах

Пример:

# In Copilot context:
# "Check the pipeline status for this project"
# → Copilot calls: check_pipeline_status("/path/to/repo")

check_job_status

Проверка статуса конкретного задания с автоматическим опросом

Input:  working_directory (string)
        job_name (string) OR job_id (integer)
Output: Job status report with polling metadata

Что он делает:

• Автоматически определяет: проект, конвейер из текущей ветки/коммита

• Поиск: по имени задания или числовому ID задания

• Опрос: каждые 2 секунды до завершения (макс. 30с)

• Возвращает: статус задания, время, URL логов, метаданные опроса

• Метаданные: is_polling, polling_timeout, polling_duration_seconds

Пример:

# In Copilot context:
# "Check the status of the 'test' job"
# → Copilot calls: check_job_status("/path/to/repo", job_name="test")

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

gitlab-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py              # MCP server entry point
│   ├── mcp_tools.py           # Tool definitions & logic
│   ├── gitlab_client.py       # GitLab API wrapper (retry logic, caching)
│   └── git_utils.py           # Git utilities (URL parsing, branch detection)
│
├── tests/                      # Comprehensive test suite
│   ├── test_gitlab_client.py  # 9 tests for API client
│   ├── test_git_utils.py      # 11 tests for git utilities
│   ├── test_mcp_tools.py      # 10 tests for tool logic
│   ├── test_server.py         # 5 tests for server initialization
│   └── conftest.py            # Pytest configuration
│
├── requirements.txt            # Runtime dependencies
├── requirements-dev.txt        # Test dependencies
├── .env.example               # Configuration template
├── pytest.ini                 # Pytest settings
├── run.sh                     # Startup script
└── README.md                  # This file

Запуск тестов

Быстрый запуск тестов

# Run all tests
python -m pytest tests/ -v

# Quick summary
python -m pytest tests/ -q

Покрытие тестами

• Всего тестов: 35 (100% успешных ✅)

• Протестированные модули: Все 4 основных модуля

  • gitlab_client.py: 9 тестов (API-клиент, логика повторов, кэширование)

  • git_utils.py: 11 тестов (парсинг URL, валидация)

  • mcp_tools.py: 10 тестов (опрос, форматирование, логика)

  • server.py: 5 тестов (инициализация, конфигурация)

Запуск конкретных тестов

# Test GitLab client
python -m pytest tests/test_gitlab_client.py -v

# Test git utilities
python -m pytest tests/test_git_utils.py -v

# Test MCP tools
python -m pytest tests/test_mcp_tools.py -v

# Test server
python -m pytest tests/test_server.py -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html

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

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

Создайте файл .env с содержимым:

# Required
GITLAB_URL=https://your-gitlab-instance.com
GITLAB_TOKEN=glpat-your-token-here

# Optional
DEBUG=false  # Set to 'true' for verbose logging

Конфигурация логики повторных попыток

Клиент автоматически повторяет неудачные вызовы API:

• Всего попыток: 3 (начальная + 2 повтора)

• Задержки: 1с, 5с, 9с

• Применяется к: Всем вызовам API GitLab

Конфигурация опроса заданий

Настройте поведение опроса через код:

# Default settings
_poll_job_status(client, project, job_name, job_id,
                timeout_seconds=30,    # Max wait time
                poll_interval=2.0)      # Check every 2 seconds

Архитектура

┌─────────────────────────────────────────────┐
│  IntelliJ IDEA + GitHub Copilot Plugin      │
│  (IDE Client)                               │
└──────────────────┬──────────────────────────┘
                   │ (stdio transport)
                   │ (MCP Protocol)
                   │
┌──────────────────▼──────────────────────────┐
│  FastMCP Server (Python)                    │
│  ┌────────────────────────────────────────┐ │
│  │ MCP Tools                              │ │
│  │ • check_pipeline_status                │ │
│  │ • check_job_status (with polling)      │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ GitLab Client                          │ │
│  │ • Session-based caching                │ │
│  │ • Retry logic (1s, 5s, 9s backoff)     │ │
│  │ • Pipeline/job/MR queries              │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ Git Utilities                          │ │
│  │ • SSH/HTTPS URL parsing                │ │
│  │ • Branch/commit detection              │ │
│  │ • Repository validation                │ │
│  └────────────────────────────────────────┘ │
└──────────────────┬──────────────────────────┘
                   │ (HTTP REST API)
                   │
┌──────────────────▼──────────────────────────┐
│  Self-Hosted GitLab Instance                │
│  (or gitlab.com)                            │
└─────────────────────────────────────────────┘

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

Проблемы с конфигурацией

"GITLAB_URL environment variable is not set"

• Проверьте наличие файла .env: ls -la .env

• Проверьте наличие GITLAB_URL в .env: grep GITLAB_URL .env

• Убедитесь, что .env находится в рабочей директории при запуске сервера

"GITLAB_TOKEN environment variable is not set"

• Добавьте GITLAB_TOKEN в .env

• Формат токена: glpat-xxx (Персональный токен доступа GitLab)

• Убедитесь, что токен имеет правильные области видимости: api, read_api, read_repository

"GitLab authentication successful", но инструменты не работают

• Проверьте доступность экземпляра GitLab: curl -H "PRIVATE-TOKEN: $TOKEN" $GITLAB_URL/api/v4/user

• Убедитесь, что токен имеет правильные области видимости

• Проверьте доступ по сети/файрвол к экземпляру GitLab

Проблемы с Git

"Not a git repository"

• Убедитесь, что вы находитесь в git-репозитории: git remote -v

• Поддерживаемые форматы удаленных репозиториев:

  • git@gitlab.host:group/project.git

  • https://gitlab.host/group/project.git

  • https://gitlab.host/group/project (без .git)

  • http://gitlab.host/group/project (HTTP, не HTTPS)

"Unable to parse git remote URL"

• Проверьте формат git remote: git remote -v

• И SSH, и HTTPS должны быть в стандартном формате GitLab

• Поддерживаются вложенные группы: company/team/project

Проблемы с конвейером/заданием

"No pipeline found for branch"

• Убедитесь, что ветка была отправлена (pushed): git push

• Проверьте, настроены ли триггеры конвейера в GitLab

• Попробуйте использовать явный SHA коммита: check_pipeline_status(dir, commit="abc123")

"Job not found: test"

• Убедитесь, что имя задания совпадает точно (регистрозависимо)

• Проверьте, есть ли в конвейере задания (может быть пустым)

• Список заданий: check_pipeline_status(dir), чтобы увидеть все задания

Тайм-аут опроса задания (30 секунд)

• Задание не началось в течение 2-минутного окна

• Можно перезапустить инструмент, чтобы проверить текущий статус

• Инструмент возвращает последнее известное состояние даже после тайм-аута

Режим отладки

Включите подробное логирование:

# In .env
DEBUG=true

# Or as environment variable
DEBUG=true python -m src.server

Проверяйте логи во время вызова инструмента для получения подробных сообщений об ошибках.

Проверка и тестирование

Результаты тестов

============================= 35 passed in 12.73s ===============================
✅ test_git_utils.py         (11 tests)
✅ test_gitlab_client.py      (9 tests)
✅ test_mcp_tools.py         (10 tests)
✅ test_server.py             (5 tests)

Что протестировано

• ✅ Клиент API GitLab с мокированными ответами

• ✅ Логика повторных попыток и экспоненциальная задержка

• ✅ Механизм кэширования ID проекта

• ✅ Парсинг Git URL (SSH, HTTPS, вложенные группы)

• ✅ Опрос заданий с тайм-аутом

• ✅ Форматирование ответов

• ✅ Инициализация и конфигурация сервера

• ✅ Обработка ошибок и валидация

Тестирование без реального экземпляра GitLab

Все тесты используют мокированный API GitLab (реальные вызовы API не требуются):

python -m pytest tests/ -v

Производительность

Типичное время отклика

• Первый вызов API: 1-3 секунды (зависит от сети)

• Последующие вызовы: <500 мс (кэшированный ID проекта)

• Опрос заданий: интервалы 2 секунды

• Весь набор тестов: ~13 секунд

Стратегия кэширования

• ID проекта: Кэшируется на время сессии сервера

• Сброс: Перезапуск сервера очищает кэш

• Преимущество: Сокращает количество вызовов API при повторных операциях

Детали реализации

Логика повторных попыток

Attempt 1: Immediate call
  ↓ (fails)
Wait 1 second
Attempt 2: Retry
  ↓ (fails)
Wait 5 seconds
Attempt 3: Final retry
  ↓ (fails)
Raise GitLabClientError

Примеры парсинга URL

SSH:   git@gitlab.com:group/project.git          → group/project
HTTPS: https://gitlab.com/group/project.git      → group/project
HTTPS: https://gitlab.com/group/project          → group/project
SSH:   git@host:company/team/subteam/project.git → company/team/subteam/project

Поведение опроса заданий

Initial check: Get job status immediately
  ↓
If terminal state (success/failed/canceled/skipped): Return
  ↓
If not started: Polling loop
  ├─ Check every 2 seconds
  ├─ Max 30 seconds total
  └─ Return with polling_timeout flag if timeout occurs

Поддерживаемые Git-репозитории

✅ Self-hosted экземпляры GitLab (любая версия) ✅ gitlab.com (публичный GitLab) ✅ Вложенные группы (company/team/project/...) ✅ SSH и HTTPS удаленные репозитории

❌ Не поддерживается: GitHub, Bitbucket и т.д. (только GitLab)

Что делать дальше

1. Локальное тестирование

# Test git utilities
python -c "
from src.git_utils import get_project_path_from_working_dir
print(get_project_path_from_working_dir('.'))
"

2. Проверка подключения к GitLab

python -c "
import os
from dotenv import load_dotenv
from src.gitlab_client import GitLabClient
load_dotenv()
client = GitLabClient(os.getenv('GITLAB_URL'), os.getenv('GITLAB_TOKEN'))
client.gl.auth()
print('✓ GitLab auth successful')
"

3. Запуск сервера

./run.sh
# Then configure in IntelliJ IDEA GitHub Copilot plugin

4. Использование с Copilot

В IntelliJ IDEA с Copilot:

• "Check the pipeline status"

• "What's the status of the test job?"

• "Show me the latest pipeline"

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

Чтобы добавить тесты или функции:

1. Создайте файл теста в директории tests/

2. Используйте мокирование для API GitLab: patch('src.gitlab_client.gitlab.Gitlab')

3. Запустите тесты: python -m pytest tests/ -v

4. Убедитесь, что все тесты проходят перед коммитом

Зависимости

Runtime

• fastmcp>=2.14.0 - Сервер протокола контекста модели

• python-gitlab>=4.0.0 - Клиент API GitLab

• python-dotenv>=1.0.0 - Загрузка переменных окружения

• GitPython>=3.1.0 - Операции с Git

Разработка/Тестирование

• pytest>=8.0.0 - Фреймворк для тестирования

• requests-mock>=1.11.0 - HTTP-мокирование (опционально)

Статус реализации

Поддержка

По вопросам или проблемам:

1. Включите отладочное логирование: Установите DEBUG=true в .env

2. Проверьте логи: Просмотрите вывод сервера во время вызова инструмента

3. Проверьте настройку: Следуйте разделу устранения неполадок выше

4. Изучите тесты: Проверьте tests/ для примеров использования

5. Проверьте git remote: git remote -v должен быть валидным URL GitLab

Лицензия

[Добавьте вашу лицензию здесь]

Последняя проверка: 10 февраля 2026 г. Набор тестов: 35/35 успешно ✅ Статус: Готов к эксплуатации 🚀