关于 efficient-gitlab
efficient-gitlab 是一个面向 GitLab 操作、注重减少上下文占用的 MCP 服务,适合使用 Agent 处理 GitLab 项目的团队。它通过按需启用工具、字段投影和内容分页精简输入与响应;仓库已归档,README 建议改用上游项目。
主要功能
- 013 个元工具按需启用 167 个工具
- 02列表响应支持字段投影
- 03按行或字节裁剪文件内容
- 04仓库树支持键集分页
- 05支持只读模式和项目范围限制
适用场景
- 01按需启用 GitLab 操作类别
- 02仅读取列表结果中的指定字段
- 03分段读取大型文件或仓库目录
MCP 相关
该 MCP 服务通过 3 个元工具向 MCP 客户端提供 GitLab 功能,并支持按类别动态启用工具。配置 GitLab 访问令牌及 API 地址后,可连接 GitLab.com 或自托管实例。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
3收录的工具列表 · 更新于 2 周前
此工具无需参数。
详细介绍
高效 GitLab MCP
注意
此仓库已于 2026-05-22 归档。
上游
zereight/gitlab-mcpv2.1+ 已独立实现渐进式披露和架构精简(提交44983ec)。本分支原有的差异化优势已不复存在——请改用上游版本。
节省令牌的 GitLab MCP 服务。 这是 zereight/gitlab-mcp 的一个分支,经过重新架构以适应 Agent 的上下文预算:通过 3 个元工具提供 167 个工具,所有列表端点均支持字段投影,文件在服务端裁剪,大型目录采用键集分页。
如果 Agent 在你提出任何问题之前,首次调用 MCP 服务就要为工具定义消耗约 20K 个令牌,那么这个分支正适合你。
快速开始
前提条件
- 具有
api作用域的 GitLab Personal Access Token(只读时可使用read_api)。创建令牌 → - Node.js 18+(用于
npx),或 Bun 1.0+(用于bunx)
MCP 客户端配置(推荐大多数用户使用)
将以下内容添加到 MCP 客户端配置中,例如 Claude Desktop、Cursor、Claude Code、IDE 扩展等:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["efficient-gitlab-mcp-server@latest"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com"
}
}
}
}
重启客户端。服务将启用 3 个元工具(list_categories、activate_tools、deactivate_tools)。Agent 可按需激活分类来发现 GitLab 工具——具体示例请参阅工作原理。
更喜欢使用
bun?将"command": "npx"替换为"command": "bunx"。
变体
自托管的 GitLab — 将实例的基础 URL 指向此处(服务会自行追加 /api/v4):
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.your-company.com"
}
固定到单个项目 — Agent 无需重复指定 project_id;它会被用作默认值:
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com",
"GITLAB_PROJECT_ID": "12345"
}
限制为多个项目 — 每次调用都必须指定允许列表中的 project_id:
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com",
"GITLAB_ALLOWED_PROJECT_IDS": "12345,67890,123"
}
只读(自动检测) — 使用仅具有 read_api 作用域的 PAT;服务会在启动时检测其受限作用域,并仅公开 93 个只读工具。无需额外配置。
只读(强制启用) — 保留具有 api 作用域的 PAT,但在服务级别强制启用只读模式:
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com",
"GITLAB_READ_ONLY_MODE": "true"
}
其他入口
Claude Code CLI(单行添加):
claude mcp add -s user gitlab \
-e GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
-e GITLAB_API_URL=https://gitlab.com \
-- npx efficient-gitlab-mcp-server@latest
GitLab CI runner — 如果未设置 PAT,则会自动检测 CI_JOB_TOKEN。使用 GITLAB_PROJECT_ID: $CI_PROJECT_ID 将范围限定为正在运行的项目。无需额外设置。
从源代码运行(开发):
git clone https://github.com/detailobsessed/efficient-gitlab-mcp.git
cd efficient-gitlab-mcp
bun install
bun run build
bun start
遇到问题?请参阅故障排除。需要调整更多环境变量?请参阅完整配置参考。
目录
为什么要创建这个分支?
GitLab 的 API 覆盖面极广,上游 MCP 服务也反映了这一点——启动时会始终公开所有工具。对于上下文预算有限的 Agent 来说,这会在三个方面造成浪费:
- 启动时的工具定义。 数百个工具架构会在用户首次发言前就被塞进提示词。
- 列表端点响应。 默认情况下,GitLab 列表端点返回的每行对象包含 100 多个字段;而相关信息通常不到 10 个字段。
- 文件内容和大型目录。 读取单个文件可能会载入数千行无关内容;列出大型仓库树时则会一次性返回所有内容。
这个分支通过三种方式解决上述问题:对工具定义采用渐进式披露,对列表响应进行字段投影,以及对内容进行裁剪和键集分页。
Token 效率
渐进式披露
服务不会公开 167 个独立工具,而是公开 3 个元工具:
| 元工具 | 用途 |
|---|---|
list_categories | 发现可用的工具类别及其启用状态 |
activate_tools | 启用一个或多个类别中的所有工具 |
deactivate_tools | 完成后禁用某个类别——释放相应 Token |
| 方式 | 公开的工具 | 估计 Token 开销 |
|---|---|---|
| 传统方式 | 167 个工具 | ~20,000+ 个 Token |
| 渐进式披露 | 3 个元工具 | ~1,500 个 Token |
启动时的工具定义 Token 减少约 90%。 工具会注册到 MCP SDK,但在 LLM 启用某个类别前保持禁用状态(tool.disable())——启用后会触发 tools/list_changed 通知,让客户端即时获取这些工具。
字段投影
列表端点——以及越来越多的单项 get_* 端点——会按资源返回经过筛选、采用允许列表的默认字段集。调用方可以通过 fields: "all" 选择完整载荷,也可以用 fields: ["id", "name"] 指定自己的字段列表。
目前已应用于:
list_projects、list_group_projects、get_projectlist_issues、my_issues、get_issuelist_merge_requests、get_merge_requestlist_pipelines、get_pipelinelist_releaseslist_commits、get_commitget_current_user、get_user、get_users、search_users
一项针对拥有 5 个项目的 list_projects 测量显示,切换到紧凑默认模式后,响应大小从 约 32 KB 降至约 3 KB。由于采用允许列表,上游 GitLab 添加新字段时,紧凑输出仍能保持紧凑。
示例——使用紧凑默认模式与完整 GitLab 载荷获取合并请求:
// Default: ~17 fields (iid, title, state, draft, labels, branches, author, …)
{ "name": "get_merge_request", "arguments": { "merge_request_iid": 42 } }
// Opt out: the raw GitLab response
{ "name": "get_merge_request", "arguments": { "merge_request_iid": 42, "fields": "all" } }
// Custom pick
{ "name": "get_merge_request", "arguments": { "merge_request_iid": 42, "fields": ["iid", "title", "state"] } }
精简默认字段源自用于验证 GitLab API 响应的同一组 Zod 响应模式(见 src/schemas/),因此它们会与类型层级的结构保持同步,并且每种资源都有唯一的事实来源。
服务端文件裁剪
get_file_contents 支持裁剪参数,Agent 无需为了读取某个函数而将整个文件拉入上下文:
| 参数 | 用途 |
|---|---|
head: N | 仅返回前 N 行 |
tail: N | 仅返回最后 N 行 |
range: "start-end" | 返回指定行范围 |
max_bytes: N | 字节数硬上限(可与按行裁剪组合使用) |
截断的响应会包含类似 Showing lines 100-200 of 5234 的说明,因此后续调用可以指定其他范围,而无需先重新获取文件来统计行数。
Keyset 分页
get_repository_tree 支持 keyset 分页(pagination=keyset),并返回一个封装对象:
{
"items": [...],
"pagination_note": "Next page available — call again with pagination=keyset&page_token=..."
}
大型单体仓库不再会在单个响应中倾倒 10K 条目。服务端会从 X-Next-Page-Token 读取游标(较旧的 GitLab 实例则回退到 X-Next-Page),并将其直接包含在响应中。
与上游有何不同?
此分支基于 zereight/gitlab-mcp 构建,采用重新设计的架构,专注于提高令牌效率和可维护性。我们会定期审查上游提交,并有选择地移植新功能和错误修复——由于代码库在结构上已出现分化,我们不会盲目变基。
架构概览
| 领域 | 上游 | 此分支 |
|---|---|---|
| 架构 | 单个 index.ts(约 10K 行) | 模块化 src/,包含 16 个工具模块 |
| 工具发现 | 一次性公开所有 140 多个工具 | SDK 原生渐进式披露(3 个元工具) |
| 列表响应 | 完整 GitLab 载荷(每行 100 多个字段) | 字段投影:紧凑默认值 + 可选 fields |
| 文件内容 | 获取整个文件 | 服务端使用 head / tail / range / max_bytes 进行裁剪 |
| 树列表 | 仅支持偏移量分页 | 偏移量分页 + keyset 分页(pagination=keyset),并提供游标封装对象 |
| 工具注释 | 部分支持 | 完整支持:每个工具均包含 readOnlyHint / destructiveHint / idempotentHint / openWorldHint |
| 配置 | 分散的独立导出项 | 带有 loadConfig() 的类型化 ServerConfig 接口 |
| 日志记录 | console.log | 用于观测 Agent 行为的结构化 MCP 协议记录器 |
| 运行时 | Node.js + npm | Bun(构建更快,原生支持 TypeScript) |
| 代码检查 | ESLint + Prettier | 严格的 Biome 规则(noExplicitAny、noNonNullAssertion、认知复杂度上限) |
| CI/CD | 基础 | GitHub Actions(代码检查、构建、测试、semantic-release) |
| 提交前检查 | 无 | prek 钩子(拼写检查、格式化、构建验证) |
| 功能标志 | 必须配置 USE_PIPELINE、USE_MILESTONE、USE_GITLAB_WIKI | 无——所有类别均已注册,启用前处于休眠状态 |
其他改进
- 只读模式与 PAT 安全性 — 自动检测 PAT 范围、显式只读模式,并提供可操作的 403 错误消息。
- 机密信息脱敏 — 默认从项目响应中移除
runners_token;设置include_secrets: true可重新包含。 - 稳健的架构强制转换 — 对布尔值、数字 ID 和字符串化数组进行防御性强制转换(LLM 的序列化方式并不一致)。
- HTTP 传输安全性 — DNS 重绑定防护,可配置允许的主机和来源。
- 全面的测试套件 — 280+ 项测试,覆盖注册表、配置、日志记录器、MCP 集成、只读模式、投影和元工具。
- 严格的代码质量 — 不使用
any类型,不使用非空断言,并强制限制认知复杂度。 - 自动化发布 — 使用约定式提交进行语义化版本控制。
可用类别
所有 GitLab 操作分为 16 个类别,共包含 167 个工具。所有类别都会在启动时注册,但默认处于休眠状态——只激活你需要的类别。
| 类别 | 工具数 | 描述 |
|---|---|---|
repositories | 11 | 搜索、创建、派生仓库。获取/推送文件、管理分支、列出目录树 |
merge-requests | 33 | 创建、更新、合并 MR。讨论、线程、差异 |
issues | 14 | 创建、更新、删除问题。关联、讨论 |
pipelines | 19 | 列出、创建、重试、取消流水线。作业输出 |
projects | 10 | 项目详情、列表、成员、标签 |
commits | 3 | 列出提交、获取提交、获取差异 |
namespaces | 3 | 列出、获取、验证命名空间 |
users | 8 | 用户详情、搜索、审计/项目事件、文件上传、当前用户(whoami) |
search | 6 | 在代码、问题、MR 和提交中进行全局、项目及群组搜索 |
wiki | 10 | 管理项目和群组的 Wiki 页面 |
milestones | 9 | 创建、编辑、删除里程碑。燃尽事件 |
releases | 7 | 列出、创建、更新、删除发布版本。下载资源 |
webhooks | 3 | 列出项目 Webhook 和近期事件 |
work-items | 12 | GraphQL 工作项:创建、更新、层级、备注、事件 |
graphql | 1 | 执行任意 GraphQL 查询 |
emoji-reactions | 18 | 对 MR / 问题 / 工作项 / 备注添加、移除和列出表情反应(REST + GraphQL) |
工作原理
典型的 Agent 会话包含三个阶段——发现、激活、工作——并可在不再需要某个类别时选择通过停用进行清理。
1. 发现(约 1.5K 个 token)
MCP 客户端连接后,服务只会公开 3 个元工具。Agent 调用 list_categories 查看可用类别:
> list_categories()
{
"categories": [
{ "name": "repositories", "tools": 11, "active": false, "description": "Search, create, fork repos. Get/push files, manage branches, list tree" },
{ "name": "merge-requests", "tools": 33, "active": false, "description": "Create, update, merge MRs. Discussions, threads, diffs" },
{ "name": "issues", "tools": 14, "active": false, "description": "Create, update, delete issues. Links, discussions" },
// ... 13 more, 167 tools total
]
}
2. 激活
Agent 决定需要什么并激活相应类别:
> activate_tools({ categories: ["merge-requests"] })
"Activated 33 tools in category 'merge-requests'."
服务会发送 tools/list_changed 通知,让客户端即时获取新增的 33 个工具定义。
Claude Code 延迟说明:在一轮对话中途激活的工具要到下一轮才能调用(Claude Code 会在轮次之间重建其延迟工具索引)。其他客户端可能会立即调用。
3. 工作
> create_merge_request({
project_id: "123",
title: "Fix bug",
source_branch: "fix",
target_branch: "main"
})
{ "id": 7891, "iid": 42, "title": "Fix bug", "state": "opened", ... }
4. 停用(可选)
Agent 完成此类别的工作后,可以释放相应 token:
> deactivate_tools({ categories: ["merge-requests"] })
"Deactivated 33 tools in category 'merge-requests'."
这在上下文资源有限的长时间 Agent 会话中特别有用——只加载所需内容,完成后将其移除,再加载其他类别。
配置
核心设置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
GITLAB_PERSONAL_ACCESS_TOKEN | 是* | - | GitLab 个人访问令牌(优先于 CI_JOB_TOKEN) |
CI_JOB_TOKEN | 否 | - | GitLab CI 作业令牌(在 CI 流水线中自动检测) |
GITLAB_API_URL | 否 | https://gitlab.com | GitLab 实例 URL |
GITLAB_PROJECT_ID | 否 | - | 工具未提供 project_id 时使用的默认项目 ID |
GITLAB_ALLOWED_PROJECT_IDS | 否 | - | 将工具限制在这些项目内(以逗号分隔)。如果只有一个项目,则将其作为默认项目。如果有多个项目,则每次调用都必须提供 project_id |
GITLAB_READ_ONLY_MODE | 否 | false | 仅公开只读工具。如果未设置,则根据 PAT 作用域自动检测 |
GITLAB_IS_OLD | 否 | false | 适用于较旧的 GitLab 实例 |
*建议使用 PAT。如果未设置 PAT,则会在 GitLab CI 流水线中自动检测 CI_JOB_TOKEN。计划支持 OAuth(参见 OAuth 设置指南)。
传输设置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
STREAMABLE_HTTP | 否 | false | 启用 HTTP 传输 |
SSE | 否 | false | 启用 SSE 传输 |
PORT | 否 | 3002 | HTTP 服务端口 |
HOST | 否 | 127.0.0.1 | HTTP 服务主机 |
日志与安全
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
LOG_LEVEL | 否 | info | debug、info、warn、error |
LOG_FORMAT | 否 | pretty | json、pretty |
HTTP_ALLOWED_HOSTS | 否 | localhost,127.0.0.1 | 允许的 Host 标头 |
HTTP_ALLOWED_ORIGINS | 否 | (任意) | 允许的 Origin 标头 |
HTTP_ENABLE_DNS_REBINDING_PROTECTION | 否 | true | 启用 DNS 重绑定攻击防护 |
远程授权(多租户)
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
REMOTE_AUTHORIZATION | 否 | false | 启用远程授权 |
ENABLE_DYNAMIC_API_URL | 否 | false | 允许使用动态 GitLab URL |
SESSION_TIMEOUT_SECONDS | 否 | 3600 | 会话超时时间 |
MAX_SESSIONS | 否 | 1000 | 最大并发会话数 |
MAX_REQUESTS_PER_MINUTE | 否 | 60 | 每个会话的速率限制 |
功能
只读模式与 PAT 安全
对于使用作用域受限的个人访问令牌的用户,服务提供了三层保护:
1. 显式只读模式 — 设置 GITLAB_READ_ONLY_MODE=true,将服务限制为只读工具。写入工具不会出现在 list_categories 计数中,也无法启用。此功能由每个工具上的 readOnlyHint 注解决定。
2. 自动检测 PAT 作用域 — 启动时,服务会调用 GitLab 的 GET /personal_access_tokens/self 来检查令牌的作用域。如果令牌缺少 api 作用域(例如,只有 read_api),则会自动启用只读模式。无需配置,开箱即用。
3. 提供可执行建议的 403 错误消息 — 如果工具调用遇到 403 Forbidden 错误,错误消息会具体说明所需的 PAT 作用域,以便大模型告知用户,而不是盲目重试。
# Explicit read-only mode
GITLAB_READ_ONLY_MODE=true
# Or just use a read_api token — auto-detected!
GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-read-only-token
密钥脱敏
默认情况下,GitLab 项目响应中会包含 runners_token 字段——任何拥有该令牌的人都可以针对该项目注册 CI Runner。服务在 get_project 和 list_projects 的响应中默认对 runners_token 进行脱敏。若要恢复包含该字段(例如,Agent 需要管理 Runner 注册时),请传入 include_secrets: true。
工具注解
每个工具都声明了一套完整的 MCP 工具注解,以便支持 MCP 的客户端能够提供按操作确认、区分破坏性操作与幂等更新,并按副作用类型筛选:
| 工具类型 | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |
|---|---|---|---|---|
| 只读(列表/获取) | true | (省略) | (省略) | true |
| 创建 | false | false | false | true |
| 更新 | false | true | true | true |
| 删除 | false | true | true | true |
openWorldHint 始终为 true,因为每个工具都会与 GitLab 的 API 通信。注解矩阵由不变量测试强制执行。
MCP 协议日志记录
该服务支持 MCP 协议日志记录,以便 Agent 观察其运行情况。连接后,大模型客户端可以接收结构化日志消息,了解服务正在执行的操作:
- 工具执行日志
- GitLab API 调用详情
- 附带上下文的错误信息
这有助于 Agent 理解服务行为并调试问题,而不是只能看到开发者才能查看的、不透明的 console.log 输出。
HTTP 传输安全
使用 HTTP 传输(STREAMABLE_HTTP=true)时,该服务包含以下安全功能:
| 环境变量 | 默认值 | 说明 |
|---|---|---|
HTTP_ALLOWED_HOSTS | localhost,127.0.0.1 | 允许的 Host 标头列表,以逗号分隔 |
HTTP_ALLOWED_ORIGINS | (任意) | 允许的 Origin 标头列表,以逗号分隔 |
HTTP_ENABLE_DNS_REBINDING_PROTECTION | true | 启用 DNS 重绑定攻击防护 |
生产环境示例:
HTTP_ALLOWED_HOSTS=api.example.com,localhost \
HTTP_ALLOWED_ORIGINS=https://app.example.com \
STREAMABLE_HTTP=true \
bun start
故障排除
Agent 激活了某个类别,但看不到新工具
你的 MCP 客户端需要支持 tools/list_changed 通知,才能接收运行时激活的工具。大多数现代客户端都支持此功能。
特别是在 Claude Code 中,已激活的工具要到下一轮才可以调用——客户端会在轮次之间重建延迟工具索引,而不是在一轮内同步完成。因此,在同一轮中调用 activate_tools({ categories: ["issues"] }),然后调用 list_issues() 不会生效;下一轮即可调用。其他客户端(Claude Desktop、Cursor)通常会更快响应。
工具返回 "403 Forbidden",但我以为它应该能正常工作
该服务返回可采取操作的 403 错误——错误消息会指出缺少哪些 PAT 权限范围。常见原因是:你的 PAT 只有 read_api 权限范围(只读),而调用的工具需要 api。你可以重新生成具有 api 权限范围的 PAT,或保持只读模式并使用读取工具。
project_id 一直被拒绝
如果设置了 GITLAB_ALLOWED_PROJECT_IDS,且包含多个以逗号分隔的 ID,则每次工具调用都必须显式提供与其中一个 ID 匹配的 project_id——没有默认值。如果只有一个 ID,未传入 project_id 时会将该 ID 用作默认值。留空或未设置表示不限制(允许任意项目 ID)。
无法连接自托管的 GitLab
GITLAB_API_URL 应为实例的基础 URL(https://gitlab.your-company.com),而不是 API 路径。服务会自行追加 /api/v4。如果你使用的基础路径已包含 /api/v4,调用将访问 /api/v4/api/v4/... 并返回 404。
GitLab CI 中的 CI 工具无法工作
如果未设置 GITLAB_PERSONAL_ACCESS_TOKEN,服务会自动回退到 CI_JOB_TOKEN(从 GitLab CI 环境自动检测)。在 .gitlab-ci.yml 中设置 GITLAB_PROJECT_ID: $CI_PROJECT_ID,即可将正在运行的流水线所属项目用作默认范围。
项目响应中缺少 runners_token
为安全起见,该字段默认会被隐藏。如需获取该字段,请在调用时传入 include_secrets: true。
列表端点返回的结果少于预期
对于 list_issues、list_merge_requests 等:GitLab 的全局端点(未提供 project_id 时)历史上默认使用 scope: created_by_me。若要查看所有内容,请显式传入 scope: "all"。如果提供了 project_id,调用会路由到项目级端点,因此不适用此默认值。
MCP 服务日志中出现 GitLab response failed schema validation
GitLab 在服务端经过模式定义的读取端点(用户、项目、合并请求、提交、议题、流水线、仓库树)上的响应,会通过 Zod 模式进行校验。如果不匹配,服务会记录 WARN GitLab response failed schema validation; passing through unchanged,并附上字段路径和 Zod 错误代码,然后将响应原样传递给你的大模型——因此调用仍会成功,但这也表明 GitLab 返回了我们尚不了解的结构。通常原因是 GitLab API 发生变化(新增字段、类型更改或字段移除),或可自托管的 EE 实例返回了仅 EE 版才有的字段。如果看到这类警告,请提交 issue,并附上 path、code 以及触发问题的工具——这能提示我们更新模式。
开发
# Install dependencies
bun install
# Run tests (280+ tests, <1s)
bun test
# Run tests with coverage
bun test --coverage
# Lint and format
bun run check
# Build
bun run build
模式漂移 CI
运行时通过 parseGitLabResponse 的路径有意采用宽松策略(.safeParse() + 记录警告 + 原样传递),这样 GitLab 出现意外字段也不会阻止 MCP 工具调用。漂移检查是严格校验的对应流程:一个 Bun 脚本会调用每个带有响应模式定义的 GitLab REST 端点,并使用声明的 Zod 模式对每个响应执行 .parse(),遇到任何不匹配都会失败。
在本地运行:
export GITLAB_API_URL=https://gitlab.com
export GITLAB_PERSONAL_ACCESS_TOKEN=glpat-... # read_api scope only
export GITLAB_PROJECT_ID=12345 # must have ≥1 MR/commit/issue/pipeline
bun run drift
适合手动运行的情况:
- 合并涉及
src/schemas/的 PR 之前——通过真实实例检查模式问题,补充基于固定样例的单元测试。 - 升级可自托管的 GitLab 后——快速检查响应结构是否发生变化。
- 排查可疑的大模型行为时——如果响应看起来不正确,但工具返回了 OK,可能是模式不匹配被静默传递;漂移检查可确认或排除此情况。
同一脚本会通过 .github/workflows/schema-drift.yml 在 CI 中运行——每周一 06:00 UTC 按 schedule 触发,也可按需通过 workflow_dispatch 触发。同样的三个环境变量已配置为仓库机密。
上游跟踪
我们将 main 维护为上游的只读镜像。我们会审查上游的新功能和错误修复,并视需要移植到我们的架构中——由于代码库的结构已出现差异,我们不会盲目地进行变基。如果你在寻找某项特定的上游功能,请查看我们的发行版本,或提交 issue。
安全
- 切勿提交令牌——使用
.env文件(已加入 gitignore) - 轮换令牌——定期重新生成
- 最小权限——仅授予必要的 API 范围
- 审计日志——监控 API 访问
- 机密信息脱敏——默认会对
runners_token进行脱敏;请参阅机密信息脱敏
致谢
本项目是 zereight/gitlab-mcp 的分支。感谢原作者全面实现 GitLab API。
资源
- MCP 协议:modelcontextprotocol.io
- GitLab API:docs.gitlab.com/ee/api
- Bun:bun.sh
许可证
MIT 许可证——详情请参阅 LICENSE。
Efficient GitLab MCP
借助 AI 实现高效的 GitLab 管理
基于 Bun 和 Model Context Protocol 构建
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。