# 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)