# GitLab MCP Server

一个支持 GitLab 操作的 Model Context Protocol (MCP) 服务器，主要用于创建和管理 Merge Requests。

## 功能特性

- ✅ 创建 Merge Request
- ✅ 合并 Merge Request
- ✅ 获取 Merge Request 详情
- ✅ 关闭 Merge Request
- ✅ 快捷合并到测试分支
- ✅ 支持 Stdio 和 Streamable HTTP 两种传输方式
- ✅ 支持通过 npx 直接运行，无需安装

## 快速开始

### 方式一：使用 npx（推荐，无需安装）

```bash
# 1. 设置环境变量
export GITLAB_ACCESS_TOKEN="your_gitlab_token_here"

# 2. 直接运行（默认 stdio 模式）
npx gitlab-mcp-server

# 或使用 HTTP 模式
npx gitlab-mcp-server --transport http --port 3000

# 查看帮助
npx gitlab-mcp-server --help
```

### 方式二：本地安装运行

```bash
# 1. 克隆或下载项目
git clone <repository-url>
cd gitlab-mcp-server

# 2. 安装依赖
npm install

# 3. 设置环境变量
export GITLAB_ACCESS_TOKEN="your_gitlab_token_here"
export GITLAB_API_BASE_URL="https://gitlab.com/api/v4"  # 可选

# 4. 运行
npm start  # 默认 stdio 模式
```

## 环境变量配置

### Windows (PowerShell)
```powershell
# 临时设置（当前会话）
$env:GITLAB_ACCESS_TOKEN="your_token_here"
$env:GITLAB_API_BASE_URL="https://gitlab.com/api/v4"

# 永久设置（用户级别）
[System.Environment]::SetEnvironmentVariable('GITLAB_ACCESS_TOKEN', 'your_token_here', 'User')
```

### Linux/Mac
```bash
# 临时设置
export GITLAB_ACCESS_TOKEN="your_token_here"
export GITLAB_API_BASE_URL="https://gitlab.com/api/v4"

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export GITLAB_ACCESS_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc
```

### 如何获取 GitLab Access Token

1. 登录 GitLab
2. 进入 **Settings** > **Access Tokens**
3. 创建新的 Personal Access Token
4. 选择 `api` 权限
5. 复制生成的 token

## 使用方式

### 通过 npx 运行（推荐）

```bash
# Stdio 模式（默认）
npx gitlab-mcp-server

# HTTP 模式
npx gitlab-mcp-server --transport http --port 3000

# 使用简写参数
npx gitlab-mcp-server -t http -p 8080

# 查看帮助
npx gitlab-mcp-server --help
```

### 本地运行

```bash
# 默认 stdio 模式
node index.js
npm start

# 明确指定 stdio 模式
node index.js --transport stdio
npm run start:stdio

# HTTP 模式
node index.js --transport http --port 3000
npm run start:http

# 开发模式（HTTP）
npm run dev:http
```

### 命令行参数

```
用法:
  node index.js [选项]

选项:
  -t, --transport <type>  传输方式: 'stdio' 或 'http' (默认: stdio)
  -p, --port <number>     HTTP 服务器端口 (默认: 3000, 仅在 http 模式下有效)
  -h, --help              显示帮助信息

示例:
  node index.js                              # stdio 模式
  node index.js --transport http --port 3000 # HTTP 模式
  npx gitlab-mcp-server -t http -p 8080      # HTTP 模式（使用 npx）
```

## 传输模式说明

### Stdio 模式（默认）

通过标准输入/输出与客户端通信，这是 MCP 的标准传输方式。

**适用场景：**
- 与 Claude Desktop 或其他 MCP 客户端集成
- 作为子进程运行
- 本地开发和使用

**特点：**
- MCP 标准传输方式
- 低延迟
- 适合本地集成

### Streamable HTTP 模式

使用最新的 Streamable HTTP 传输协议，支持远程访问和多客户端连接。

**适用场景：**
- 远程服务器部署
- 多客户端访问
- 调试和测试
- 需要 HTTP 接口的场景

