DIESES PROJEKT IST ARCHIVIERT

Erwägen Sie stattdessen die Verwendung des offiziellen glab mcp

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

GitLab MCP-Server

Ein produktionsreifer Model Context Protocol (MCP)-Server für GitLab, der sich in GitHub Copilot in IntelliJ IDEA integrieren lässt. Erkennt automatisch Ihr GitLab-Projekt anhand des Git-Remotes, überwacht Pipeline- und Job-Status mit intelligentem Polling und bietet eine zuverlässige API-Integration mit Wiederholungslogik.

Status: ✅ Vollständig verifiziert (35 Tests, 100 % Erfolgsquote)

Schnellstart

1. Abhängigkeiten installieren

# Runtime dependencies
pip install -r requirements.txt

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

2. Umgebung konfigurieren

# 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

So erhalten Sie ein GitLab-Token:

1. GitLab-Einstellungen → Persönliche Zugriffstoken

2. Token mit folgenden Scopes erstellen: api, read_api, read_repository

3. Token-Wert in die .env kopieren

3. Server starten

# Using the startup script
./run.sh

# Or directly
python -m src.server

Erwartete Ausgabe:

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. In IntelliJ IDEA konfigurieren

1. GitHub Copilot-Plugin installieren (falls noch nicht geschehen)

2. Einstellungen → Tools → GitHub Copilot → MCP-Server

3. MCP-Server hinzufügen:

   • Typ: stdio

   • Befehl: python -m src.server

   • Umgebung: Auf Ihre .env-Datei verweisen

Related MCP server: GitLab MCP Server

Funktionen

✅ Automatische Projekterkennung

• Kein manuelles Angeben des Projektpfads erforderlich

• Automatische Erkennung über Git-Remote-Origin

• Funktioniert mit SSH- und HTTPS-URLs

• Unterstützt verschachtelte GitLab-Gruppen

✅ Pipeline-Statusüberwachung

• Pipeline-Status in Echtzeit

• Alle Job-Details und Status

• Automatische Erkennung von Branches und Commits

• Menschenlesbare formatierte Ausgabe

✅ Job-Status mit Smart Polling

• Polling alle 2 Sekunden auf Job-Abschluss

• Konfigurierbares Timeout (Standard: 30 Sekunden)

• Gibt Zwischenzustände zurück

• Polling-Metadaten in der Antwort enthalten

✅ Zuverlässige API-Integration

• 3 Wiederholungsversuche mit exponentiellem Backoff (1s, 5s, 9s)

• Geht elegant mit vorübergehenden Netzwerkfehlern um

• Caching der Projekt-ID auf Sitzungsebene

• Klare Fehlermeldungen für das Debugging

✅ Unterstützung für selbst gehostetes GitLab

• Funktioniert mit jeder selbst gehosteten GitLab-Instanz

• Keine Abhängigkeit von gitlab.com

• Volle API-Kompatibilität

Verfügbare Tools

check_pipeline_status

Pipeline-Status für das aktuelle Projekt und den aktuellen Branch abrufen

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

Was es tut:

• Automatische Erkennung: Projekt, Branch, Commit aus dem Git-Repository

• Rückgabe: Pipeline-ID, Status, Jobs mit individuellem Status

• Format: Menschenlesbarer Textbericht

• Enthält: Zeitangaben, Web-URLs, Phaseninformationen

Beispiel:

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

check_job_status

Spezifischen Job-Status mit automatischem Polling prüfen

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

Was es tut:

• Automatische Erkennung: Projekt, Pipeline vom aktuellen Branch/Commit

• Suche: nach Job-Name oder numerischer Job-ID

• Polling: alle 2 Sekunden bis zum Abschluss (max. 30s)

• Rückgabe: Job-Status, Zeitangaben, Log-URL, Polling-Metadaten

• Metadaten: is_polling, polling_timeout, polling_duration_seconds

Beispiel:

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

