GitLab MCP 服务器

一个基于 Model Context Protocol (MCP) 的 GitLab 接口工具，提供了与 GitLab 项目交互的各种功能。

功能特性

• 🔍 获取 GitLab 仓库列表
• 🔀 创建合并请求（MR）
• 👥 获取项目成员信息
• 🌿 管理项目分支（列出、创建、删除）
• 🔐 支持访问权限控制
• 📋 详细的错误处理和反馈

环境要求

• Node.js 16+
• GitLab 访问权限
• 有效的 GitLab Personal Access Token

安装配置

1. 环境变量配置

# GitLab API 地址（可选，默认使用内置地址）
export GITLAB_API="https://your-gitlab-instance.com/api/v4/projects?membership=true&per_page=100&page=1"

# GitLab Personal Access Token（必需）
export GITLAB_TOKEN="your-gitlab-token"

2. 启动服务器

# 直接运行
node dist/index.js

# 或使用 npm 脚本
npm start

工具列表

1. 📋 gitlab_get_interfaces

获取当前用户有权限访问的所有 GitLab 仓库列表。

参数： 无

示例输出：

📋 仓库列表（共 10 个）：
- project-1
- project-2
- project-3

2. 🔀 gitlab_create_merge_request_by_name

为指定项目创建合并请求（MR）。

参数： | 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | project_name | string | ✅ | GitLab 项目名称 | | source_branch | string | ✅ | 源分支名称 | | target_branch | string | ✅ | 目标分支名称 | | title | string | ✅ | 合并请求标题 | | description | string | ❌ | 合并请求描述 | | assignee_username | string | ❌ | 指定审批人用户名 | | reviewer_username | string | ❌ | 指定评审人用户名 |

示例：

{
  "project_name": "my-awesome-project",
  "source_branch": "feature/new-feature",
  "target_branch": "main",
  "title": "添加新功能",
  "description": "这个PR添加了一个很棒的新功能",
  "assignee_username": "team-lead",
  "reviewer_username": "senior-dev"
}

3. 👥 gitlab_get_project_members_by_name

获取指定项目的成员列表。

参数： | 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | project_name | string | ✅ | GitLab 项目名称 |

示例输出：

👥 项目 "my-project" 成员列表：
- john.doe (John Doe) - 维护者
- jane.smith (Jane Smith) - 开发者
- bob.wilson (Bob Wilson) - 普通成员

4. 🌿 gitlab_list_branches_by_name

获取指定项目的分支列表。

参数： | 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | project_name | string | ✅ | GitLab 项目名称 |

示例输出：

📂 项目 "my-project" 分支列表：
- main
- develop
- feature/user-auth
- hotfix/critical-bug

5. ➕ gitlab_create_branch_by_name

为指定项目创建新分支。

参数： | 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | project_name | string | ✅ | GitLab 项目名称 | | new_branch | string | ✅ | 要创建的新分支名称 | | ref_branch | string | ✅ | 基准分支（如 main） |

示例：

{
  "project_name": "my-project",
  "new_branch": "feature/payment-integration",
  "ref_branch": "main"
}

6. ❌ gitlab_delete_branch_by_name

删除指定项目的分支。

参数： | 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | project_name | string | ✅ | GitLab 项目名称 | | branch_name | string | ✅ | 要删除的分支名称 |

示例：

{
  "project_name": "my-project",
  "branch_name": "feature/old-feature"
}

错误处理

该工具包含完善的错误处理机制：

• ❌ 项目未找到： 当指定的项目名称不存在时
• ❌ 用户未找到： 当指定的审批人或评审人不存在时
• ❌ 权限不足： 当没有足够权限执行操作时
• ❌ API 错误： 当 GitLab API 返回错误时
• ❌ 网络错误： 当无法连接到 GitLab 服务器时

配置说明

GitLab Token 权限要求

您的 Personal Access Token 需要包含以下权限：

• read_api - 读取 API 访问权限
• read_repository - 读取仓库权限
• write_repository - 写入仓库权限（用于创建/删除分支）
• read_user - 读取用户信息权限

默认配置

const GITLAB_API = process.env.GITLAB_API || 
  "https://code.qschou.com/api/v4/projects?membership=true&per_page=100&page=1"
const GITLAB_TOKEN = "glpat-yruxzDESzqxSFQ1MoMgH"

使用示例

创建一个完整的开发流程

1. 查看项目列表

   # 使用 gitlab_get_interfaces 工具

2. 创建新功能分支

   {
     "tool": "gitlab_create_branch_by_name",
     "project_name": "my-awesome-app",
     "new_branch": "feature/user-dashboard",
     "ref_branch": "main"
   }

3. 查看项目成员

   {
     "tool": "gitlab_get_project_members_by_name",
     "project_name": "my-awesome-app"
   }

4. 创建合并请求

   {
     "tool": "gitlab_create_merge_request_by_name",
     "project_name": "my-awesome-app",
     "source_branch": "feature/user-dashboard",
     "target_branch": "main",
     "title": "添加用户仪表板功能",
     "description": "实现了用户仪表板的基本功能，包括数据展示和交互",
     "assignee_username": "project-manager",
     "reviewer_username": "senior-developer"
   }

注意事项

• ⚠️ 安全性： 请妥善保管您的 GitLab Token，不要将其提交到版本控制系统中
• ⚠️ 权限： 确保您的 Token 具有必要的权限来执行相应操作
• ⚠️ 分支删除： 删除分支操作不可逆，请谨慎使用
• ⚠️ API 限制： 注意 GitLab API 的调用频率限制

故障排除

常见问题

1. Token 认证失败

   • 检查 GITLAB_TOKEN 是否正确
   • 确认 Token 权限是否足够

2. 项目未找到

   • 确认项目名称拼写正确
   • 检查您是否有该项目的访问权限

3. 分支操作失败

   • 确认分支名称是否存在/不存在（取决于操作类型）
   • 检查您是否有分支的写入权限

许可证

本项目使用 MIT 许可证。

贡献

欢迎提交 Issue 和 Pull Request！

作者： GitLab MCP 团队
版本： 1.0.0
更新时间： 2024年