**特点：**
- 基于 HTTP POST 的消息传输
- 支持 Server-Sent Events (SSE) 流式响应
- 支持断线重连和消息重放
- 更好的网络适应性

**HTTP 端点：**
- `POST /message` - MCP 消息端点（接收 JSON-RPC 请求，返回 JSON 或 SSE 流）

**测试 HTTP 模式：**
```bash
# 启动服务器
npm run start:http

# 在另一个终端发送测试请求
curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

## 在 MCP 客户端中使用

### Claude Desktop 配置（使用 npx）

编辑 Claude Desktop 的配置文件：
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["gitlab-mcp-server"],
      "env": {
        "GITLAB_ACCESS_TOKEN": "your_token_here",
        "GITLAB_API_BASE_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}
```

### 使用本地路径

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["d:/path/to/gitlab-mcp-server/index.js"],
      "env": {
        "GITLAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### HTTP 模式配置

如果你部署了 HTTP 模式的服务器，客户端可以通过 HTTP 连接：

```json
{
  "mcpServers": {
    "gitlab-http": {
      "url": "http://localhost:3000/message",
      "transport": "streamable-http",
      "env": {
        "GITLAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

## 可用工具

### 1. create_merge_request

在指定的 GitLab 项目中创建一个新的 Merge Request。

**参数:**
- `projectId` (string): GitLab 项目的 ID 或 URL 编码的路径
- `sourceBranch` (string): 源分支名称
- `targetBranch` (string): 目标分支名称
- `title` (string): Merge Request 的标题
- `description` (string, 可选): Merge Request 的描述
- `assigneeId` (number, 可选): 负责人 ID
- `reviewerIds` (array, 可选): 审阅者 ID 数组

**示例:**
```javascript
{
  "tool": "create_merge_request",
  "arguments": {
    "projectId": "123",
    "sourceBranch": "feature/new-feature",
    "targetBranch": "main",
    "title": "Add new feature",
    "description": "This PR adds a new feature",
    "assigneeId": 456,
    "reviewerIds": [789, 101]
  }
}
```

### 2. merge_merge_request

合并指定的 GitLab Merge Request。

**参数:**
- `projectId` (string): GitLab 项目的 ID 或 URL 编码的路径
- `mrIid` (number): Merge Request 的内部 ID
- `mergeCommitMessage` (string, 可选): 合并提交的消息
- `shouldRemoveSourceBranch` (boolean, 可选): 是否在合并后删除源分支
- `mergeWhenPipelineSucceeds` (boolean, 可选): 是否在 CI 管道成功后合并

**示例:**
```javascript
{
  "tool": "merge_merge_request",
  "arguments": {
    "projectId": "123",
    "mrIid": 42,
    "mergeCommitMessage": "Merge feature branch",
    "shouldRemoveSourceBranch": true,
    "mergeWhenPipelineSucceeds": false
  }
}
```

### 3. get_merge_request

获取指定 Merge Request 的详细信息。

**参数:**
- `projectId` (string): GitLab 项目的 ID 或 URL 编码的路径
- `mrIid` (number): Merge Request 的内部 ID

**示例:**
```javascript
{
  "tool": "get_merge_request",
  "arguments": {
    "projectId": "123",
    "mrIid": 42
  }
}
```

### 4. close_merge_request

关闭指定的 GitLab Merge Request 而不合并。

**参数:**
- `projectId` (string): GitLab 项目的 ID 或 URL 编码的路径
- `mrIid` (number): Merge Request 的内部 ID

**示例:**
```javascript
{
  "tool": "close_merge_request",
  "arguments": {
    "projectId": "123",
    "mrIid": 42
  }
}
```

### 5. merge_to_test

快捷工具：将源分支合并到测试分支（test）并自动部署。

**参数:**
- `projectId` (string): GitLab 项目的 ID
- `sourceBranch` (string): 源分支名称（如果未提供，将自动获取当前分支）

**示例:**
```javascript
{
  "tool": "merge_to_test",
  "arguments": {
    "projectId": "123",
    "sourceBranch": "feature/my-feature"
  }
}
```

## 常见问题

### Q: 如何找到项目 ID?
**A:** 
1. 进入 GitLab 项目页面
2. 项目 ID 显示在项目名称下方
3. 或者使用项目的 URL 编码路径，如 `username%2Fproject-name`

### Q: Stdio 和 HTTP 模式有什么区别?
**A:**
- **Stdio 模式**: 通过标准输入/输出通信，MCP 标准方式，适合本地集成
- **HTTP 模式**: 使用 Streamable HTTP 协议，适合远程访问、多客户端和调试

### Q: 什么是 Streamable HTTP?
**A:** Streamable HTTP 是 MCP 的最新 HTTP 传输协议，相比旧的 SSE 传输有以下优势：
- 统一的连接模型（单个 POST 请求即可发送和接收）
- 支持断线重连和消息重放
- 更好的网络适应性
- 更高的可靠性

### Q: 端口被占用怎么办？
**A:** 使用不同的端口：
```bash
node index.js --transport http --port 8080
```

### Q: 如何查看详细日志？
**A:** 日志输出到 stderr，可以重定向到文件：
```bash
node index.js --transport http 2> server.log
```

### Q: npx 和本地安装有什么区别？
**A:**
- **npx**: 无需安装，直接运行最新版本，适合快速测试和使用
- **本地安装**: 需要先安装依赖，但可以离线使用，适合开发和定制

## 开发

### 使用 MCP Inspector 调试

```bash
# Stdio 模式
npm run dev

# HTTP 模式
npm run dev:http
```

MCP Inspector 会启动一个交互式界面，让你可以测试服务器的各项功能。

### 项目结构

```
gitlab-mcp-server/
├── index.js           # 主入口文件
├── package.json       # 项目配置
├── README.md          # 文档
├── .npmignore         # npm 发布配置
└── .gitignore         # Git 忽略配置
```

## 发布到 npm

如果你想发布自己的版本到 npm：

```bash
# 1. 登录 npm
npm login

# 2. 更新版本号
npm version patch  # 或 minor, major

# 3. 发布
npm publish

# 4. 发布后，其他人可以通过 npx 使用
npx your-package-name
```

## 技术栈

- **@modelcontextprotocol/sdk**: MCP SDK (最新版本，支持 Streamable HTTP)
- **zod**: 参数验证
- **Node.js**: 运行时环境

## 更新日志

### [1.1.0] - 2025-12-15

**新增功能:**
- ✨ 支持通过命令行参数选择传输方式（stdio 或 http）
- ✨ 使用最新的 Streamable HTTP 传输协议（替代已弃用的 SSE）
- ✨ 支持通过 npx 直接运行，无需安装
- ✨ 添加 `bin` 字段，支持 `gitlab-mcp-server` 和 `gitlab-mcp` 命令
- ✨ 添加命令行帮助信息 `--help`

**改进:**
- 📝 完善文档，整合所有内容到 README
- 🔧 默认使用 stdio 模式（MCP 标准）
- 🔧 升级 SDK 到最新版本，移除已弃用的 API
- 🔧 优化服务器启动逻辑，支持参数化配置

**技术细节:**
- 使用 `StreamableHTTPServerTransport` 替代已弃用的 `SSEServerTransport`
- 升级 `@modelcontextprotocol/sdk` 到最新版本（1.24.0+）
- 添加 DNS rebinding 保护（SDK 1.24.0 的安全特性）

### [1.0.0] - 初始版本

**功能:**
- ✅ 创建 Merge Request
- ✅ 合并 Merge Request
- ✅ 获取 Merge Request 详情
- ✅ 关闭 Merge Request
- ✅ 快捷合并到测试分支

## 许可证

ISC

## 作者

Jasery

## 贡献

欢迎提交 Issue 和 Pull Request！

## 支持

如果遇到问题，请检查：
1. ✅ 环境变量 `GITLAB_ACCESS_TOKEN` 是否正确设置
2. ✅ GitLab API 是否可访问
3. ✅ Token 是否有足够的权限（需要 `api` 权限）
4. ✅ 项目 ID 是否正确
5. ✅ 使用的 SDK 版本是否为最新版本（1.24.0+）