# gitlab-mcp

GitLab 16.x용 FastMCP 서버. 프로젝트·MR·파이프라인·커밋 조회, 버그 기여 요약·릴리즈 노트 초안, 그리고 [Runners API](https://docs.gitlab.com/api/runners/) 기반 Runner 관리 도구를 제공합니다.

## 노출 Tool (MCP)

프로젝트·MR 등 **조회·요약** 계열은 GitLab REST API `GET` 위주입니다. **Runner** 도구는 목록·상세 조회뿐 아니라 등록·토큰 재설정·할당/해제·설정 변경·삭제 등 `POST` / `PUT` / `DELETE`를 사용합니다. Runner 토큰만 쓰는 일부 호출(`verify_runner_authentication` 등)은 `PRIVATE-TOKEN`을 보내지 않습니다.

### GitLab Runner 관련

| Tool | 파라미터 | 설명 |
|------|----------|------|
| `list_runners` | `scope`, `runner_type`, `status`, `paused`, `tag_list`, `version_prefix`, `page`, `per_page` | 현재 사용자 기준 Runner 목록 (`GET /runners`) |
| `list_all_runners` | 위와 동일 | 인스턴스 전체 Runner (`GET /runners/all`, 관리자/감사 권한) |
| `get_runner` | `runner_id` | Runner 상세 (`GET /runners/:id`) |
| `update_runner` | `runner_id`, `description`, `paused`, `active`, `tag_list`, `run_untagged`, `locked`, `access_level`, `maximum_timeout`, `maintenance_note` | Runner 설정 변경 (`PUT /runners/:id`, `active`보다 `paused` 권장) |
| `delete_runner` | `runner_id` | Runner 삭제 (`DELETE /runners/:id`) |
| `list_runner_jobs` | `runner_id`, `system_id`, `status`, `order_by`, `sort`, `page`, `per_page` | Runner가 처리한 Job 목록 (`GET /runners/:id/jobs`) |
| `list_runner_managers` | `runner_id` | Runner manager 목록 (`GET /runners/:id/managers`) |
| `list_project_runners` | `project`, `scope`, `runner_type`, `status`, `paused`, `tag_list`, `version_prefix`, `page`, `per_page` | 프로젝트에 연결 가능한 Runner (`GET /projects/:id/runners`) |
| `assign_runner_to_project` | `project`, `runner_id` | 프로젝트에 Runner 할당 (`POST /projects/:id/runners`) |
| `unassign_runner_from_project` | `project`, `runner_id` | 프로젝트에서 Runner 해제 (`DELETE /projects/:id/runners/:runner_id`) |
| `list_group_runners` | `group_id`, `runner_type`, `status`, `paused`, `tag_list`, `version_prefix`, `page`, `per_page` | 그룹 Runner 목록 (`GET /groups/:id/runners`) |
| `create_runner_with_registration_token` | `registration_token`, `description`, `paused`, `active`, `locked`, `run_untagged`, `tag_list`, `access_level`, `maximum_timeout`, `maintenance_note`, `maintainer_note` | 등록 토큰으로 Runner 등록 (`POST /runners`, 레거시 비활성 시 410 가능) |
| `delete_runner_by_authentication_token` | `authentication_token` | 인증 토큰으로 Runner 삭제 (`DELETE /runners`, PAT 미사용) |
| `verify_runner_authentication` | `authentication_token`, `system_id` | Runner 자격 검증 (`POST /runners/verify`, PAT 미사용; `glrt-` 토큰이면 `system_id` 필요할 수 있음) |
| `reset_instance_runner_registration_token` | (없음) | 인스턴스 등록 토큰 재설정 (관리자) |
| `reset_project_runner_registration_token` | `project` | 프로젝트 등록 토큰 재설정 |
| `reset_group_runner_registration_token` | `group_id` | 그룹 등록 토큰 재설정 |
| `reset_runner_authentication_token_by_runner_id` | `runner_id` | Runner ID + PAT로 인증 토큰 재설정 |
| `reset_runner_authentication_token_by_current_token` | `authentication_token` | 현재 Runner 토큰으로 인증 토큰 재설정 (`POST /runners/reset_authentication_token`) |
| `get_runner_job_router_discovery` | `authentication_token` | Job Router discovery (`GET /runners/router/discovery`, `Runner-Token` 헤더) |

### 프로젝트·MR·파이프라인·커밋·요약

| Tool | 파라미터 | 설명 |
|------|----------|------|
| `list_projects` | `search`, `membership`, `owned`, `page`, `per_page` | 토큰으로 접근 가능한 프로젝트 목록 |
| `get_project` | `project_id`, `project_path` (둘 중 하나) | 프로젝트 상세; `project_path`는 URL 인코딩 경로·`path_with_namespace`·동일 호스트 웹 URL |
| `list_merge_requests` | `project`, `state`, `source_branch`, `target_branch`, `labels`, `merged_after`, `merged_before`, `page`, `per_page` | 프로젝트 MR 목록 |
| `get_merge_request` | `project`, `mr_iid` | 단일 MR 상세 |
| `list_pipelines` | `project`, `ref`, `status`, `page`, `per_page` | 파이프라인 목록 |
| `get_pipeline` | `project`, `pipeline_id` | 단일 파이프라인 상세 |
| `get_job_trace` | `project`, `job_id` | CI Job 콘솔 로그(plain text trace, `GET /projects/:id/jobs/:job_id/trace`; `job_id`는 숫자 id) |
| `list_commits` | `project`, `ref_name`, `since`, `until`, `path`, `with_stats`, `page`, `per_page` | 커밋 이력 |
| `get_commit` | `project`, `sha`, `stats` | 단일 커밋 상세 |
| `compare_commits` | `project`, `from_ref`, `to_ref`, `straight` | 두 ref(브랜치/태그/SHA) 비교 |
| `summarize_bugfix_contribution` | `project`, `since`, `until`, `branch`, `bug_keywords`, `component_path_rules`, `top_n` | 기간 내 bugfix 추정 커밋으로 기여자·컴포넌트 요약 |
| `generate_release_notes` | `project`, `since`, `until`, `ref_name`, `categories`, `audience`, `max_items_per_category`, `max_commits_to_scan`, `include_merge_commits` | **기간 내 커밋** 기준 고객용 릴리즈 노트 마크다운 초안 |

## Requirements
- Python 3.11+
- GitLab 인증: **Personal Access Token** (`GITLAB_TOKEN`, `read_api` 권장) 또는 **HTTP Basic** (`GITLAB_USERNAME` + `GITLAB_PASSWORD`)

## Install
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Configuration
GitLab REST API 인증은 다음 중 **하나**를 씁니다.

1. **`GITLAB_TOKEN`** — Personal Access Token. GitLab → **Preferences** → **Access Tokens**에서 발급, `read_api` 스코프 권장.
2. **`GITLAB_USERNAME` + `GITLAB_PASSWORD`** — HTTP Basic. 비밀번호 자리에는 계정 비밀번호 대신 **PAT를 넣는 방식**(GitLab 문서 허용)도 가능합니다.

**우선순위:** `GITLAB_USERNAME`과 `GITLAB_PASSWORD`가 **둘 다** 비어 있지 않으면 HTTP Basic만 사용하고, 그렇지 않으면 `GITLAB_TOKEN`의 `PRIVATE-TOKEN` 헤더를 사용합니다. 둘 다 없으면 인증 없이 공개 리소스만 호출합니다.

**참고:** GitLab.com에서 **2FA**가 켜진 계정은 일반 계정 비밀번호로 API가 거절되는 경우가 많습니다. 그때는 PAT(또는 OAuth)를 사용하세요. 셀프호스팅·2FA 없음 환경에서는 Basic이 동작할 수 있습니다.

`GITLAB_USERNAME`만 넣거나 `GITLAB_PASSWORD`만 넣은 채 `GITLAB_TOKEN`도 없으면 서버가 시작 시 오류를 냅니다.

설정은 **프로세스 환경 변수**로 넣습니다 (`export …` / Docker `environment` / 호스트에서 `docker compose` 실행 시 셸에 `export`한 값이 `${VAR}` 로 전달).

| 변수 | 설명 |
|------|------|
| `GITLAB_BASE_URL` | GitLab 베이스 URL (기본: `https://gitlab.com`) |
| `GITLAB_TOKEN` | Personal Access Token (`PRIVATE-TOKEN` 헤더; Basic 미사용 시) |
| `GITLAB_USERNAME` | HTTP Basic 사용자명 (비밀번호와 함께 사용) |
| `GITLAB_PASSWORD` | HTTP Basic 비밀번호 또는 PAT |
| `GITLAB_TIMEOUT_SECONDS` | API 타임아웃 초 (기본: `15`) |
| `GITLAB_DEFAULT_PER_PAGE` | 기본 페이지 크기 (기본: `20`) |
| `GITLAB_MAX_PER_PAGE` | 페이지 상한 (기본: `100`) |
| `MCP_TRANSPORT` | `stdio`(기본) \| `http`(Streamable HTTP) \| `sse` |
| `MCP_HOST` | HTTP/SSE 바인드 주소 (기본: `127.0.0.1`) |
| `MCP_PORT` | HTTP/SSE 포트 (기본: `8000`) |

## Run (stdio, 로컬 기본)
```bash
gitlab-mcp
```

## Run (Streamable HTTP, 로컬)
터미널에서 MCP 엔드포인트는 **`http://<MCP_HOST>:<MCP_PORT>/mcp`** 입니다 (예: `http://127.0.0.1:8000/mcp`).

```bash
export MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=8000
export GITLAB_BASE_URL="https://gitlab.example.com"
export GITLAB_TOKEN="<your_pat>"
gitlab-mcp
```

## Run (Docker)
이미지는 HTTP(Streamable)로 뜨도록 되어 있습니다. 호스트에서 시크릿을 넣고 실행하려면 예를 들어:

```bash
export GITLAB_BASE_URL="https://gitlab.example.com"
export GITLAB_TOKEN="<your_pat>"
docker compose up --build
```

MCP URL은 **`http://<호스트>:<MCP_PORT>/mcp`** (기본 포트 `8000`) 입니다. 포트는 `MCP_PORT` 로 바꿀 수 있습니다.

## Cursor MCP config example

**stdio** (로컬에서 프로세스로 실행):
```json
{
  "mcpServers": {
    "gitlab-mcp-local": {
      "command": "gitlab-mcp"
    }
  }
}
```

**Streamable HTTP** (서버를 띄운 뒤 URL로 연결 — Cursor가 원격 MCP URL을 지원하는 경우):
```json
{
  "mcpServers": {
    "gitlab-mcp-http": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## Notes
- `project` 인자는 GitLab API 규칙에 맞게 **URL 인코딩된 경로**를 사용합니다 (예: `group%2Frepo`).
- Runner 도구는 GitLab Runners API 스펙과 권한(관리자·프로젝트 Maintainer 등)에 따릅니다. 토큰·등록 방식은 인스턴스 설정에 따라 동작이 달라질 수 있습니다.
- 프로젝트·MR·파이프라인 등 **비 Runner** 영역은 조회·요약 위주이며, 일반적인 리소스 변경용 쓰기 API는 범위에 두지 않았습니다.