Projektstruktur

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

Tests ausführen

Schneller Testlauf

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

# Quick summary
python -m pytest tests/ -q

Testabdeckung

• Gesamte Tests: 35 (100 % Erfolgsquote ✅)

• Getestete Module: Alle 4 Kernmodule

  • gitlab_client.py: 9 Tests (API-Client, Wiederholungslogik, Caching)

  • git_utils.py: 11 Tests (URL-Parsing, Validierung)

  • mcp_tools.py: 10 Tests (Polling, Formatierung, Logik)

  • server.py: 5 Tests (Initialisierung, Konfiguration)

Spezifische Tests ausführen

# 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

Konfiguration

Umgebungsvariablen

Erstellen Sie eine .env-Datei mit:

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

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

Konfiguration der Wiederholungslogik

Der Client wiederholt fehlgeschlagene API-Aufrufe automatisch:

• Gesamtversuche: 3 (initial + 2 Wiederholungen)

• Backoff-Verzögerungen: 1s, 5s, 9s

• Gilt für: Alle GitLab-API-Aufrufe

Konfiguration des Job-Pollings

Konfigurieren Sie das Polling-Verhalten über den Code:

# 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

Architektur

┌─────────────────────────────────────────────┐
│  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)                            │
└─────────────────────────────────────────────┘

Fehlerbehebung

Konfigurationsprobleme

"GITLAB_URL environment variable is not set"

• Überprüfen Sie, ob die .env-Datei existiert: ls -la .env

• Prüfen Sie, ob GITLAB_URL in .env enthalten ist: grep GITLAB_URL .env

• Stellen Sie sicher, dass sich .env beim Starten des Servers im Arbeitsverzeichnis befindet

"GITLAB_TOKEN environment variable is not set"

• Fügen Sie GITLAB_TOKEN zur .env hinzu

• Token-Format: glpat-xxx (GitLab Personal Access Token)

• Überprüfen Sie, ob das Token die richtigen Scopes hat: api, read_api, read_repository

"GitLab authentication successful", aber Tools schlagen fehl

• Prüfen Sie, ob die GitLab-Instanz erreichbar ist: curl -H "PRIVATE-TOKEN: $TOKEN" $GITLAB_URL/api/v4/user

• Überprüfen Sie, ob das Token die richtigen Scopes hat

• Prüfen Sie Firewall/Netzwerkzugriff auf die GitLab-Instanz

Git-Probleme

"Not a git repository"

• Stellen Sie sicher, dass Sie sich in einem Git-Repository befinden: git remote -v

• Unterstützte Remote-Formate:

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

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

  • https://gitlab.host/group/project (ohne .git)

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

"Unable to parse git remote URL"

• Prüfen Sie das Git-Remote-Format: git remote -v

• Sowohl SSH als auch HTTPS müssen im Standard-GitLab-Format vorliegen

• Verschachtelte Gruppen werden unterstützt: company/team/project

Pipeline-/Job-Probleme

"No pipeline found for branch"

• Überprüfen Sie, ob der Branch gepusht wurde: git push

• Prüfen Sie, ob Pipeline-Trigger in GitLab konfiguriert sind

• Versuchen Sie es mit einem expliziten Commit-SHA: check_pipeline_status(dir, commit="abc123")

"Job not found: test"

• Überprüfen Sie, ob der Job-Name exakt übereinstimmt (Groß-/Kleinschreibung beachten)

• Prüfen Sie, ob die Pipeline Jobs enthält (könnte leer sein)

• Jobs auflisten: check_pipeline_status(dir), um alle Jobs zu sehen

Job-Polling überschreitet Zeitlimit (30 Sekunden)

• Job wurde nicht innerhalb des 2-Minuten-Fensters gestartet

• Tool kann erneut ausgeführt werden, um den aktuellen Status zu prüfen

• Tool gibt auch nach Zeitüberschreitung den letzten bekannten Status zurück

