ESTE PROYECTO ESTÁ ARCHIVADO

Considere utilizar el glab mcp oficial en su lugar

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

Servidor MCP de GitLab

Un servidor de Protocolo de Contexto de Modelo (MCP) listo para producción para GitLab que se integra con GitHub Copilot en IntelliJ IDEA. Detecta automáticamente su proyecto de GitLab desde el remoto de git, monitoriza los estados de los pipelines y trabajos con sondeos inteligentes, y proporciona una integración de API fiable con lógica de reintento.

Estado: ✅ Totalmente verificado (35 pruebas, 100% de tasa de éxito)

Inicio rápido

1. Instalar dependencias

# Runtime dependencies
pip install -r requirements.txt

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

2. Configurar el entorno

# 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

Cómo obtener un token de GitLab:

1. Configuración de GitLab → Tokens de acceso personal

2. Crear un token con los alcances: api, read_api, read_repository

3. Copiar el valor del token en .env

3. Iniciar el servidor

# Using the startup script
./run.sh

# Or directly
python -m src.server

Salida esperada:

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. Configurar en IntelliJ IDEA

1. Instalar el plugin de GitHub Copilot (si no está instalado)

2. Configuración → Herramientas → GitHub Copilot → Servidores MCP

3. Añadir servidor MCP:

   • Tipo: stdio

   • Comando: python -m src.server

   • Entorno: Apunte a su archivo .env

Related MCP server: GitLab MCP Server

Características

✅ Detección automática de proyectos

• No es necesario especificar la ruta del proyecto

• Detectado automáticamente desde el origen remoto de git

• Funciona con URLs SSH y HTTPS

• Soporta grupos de GitLab anidados

✅ Monitorización del estado del pipeline

• Estado del pipeline en tiempo real

• Todos los detalles y estados de los trabajos

• Detección automática de ramas y commits

• Salida formateada legible para humanos

✅ Estado del trabajo con sondeo inteligente

• Sondea cada 2 segundos para completar el trabajo

• Tiempo de espera configurable (30 segundos por defecto)

• Devuelve estados intermedios

• Metadatos de sondeo incluidos en la respuesta

✅ Integración de API fiable

• 3 reintentos con retroceso exponencial (1s, 5s, 9s)

• Maneja fallos de red transitorios con elegancia

• Caché de ID de proyecto a nivel de sesión

• Mensajes de error claros para la depuración

✅ Soporte para GitLab autohospedado

• Funciona con cualquier instancia de GitLab autohospedada

• Sin dependencia de gitlab.com

• Compatibilidad total con la API

Herramientas disponibles

check_pipeline_status

Obtener el estado del pipeline para el proyecto y la rama actuales

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

Qué hace:

• Autodetecta: proyecto, rama, commit desde el repositorio git

• Devuelve: ID del pipeline, estado, trabajos con estados individuales

• Formato: Informe de texto legible para humanos

• Incluye: tiempos, URLs web, información de etapas

Ejemplo:

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

check_job_status

Comprobar el estado de un trabajo específico con sondeo automático

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

Qué hace:

• Autodetecta: proyecto, pipeline desde la rama/commit actual

• Busca: por nombre de trabajo o ID numérico de trabajo

• Sondea: cada 2 segundos hasta completar (máximo 30s)

• Devuelve: estado del trabajo, tiempos, URL de registros, metadatos de sondeo

• Metadatos: is_polling, polling_timeout, polling_duration_seconds

Ejemplo:

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

Estructura del proyecto

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

Ejecución de pruebas

Ejecución rápida de pruebas

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

# Quick summary
python -m pytest tests/ -q

Cobertura de pruebas

• Total de pruebas: 35 (100% de tasa de éxito ✅)

• Módulos probados: Los 4 módulos principales

  • gitlab_client.py: 9 pruebas (cliente API, lógica de reintento, caché)

  • git_utils.py: 11 pruebas (análisis de URL, validación)

  • mcp_tools.py: 10 pruebas (sondeo, formato, lógica)

  • server.py: 5 pruebas (inicialización, configuración)

Ejecución de pruebas específicas

# 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

Configuración

Variables de entorno

Cree un archivo .env con:

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

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

Configuración de la lógica de reintento

El cliente reintenta automáticamente las llamadas a la API fallidas:

• Intentos totales: 3 (inicial + 2 reintentos)

• Retrasos de retroceso: 1s, 5s, 9s

• Se aplica a: Todas las llamadas a la API de GitLab

Configuración del sondeo de trabajos

Configure el comportamiento del sondeo mediante código:

# 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

Arquitectura

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

Solución de problemas

Problemas de configuración

"GITLAB_URL environment variable is not set"

• Verifique que el archivo .env exista: ls -la .env

• Compruebe que .env tiene GITLAB_URL: grep GITLAB_URL .env

• Asegúrese de que .env esté en el directorio de trabajo al ejecutar el servidor

"GITLAB_TOKEN environment variable is not set"

• Añada GITLAB_TOKEN a .env

• Formato del token: glpat-xxx (Token de acceso personal de GitLab)

• Verifique que el token tenga los alcances correctos: api, read_api, read_repository

