Refactor GitLab MCP server implementation
- 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.
This commit is contained in:
zhangguoyun committed
1 parent
09d624a464
commit
347096b2e1
5 files changed
+1060
-663
No files matched your search
@@ -1,103 +1,490 @@
|
||||
# GitLab MCP 服务器
|
||||
# GitLab MCP Server
|
||||
|
||||
这是一个 Model Context Protocol (MCP) 服务器，专门用于与 GitLab 交互，主要功能包括创建和合并 Merge Request。
|
||||
一个支持 GitLab 操作的 Model Context Protocol (MCP) 服务器，主要用于创建和管理 Merge Requests。
|
||||
|
||||
## 功能
|
||||
## 功能特性
|
||||
|
||||
- `create_merge_request`: 在指定的 GitLab 项目中创建一个新的 Merge Request
|
||||
- `merge_merge_request`: 合并指定的 GitLab Merge Request
|
||||
- `get_merge_request`: 获取指定 Merge Request 的详细信息
|
||||
- `close_merge_request`: 关闭指定的 GitLab Merge Request 而不合并
|
||||
- ✅ 创建 Merge Request
|
||||
- ✅ 合并 Merge Request
|
||||
- ✅ 获取 Merge Request 详情
|
||||
- ✅ 关闭 Merge Request
|
||||
- ✅ 快捷合并到测试分支
|
||||
- ✅ 支持 Stdio 和 Streamable HTTP 两种传输方式
|
||||
- ✅ 支持通过 npx 直接运行，无需安装
|
||||
|
||||
## 环境变量
|
||||
## 快速开始
|
||||
|
||||
- `GITLAB_ACCESS_TOKEN`: 用于访问 GitLab API 的访问令牌
|
||||
- `GITLAB_API_BASE_URL`: GitLab API 的基础 URL（默认为 `https://gitlab.com/api/v4`）
|
||||
### 方式一：使用 npx（推荐，无需安装）
|
||||
|
||||
## 安装和运行
|
||||
```bash
|
||||
# 1. 设置环境变量
|
||||
export GITLAB_ACCESS_TOKEN="your_gitlab_token_here"
|
||||
|
||||
1. 首先，确保你已经安装了 Node.js 和 npm。
|
||||
2. 安装依赖：
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
3. 设置环境变量：
|
||||
```bash
|
||||
export GITLAB_ACCESS_TOKEN="your_gitlab_access_token"
|
||||
export GITLAB_API_BASE_URL="https://your-gitlab-instance.com/api/v4" # 可选，仅当使用自托管的 GitLab 时
|
||||
```
|
||||
4. 运行 GitLab MCP 服务器：
|
||||
```bash
|
||||
npm run gitlab
|
||||
```
|
||||
# 2. 直接运行（默认 stdio 模式）
|
||||
npx gitlab-mcp-server
|
||||
|
||||
## 架构
|
||||
# 或使用 HTTP 模式
|
||||
npx gitlab-mcp-server --transport http --port 3000
|
||||
|
||||
该项目使用一个封装的 `gitlabApiClient` 对象来处理所有与 GitLab API 的交互，这使得代码更模块化和可维护。API 客户端包含以下方法：
|
||||
# 查看帮助
|
||||
npx gitlab-mcp-server --help
|
||||
```
|
||||
|
||||
- `createMergeRequest`: 创建 Merge Request
|
||||
- `mergeMergeRequest`: 合并 Merge Request
|
||||
- `getMergeRequest`: 获取 Merge Request 详情
|
||||
- `closeMergeRequest`: 关闭 Merge Request
|
||||
### 方式二：本地安装运行
|
||||
|
||||
## 工具详情
|
||||
```bash
|
||||
# 1. 克隆或下载项目
|
||||
git clone <repository-url>
|
||||
cd gitlab-mcp-server
|
||||
|
||||
### create_merge_request
|
||||
# 2. 安装依赖
|
||||
npm install
|
||||
|
||||
创建一个新的 Merge Request。
|
||||
# 3. 设置环境变量
|
||||
export GITLAB_ACCESS_TOKEN="your_gitlab_token_here"
|
||||
export GITLAB_API_BASE_URL="https://gitlab.com/api/v4" # 可选
|
||||
|
||||
参数：
|
||||
- `projectId`: GitLab 项目的 ID 或 URL 编码的路径
|
||||
- `sourceBranch`: 源分支名称
|
||||
- `targetBranch`: 目标分支名称
|
||||
- `title`: Merge Request 的标题
|
||||
- `description`: (可选) Merge Request 的描述
|
||||
- `assigneeId`: (可选) 负责人 ID
|
||||
- `reviewerIds`: (可选) 审阅者 ID 数组
|
||||
# 4. 运行
|
||||
npm start # 默认 stdio 模式
|
||||
```
|
||||
|
||||
### merge_merge_request
|
||||
## 环境变量配置
|
||||
|
||||
合并一个 Merge Request。
|
||||
### Windows (PowerShell)
|
||||
```powershell
|
||||
# 临时设置（当前会话）
|
||||
$env:GITLAB_ACCESS_TOKEN="your_token_here"
|
||||
$env:GITLAB_API_BASE_URL="https://gitlab.com/api/v4"
|
||||
|
||||
参数：
|
||||
- `projectId`: GitLab 项目的 ID 或 URL 编码的路径
|
||||
- `mrIid`: Merge Request 的内部 ID
|
||||
- `mergeCommitMessage`: (可选) 合并提交的消息
|
||||
- `shouldRemoveSourceBranch`: (可选) 是否在合并后删除源分支
|
||||
- `mergeWhenPipelineSucceeds`: (可选) 是否在 CI 管道成功后合并
|
||||
# 永久设置（用户级别）
|
||||
[System.Environment]::SetEnvironmentVariable('GITLAB_ACCESS_TOKEN', 'your_token_here', 'User')
|
||||
```
|
||||
|
||||
### get_merge_request
|
||||
### Linux/Mac
|
||||
```bash
|
||||
# 临时设置
|
||||
export GITLAB_ACCESS_TOKEN="your_token_here"
|
||||
export GITLAB_API_BASE_URL="https://gitlab.com/api/v4"
|
||||
|
||||
获取 Merge Request 的详细信息。
|
||||
# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
|
||||
echo 'export GITLAB_ACCESS_TOKEN="your_token_here"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
参数：
|
||||
- `projectId`: GitLab 项目的 ID 或 URL 编码的路径
|
||||
- `mrIid`: Merge Request 的内部 ID
|
||||
### 如何获取 GitLab Access Token
|
||||
|
||||
### close_merge_request
|
||||
1. 登录 GitLab
|
||||
2. 进入 **Settings** > **Access Tokens**
|
||||
3. 创建新的 Personal Access Token
|
||||
4. 选择 `api` 权限
|
||||
5. 复制生成的 token
|
||||
|
||||
关闭一个 Merge Request 而不合并。
|
||||
## 使用方式
|
||||
|
||||
参数：
|
||||
- `projectId`: GitLab 项目的 ID 或 URL 编码的路径
|
||||
- `mrIid`: Merge Request 的内部 ID
|
||||
### 通过 npx 运行（推荐）
|
||||
|
||||
```bash
|
||||
# Stdio 模式（默认）
|
||||
npx gitlab-mcp-server
|
||||
|
||||
## 配置 MCP 服务器
|
||||
# HTTP 模式
|
||||
npx gitlab-mcp-server --transport http --port 3000
|
||||
|
||||
``` json
|
||||
# 使用简写参数
|
||||
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-mcp-server": {
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/your/code/path/index-gitlab.js"
|
||||
],
|
||||
"gitlab": {
|
||||
"command": "npx",
|
||||
"args": ["gitlab-mcp-server"],
|
||||
"env": {
|
||||
"GITLAB_API_BASE_URL": "https://git.ifengqun.com/api/v4",
|
||||
"GITLAB_ACCESS_TOKEN": "your_gitlab_token"
|
||||
"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+）
|
||||
Reference in new issue
Block a user