Debug-Modus

Aktivieren Sie ausführliche Protokollierung:

# In .env
DEBUG=true

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

Überprüfen Sie die Protokolle während des Tool-Aufrufs auf detaillierte Fehlermeldungen.

Verifizierung & Tests

Testergebnisse

============================= 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)

Was wird getestet

• ✅ GitLab API-Client mit gemockten Antworten

• ✅ Wiederholungslogik und exponentielles Backoff

• ✅ Mechanismus zum Caching der Projekt-ID

• ✅ Git-URL-Parsing (SSH, HTTPS, verschachtelte Gruppen)

• ✅ Job-Polling mit Timeout

• ✅ Antwortformatierung

• ✅ Serverinitialisierung und -konfiguration

• ✅ Fehlerbehandlung und Validierung

Testen ohne echte GitLab-Instanz

Alle Tests verwenden eine gemockte GitLab-API (keine echten API-Aufrufe erforderlich):

python -m pytest tests/ -v

Leistung

Typische Antwortzeiten

• Erster API-Aufruf: 1-3 Sekunden (abhängig vom Netzwerk)

• Nachfolgende Aufrufe: <500ms (gecachte Projekt-ID)

• Job-Polling: 2-Sekunden-Intervalle

• Gesamte Test-Suite: ~13 Sekunden

Caching-Strategie

• Projekt-ID: Gecacht pro Serversitzung

• Zurücksetzen: Serverneustart leert den Cache

• Vorteil: Reduziert API-Aufrufe bei wiederholten Vorgängen

Implementierungsdetails

Wiederholungslogik

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

Beispiele für URL-Parsing

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

Verhalten beim Job-Polling

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

Unterstützte Git-Repositories

✅ Selbst gehostete GitLab-Instanzen (jede Version) ✅ gitlab.com (öffentliches GitLab) ✅ Verschachtelte Gruppen (company/team/project/...) ✅ SSH- und HTTPS-Remotes

❌ Nicht unterstützt: GitHub, Bitbucket usw. (nur GitLab)

Nächste Schritte

1. Lokales Testen

# 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-Verbindung testen

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. Server starten

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

4. Mit Copilot verwenden

In IntelliJ IDEA mit Copilot:

• "Check the pipeline status"

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

• "Show me the latest pipeline"

Mitwirken

Um Tests oder Funktionen hinzuzufügen:

1. Testdatei im Verzeichnis tests/ erstellen

2. Mocking für die GitLab-API verwenden: patch('src.gitlab_client.gitlab.Gitlab')

3. Tests ausführen: python -m pytest tests/ -v

4. Sicherstellen, dass alle Tests bestehen, bevor Sie committen

Abhängigkeiten

Laufzeit

• fastmcp>=2.14.0 - Model Context Protocol-Server

• python-gitlab>=4.0.0 - GitLab API-Client

• python-dotenv>=1.0.0 - Laden von Umgebungsvariablen

• GitPython>=3.1.0 - Git-Operationen

Entwicklung/Testen

• pytest>=8.0.0 - Test-Framework

• requests-mock>=1.11.0 - HTTP-Mocking (optional)

Implementierungsstatus

Support

Bei Problemen oder Fragen:

1. Debug-Protokollierung aktivieren: Setzen Sie DEBUG=true in .env

2. Protokolle prüfen: Überprüfen Sie die Serverausgabe während des Tool-Aufrufs

3. Setup verifizieren: Befolgen Sie den Abschnitt zur Fehlerbehebung oben

4. Tests prüfen: Überprüfen Sie tests/ auf Anwendungsbeispiele

5. Git-Remote prüfen: git remote -v muss eine gültige GitLab-URL sein

Lizenz

[Fügen Sie hier Ihre Lizenz ein]

Zuletzt verifiziert: 10. Februar 2026 Test-Suite: 35/35 bestanden ✅ Status: Produktionsbereit 🚀