# GitLab MCP Proxy

> 사내 폐쇄망 GitLab 16.11 을 Claude Code 에서 MCP 로 사용하기 위한 프록시 서버
> 버전 0.4.0 · 연관 문서: [docs/PRD.md](docs/PRD.md), [docs/test-design.md](docs/test-design.md)

GitLab REST API v4 를 MCP(Model Context Protocol) tool 로 래핑한다. Claude Code 에서 자연어로
MR 리뷰·이슈 확인·파이프라인 조회·브랜치 비교를 수행할 수 있다.

## 주요 특징

- **분할 MCP 프로필** — 같은 바이너리를 `--profile` 로 기동해 세션 목적별 tool 만 노출 (Token Budget 절감)
- **레지스트리 기반 확장** — TypeScript ToolGroup + YAML Spec 을 한 레지스트리로 통합, 코드 수정 없이 API 추가
- **OS 독립 토큰 저장** — Node 내장 `crypto`(AES-256-GCM) 암호화 파일. 외부 의존성/네이티브 모듈 없음
- **폐쇄망 대응** — 인스턴스별 SSL 검증 비활성, 다중 인스턴스 라우팅
- **응답 최적화** — 요약 필드 추출, 대용량 diff 파일 단위 분할, 민감 정보 자동 마스킹, 60초 캐시 + 쓰기 시 무효화

## 요구 사항

- Node.js 20 LTS 이상
- TypeScript 5+

## 설치 및 빌드

```bash
npm install
npm run build        # tsc 컴파일 + src/specs/*.yaml → dist/specs 복사
```

## 설정

### `config/instances.yaml` — GitLab 인스턴스

```yaml
instances:
  - name: company-gitlab
    url: https://gitlab.internal.company.com
    default: true            # instance 미지정 시 이 인스턴스로 라우팅
    api_version: v4
    ssl_verify: false        # 폐쇄망 자체서명 인증서 대응
```

### `config/config.yaml` — Tool Group 활성화

```yaml
tool_groups:
  group:    { enabled: true }
  project:  { enabled: true }
  issue:    { enabled: true }
  mr:       { enabled: true }
  compare:  { enabled: true }
  pipeline: { enabled: false }   # 비활성 → tool 목록에서 제외 (Token Budget)
  repo:     { enabled: false }
  wiki:     { enabled: false }   # YAML 독립 등록 그룹
cache_ttl_seconds: 60
callback_port: 17432
```

## Claude Code 연동

### Step 1 — `config/instances.yaml` 에 GitLab 인스턴스 등록

```yaml
instances:
  - name: company-gitlab
    url: http://localhost:8929   # 로컬 Docker 검증 시. 실서버는 사내 URL로 변경
    default: true
    api_version: v4
    ssl_verify: false
```

### Step 2 — `config/config.yaml` 에서 사용할 Tool Group 활성화

```yaml
tool_groups:
  group:    { enabled: true }
  project:  { enabled: true }
  issue:    { enabled: true }
  mr:       { enabled: true }
  compare:  { enabled: true }
  pipeline: { enabled: true }
  repo:     { enabled: true }
  wiki:     { enabled: true }
cache_ttl_seconds: 60
callback_port: 17432
```

> 필요 없는 그룹은 `enabled: false` 로 끄면 Claude 의 tool 목록에서 제외되어 Token Budget 을 절감한다.

### Step 3 — 빌드

```bash
npm install
npm run build
```

### Step 4 — Claude Code 에 MCP 서버 등록

`claude mcp add` 명령으로 등록한다. `dist/index.js` 와 `config/` 는 **절대 경로**로 지정해야 Claude 가 어느 디렉토리에서 실행되든 올바르게 찾는다.

**macOS / Linux**

```bash
claude mcp add --scope user gitlab \
  -- node /Users/your-name/projects/gitlab-mcp/dist/index.js \
  --profile all \
  --config-dir /Users/your-name/projects/gitlab-mcp/config
```

**Windows (PowerShell)**

```powershell
claude mcp add --scope user gitlab `
  -- node C:\Users\your-name\projects\gitlab-mcp\dist\index.js `
  --profile all `
  --config-dir C:\Users\your-name\projects\gitlab-mcp\config
```

- `--scope user` — `~/.claude.json` 에 저장되어 모든 프로젝트에서 전역으로 사용된다
- `--profile all` — 8개 그룹 전체 활성화 (`config.yaml` 설정 무시)
- `--config-dir` — `instances.yaml` 위치를 절대 경로로 지정

```bash
claude mcp list   # 등록 목록 + 연결 상태 확인
```

### 프로필 요약

| 프로필 | 노출 그룹 | 용도 |
|--------|----------|------|
| `all` | 전체 8개 그룹 | 기본 권장 |
| `project` | group, project, issue, repo | 프로젝트 탐색 + 코드 |
| `mr` | mr, compare | 코드 리뷰 전용 |
| `pipeline` | pipeline | CI 모니터링 전용 |
| _(생략)_ | `config.yaml` 설정 그대로 | 커스텀 |

Token Budget 을 줄이려면 프로필별로 분리 등록한다:

```bash
# macOS / Linux
claude mcp add --scope user gitlab-mr \
  -- node /Users/your-name/projects/gitlab-mcp/dist/index.js \
  --profile mr \
  --config-dir /Users/your-name/projects/gitlab-mcp/config

