zhangguoyun
347096b2e1
- Removed gitlab-index.js and integrated its functionality into index.js. - Updated server name to "gitlab-mcp-server" and version to "1.1.0". - Enhanced GitLab API client with methods for creating, merging, retrieving, and closing merge requests. - Added tools for handling merge requests with detailed input validation using Zod. - Implemented command-line argument parsing for transport mode (stdio or http) and port configuration. - Introduced Streamable HTTP transport for remote access and debugging. - Updated package dependencies to the latest versions.
490 lines
11 KiB
Markdown
490 lines
11 KiB
Markdown
# 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+） |