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

# Runtime dependencies
pip install -r requirements.txt

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

# 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

# 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

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

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

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

# 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

# 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

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

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

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

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

python -m pytest tests/ -v

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

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

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

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')
"

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