README.md•5.96 kB
# GitLab Pipeline MCP Server
一个用于 GitLab 流水线操作的 Model Context Protocol (MCP) 服务器。
## 🎯 项目概述
本项目允许AI客户端（如Cursor、Claude Desktop等）通过自然语言直接操作GitLab流水线。
## 功能特性
- 🚀 触发 GitLab 流水线
- 📊 获取流水线状态
- 📋 列出流水线
- 🔧 获取流水线作业
- ❌ 取消流水线
## 安装
```bash
yarn install
```
## 环境变量配置
在使用前，请设置以下环境变量：
```bash
export GITLAB_URL="https://gitlab.example.com"
export GITLAB_PROJECT_ID="123"
export GITLAB_TOKEN="your-gitlab-token"
```
或者创建 `.env` 文件：
```env
GITLAB_URL=https://gitlab.example.com
GITLAB_PROJECT_ID=123
GITLAB_TOKEN=your-gitlab-token
```
## 使用方式
### 1. STDIO 模式（标准输入输出）
适用于 MCP 客户端直接连接：
```bash
# 使用原版实现（支持所有5个工具）
yarn build
```
**MCP 客户端配置示例：**
```json
{
"mcpServers": {
"gitlab": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-gitlab/build/index.js"],//你的路径
"env": {
"GITLAB_URL": "https://gitlab.example.com",
"GITLAB_PROJECT_ID": "123",
"GITLAB_TOKEN": "your-gitlab-token"
}
}
}
}
```
### 2. Streamable HTTP 模式
适用于开发和调试，支持 HTTP 端点访问：
```bash
# 使用原版实现（支持所有5个工具）
yarn dev
```
**MCP 客户端配置示例：**
```json
{
"mcpServers": {
"gitlab-http": {
"env": {
"GITLAB_URL": "https://gitlab.example.com",
"GITLAB_PROJECT_ID": "123",
"GITLAB_TOKEN": "your-gitlab-token"
},
"url": "http://localhost:3300/mcp"
}
}
}
```
**HTTP 端点：**
- 🔗 MCP 端点: `http://localhost:3300/mcp`
- 💚 健康检查: `http://localhost:3300/health`
- 📋 服务信息: `http://localhost:3300/`
## 🔧 使用MCP Inspector调试
```bash
# 启动调试界面
./debug-with-inspector.sh
```
这将打开一个Web界面（通常在 http://localhost:5173），你可以在其中：
- 查看所有可用工具
- 测试工具调用
- 查看请求和响应
- 调试参数传递
## 🛠️ 核心功能
### 动态参数支持
所有工具都支持动态传入以下参数，无需预先配置：
- **gitlabUrl**: GitLab基础URL（如：`https://gitlab.com`）
- **projectId**: 项目ID或路径（如：`123` 或 `group/project`）
- **token**: GitLab访问令牌（如：`glpat-xxxxxxxxxxxx`）
### 可用工具列表
| 工具名称 | 功能描述 | 主要参数 |
|---------|----------|----------|
| `trigger_pipeline` | 触发流水线 | gitlabUrl, projectId, ref, token, variables(可选) |
| `get_pipeline_status` | 获取流水线状态 | gitlabUrl, projectId, pipelineId, token |
| `list_pipelines` | 列出流水线 | gitlabUrl, projectId, token, ref(可选), status(可选) |
| `get_pipeline_jobs` | 获取流水线作业 | gitlabUrl, projectId, pipelineId, token |
| `cancel_pipeline` | 取消流水线 | gitlabUrl, projectId, pipelineId, token |
## 💬 使用示例
在支持MCP的AI客户端中，你可以使用自然语言来操作GitLab流水线：
### 基础操作
```
"帮我触发 mygroup/myproject 项目的 main 分支流水线，GitLab地址是 https://gitlab.example.com，使用令牌 glpat-xxxxxxxxxxxx"
"查看项目 123 在 https://gitlab.com 上的流水线 456 的状态"
"列出 mygroup/myproject 项目最近的流水线，只显示失败的"
```
### 高级操作
```
"触发流水线时传入环境变量 DEPLOY_ENV=production 和 VERSION=v1.2.3"
"取消正在运行的流水线 789"
"查看流水线 456 的所有作业状态，看看哪个作业失败了"
```
### 多环境支持
```
"在我们的私有GitLab https://gitlab.company.com 上触发项目 team/backend 的 develop 分支流水线"
"检查生产环境流水线状态，项目在 https://gitlab.com/prod/app，流水线ID是 999"
```
## 🔐 安全配置
### GitLab访问令牌
1. 登录GitLab
2. 进入 **Settings** > **Access Tokens**
3. 创建新令牌，需要以下权限：
- `api` - 完整API访问权限
- `read_repository` - 读取仓库权限
- `write_repository` - 写入仓库权限
### 环境变量安全
- 永远不要将 `.env` 文件提交到版本控制
- 使用不同的令牌用于不同的环境
- 定期轮换访问令牌
- 限制令牌的权限范围
## 📁 项目结构
```
mcp-gitlab/
├── src/ # 源代码
│ ├── index.ts # 主服务器文件
│ ├── services/
│ │ └── gitlab.ts # GitLab API服务
│ └── utils/
│ └── logger.ts # 日志工具
├── dist/ # 构建输出
├── .env.example # 环境变量模板
├── mcp-config-examples.json # MCP客户端配置示例
├── test-server.js # 服务器测试脚本
├── debug-with-inspector.sh # 调试脚本
├── package.json # 项目配置
├── tsconfig.json # TypeScript配置
└── README.md # 项目说明
```
## 🐛 常见问题
### Q: 服务器启动失败
A: 检查Node.js版本（需要>=18），确保依赖已安装，检查TypeScript编译错误。
### Q: GitLab API调用失败
A: 验证访问令牌权限，检查GitLab URL格式，确认项目ID正确。
### Q: MCP客户端连接不上
A: 检查配置文件路径，确认服务器已构建，查看客户端日志。
### Q: 工具调用参数错误
A: 参考工具定义中的参数要求，使用MCP Inspector测试参数格式。
## 📚 相关资源
- [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
- [GitLab API 文档](https://docs.gitlab.com/ee/api/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)