"GitLab authentication successful" pero las herramientas fallan

• Compruebe que la instancia de GitLab sea accesible: curl -H "PRIVATE-TOKEN: $TOKEN" $GITLAB_URL/api/v4/user

• Verifique que el token tenga los alcances correctos

• Compruebe el acceso al firewall/red a la instancia de GitLab

Problemas de Git

"Not a git repository"

• Asegúrese de estar en un repositorio git: git remote -v

• Formatos remotos soportados:

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

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

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

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

"Unable to parse git remote URL"

• Compruebe el formato remoto de git: git remote -v

• Tanto SSH como HTTPS deben estar en el formato estándar de GitLab

• Grupos anidados soportados: company/team/project

Problemas de Pipeline/Trabajo

"No pipeline found for branch"

• Verifique que la rama se haya enviado: git push

• Compruebe que los disparadores de pipeline estén configurados en GitLab

• Intente con el SHA de commit explícito: check_pipeline_status(dir, commit="abc123")

"Job not found: test"

• Verifique que el nombre del trabajo coincida exactamente (distingue entre mayúsculas y minúsculas)

• Compruebe que el pipeline tenga trabajos (puede estar vacío)

• Listar trabajos: check_pipeline_status(dir) para ver todos los trabajos

El sondeo de trabajo agota el tiempo de espera (30 segundos)

• El trabajo no ha comenzado en el intervalo de 2 minutos

• Puede volver a ejecutar la herramienta para comprobar el estado actual

• La herramienta devuelve el último estado conocido incluso después del tiempo de espera

Modo de depuración

Active el registro detallado:

# In .env
DEBUG=true

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

Compruebe los registros durante la invocación de la herramienta para obtener mensajes de error detallados.

Verificación y pruebas

Resultados de las pruebas

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

Qué se prueba

• ✅ Cliente de API de GitLab con respuestas simuladas

• ✅ Lógica de reintento y retroceso exponencial

• ✅ Mecanismo de caché de ID de proyecto

• ✅ Análisis de URL de Git (SSH, HTTPS, grupos anidados)

• ✅ Sondeo de trabajos con tiempo de espera

• ✅ Formato de respuesta

• ✅ Inicialización y configuración del servidor

• ✅ Manejo de errores y validación

Pruebas sin una instancia real de GitLab

Todas las pruebas utilizan la API de GitLab simulada (no se necesitan llamadas reales a la API):

python -m pytest tests/ -v

Rendimiento

Tiempos de respuesta típicos

• Primera llamada a la API: 1-3 segundos (depende de la red)

• Llamadas posteriores: <500ms (ID de proyecto en caché)

• Sondeo de trabajos: intervalos de 2 segundos

• Suite de pruebas total: ~13 segundos

Estrategia de caché

• ID de proyecto: Caché por sesión de servidor

• Reinicio: El reinicio del servidor borra la caché

• Beneficio: Reduce las llamadas a la API para operaciones repetidas

Detalles de implementación

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

Ejemplos de análisis de 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

Comportamiento del sondeo de trabajos

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

Repositorios Git soportados

✅ Instancias de GitLab autohospedadas (cualquier versión) ✅ gitlab.com (GitLab público) ✅ Grupos anidados (company/team/project/...) ✅ Remotos SSH y HTTPS

❌ No soportado: GitHub, Bitbucket, etc. (Solo GitLab)

Qué hacer a continuación

1. Pruebas locales

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

2. Probar la conexión a 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. Iniciar el servidor

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

4. Usar con Copilot

En IntelliJ IDEA con Copilot:

• "Comprueba el estado del pipeline"

• "¿Cuál es el estado del trabajo de prueba?"

• "Muéstrame el último pipeline"

Contribución

Para añadir pruebas o características:

1. Cree un archivo de prueba en el directorio tests/

2. Use simulación para la API de GitLab: patch('src.gitlab_client.gitlab.Gitlab')

3. Ejecute las pruebas: python -m pytest tests/ -v

4. Asegúrese de que todas las pruebas pasen antes de confirmar

Dependencias

Tiempo de ejecución

• fastmcp>=2.14.0 - Servidor de Protocolo de Contexto de Modelo

• python-gitlab>=4.0.0 - Cliente de API de GitLab

• python-dotenv>=1.0.0 - Carga de variables de entorno

• GitPython>=3.1.0 - Operaciones Git

Desarrollo/Pruebas

• pytest>=8.0.0 - Framework de pruebas

• requests-mock>=1.11.0 - Simulación HTTP (opcional)

Estado de implementación

Soporte

Para problemas o preguntas:

1. Activar registro de depuración: Establezca DEBUG=true en .env

2. Comprobar registros: Revise la salida del servidor durante la invocación de la herramienta

3. Verificar configuración: Siga la sección de solución de problemas anterior

4. Revisar pruebas: Compruebe tests/ para ver ejemplos de uso

5. Comprobar remoto git: git remote -v debe ser una URL de GitLab válida

Licencia

[Añada su licencia aquí]

Última verificación: 10 de febrero de 2026 Suite de pruebas: 35/35 superadas ✅ Estado: Listo para producción 🚀