claude mcp add --scope user gitlab-pipeline \
  -- node /Users/your-name/projects/gitlab-mcp/dist/index.js \
  --profile pipeline \
  --config-dir /Users/your-name/projects/gitlab-mcp/config
```

`--profile` 을 생략하면 `config/config.yaml` 의 `tool_groups` 설정을 그대로 따르므로, 아래처럼 모두 켜두고 등록해도 동일한 효과를 낸다.

```bash
claude mcp add gitlab -- node /Users/your-name/projects/gitlab-mcp/dist/index.js
```

| 방법 | `config.yaml` 참조 | wiki 포함 여부 |
|------|-------------------|---------------|
| `--profile all` | 무시 | 항상 포함 |
| `--profile` 생략 | 참조 | 설정값에 따라 |

## 인증 (토큰 등록)

토큰이 없으면 tool 호출 시 PAT 발행 페이지 URL 을 안내한다.

1. 안내된 URL 로 GitLab 에서 Personal Access Token 발급 (scope: `api`, `read_repository`, `write_repository`)
2. 로컬 콜백 페이지(`http://localhost:17432`)에 토큰을 붙여넣고 제출
3. 서버가 `GET /user` 로 토큰을 검증 후 암호화 저장하고 콜백 서버를 즉시 종료

### 토큰 저장 방식 (OS 독립)

- 위치: `~/.gitlab-mcp/credentials.enc`
- 암호화: AES-256-GCM. 키는 머신 고유값(hostname + 사용자명)에서 `scrypt` 로 파생
- 인스턴스별 분리 저장. 동일 머신/사용자에서만 복호화 가능
- 초기화: `~/.gitlab-mcp/credentials.enc` 파일을 삭제하면 전체 재등록 상태로 돌아간다

> 폐쇄망에서 콜백 접근이 막히는 경우(V-05), tool 인자로 토큰을 직접 전달하는 폴백 경로를 사용한다.

## YAML Spec 으로 API 추가 (코드 수정 없이)

`src/specs/*.yaml` 에 spec 을 추가하면 빌드 시 자동 등록된다.

```yaml
# group 이 기존 TS ToolGroup 과 일치하면 병합, 없으면 독립 그룹으로 등록
group: wiki
description: GitLab Wiki 관리
tools:
  - name: list_wiki_pages
    description: Wiki 페이지 목록 조회
    method: GET
    path: /projects/{project_id}/wikis
    params:
      - { name: project_id, in: path, required: true }
      - { name: with_content, in: query, default: false, type: boolean }
```

독립 그룹은 기본 비활성이므로 `config.yaml` 에서 `wiki: { enabled: true }` 로 켜야 노출된다.

### OpenAPI → YAML 변환 보조 CLI

```bash
npm run spec -- spec extract --source specs/gitlab-v4.yaml --tag wikis --output src/specs/wiki.yaml
```

## 테스트

```bash
npm test              # 전체 (Unit + Integration + Contract)
npm run test:cov      # 커버리지 (전체 80%+ 게이트)
```

- **Unit**: 마스킹, 캐시, 토큰 저장, 설정/프로필, 레지스트리, 콜백 서버, 에러 매핑
- **Integration**: GitLab 클라이언트 ↔ Mock, 도메인 tool, 인증 흐름, YAML generic handler
- **Contract**: 실제 MCP Client ↔ Server (InMemoryTransport) tools/list·call 계약

Mock GitLab 은 `fetch` 주입 방식([tests/mock/mock-gitlab.ts](tests/mock/mock-gitlab.ts))으로 결정적·고속이다.

### Docker GitLab 16.11 CE (E2E 선검증)

사내 이관 전 로컬에서 실 GitLab API 계약을 검증한다. CE 전용이므로 EE 기능(MR 승인)은 사내 검증 대상이다.

```bash
docker compose -f tests/docker/docker-compose.yml up -d
docker compose -f tests/docker/docker-compose.yml ps      # healthy 대기 (부팅 5~10분+)
docker exec gitlab-test cat /etc/gitlab/initial_root_password
```

## 디렉토리 구조

```
src/
  index.ts            진입점 (--profile, stdio)
  server.ts           MCP 서버 조립 (tools/list·call)
  types/              ToolGroup, 설정, spec, GitLab 응답 타입
  config/             설정 로더 + 프로필
  auth/               토큰 저장(crypto), 콜백 서버, PAT URL, AuthService
  client/             GitLab REST 클라이언트, ClientManager
  registry/           ToolRegistry(병합/독립등록), spec→tool 변환
  tools/              도메인 ToolGroup (group/project/issue/mr/compare/pipeline/repo)
  specs/              YAML Spec (mr-extra, wiki)
  util/               마스킹, 캐시, 에러, 응답
config/               instances.yaml, config.yaml
tests/                unit / integration / contract / mock / fixtures / docker
```

## 보안 주의

- 토큰은 암호화 저장되며 `*.enc` 는 `.gitignore` 에 포함된다. 절대 커밋하지 않는다
- API 응답의 `private_token`, `runners_token`, `*_secret`, webhook url token 등은 자동 마스킹된다
- 폐쇄망 SSL 비활성은 `ssl_verify: false` 인스턴스에만 적용된다