npm package: @neosamon/gitlab-mcp-server
Description: MCP Server for GitLab - enables AI assistants to access GitLab repositories for code review assistance
Latest version: 1.0.0

# GitLab MCP 服务器

一个用于 GitLab 集成的模型上下文协议（MCP）服务器。该服务器使 Claude 等 AI 助手能够访问 GitLab 仓库，辅助代码审查。

## 功能特性

- **合并请求工具**
  - 获取 MR 详情、提交记录和代码变更
  - 支持完整的 GitLab URL 或独立参数

- **提交工具**
  - 获取提交详情和差异对比
  - 支持完整的 GitLab URL 或独立参数

- **URL 解析**
  - 自动从 GitLab URL 中提取项目路径和资源 ID
  - 支持提交和合并请求 URL

## 系统要求

- Node.js >= 18.0.0
- 具有 `read_api` 权限的 GitLab 个人访问令牌
- GitLab CE 13.10.2+（已在 CE 13.10.2 上测试）

## 安装

```bash
# 克隆仓库
git clone <repository-url>
cd gitlab-mcp-server-ts

# 安装依赖
npm install

# 构建项目
npm run build
```

## 配置

设置以下环境变量：

```bash
export GITLAB_URL="http://your-gitlab-instance.com"
export GITLAB_TOKEN="your-personal-access-token"
```

可选配置：
```bash
export GITLAB_TIMEOUT="30000"  # 请求超时时间（毫秒），默认：30000
```

### 配置示例

**示例 1：无线团队 GitLab 实例**
```bash
export GITLAB_URL="http://192.168.11.252"
export GITLAB_TOKEN="your-personal-access-token"
```

**示例 2：交换机团队 GitLab 实例**
```bash
export GITLAB_URL="http://192.168.11.18:8081"
export GITLAB_TOKEN="your-personal-access-token"
```

### 如何获取个人访问令牌

1. 登录 GitLab 实例
2. 进入 **用户设置** > **访问令牌**
3. 创建新令牌，勾选 `api` 和 `read_repository` 权限
4. 复制生成的令牌

## Claude Desktop 集成

将服务器添加到 Claude Desktop 配置中：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/gitlab-mcp-server-ts/dist/index.js"],
      "env": {
        "GITLAB_URL": "http://192.168.11.252",
        "GITLAB_TOKEN": "your-personal-access-token"
      }
    }
  }
}
```

## 可用工具

### get_merge_request

获取 GitLab 合并请求的详情。

**参数：**
- `url`（可选）：完整的 GitLab 合并请求 URL
- `project`（可选）：项目路径（例如 `namespace/project`）
- `mrIid`（可选）：合并请求 IID

**示例：**
```
获取 http://192.168.11.252/RAP_SD-Branch/EOS/-/merge_requests/123 的 MR 详情
```

### get_mr_commits

获取 GitLab 合并请求中的提交列表。

**参数：**
- `url`（可选）：完整的 GitLab 合并请求 URL
- `project`（可选）：项目路径
- `mrIid`（可选）：合并请求 IID

### get_mr_changes

获取 GitLab 合并请求中的文件变更（差异对比）。

**参数：**
- `url`（可选）：完整的 GitLab 合并请求 URL
- `project`（可选）：项目路径
- `mrIid`（可选）：合并请求 IID

### get_commit

获取 GitLab 提交的详情。

**参数：**
- `url`（可选）：完整的 GitLab 提交 URL
- `project`（可选）：项目路径
- `sha`（可选）：提交 SHA

**示例：**
```
获取 http://192.168.11.252/RAP_SD-Branch/EOS/-/commit/11ab7d0e96e95d56fd370b36325d84c62270a697 的提交详情
```

### get_commit_diff

获取 GitLab 提交的差异对比。

**参数：**
- `url`（可选）：完整的 GitLab 提交 URL
- `project`（可选）：项目路径
- `sha`（可选）：提交 SHA

## URL 格式支持

服务器支持以下 GitLab URL 格式：

**提交 URL：**
```
http://192.168.11.252/RAP_SD-Branch/EOS/-/commit/11ab7d0e96e95d56fd370b36325d84c62270a697
```

**合并请求 URL：**
```
http://192.168.11.252/RAP_SD-Branch/EOS/-/merge_requests/123
```

**项目路径格式（用于 project 参数）：**
```
RAP_SD-Branch/EOS
hap/HOS-AX
switch/HAOS-RTK
```

## GitLab CE 13.10.2 兼容性说明

本服务器针对 **GitLab CE 13.10.2** 进行了兼容性优化：

### API 端点
- 使用 `/api/v4` 标准 API 路径
- 支持项目路径或 project_id 两种方式访问

### 权限要求
- 个人访问令牌需要 `api` 或 `read_api` 权限
- 对于 open 状态的 MR，某些 API 可能有访问限制

### 已知限制
- Open 状态的 MR 提交访问可能受限（GitLab CE 13.x 限制）
- 建议使用 merged 状态的 MR 进行代码审查

## 错误处理

服务器为常见问题提供清晰的错误信息：

- **401 Unauthorized**：请检查你的 `GITLAB_TOKEN`
- **403 Forbidden**：令牌可能缺少所需权限
- **404 Not Found**：资源或项目不存在
- **Timeout**：请求超时（请调整 `GITLAB_TIMEOUT`）

## 许可证

MIT