# GitLab MCP Server

MCP (Model Context Protocol) server để tích hợp với GitLab API, cho phép AI assistants tương tác với GitLab thông qua các tools và resources.

## Tính năng

### Tools (Các thao tác có thể thực hiện)

#### Project Tools
- `list_projects` - Liệt kê GitLab projects
- `get_project` - Lấy thông tin chi tiết project
- `create_project` - Tạo project mới
- `search_projects` - Tìm kiếm projects

#### Issue Tools
- `list_issues` - Liệt kê issues
- `get_issue` - Lấy thông tin chi tiết issue
- `create_issue` - Tạo issue mới
- `update_issue` - Cập nhật issue
- `close_issue` - Đóng issue

#### Merge Request Tools
- `list_merge_requests` - Liệt kê merge requests
- `get_merge_request` - Lấy thông tin chi tiết merge request
- `create_merge_request` - Tạo merge request mới
- `update_merge_request` - Cập nhật merge request
- `merge_merge_request` - Merge merge request

#### File Tools
- `get_file` - Đọc file từ repository
- `list_files` - Liệt kê files trong directory
- `create_file` - Tạo file mới
- `update_file` - Cập nhật file

### Resources (Dữ liệu có thể truy cập)

- `gitlab://projects` - Danh sách projects
- `gitlab://issues` - Danh sách issues
- `gitlab://merge-requests` - Danh sách merge requests
- `gitlab://project/{projectId}` - Thông tin project cụ thể
- `gitlab://issue/{projectId}/{issueIid}` - Thông tin issue cụ thể
- `gitlab://merge-request/{projectId}/{mrIid}` - Thông tin merge request cụ thể
- `gitlab://file/{projectId}/{filePath}` - Nội dung file

## Cài đặt

### Yêu cầu

- Node.js >= 18.0.0
- GitLab Personal Access Token với các quyền: `api`, `read_api`, `write_repository`

### Cài đặt dependencies

```bash
npm install
```

### Cài đặt global (tùy chọn)

Để cài đặt package này như một global command, bạn có thể sử dụng:

```bash
npm run install-global
```

Hoặc cài đặt trực tiếp từ thư mục hiện tại:

```bash
npm run build
npm install -g .
```

Sau khi cài đặt global, bạn có thể chạy server từ bất kỳ đâu bằng lệnh:

```bash
gitlab-mcp-server
```

### Sử dụng với npx (không cần cài đặt)

Bạn cũng có thể chạy trực tiếp bằng `npx` mà không cần cài đặt global:

```bash
npx -y gitlab-mcp-server
```

**Lưu ý:** Nếu package chưa được publish lên npm, bạn có thể sử dụng npx với đường dẫn local:
```bash
npx -y /path/to/mcp_ts
```

### Cấu hình

1. Copy file `env.example` thành `.env`:
```bash
cp env.example .env
```

2. Chỉnh sửa file `.env` và thêm GitLab token của bạn:
```
GITLAB_TOKEN=your_gitlab_personal_access_token_here
GITLAB_URL=https://gitlab.com/api/v4
```

Đối với GitLab self-hosted, thay đổi `GITLAB_URL` thành URL của instance của bạn.

## Sử dụng

### Build project

```bash
npm run build
```

### Chạy server

```bash
npm start
```

Hoặc chạy ở chế độ development với auto-reload:

```bash
npm run dev
```

### Type checking

```bash
npm run type-check
```

## Cấu hình MCP Client

### Claude Desktop

Thêm cấu hình sau vào file MCP settings của Claude Desktop (thường ở `~/Library/Application Support/Claude/claude_desktop_config.json` trên macOS hoặc `%APPDATA%\Claude\claude_desktop_config.json` trên Windows):

**Tùy chọn 1: Sử dụng npx (khuyến nghị, không cần cài đặt global):**
```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-server"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

**Tùy chọn 2: Nếu đã cài đặt global:**
```json
{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

**Tùy chọn 3: Sử dụng đường dẫn local:**
```json
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/mcp_ts/dist/index.js"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

### Cursor IDE

Thêm cấu hình vào file MCP settings của Cursor:

**Tùy chọn 1: Sử dụng npx (khuyến nghị, không cần cài đặt global):**
```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-server"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

**Tùy chọn 2: Nếu đã cài đặt global:**
```json
{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

**Tùy chọn 3: Sử dụng đường dẫn local:**
```json
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/mcp_ts/dist/index.js"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

## Ví dụ sử dụng

### Liệt kê projects

```json
{
  "tool": "list_projects",
  "arguments": {
    "search": "my-project",
    "owned": true
  }
}
```

### Tạo issue

```json
{
  "tool": "create_issue",
  "arguments": {
    "projectId": "123",
    "title": "Bug fix needed",
    "description": "This is a bug that needs to be fixed",
    "labels": "bug,urgent"
  }
}
```

### Đọc file từ repository

```json
{
  "tool": "get_file",
  "arguments": {
    "projectId": "group/project",
    "filePath": "src/index.ts",
    "ref": "main"
  }
}
```

## Cấu trúc dự án

```
mcp_ts/
├── src/
│   ├── index.ts              # Entry point, MCP server setup
│   ├── config.ts             # Configuration management
│   ├── gitlab/
│   │   ├── client.ts         # GitLab API client wrapper
│   │   ├── projects.ts       # Project operations
│   │   ├── issues.ts         # Issue operations
│   │   ├── mergeRequests.ts  # MR operations
│   │   └── files.ts          # File operations
│   └── tools/
│       ├── projectTools.ts   # MCP tools for projects
│       ├── issueTools.ts     # MCP tools for issues
│       ├── mrTools.ts        # MCP tools for merge requests
│       └── fileTools.ts      # MCP tools for files
├── package.json
├── tsconfig.json
├── env.example
└── README.md
```

## Phát triển

### Thêm tool mới

1. Tạo function trong module tương ứng trong `src/gitlab/`
2. Thêm tool definition vào file tương ứng trong `src/tools/`
3. Thêm handler trong function `handle*Tool` tương ứng
4. Tool sẽ tự động được đăng ký trong MCP server

### Error Handling

Tất cả các GitLab API calls đều được wrap với error handling. Errors sẽ được chuyển đổi thành messages dễ hiểu và trả về cho client.

## License

MIT