@zereight/mcp-gitlab 2.3.21 → 2.3.22-next.205
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +12 -10
- package/README.md +17 -15
- package/README.pt-BR.md +12 -10
- package/README.zh-CN.md +12 -10
- package/build/index.js +1 -1
- package/build/schemas.js +120 -220
- package/build/server/mcp-help.js +6 -3
- package/build/server/mcp-instructions.js +1 -1
- package/build/tools/registry.js +7 -9
- package/build/tools/tool-descriptions.js +4 -4
- package/package.json +1 -1
package/README.ko.md
CHANGED
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
**기본 노출: 40개 도구** (`core` 38개 + `discover_tools` + `help`). 전체는 288개(toolset 285개 + `execute_graphql` + `discover_tools` + `help`). 작게 시작하고, 세션에서 `discover_tools`로 확장하세요.
|
|
10
10
|
|
|
11
|
+
> **토큰 예산:** MCP 클라이언트는 세션 시작 때 `tools/list` 전체를 모델에 보냅니다. 기본값(~40개 도구, 스키마 ~12k 토큰)을 유지하세요. 확장은 `discover_tools`로 이 세션에만 카테고리를 켜거나(`OAUTH_STATELESS_MODE=true`면 `GITLAB_TOOLSETS`로 남기세요), [Skill + CLI](./docs/getting-started/cli-without-mcp.md)로 MCP 스키마를 건너뛰세요. **`GITLAB_TOOLSETS=all`은 쓰지 마세요** — 거의 모든 도구를 올려 스키마만 ~73k 토큰입니다. [tools/list 크기](#toolslist-크기-2026-11-05-실측)와 [비교](./docs/comparison/index.md)를 보세요.
|
|
12
|
+
|
|
11
13
|
`zereight-mcp-gitlab` 바이너리를 먼저 설치하세요. `npm install -g @zereight/mcp-gitlab`, 또는 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 다음 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. 공식 MCP Registry 항목: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). 한 줄 설치: `npx -y @zereight/mcp-gitlab@latest`.
|
|
12
14
|
|
|
13
15
|
### Without → With
|
|
@@ -58,7 +60,7 @@ MCP 설정을 고칠 수 있는 에이전트에 그대로 붙여넣으세요:
|
|
|
58
60
|
또는: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
59
61
|
Cursor: README deeplink 또는 docs/clients/cursor.md.
|
|
60
62
|
원격 HTTP: 클라이언트를 https://mcp.example.com/mcp (Streamable HTTP)로 연결. Claude.ai는 그 호스트에 GITLAB_MCP_OAUTH가 필요합니다.
|
|
61
|
-
기본 목록: 40개 도구(core 38 + discover_tools + help). 확장은 discover_tools. api toolset은 우회 위험을 받아들일 때만.
|
|
63
|
+
기본 목록: 40개 도구(core 38 + discover_tools + help). 확장은 discover_tools. GITLAB_TOOLSETS=all은 쓰지 마세요(스키마 ~73k 토큰). api toolset은 우회 위험을 받아들일 때만.
|
|
62
64
|
MCP 없는 동등 경로: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill 와 zereight-mcp-gitlab CLI.
|
|
63
65
|
```
|
|
64
66
|
|
|
@@ -111,7 +113,7 @@ Human CLI는 compact되지 않습니다. 파괴적 도구와 `GITLAB_TOOL_POLICY
|
|
|
111
113
|
|
|
112
114
|
**인증은 어떻게 하나요?** 로컬 데스크톱은 `GITLAB_PERSONAL_ACCESS_TOKEN`(또는 `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`)이 가장 단순합니다. 로컬 OAuth는 `GITLAB_USE_OAUTH=true`. 원격 Claude.ai는 `GITLAB_MCP_OAUTH`. 멀티유저 HTTP는 `REMOTE_AUTHORIZATION`과 요청별 토큰 헤더입니다.
|
|
113
115
|
|
|
114
|
-
**도구가 40개만 보이는 이유는?** 기본 `core` toolset 38개에 항상 켜진 `discover_tools`와 `help`가 더해집니다. 인자 없이 `discover_tools`를 호출하면 카테고리 목록이 나오고, 카테고리(`pipelines`, `wiki` 등)를 넘기면 이 세션에 활성화됩니다. `GITLAB_TOOLSETS=all
|
|
116
|
+
**도구가 40개만 보이는 이유는?** 기본 `core` toolset 38개에 항상 켜진 `discover_tools`와 `help`가 더해집니다. 클라이언트가 나열된 스키마를 모델에 한꺼번에 보내기 때문입니다. 인자 없이 `discover_tools`를 호출하면 카테고리 목록이 나오고, 카테고리(`pipelines`, `wiki` 등)를 넘기면 이 세션에 활성화됩니다. 세션 한정이며, `OAUTH_STATELESS_MODE=true`면 `GITLAB_TOOLSETS`로 남기세요. **`GITLAB_TOOLSETS=all`은 쓰지 마세요** — 스키마만 ~73k 토큰이고, `api`도 켜지지 않습니다.
|
|
115
117
|
|
|
116
118
|
**로컬 OAuth / MCP OAuth / 원격 인증 차이는?** 로컬 OAuth는 서버와 같은 머신에서 브라우저를 엽니다. MCP OAuth는 공개 HTTPS 서버와 Claude.ai 같은 클라이언트용입니다. 원격 인증은 호출자의 PAT 또는 job token을 전달하며 OAuth 흐름이 없습니다.
|
|
117
119
|
|
|
@@ -123,7 +125,7 @@ Human CLI는 compact되지 않습니다. 파괴적 도구와 `GITLAB_TOOL_POLICY
|
|
|
123
125
|
|
|
124
126
|
```
|
|
125
127
|
GitLab 머지 리퀘스트, 이슈, 파이프라인은 이 MCP(@zereight/mcp-gitlab)로 처리하세요.
|
|
126
|
-
기본 core 도구로 시작하고, 확장은 discover_tools를 호출하세요.
|
|
128
|
+
기본 core 도구로 시작하고, 확장은 discover_tools를 호출하세요. GITLAB_TOOLSETS=all은 쓰지 마세요.
|
|
127
129
|
list_merge_request_changed_files 다음 배치 get_merge_request_file_diff를 우선하세요.
|
|
128
130
|
결과는 jmespath 또는 compact를 쓰고, 전체 diff와 job 로그는 CLI를 쓰세요.
|
|
129
131
|
```
|
|
@@ -138,7 +140,7 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
|
|
|
138
140
|
|
|
139
141
|
### 왜 이 GitLab MCP를 사용하나요?
|
|
140
142
|
|
|
141
|
-
- **기본 40개 도구(`core` 38 + `discover_tools` + `help`); 전체 288개** — 작게 시작하고, `discover_tools`로 세션에서
|
|
143
|
+
- **기본 40개 도구(`core` 38 + `discover_tools` + `help`); 전체 288개** — 작게 시작하고, `discover_tools`로 세션에서 확장. `GITLAB_TOOLSETS=all`은 스키마 ~73k 토큰; 필요할 때만 켜거나 Skill + CLI를 쓰세요
|
|
142
144
|
- **MR 2단계 리뷰** — `list_merge_request_changed_files` → 배치 `get_merge_request_file_diff`
|
|
143
145
|
- **Agent Skill 내장** — `skills/gitlab-mcp/` 워크플로우 가이드
|
|
144
146
|
- **유연한 인증** — Personal Access Token, 로컬 OAuth2 브라우저 플로우, MCP OAuth 프록시, 요청별 원격 인증
|
|
@@ -157,17 +159,17 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
|
|
|
157
159
|
| **Node.js** | >=20.0.0 | 보통 >=24 | stdio는 `mcp-remote`, Node.js 20+ |
|
|
158
160
|
| **라이선스** | MIT | 서버마다 다름 | GitLab의 일부 |
|
|
159
161
|
|
|
160
|
-
### tools/list 크기 (2026-
|
|
162
|
+
### tools/list 크기 (2026-11-05 실측)
|
|
161
163
|
|
|
162
164
|
클라이언트는 세션 시작 때 `tools/list` 전체를 모델에 보냅니다. 토큰 추정은 UTF-8 바이트 / 4입니다.
|
|
163
165
|
|
|
164
166
|
| 프로필 | 도구 수 | JSON 바이트 | 추정 토큰 |
|
|
165
167
|
| ------ | ------: | ----------: | --------: |
|
|
166
|
-
| 기본값 (`core` + `discover_tools` + `help`) | 40 |
|
|
167
|
-
| `GITLAB_TOOL_PROFILE=slim` | 39 |
|
|
168
|
-
| `GITLAB_TOOLSETS=all` |
|
|
168
|
+
| 기본값 (`core` + `discover_tools` + `help`) | 40 | 46,943 | 11,736 |
|
|
169
|
+
| `GITLAB_TOOL_PROFILE=slim` | 39 | 45,935 | 11,484 |
|
|
170
|
+
| `GITLAB_TOOLSETS=all` | 286 | 293,906 | 73,477 |
|
|
169
171
|
|
|
170
|
-
설명이나 스키마를 바꾼 뒤에는 `npm run test:mock` (`test/tools-list-budget.test.ts`)으로 다시 측정하세요.
|
|
172
|
+
설명이나 스키마를 바꾼 뒤에는 `npm run build && npm run test:mock` (`test/tools-list-budget.test.ts`)으로 다시 측정하세요.
|
|
171
173
|
|
|
172
174
|
GitLab은 [공식 MCP 서버](https://docs.gitlab.com/user/model_context_protocol/mcp_server/)도 제공합니다.
|
|
173
175
|
|
|
@@ -282,7 +284,7 @@ v2.3.1 이후의 GitHub 릴리스마다 `gitlab-mcp.mcpb` [MCP Bundle](https://g
|
|
|
282
284
|
- `--api-url` - GitLab API URL (`GITLAB_API_URL` 대체)
|
|
283
285
|
- `--read-only=true` - Deprecated (removed in next major (v3.0.0)); `--permission-mode=readonly`를 사용 (`GITLAB_READ_ONLY_MODE` 대체)
|
|
284
286
|
- `--permission-mode` - 권한 수준: `readonly`, `modify`(삭제/중단 도구 비활성), `full` (`GITLAB_PERMISSION_MODE` 대체, 기본값 `full`)
|
|
285
|
-
- `--toolsets
|
|
287
|
+
- `--toolsets` - 지정한 툴셋 (`GITLAB_TOOLSETS` 대체, 미설정 시 lean `core` 기본값). `all`은 스키마 ~73k 토큰이므로 쓰지 마세요. `gitlab_api_request`는 `--toolsets=api`
|
|
286
288
|
- `--tools=list_issues` - 개별 도구 추가 (`GITLAB_TOOLS` 대체)
|
|
287
289
|
- `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); `--toolsets=core,wiki`를 사용 (`USE_GITLAB_WIKI` 대체)
|
|
288
290
|
- `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); `--toolsets=core,milestones`를 사용 (`USE_MILESTONE` 대체)
|
package/README.md
CHANGED
|
@@ -14,6 +14,8 @@
|
|
|
14
14
|
|
|
15
15
|
**Default: 40 tools** (38 `core` + `discover_tools` + `help`). 288 tools exist in total (285 in toolsets + `execute_graphql` + `discover_tools` + `help`). Start lean; call `discover_tools` to activate more for this session.
|
|
16
16
|
|
|
17
|
+
> **Token budget:** MCP clients send the whole `tools/list` to the model at session start. Keep the default (~40 tools, ~12k schema tokens). Call `discover_tools` to activate a category for this session (session-only; with `OAUTH_STATELESS_MODE=true` persist a named `GITLAB_TOOLSETS` list), or use [Skill + CLI](./docs/getting-started/cli-without-mcp.md) and skip MCP schemas. **Do not set `GITLAB_TOOLSETS=all`** — it loads ~all tools and costs ~73k schema tokens. See [tools/list size](#toolslist-size-measured-2026-11-05) and [comparison](./docs/comparison/index.md).
|
|
18
|
+
|
|
17
19
|
Install the `zereight-mcp-gitlab` binary first with `npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` and `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. Official MCP Registry listing: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). One-liner: `npx -y @zereight/mcp-gitlab@latest`.
|
|
18
20
|
|
|
19
21
|
### Without → With
|
|
@@ -64,7 +66,7 @@ Local: claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSON
|
|
|
64
66
|
Or: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
65
67
|
Cursor: use the README deeplink or docs/clients/cursor.md.
|
|
66
68
|
Remote HTTP: point the client at https://mcp.example.com/mcp (Streamable HTTP). Claude.ai needs GITLAB_MCP_OAUTH on that host.
|
|
67
|
-
Default list: 40 tools (38 core + discover_tools + help). Call discover_tools to expand. Do not enable the api toolset unless you accept its bypass risk.
|
|
69
|
+
Default list: 40 tools (38 core + discover_tools + help). Call discover_tools to expand. Do not set GITLAB_TOOLSETS=all (loads ~all schemas, ~73k tokens). Do not enable the api toolset unless you accept its bypass risk.
|
|
68
70
|
Equal non-MCP path: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill plus the zereight-mcp-gitlab CLI.
|
|
69
71
|
```
|
|
70
72
|
|
|
@@ -117,7 +119,7 @@ Human CLI is never compacted. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE`
|
|
|
117
119
|
|
|
118
120
|
**How do I authenticate?** Local desktop: `GITLAB_PERSONAL_ACCESS_TOKEN` (or `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) is the simplest. Local OAuth is `GITLAB_USE_OAUTH=true`. Remote Claude.ai uses `GITLAB_MCP_OAUTH`. Multi-user HTTP uses `REMOTE_AUTHORIZATION` and a per-request token header.
|
|
119
121
|
|
|
120
|
-
**Why do I only see ~40 tools?** The default `core` toolset is 38 tools plus always-on `discover_tools` and `help`. Call `discover_tools` with no args to list categories, then pass a category (`pipelines`, `wiki`, …) to activate it for this session. `GITLAB_TOOLSETS=all
|
|
122
|
+
**Why do I only see ~40 tools?** The default `core` toolset is 38 tools plus always-on `discover_tools` and `help`. That is intentional: a client sends every listed schema to the model up front. Call `discover_tools` with no args to list categories, then pass a category (`pipelines`, `wiki`, …) to activate it for this session. Session-only; with `OAUTH_STATELESS_MODE=true` persist a named `GITLAB_TOOLSETS` list. **Do not set `GITLAB_TOOLSETS=all`** — it loads ~all schemas (~73k tokens) and still does **not** enable `api`.
|
|
121
123
|
|
|
122
124
|
**Local OAuth vs MCP OAuth vs remote auth?** Local OAuth opens a browser on the same machine as the server. MCP OAuth is for a public HTTPS server and clients such as Claude.ai. Remote authorization forwards the caller's PAT or job token; there is no OAuth dance.
|
|
123
125
|
|
|
@@ -129,7 +131,7 @@ Human CLI is never compacted. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE`
|
|
|
129
131
|
|
|
130
132
|
```
|
|
131
133
|
GitLab merge requests, issues, and pipelines go through this MCP (@zereight/mcp-gitlab).
|
|
132
|
-
Start with the default core tools. Call discover_tools to expand.
|
|
134
|
+
Start with the default core tools. Call discover_tools to expand. Do not set GITLAB_TOOLSETS=all.
|
|
133
135
|
Prefer list_merge_request_changed_files, then batched get_merge_request_file_diff.
|
|
134
136
|
Use jmespath or compact results; use the CLI for full diffs and job logs.
|
|
135
137
|
```
|
|
@@ -144,7 +146,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
|
|
|
144
146
|
|
|
145
147
|
### Why use this GitLab MCP?
|
|
146
148
|
|
|
147
|
-
- **Default 40 tools (38 `core` + `discover_tools` + `help`); 288 total** — start lean; call `discover_tools` to activate more without CQRS-style grouping
|
|
149
|
+
- **Default 40 tools (38 `core` + `discover_tools` + `help`); 288 total** — start lean; call `discover_tools` to activate more without CQRS-style grouping. `GITLAB_TOOLSETS=all` loads ~all schemas (~73k tokens); prefer discover-on-demand or Skill + CLI
|
|
148
150
|
- **MR 2-step review** — `list_merge_request_changed_files` → batched `get_merge_request_file_diff`
|
|
149
151
|
- **Agent Skill built in** — workflow guidance in `skills/gitlab-mcp/`
|
|
150
152
|
- **Flexible auth** — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
|
|
@@ -163,17 +165,17 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
|
|
|
163
165
|
| **Node.js** | >=20.0.0 | Often >=24 | Node.js 20+ for stdio via `mcp-remote` |
|
|
164
166
|
| **License** | MIT | Varies | Part of GitLab |
|
|
165
167
|
|
|
166
|
-
### tools/list size (measured 2026-
|
|
168
|
+
### tools/list size (measured 2026-11-05)
|
|
167
169
|
|
|
168
170
|
A client sends the whole `tools/list` result to the model at session start. Token estimate is UTF-8 bytes / 4.
|
|
169
171
|
|
|
170
172
|
| Profile | Tools | JSON bytes | Est. tokens |
|
|
171
173
|
| ------- | ----: | ---------: | ----------: |
|
|
172
|
-
| Default (`core` + `discover_tools` + `help`) | 40 |
|
|
173
|
-
| `GITLAB_TOOL_PROFILE=slim` | 39 |
|
|
174
|
-
| `GITLAB_TOOLSETS=all` |
|
|
174
|
+
| Default (`core` + `discover_tools` + `help`) | 40 | 46,943 | 11,736 |
|
|
175
|
+
| `GITLAB_TOOL_PROFILE=slim` | 39 | 45,935 | 11,484 |
|
|
176
|
+
| `GITLAB_TOOLSETS=all` | 286 | 293,906 | 73,477 |
|
|
175
177
|
|
|
176
|
-
Re-measure with `npm run test:mock` (`test/tools-list-budget.test.ts`) after description or schema changes.
|
|
178
|
+
Re-measure with `npm run build && npm run test:mock` (`test/tools-list-budget.test.ts`) after description or schema changes.
|
|
177
179
|
|
|
178
180
|
GitLab also ships an [official MCP server](https://docs.gitlab.com/user/model_context_protocol/mcp_server/).
|
|
179
181
|
|
|
@@ -288,7 +290,7 @@ Some MCP clients (like GitHub Copilot CLI) have issues with environment variable
|
|
|
288
290
|
- `--api-url` - GitLab API URL (replaces `GITLAB_API_URL`)
|
|
289
291
|
- `--read-only=true` - Deprecated (removed in next major (v3.0.0)); use `--permission-mode=readonly` instead (replaces `GITLAB_READ_ONLY_MODE`)
|
|
290
292
|
- `--permission-mode` - Permission level: `readonly`, `modify` (no delete or teardown tools), or `full` (replaces `GITLAB_PERMISSION_MODE`, default `full`)
|
|
291
|
-
- `--toolsets
|
|
293
|
+
- `--toolsets` - Named toolsets (replaces `GITLAB_TOOLSETS`; unset uses the lean `core` default). Do not pass `all` unless you accept ~73k schema tokens. `gitlab_api_request` needs `--toolsets=api`
|
|
292
294
|
- `--tools=list_issues` - Add individual tools (replaces `GITLAB_TOOLS`)
|
|
293
295
|
- `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,wiki` instead (replaces `USE_GITLAB_WIKI`)
|
|
294
296
|
- `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,milestones` instead (replaces `USE_MILESTONE`)
|
|
@@ -852,9 +854,9 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
|
|
|
852
854
|
69. `delete_issue_note_emoji_reaction` - Remove an emoji reaction from an issue note. Pass discussion_id for discussion thread replies.
|
|
853
855
|
70. `list_issues` - List issues (default: created by current user; use scope='all' for all)
|
|
854
856
|
71. `my_issues` - List issues assigned to the authenticated user
|
|
855
|
-
72. `get_issue` - Get
|
|
856
|
-
73. `update_issue` - Update an issue.
|
|
857
|
-
74. `update_issue_description_patch` -
|
|
857
|
+
72. `get_issue` - Get one issue. Slim nested milestone by default; full_response=true for the complete milestone
|
|
858
|
+
73. `update_issue` - Update an issue. Slim confirmation by default; full_response=true for the complete object
|
|
859
|
+
74. `update_issue_description_patch` - Patch an issue description (search/replace or unified diff) without resending the full body. dry_run previews; create_note summarizes
|
|
858
860
|
75. `reorder_issue` - Move an issue within the manual sort order shown on issue boards. move_after_id and move_before_id take the neighbor issue's global id (the `id` field), not its iid; pass at least one. Returns the reordered issue.
|
|
859
861
|
76. `delete_issue` - Delete an issue
|
|
860
862
|
77. `list_todos` - List GitLab to-do items for the current user
|
|
@@ -990,7 +992,7 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
|
|
|
990
992
|
207. `delete_group_iteration_cadence` - Delete an iteration cadence
|
|
991
993
|
208. `upload_markdown` - Upload a file for use in markdown content
|
|
992
994
|
209. `download_attachment` - Download an uploaded file from a project (images returned as base64; other files, or images with local_path, are saved as new files under the download directory)
|
|
993
|
-
210. `health_check` -
|
|
995
|
+
210. `health_check` - Check auth and versions. Always includes mcp_server_version. When authenticated, also GitLab version, revision, and enterprise from GET /api/v4/version. Version lookup failures omit those fields instead of failing
|
|
994
996
|
211. `list_events` - List events for the authenticated user (before/after: YYYY-MM-DD)
|
|
995
997
|
212. `get_project_events` - List events for a project (before/after: YYYY-MM-DD)
|
|
996
998
|
213. `list_releases` - List all releases for a project
|
|
@@ -1067,7 +1069,7 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
|
|
|
1067
1069
|
284. `get_runner` - Get a runner's tag_list, run_untagged, locked, and access_level. When a project allowlist is active, the runner must be available to an allowed project. Omits registration and authentication tokens.
|
|
1068
1070
|
285. `rebase_merge_request` - Rebase the source branch of a merge request onto its target branch
|
|
1069
1071
|
286. `gitlab_api_request` - Send one GitLab REST call under /api/v4. Enabled only when GITLAB_TOOLSETS lists api. Readonly allows GET; modify rejects DELETE.
|
|
1070
|
-
287. `discover_tools` -
|
|
1072
|
+
287. `discover_tools` - List or activate a toolset for this session. Omit category to list; pass one to enable. Prefer this over GITLAB_TOOLSETS=all (loads ~all schemas). Session-only; with OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS.
|
|
1071
1073
|
288. `help` - Return a short GitLab workflow guide. Omit topic for the overview and topic list.
|
|
1072
1074
|
|
|
1073
1075
|
<!-- TOOLS-END -->
|
package/README.pt-BR.md
CHANGED
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
**Padrão: 40 ferramentas** (38 `core` + `discover_tools` + `help`). Existem 288 no total (285 em toolsets + `execute_graphql` + `discover_tools` + `help`). Comece enxuto; chame `discover_tools` para ativar mais nesta sessão.
|
|
10
10
|
|
|
11
|
+
> **Orçamento de tokens:** clientes MCP enviam o `tools/list` inteiro ao modelo no início da sessão. Mantenha o padrão (~40 ferramentas, ~12k tokens de schema). Chame `discover_tools` para ativar uma categoria nesta sessão (somente nesta sessão; com `OAUTH_STATELESS_MODE=true` persista uma lista `GITLAB_TOOLSETS`), ou use [Skill + CLI](./docs/getting-started/cli-without-mcp.md) e pule os schemas MCP. **Não defina `GITLAB_TOOLSETS=all`** — carrega quase todas as ferramentas e custa ~73k tokens de schema. Veja [tamanho do tools/list](#tamanho-do-toolslist-medido-em-2026-11-05) e [comparação](./docs/comparison/index.md).
|
|
12
|
+
|
|
11
13
|
Instale o binário `zereight-mcp-gitlab` antes. `npm install -g @zereight/mcp-gitlab`, ou Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` e `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. Listagem oficial no MCP Registry: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). Instalação em uma linha: `npx -y @zereight/mcp-gitlab@latest`.
|
|
12
14
|
|
|
13
15
|
### Without → With
|
|
@@ -58,7 +60,7 @@ Local: claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSON
|
|
|
58
60
|
Ou: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
59
61
|
Cursor: use o deeplink do README ou docs/clients/cursor.md.
|
|
60
62
|
HTTP remoto: aponte o cliente para https://mcp.example.com/mcp (Streamable HTTP). Claude.ai precisa de GITLAB_MCP_OAUTH nesse host.
|
|
61
|
-
Lista padrão: 40 ferramentas (38 core + discover_tools + help). Expanda com discover_tools. Não habilite o toolset api sem aceitar o risco de bypass.
|
|
63
|
+
Lista padrão: 40 ferramentas (38 core + discover_tools + help). Expanda com discover_tools. Não defina GITLAB_TOOLSETS=all (carrega ~todos os schemas, ~73k tokens). Não habilite o toolset api sem aceitar o risco de bypass.
|
|
62
64
|
Caminho equivalente sem MCP: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill mais a CLI zereight-mcp-gitlab.
|
|
63
65
|
```
|
|
64
66
|
|
|
@@ -111,7 +113,7 @@ A CLI humana nunca é compactada. Ferramentas destrutivas e `GITLAB_TOOL_POLICY_
|
|
|
111
113
|
|
|
112
114
|
**Como autenticar?** No desktop local, `GITLAB_PERSONAL_ACCESS_TOKEN` (ou `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) é o mais simples. OAuth local é `GITLAB_USE_OAUTH=true`. Claude.ai remoto usa `GITLAB_MCP_OAUTH`. HTTP multi-usuário usa `REMOTE_AUTHORIZATION` e um cabeçalho de token por requisição.
|
|
113
115
|
|
|
114
|
-
**Por que vejo só ~40 ferramentas?** O toolset `core` padrão tem 38 ferramentas mais o `discover_tools` e o `help` sempre ligados. Chame `discover_tools` sem args para listar categorias e passe uma (`pipelines`, `wiki`, …) para ativá-la nesta sessão. `GITLAB_TOOLSETS=all
|
|
116
|
+
**Por que vejo só ~40 ferramentas?** O toolset `core` padrão tem 38 ferramentas mais o `discover_tools` e o `help` sempre ligados. Isso é intencional: o cliente envia todos os schemas listados ao modelo de uma vez. Chame `discover_tools` sem args para listar categorias e passe uma (`pipelines`, `wiki`, …) para ativá-la nesta sessão. Somente nesta sessão; com `OAUTH_STATELESS_MODE=true` persista uma lista `GITLAB_TOOLSETS`. **Não defina `GITLAB_TOOLSETS=all`** — custa ~73k tokens de schema e ainda **não** habilita `api`.
|
|
115
117
|
|
|
116
118
|
**OAuth local vs MCP OAuth vs auth remota?** OAuth local abre o navegador na mesma máquina do servidor. MCP OAuth é para um servidor HTTPS público e clientes como Claude.ai. Autorização remota encaminha o PAT ou job token do chamador; não há fluxo OAuth.
|
|
117
119
|
|
|
@@ -123,7 +125,7 @@ A CLI humana nunca é compactada. Ferramentas destrutivas e `GITLAB_TOOL_POLICY_
|
|
|
123
125
|
|
|
124
126
|
```
|
|
125
127
|
Merge requests, issues e pipelines do GitLab passam por este MCP (@zereight/mcp-gitlab).
|
|
126
|
-
Comece pelas ferramentas core padrão. Chame discover_tools para expandir.
|
|
128
|
+
Comece pelas ferramentas core padrão. Chame discover_tools para expandir. Não defina GITLAB_TOOLSETS=all.
|
|
127
129
|
Prefira list_merge_request_changed_files e depois get_merge_request_file_diff em lote.
|
|
128
130
|
Use jmespath ou resultados compactos; use a CLI para diffs e logs completos.
|
|
129
131
|
```
|
|
@@ -138,7 +140,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
|
|
|
138
140
|
|
|
139
141
|
### Por que usar este GitLab MCP?
|
|
140
142
|
|
|
141
|
-
- **40 ferramentas por padrão (38 `core` + `discover_tools` + `help`); 288 no total** — comece enxuto; chame `discover_tools` para expandir nesta sessão
|
|
143
|
+
- **40 ferramentas por padrão (38 `core` + `discover_tools` + `help`); 288 no total** — comece enxuto; chame `discover_tools` para expandir nesta sessão. `GITLAB_TOOLSETS=all` custa ~73k tokens de schema; prefira descoberta sob demanda ou Skill + CLI
|
|
142
144
|
- **Revisão de MR em 2 etapas** — `list_merge_request_changed_files` → `get_merge_request_file_diff` em lote
|
|
143
145
|
- **Agent Skill integrado** — orientação de workflows em `skills/gitlab-mcp/`
|
|
144
146
|
- **Autenticação flexível** — Personal Access Token, fluxo OAuth2 local no navegador, proxy MCP OAuth e autorização remota por requisição
|
|
@@ -157,17 +159,17 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
|
|
|
157
159
|
| **Node.js** | >=20.0.0 | Frequentemente >=24 | Node.js 20+ para stdio via `mcp-remote` |
|
|
158
160
|
| **Licença** | MIT | Varia | Parte do GitLab |
|
|
159
161
|
|
|
160
|
-
### Tamanho do tools/list (medido em 2026-
|
|
162
|
+
### Tamanho do tools/list (medido em 2026-11-05)
|
|
161
163
|
|
|
162
164
|
O cliente envia o `tools/list` inteiro ao modelo no início da sessão. A estimativa de tokens é bytes UTF-8 / 4.
|
|
163
165
|
|
|
164
166
|
| Perfil | Ferramentas | Bytes JSON | Tokens estimados |
|
|
165
167
|
| ------ | ----------: | ---------: | ---------------: |
|
|
166
|
-
| Padrão (`core` + `discover_tools` + `help`) | 40 |
|
|
167
|
-
| `GITLAB_TOOL_PROFILE=slim` | 39 |
|
|
168
|
-
| `GITLAB_TOOLSETS=all` |
|
|
168
|
+
| Padrão (`core` + `discover_tools` + `help`) | 40 | 46.943 | 11.736 |
|
|
169
|
+
| `GITLAB_TOOL_PROFILE=slim` | 39 | 45.935 | 11.484 |
|
|
170
|
+
| `GITLAB_TOOLSETS=all` | 286 | 293.906 | 73.477 |
|
|
169
171
|
|
|
170
|
-
Após alterar descrições ou schemas, meça de novo com `npm run test:mock` (`test/tools-list-budget.test.ts`).
|
|
172
|
+
Após alterar descrições ou schemas, meça de novo com `npm run build && npm run test:mock` (`test/tools-list-budget.test.ts`).
|
|
171
173
|
|
|
172
174
|
O GitLab também inclui um [servidor MCP oficial](https://docs.gitlab.com/user/model_context_protocol/mcp_server/).
|
|
173
175
|
|
|
@@ -282,7 +284,7 @@ Alguns clientes MCP, como o GitHub Copilot CLI, têm problemas com variáveis de
|
|
|
282
284
|
- `--api-url` - URL da API do GitLab (substitui `GITLAB_API_URL`)
|
|
283
285
|
- `--read-only=true` - Deprecated (removed in next major (v3.0.0)); use `--permission-mode=readonly` (substitui `GITLAB_READ_ONLY_MODE`)
|
|
284
286
|
- `--permission-mode` - nível de permissão: `readonly`, `modify` (sem ferramentas de exclusão ou teardown) ou `full` (substitui `GITLAB_PERMISSION_MODE`, padrão `full`)
|
|
285
|
-
- `--toolsets
|
|
287
|
+
- `--toolsets` - toolsets nomeados (substitui `GITLAB_TOOLSETS`; sem valor usa o padrão enxuto `core`). Não passe `all` a menos que aceite ~73k tokens de schema. `gitlab_api_request` exige `--toolsets=api`
|
|
286
288
|
- `--tools=list_issues` - adiciona ferramentas individuais (substitui `GITLAB_TOOLS`)
|
|
287
289
|
- `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,wiki` (substitui `USE_GITLAB_WIKI`)
|
|
288
290
|
- `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,milestones` (substitui `USE_MILESTONE`)
|
package/README.zh-CN.md
CHANGED
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
**默认暴露 40 个工具**(38 个 `core` + `discover_tools` + `help`)。总共 288 个(toolset 中 285 个 + `execute_graphql` + `discover_tools` + `help`)。先用精简集,再在本会话中用 `discover_tools` 扩展。
|
|
10
10
|
|
|
11
|
+
> **Token 预算:** MCP 客户端会在会话开始时把整份 `tools/list` 发给模型。请保持默认(约 40 个工具,约 12k schema token)。用 `discover_tools` 为本会话激活类别(仅限本会话;`OAUTH_STATELESS_MODE=true` 时请改用命名的 `GITLAB_TOOLSETS`),或走 [Skill + CLI](./docs/getting-started/cli-without-mcp.md) 以跳过 MCP schema。**不要设置 `GITLAB_TOOLSETS=all`** — 它会加载几乎全部工具,schema 约 73k token。见 [tools/list 体积](#toolslist-体积2026-11-05-实测) 和 [对比](./docs/comparison/index.md)。
|
|
12
|
+
|
|
11
13
|
先安装 `zereight-mcp-gitlab` 二进制。`npm install -g @zereight/mcp-gitlab`,或 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 然后 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`。官方 MCP Registry 条目:[`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp)。一键安装:`npx -y @zereight/mcp-gitlab@latest`。
|
|
12
14
|
|
|
13
15
|
### Without → With
|
|
@@ -58,7 +60,7 @@ codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS
|
|
|
58
60
|
或:codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
|
|
59
61
|
Cursor:使用 README deeplink 或 docs/clients/cursor.md。
|
|
60
62
|
远程 HTTP:将客户端指向 https://mcp.example.com/mcp(Streamable HTTP)。Claude.ai 需要该主机启用 GITLAB_MCP_OAUTH。
|
|
61
|
-
默认列表:40 个工具(38 个 core + discover_tools + help)。用 discover_tools
|
|
63
|
+
默认列表:40 个工具(38 个 core + discover_tools + help)。用 discover_tools 扩展。不要设置 GITLAB_TOOLSETS=all(约 73k schema token)。除非接受绕过风险,否则不要启用 api toolset。
|
|
62
64
|
同等非 MCP 路径:npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill 加上 zereight-mcp-gitlab CLI。
|
|
63
65
|
```
|
|
64
66
|
|
|
@@ -111,7 +113,7 @@ Human CLI 从不 compact。破坏性工具和 `GITLAB_TOOL_POLICY_APPROVE` 工
|
|
|
111
113
|
|
|
112
114
|
**如何认证?** 本地桌面最简单的是 `GITLAB_PERSONAL_ACCESS_TOKEN`(或 `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`)。本地 OAuth 用 `GITLAB_USE_OAUTH=true`。远程 Claude.ai 用 `GITLAB_MCP_OAUTH`。多用户 HTTP 用 `REMOTE_AUTHORIZATION` 和每请求令牌头。
|
|
113
115
|
|
|
114
|
-
**为什么只看到大约 40 个工具?** 默认 `core` toolset 有 38 个工具,外加始终开启的 `discover_tools` 和 `help
|
|
116
|
+
**为什么只看到大约 40 个工具?** 默认 `core` toolset 有 38 个工具,外加始终开启的 `discover_tools` 和 `help`。这是有意为之:客户端会把列出的 schema 一次性发给模型。不带参数调用 `discover_tools` 可列出类别,再传入类别(`pipelines`、`wiki` 等)即可在本会话激活。仅限本会话;`OAUTH_STATELESS_MODE=true` 时请改用命名的 `GITLAB_TOOLSETS`。**不要设置 `GITLAB_TOOLSETS=all`** — schema 约 73k token,而且仍然**不会**启用 `api`。
|
|
115
117
|
|
|
116
118
|
**本地 OAuth、MCP OAuth 和远程授权有何区别?** 本地 OAuth 在服务器同一台机器上打开浏览器。MCP OAuth 用于公网 HTTPS 服务器和 Claude.ai 这类客户端。远程授权转发调用者的 PAT 或 job token,没有 OAuth 流程。
|
|
117
119
|
|
|
@@ -123,7 +125,7 @@ Human CLI 从不 compact。破坏性工具和 `GITLAB_TOOL_POLICY_APPROVE` 工
|
|
|
123
125
|
|
|
124
126
|
```
|
|
125
127
|
GitLab 合并请求、议题和流水线走此 MCP(@zereight/mcp-gitlab)。
|
|
126
|
-
从默认 core 工具开始,用 discover_tools
|
|
128
|
+
从默认 core 工具开始,用 discover_tools 扩展。不要设置 GITLAB_TOOLSETS=all。
|
|
127
129
|
优先 list_merge_request_changed_files,再批量 get_merge_request_file_diff。
|
|
128
130
|
结果用 jmespath 或 compact;完整 diff 和 job 日志用 CLI。
|
|
129
131
|
```
|
|
@@ -138,7 +140,7 @@ GitLab 合并请求、议题和流水线走此 MCP(@zereight/mcp-gitlab)。
|
|
|
138
140
|
|
|
139
141
|
### 为什么使用这个 GitLab MCP?
|
|
140
142
|
|
|
141
|
-
- **默认 40 个工具(38 个 `core` + `discover_tools` + `help`);共 288 个** — 先精简,再用 `discover_tools`
|
|
143
|
+
- **默认 40 个工具(38 个 `core` + `discover_tools` + `help`);共 288 个** — 先精简,再用 `discover_tools` 在本会话扩展。`GITLAB_TOOLSETS=all` 约 73k schema token;按需发现或使用 Skill + CLI
|
|
142
144
|
- **MR 两步审查** — `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff`
|
|
143
145
|
- **内置 Agent Skill** — `skills/gitlab-mcp/` 工作流指南
|
|
144
146
|
- **认证灵活** — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
|
|
@@ -157,17 +159,17 @@ GitLab 合并请求、议题和流水线走此 MCP(@zereight/mcp-gitlab)。
|
|
|
157
159
|
| **Node.js** | >=20.0.0 | 通常 >=24 | stdio 经 `mcp-remote`,需要 Node.js 20+ |
|
|
158
160
|
| **许可证** | MIT | 因服务器而异 | GitLab 的一部分 |
|
|
159
161
|
|
|
160
|
-
### tools/list 体积(2026-
|
|
162
|
+
### tools/list 体积(2026-11-05 实测)
|
|
161
163
|
|
|
162
164
|
客户端会在会话开始时把整份 `tools/list` 发给模型。Token 估算为 UTF-8 字节 / 4。
|
|
163
165
|
|
|
164
166
|
| 配置 | 工具数 | JSON 字节 | 估算 token |
|
|
165
167
|
| ---- | -----: | --------: | ---------: |
|
|
166
|
-
| 默认(`core` + `discover_tools` + `help`) | 40 |
|
|
167
|
-
| `GITLAB_TOOL_PROFILE=slim` | 39 |
|
|
168
|
-
| `GITLAB_TOOLSETS=all` |
|
|
168
|
+
| 默认(`core` + `discover_tools` + `help`) | 40 | 46,943 | 11,736 |
|
|
169
|
+
| `GITLAB_TOOL_PROFILE=slim` | 39 | 45,935 | 11,484 |
|
|
170
|
+
| `GITLAB_TOOLSETS=all` | 286 | 293,906 | 73,477 |
|
|
169
171
|
|
|
170
|
-
更改描述或 schema 后,用 `npm run test:mock`(`test/tools-list-budget.test.ts`)重新测量。
|
|
172
|
+
更改描述或 schema 后,用 `npm run build && npm run test:mock`(`test/tools-list-budget.test.ts`)重新测量。
|
|
171
173
|
|
|
172
174
|
GitLab 还提供[官方 MCP 服务器](https://docs.gitlab.com/user/model_context_protocol/mcp_server/)。
|
|
173
175
|
|
|
@@ -282,7 +284,7 @@ v2.3.1 之后的每个 GitHub Release 都附带 `gitlab-mcp.mcpb` [MCP Bundle](h
|
|
|
282
284
|
- `--api-url` - GitLab API URL(替代 `GITLAB_API_URL`)
|
|
283
285
|
- `--read-only=true` - Deprecated (removed in next major (v3.0.0));请改用 `--permission-mode=readonly`(替代 `GITLAB_READ_ONLY_MODE`)
|
|
284
286
|
- `--permission-mode` - 权限级别:`readonly`、`modify`(禁用删除/拆除工具)或 `full`(替代 `GITLAB_PERMISSION_MODE`,默认 `full`)
|
|
285
|
-
- `--toolsets
|
|
287
|
+
- `--toolsets` - 指定工具集(替代 `GITLAB_TOOLSETS`;未设置时使用精简 `core` 默认值)。不要传 `all`,除非接受约 73k schema token。`gitlab_api_request` 需要 `--toolsets=api`
|
|
286
288
|
- `--tools=list_issues` - 添加单个工具(替代 `GITLAB_TOOLS`)
|
|
287
289
|
- `--use-wiki=true` - Deprecated (removed in next major (v3.0.0));请改用 `--toolsets=core,wiki`(替代 `USE_GITLAB_WIKI`)
|
|
288
290
|
- `--use-milestone=true` - Deprecated (removed in next major (v3.0.0));请改用 `--toolsets=core,milestones`(替代 `USE_MILESTONE`)
|
package/build/index.js
CHANGED
|
@@ -390,7 +390,7 @@ function createServer() {
|
|
|
390
390
|
type: "text",
|
|
391
391
|
text: JSON.stringify({
|
|
392
392
|
categories,
|
|
393
|
-
hint: "Call discover_tools with a category name to activate it",
|
|
393
|
+
hint: "Call discover_tools with a category name to activate it for this session. Prefer a category over GITLAB_TOOLSETS=all. Session-only; with OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS=core,<category> (if GITLAB_TOOLSETS is already set, append the category and keep core).",
|
|
394
394
|
}),
|
|
395
395
|
},
|
|
396
396
|
],
|
package/build/schemas.js
CHANGED
|
@@ -211,11 +211,8 @@ export const GitLabPipelineTriggerJobSchema = z.object({
|
|
|
211
211
|
// Shared base schema for various pagination options
|
|
212
212
|
// See https://docs.gitlab.com/api/rest/#pagination
|
|
213
213
|
export const PaginationOptionsSchema = z.object({
|
|
214
|
-
page: z.coerce.number().optional().describe("Page number
|
|
215
|
-
per_page: z.coerce
|
|
216
|
-
.number()
|
|
217
|
-
.optional()
|
|
218
|
-
.describe("Number of items per page (max: 100, default: 20)"),
|
|
214
|
+
page: z.coerce.number().optional().describe("Page number (default 1)"),
|
|
215
|
+
per_page: z.coerce.number().optional().describe("Items per page (max 100, default 20)"),
|
|
219
216
|
});
|
|
220
217
|
// Schema for listing pipelines
|
|
221
218
|
export const ListPipelinesSchema = z
|
|
@@ -1288,28 +1285,22 @@ export const GitLabTreeItemSchema = z.object({
|
|
|
1288
1285
|
mode: z.string(),
|
|
1289
1286
|
});
|
|
1290
1287
|
export const GetRepositoryTreeSchema = z.object({
|
|
1291
|
-
project_id: z.coerce.string().describe("
|
|
1292
|
-
path: z.string().optional().describe("
|
|
1293
|
-
ref: z
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
.describe("The name of a repository branch or tag. Defaults to the default branch."),
|
|
1297
|
-
recursive: coerceBooleanString.optional().describe("Boolean value to get a recursive tree"),
|
|
1298
|
-
per_page: z.coerce.number().optional().describe("Number of results to show per page"),
|
|
1288
|
+
project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
|
|
1289
|
+
path: z.string().optional().describe("Path inside the repository"),
|
|
1290
|
+
ref: z.string().optional().describe("Branch or tag. Defaults to the default branch."),
|
|
1291
|
+
recursive: coerceBooleanString.optional().describe("Recursive tree"),
|
|
1292
|
+
per_page: z.coerce.number().optional().describe("Items per page"),
|
|
1299
1293
|
page: z.coerce
|
|
1300
1294
|
.number()
|
|
1301
1295
|
.int()
|
|
1302
1296
|
.positive()
|
|
1303
1297
|
.optional()
|
|
1304
|
-
.describe("
|
|
1305
|
-
page_token: z
|
|
1306
|
-
.string()
|
|
1307
|
-
.optional()
|
|
1308
|
-
.describe("Token for keyset pagination. Use the next_page_token value returned in the previous response to retrieve the next page."),
|
|
1298
|
+
.describe("Offset page number from 1 (items + next_page)"),
|
|
1299
|
+
page_token: z.string().optional().describe("Keyset token from the previous next_page_token"),
|
|
1309
1300
|
pagination: z
|
|
1310
1301
|
.string()
|
|
1311
1302
|
.optional()
|
|
1312
|
-
.describe("
|
|
1303
|
+
.describe("Use keyset for large trees (items + next_page_token). Omit both page and pagination for the legacy array (deprecated)."),
|
|
1313
1304
|
});
|
|
1314
1305
|
export const GitLabTreeSchema = z.object({
|
|
1315
1306
|
id: z.string(), // Changed from sha to match GitLab API
|
|
@@ -1970,18 +1961,15 @@ export const PushFilesSchema = ProjectParamsSchema.extend({
|
|
|
1970
1961
|
export const CreateIssueSchema = ProjectParamsSchema.extend({
|
|
1971
1962
|
title: z.string().describe("Issue title"),
|
|
1972
1963
|
description: z.string().optional().describe("Issue description"),
|
|
1973
|
-
assignee_ids: z.array(z.coerce.number()).optional().describe("
|
|
1974
|
-
labels: coerceStringArray.optional().describe("
|
|
1975
|
-
milestone_id: z.coerce.string().optional().describe("Milestone ID
|
|
1964
|
+
assignee_ids: z.array(z.coerce.number()).optional().describe("Assignee user IDs"),
|
|
1965
|
+
labels: coerceStringArray.optional().describe("Label names"),
|
|
1966
|
+
milestone_id: z.coerce.string().optional().describe("Milestone ID"),
|
|
1976
1967
|
issue_type: z
|
|
1977
1968
|
.enum(["issue", "incident", "test_case", "task"])
|
|
1978
1969
|
.optional()
|
|
1979
1970
|
.default("issue")
|
|
1980
|
-
.describe("
|
|
1981
|
-
weight: z.coerce
|
|
1982
|
-
.number()
|
|
1983
|
-
.optional()
|
|
1984
|
-
.describe("Weight of the issue (numeric, typically hours of work)"),
|
|
1971
|
+
.describe("issue, incident, test_case, or task"),
|
|
1972
|
+
weight: z.coerce.number().optional().describe("Issue weight"),
|
|
1985
1973
|
});
|
|
1986
1974
|
export const GitLabTodoSchema = z.object({
|
|
1987
1975
|
id: z.coerce.number(),
|
|
@@ -2040,30 +2028,19 @@ export const MarkAllTodosDoneSchema = z.object({});
|
|
|
2040
2028
|
const MergeRequestOptionsSchema = {
|
|
2041
2029
|
title: z.string().describe("Merge request title"),
|
|
2042
2030
|
description: z.string().optional().describe("Merge request description"),
|
|
2043
|
-
source_branch: z.string().describe("
|
|
2044
|
-
target_branch: z.string().describe("
|
|
2045
|
-
target_project_id: z.coerce.string().optional().describe("
|
|
2046
|
-
assignee_ids: z
|
|
2047
|
-
|
|
2048
|
-
|
|
2049
|
-
|
|
2050
|
-
|
|
2051
|
-
.array(z.coerce.number())
|
|
2052
|
-
.optional()
|
|
2053
|
-
.describe("The ID of the users to assign as reviewers of the MR"),
|
|
2054
|
-
labels: coerceStringArray.optional().describe("Labels for the MR"),
|
|
2055
|
-
draft: coerceBooleanString.optional().describe("Create as draft merge request"),
|
|
2056
|
-
allow_collaboration: coerceBooleanString
|
|
2057
|
-
.optional()
|
|
2058
|
-
.describe("Allow commits from upstream members"),
|
|
2031
|
+
source_branch: z.string().describe("Source branch"),
|
|
2032
|
+
target_branch: z.string().describe("Target branch"),
|
|
2033
|
+
target_project_id: z.coerce.string().optional().describe("Target project numeric ID"),
|
|
2034
|
+
assignee_ids: z.array(z.coerce.number()).optional().describe("Assignee user IDs"),
|
|
2035
|
+
reviewer_ids: z.array(z.coerce.number()).optional().describe("Reviewer user IDs"),
|
|
2036
|
+
labels: coerceStringArray.optional().describe("MR labels"),
|
|
2037
|
+
draft: coerceBooleanString.optional().describe("Create as draft"),
|
|
2038
|
+
allow_collaboration: coerceBooleanString.optional().describe("Allow eligible upstream members to push to the fork source branch"),
|
|
2059
2039
|
remove_source_branch: coerceBooleanString
|
|
2060
2040
|
.nullable()
|
|
2061
2041
|
.optional()
|
|
2062
|
-
.describe("
|
|
2063
|
-
squash: coerceBooleanString
|
|
2064
|
-
.nullable()
|
|
2065
|
-
.optional()
|
|
2066
|
-
.describe("If true, squash all commits into a single commit on merge."),
|
|
2042
|
+
.describe("Remove source branch on merge"),
|
|
2043
|
+
squash: coerceBooleanString.nullable().optional().describe("Squash commits on merge"),
|
|
2067
2044
|
};
|
|
2068
2045
|
export const CreateMergeRequestOptionsSchema = z.object(MergeRequestOptionsSchema);
|
|
2069
2046
|
export const CreateMergeRequestSchema = ProjectParamsSchema.extend(MergeRequestOptionsSchema);
|
|
@@ -2294,40 +2271,27 @@ const MergeRequestParamsSchema = ProjectParamsSchema.extend({
|
|
|
2294
2271
|
})
|
|
2295
2272
|
.refine(value => value === "" || value.trim().length > 0, "project_id is required")
|
|
2296
2273
|
.transform(value => (value === "" ? value : value.trim())))
|
|
2297
|
-
.describe("Project ID or
|
|
2298
|
-
merge_request_iid: z.coerce.string().optional().describe("
|
|
2274
|
+
.describe("Project ID or URL-encoded path"),
|
|
2275
|
+
merge_request_iid: z.coerce.string().optional().describe("Merge request IID"),
|
|
2299
2276
|
source_branch: z.string().optional().describe("Source branch name"),
|
|
2300
2277
|
});
|
|
2301
2278
|
export const GetMergeRequestSchema = MergeRequestParamsSchema.extend({
|
|
2302
|
-
include_summaries: flexibleBooleanOptional.describe("If true, include
|
|
2279
|
+
include_summaries: flexibleBooleanOptional.describe("If true, include deployment, commit, and approval summaries (extra API calls). Default false."),
|
|
2303
2280
|
});
|
|
2304
2281
|
export const UpdateMergeRequestSchema = MergeRequestParamsSchema.extend({
|
|
2305
|
-
title: z.string().optional().describe("
|
|
2306
|
-
description: z.string().optional().describe("
|
|
2307
|
-
target_branch: z.string().optional().describe("
|
|
2308
|
-
assignee_ids: z
|
|
2309
|
-
|
|
2310
|
-
|
|
2311
|
-
|
|
2312
|
-
|
|
2313
|
-
|
|
2314
|
-
|
|
2315
|
-
.describe("The ID of the users to assign as reviewers of the MR"),
|
|
2316
|
-
labels: coerceStringArray.optional().describe("Labels for the MR"),
|
|
2317
|
-
state_event: z
|
|
2318
|
-
.enum(["close", "reopen"])
|
|
2319
|
-
.optional()
|
|
2320
|
-
.describe("New state (close/reopen) for the MR"),
|
|
2321
|
-
remove_source_branch: coerceBooleanString
|
|
2322
|
-
.optional()
|
|
2323
|
-
.describe("Flag indicating if the source branch should be removed"),
|
|
2324
|
-
squash: coerceBooleanString
|
|
2325
|
-
.optional()
|
|
2326
|
-
.describe("Squash commits into a single commit when merging"),
|
|
2327
|
-
draft: coerceBooleanString.optional().describe("Work in progress merge request"),
|
|
2282
|
+
title: z.string().optional().describe("MR title"),
|
|
2283
|
+
description: z.string().optional().describe("MR description"),
|
|
2284
|
+
target_branch: z.string().optional().describe("Target branch"),
|
|
2285
|
+
assignee_ids: z.array(z.coerce.number()).optional().describe("Assignee user IDs"),
|
|
2286
|
+
reviewer_ids: z.array(z.coerce.number()).optional().describe("Reviewer user IDs"),
|
|
2287
|
+
labels: coerceStringArray.optional().describe("MR labels"),
|
|
2288
|
+
state_event: z.enum(["close", "reopen"]).optional().describe("close or reopen"),
|
|
2289
|
+
remove_source_branch: coerceBooleanString.optional().describe("Remove source branch on merge"),
|
|
2290
|
+
squash: coerceBooleanString.optional().describe("Squash commits on merge"),
|
|
2291
|
+
draft: coerceBooleanString.optional().describe("Draft / WIP"),
|
|
2328
2292
|
milestone_id: z
|
|
2329
2293
|
.preprocess(val => (val === null ? undefined : val), z.coerce.string().optional())
|
|
2330
|
-
.describe("Milestone ID
|
|
2294
|
+
.describe("Milestone ID. 0 unassigns. Null is omitted."),
|
|
2331
2295
|
});
|
|
2332
2296
|
export const MergeMergeRequestSchema = ProjectParamsSchema.extend({
|
|
2333
2297
|
merge_request_iid: z.coerce.string().optional().describe("The IID of a merge request"),
|
|
@@ -2515,51 +2479,46 @@ export const ListIssuesSchema = z
|
|
|
2515
2479
|
project_id: z.coerce
|
|
2516
2480
|
.string()
|
|
2517
2481
|
.optional()
|
|
2518
|
-
.describe("Project ID or URL-encoded path
|
|
2482
|
+
.describe("Project ID or URL-encoded path. Omit to list issues across accessible projects."),
|
|
2519
2483
|
assignee_id: z.coerce
|
|
2520
2484
|
.string()
|
|
2521
2485
|
.optional()
|
|
2522
|
-
.describe("
|
|
2486
|
+
.describe("User ID, none, or any. Mutually exclusive with assignee_username."),
|
|
2523
2487
|
assignee_username: z
|
|
2524
2488
|
.array(z.string())
|
|
2525
2489
|
.optional()
|
|
2526
|
-
.describe("
|
|
2490
|
+
.describe("Username. Mutually exclusive with assignee_id."),
|
|
2527
2491
|
author_id: z.coerce
|
|
2528
2492
|
.string()
|
|
2529
2493
|
.optional()
|
|
2530
|
-
.describe("
|
|
2494
|
+
.describe("Author user ID. Mutually exclusive with author_username."),
|
|
2531
2495
|
author_username: z
|
|
2532
2496
|
.string()
|
|
2533
2497
|
.optional()
|
|
2534
|
-
.describe("
|
|
2535
|
-
confidential: coerceBooleanString.optional().describe("
|
|
2536
|
-
created_after: z.string().optional().describe("
|
|
2537
|
-
created_before: z.string().optional().describe("
|
|
2538
|
-
due_date: z.string().optional().describe("
|
|
2539
|
-
labels: coerceStringArray.optional().describe("
|
|
2498
|
+
.describe("Author username. Mutually exclusive with author_id."),
|
|
2499
|
+
confidential: coerceBooleanString.optional().describe("Confidential or public"),
|
|
2500
|
+
created_after: z.string().optional().describe("Created after"),
|
|
2501
|
+
created_before: z.string().optional().describe("Created before"),
|
|
2502
|
+
due_date: z.string().optional().describe("Due date"),
|
|
2503
|
+
labels: coerceStringArray.optional().describe("Label names"),
|
|
2540
2504
|
milestone: z.string().optional().describe("Milestone title"),
|
|
2541
2505
|
issue_type: z
|
|
2542
2506
|
.enum(["issue", "incident", "test_case", "task"])
|
|
2543
2507
|
.optional()
|
|
2544
|
-
.describe("
|
|
2508
|
+
.describe("issue, incident, test_case, or task"),
|
|
2545
2509
|
iteration_id: z.coerce
|
|
2546
2510
|
.string()
|
|
2547
2511
|
.optional()
|
|
2548
|
-
.describe("
|
|
2512
|
+
.describe("Iteration ID, none (no iteration), or any (has an iteration)."),
|
|
2549
2513
|
scope: z
|
|
2550
2514
|
.enum(["created_by_me", "assigned_to_me", "all"])
|
|
2551
2515
|
.optional()
|
|
2552
|
-
.describe("
|
|
2553
|
-
search: z.string().optional().describe("Search
|
|
2554
|
-
state: z
|
|
2555
|
-
|
|
2556
|
-
|
|
2557
|
-
|
|
2558
|
-
updated_after: z.string().optional().describe("Return issues updated after the given time"),
|
|
2559
|
-
updated_before: z.string().optional().describe("Return issues updated before the given time"),
|
|
2560
|
-
with_labels_details: coerceBooleanString
|
|
2561
|
-
.optional()
|
|
2562
|
-
.describe("Return more details for each label"),
|
|
2516
|
+
.describe("Issue scope"),
|
|
2517
|
+
search: z.string().optional().describe("Search terms"),
|
|
2518
|
+
state: z.enum(["opened", "closed", "all"]).optional().describe("Issue state"),
|
|
2519
|
+
updated_after: z.string().optional().describe("Updated after"),
|
|
2520
|
+
updated_before: z.string().optional().describe("Updated before"),
|
|
2521
|
+
with_labels_details: coerceBooleanString.optional().describe("Include label details"),
|
|
2563
2522
|
})
|
|
2564
2523
|
.merge(PaginationOptionsSchema);
|
|
2565
2524
|
// Merge Requests API operation schemas
|
|
@@ -2568,61 +2527,47 @@ export const ListMergeRequestsSchema = z
|
|
|
2568
2527
|
project_id: z.coerce
|
|
2569
2528
|
.string()
|
|
2570
2529
|
.optional()
|
|
2571
|
-
.describe("Project ID or URL-encoded path
|
|
2530
|
+
.describe("Project ID or URL-encoded path. Omit to list the user's accessible MRs."),
|
|
2572
2531
|
assignee_id: z.coerce
|
|
2573
2532
|
.string()
|
|
2574
2533
|
.optional()
|
|
2575
|
-
.describe("
|
|
2534
|
+
.describe("User ID, none, or any. Mutually exclusive with assignee_username."),
|
|
2576
2535
|
assignee_username: z
|
|
2577
2536
|
.string()
|
|
2578
2537
|
.optional()
|
|
2579
|
-
.describe("
|
|
2538
|
+
.describe("Username. Mutually exclusive with assignee_id."),
|
|
2580
2539
|
author_id: z.coerce
|
|
2581
2540
|
.string()
|
|
2582
2541
|
.optional()
|
|
2583
|
-
.describe("
|
|
2542
|
+
.describe("Author user ID. Mutually exclusive with author_username."),
|
|
2584
2543
|
author_username: z
|
|
2585
2544
|
.string()
|
|
2586
2545
|
.optional()
|
|
2587
|
-
.describe("
|
|
2546
|
+
.describe("Author username. Mutually exclusive with author_id."),
|
|
2588
2547
|
reviewer_id: z.coerce
|
|
2589
2548
|
.string()
|
|
2590
2549
|
.optional()
|
|
2591
|
-
.describe("
|
|
2550
|
+
.describe("Reviewer user ID, none, or any. Mutually exclusive with reviewer_username."),
|
|
2592
2551
|
reviewer_username: z
|
|
2593
2552
|
.string()
|
|
2594
2553
|
.optional()
|
|
2595
|
-
.describe("
|
|
2596
|
-
approved_by_usernames: coerceStringArray
|
|
2597
|
-
|
|
2598
|
-
|
|
2599
|
-
|
|
2600
|
-
|
|
2601
|
-
|
|
2602
|
-
.describe("Return merge requests created after the given time"),
|
|
2603
|
-
created_before: z
|
|
2604
|
-
.string()
|
|
2605
|
-
.optional()
|
|
2606
|
-
.describe("Return merge requests created before the given time"),
|
|
2607
|
-
updated_after: z
|
|
2608
|
-
.string()
|
|
2609
|
-
.optional()
|
|
2610
|
-
.describe("Return merge requests updated after the given time"),
|
|
2611
|
-
updated_before: z
|
|
2612
|
-
.string()
|
|
2613
|
-
.optional()
|
|
2614
|
-
.describe("Return merge requests updated before the given time"),
|
|
2615
|
-
labels: coerceStringArray.optional().describe("Array of label names"),
|
|
2554
|
+
.describe("Reviewer username. Mutually exclusive with reviewer_id."),
|
|
2555
|
+
approved_by_usernames: coerceStringArray.optional().describe("Approved by these usernames"),
|
|
2556
|
+
created_after: z.string().optional().describe("Created after"),
|
|
2557
|
+
created_before: z.string().optional().describe("Created before"),
|
|
2558
|
+
updated_after: z.string().optional().describe("Updated after"),
|
|
2559
|
+
updated_before: z.string().optional().describe("Updated before"),
|
|
2560
|
+
labels: coerceStringArray.optional().describe("Label names"),
|
|
2616
2561
|
milestone: z.string().optional().describe("Milestone title"),
|
|
2617
2562
|
scope: z
|
|
2618
2563
|
.enum(["created_by_me", "assigned_to_me", "all"])
|
|
2619
2564
|
.optional()
|
|
2620
|
-
.describe("
|
|
2621
|
-
search: z.string().optional().describe("Search
|
|
2565
|
+
.describe("MR scope"),
|
|
2566
|
+
search: z.string().optional().describe("Search terms"),
|
|
2622
2567
|
state: z
|
|
2623
2568
|
.enum(["opened", "closed", "locked", "merged", "all"])
|
|
2624
2569
|
.optional()
|
|
2625
|
-
.describe("
|
|
2570
|
+
.describe("MR state"),
|
|
2626
2571
|
order_by: z
|
|
2627
2572
|
.enum([
|
|
2628
2573
|
"created_at",
|
|
@@ -2633,26 +2578,12 @@ export const ListMergeRequestsSchema = z
|
|
|
2633
2578
|
"popularity",
|
|
2634
2579
|
])
|
|
2635
2580
|
.optional()
|
|
2636
|
-
.describe("
|
|
2637
|
-
sort: z
|
|
2638
|
-
|
|
2639
|
-
|
|
2640
|
-
|
|
2641
|
-
|
|
2642
|
-
.string()
|
|
2643
|
-
.optional()
|
|
2644
|
-
.describe("Return merge requests targeting a specific branch"),
|
|
2645
|
-
source_branch: z
|
|
2646
|
-
.string()
|
|
2647
|
-
.optional()
|
|
2648
|
-
.describe("Return merge requests from a specific source branch"),
|
|
2649
|
-
wip: z
|
|
2650
|
-
.enum(["yes", "no"])
|
|
2651
|
-
.optional()
|
|
2652
|
-
.describe("Filter merge requests against their wip status"),
|
|
2653
|
-
with_labels_details: coerceBooleanString
|
|
2654
|
-
.optional()
|
|
2655
|
-
.describe("Return more details for each label"),
|
|
2581
|
+
.describe("Sort field"),
|
|
2582
|
+
sort: z.enum(["asc", "desc"]).optional().describe("asc or desc"),
|
|
2583
|
+
target_branch: z.string().optional().describe("Target branch"),
|
|
2584
|
+
source_branch: z.string().optional().describe("Source branch"),
|
|
2585
|
+
wip: z.enum(["yes", "no"]).optional().describe("WIP filter"),
|
|
2586
|
+
with_labels_details: coerceBooleanString.optional().describe("Include label details"),
|
|
2656
2587
|
})
|
|
2657
2588
|
.merge(PaginationOptionsSchema);
|
|
2658
2589
|
export const ListGroupMergeRequestsSchema = ListMergeRequestsSchema.omit({
|
|
@@ -2669,32 +2600,26 @@ export const ListGroupMergeRequestsSchema = ListMergeRequestsSchema.omit({
|
|
|
2669
2600
|
});
|
|
2670
2601
|
export const GetIssueSchema = z.object({
|
|
2671
2602
|
project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
|
|
2672
|
-
issue_iid: z.coerce.string().describe("
|
|
2673
|
-
full_response: flexibleBooleanOptional.describe("If true, include the complete milestone
|
|
2603
|
+
issue_iid: z.coerce.string().describe("Issue IID"),
|
|
2604
|
+
full_response: flexibleBooleanOptional.describe("If true, include the complete milestone (including description). Default is slim (id, iid, title, state, web_url)."),
|
|
2674
2605
|
});
|
|
2675
2606
|
export const UpdateIssueSchema = z.object({
|
|
2676
2607
|
project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
|
|
2677
|
-
issue_iid: z.coerce.string().describe("
|
|
2678
|
-
title: z.string().optional().describe("
|
|
2679
|
-
description: z.string().optional().describe("
|
|
2680
|
-
assignee_ids: z
|
|
2681
|
-
|
|
2682
|
-
|
|
2683
|
-
|
|
2684
|
-
|
|
2685
|
-
|
|
2686
|
-
|
|
2687
|
-
|
|
2688
|
-
milestone_id: z.coerce.string().optional().describe("Milestone ID to assign"),
|
|
2689
|
-
state_event: z.enum(["close", "reopen"]).optional().describe("Update issue state (close/reopen)"),
|
|
2690
|
-
weight: z.coerce
|
|
2691
|
-
.number()
|
|
2692
|
-
.optional()
|
|
2693
|
-
.describe("Weight of the issue (numeric, typically hours of work)"),
|
|
2608
|
+
issue_iid: z.coerce.string().describe("Issue IID"),
|
|
2609
|
+
title: z.string().optional().describe("Issue title"),
|
|
2610
|
+
description: z.string().optional().describe("Issue description"),
|
|
2611
|
+
assignee_ids: z.array(z.coerce.number()).optional().describe("Assignee user IDs"),
|
|
2612
|
+
confidential: coerceBooleanString.optional().describe("Confidential"),
|
|
2613
|
+
discussion_locked: coerceBooleanString.optional().describe("Lock discussions"),
|
|
2614
|
+
due_date: z.string().optional().describe("Due date (YYYY-MM-DD)"),
|
|
2615
|
+
labels: coerceStringArray.optional().describe("Label names"),
|
|
2616
|
+
milestone_id: z.coerce.string().optional().describe("Milestone ID"),
|
|
2617
|
+
state_event: z.enum(["close", "reopen"]).optional().describe("close or reopen"),
|
|
2618
|
+
weight: z.coerce.number().optional().describe("Issue weight"),
|
|
2694
2619
|
issue_type: z
|
|
2695
2620
|
.preprocess(val => (typeof val === "string" ? val.toLowerCase() : val), z.enum(["issue", "incident", "test_case", "task"]).optional())
|
|
2696
|
-
.describe("
|
|
2697
|
-
full_response: flexibleBooleanOptional.describe("If true, return the complete updated issue
|
|
2621
|
+
.describe("issue, incident, test_case, or task"),
|
|
2622
|
+
full_response: flexibleBooleanOptional.describe("If true, return the complete updated issue. Default is slim (iid, title, state, web_url, updated_at)."),
|
|
2698
2623
|
});
|
|
2699
2624
|
export const DeleteIssueSchema = z.object({
|
|
2700
2625
|
project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
|
|
@@ -2830,36 +2755,29 @@ export const UpdateProjectSchema = ProjectParamsSchema.extend({
|
|
|
2830
2755
|
});
|
|
2831
2756
|
export const ListProjectsSchema = z
|
|
2832
2757
|
.object({
|
|
2833
|
-
search: z.string().optional().describe("Search term
|
|
2758
|
+
search: z.string().optional().describe("Search term"),
|
|
2834
2759
|
search_namespaces: coerceBooleanString
|
|
2835
2760
|
.optional()
|
|
2836
|
-
.describe("
|
|
2837
|
-
owned: coerceBooleanString.optional().describe("
|
|
2838
|
-
membership: coerceBooleanString
|
|
2839
|
-
|
|
2840
|
-
|
|
2841
|
-
simple: coerceBooleanString.optional().describe("Return only limited fields"),
|
|
2842
|
-
archived: coerceBooleanString.optional().describe("Filter for archived projects"),
|
|
2761
|
+
.describe("Set true when search is a full path"),
|
|
2762
|
+
owned: coerceBooleanString.optional().describe("Owned by current user"),
|
|
2763
|
+
membership: coerceBooleanString.optional().describe("Current user is a member"),
|
|
2764
|
+
simple: coerceBooleanString.optional().describe("Limited fields only"),
|
|
2765
|
+
archived: coerceBooleanString.optional().describe("Archived projects"),
|
|
2843
2766
|
visibility: z
|
|
2844
2767
|
.enum(["public", "internal", "private"])
|
|
2845
2768
|
.optional()
|
|
2846
|
-
.describe("
|
|
2769
|
+
.describe("public, internal, or private"),
|
|
2847
2770
|
order_by: z
|
|
2848
2771
|
.enum(["id", "name", "path", "created_at", "updated_at", "last_activity_at"])
|
|
2849
2772
|
.optional()
|
|
2850
|
-
.describe("
|
|
2851
|
-
sort: z
|
|
2852
|
-
|
|
2853
|
-
.optional()
|
|
2854
|
-
.describe("Return projects sorted in ascending or descending order"),
|
|
2855
|
-
with_issues_enabled: coerceBooleanString
|
|
2856
|
-
.optional()
|
|
2857
|
-
.describe("Filter projects with issues feature enabled"),
|
|
2773
|
+
.describe("Sort field"),
|
|
2774
|
+
sort: z.enum(["asc", "desc"]).optional().describe("asc or desc"),
|
|
2775
|
+
with_issues_enabled: coerceBooleanString.optional().describe("Issues enabled"),
|
|
2858
2776
|
with_merge_requests_enabled: coerceBooleanString
|
|
2859
2777
|
.optional()
|
|
2860
|
-
.describe("
|
|
2861
|
-
min_access_level: z.coerce.number().optional().describe("
|
|
2862
|
-
topic: z.string().optional().describe("
|
|
2778
|
+
.describe("Merge requests enabled"),
|
|
2779
|
+
min_access_level: z.coerce.number().optional().describe("Minimum access level"),
|
|
2780
|
+
topic: z.string().optional().describe("Topic tag"),
|
|
2863
2781
|
})
|
|
2864
2782
|
.merge(PaginationOptionsSchema);
|
|
2865
2783
|
// Label operation schemas
|
|
@@ -3350,37 +3268,19 @@ export const GetGroupMilestoneMergeRequestsSchema = GetGroupMilestoneSchema.merg
|
|
|
3350
3268
|
export const GetGroupMilestoneBurndownEventsSchema = GetGroupMilestoneSchema.merge(PaginationOptionsSchema);
|
|
3351
3269
|
// Add schemas for commit operations
|
|
3352
3270
|
export const ListCommitsSchema = z.object({
|
|
3353
|
-
project_id: z.coerce.string().describe("Project ID or
|
|
3354
|
-
ref_name: z
|
|
3355
|
-
|
|
3356
|
-
|
|
3357
|
-
|
|
3358
|
-
|
|
3359
|
-
|
|
3360
|
-
|
|
3361
|
-
|
|
3362
|
-
|
|
3363
|
-
|
|
3364
|
-
|
|
3365
|
-
|
|
3366
|
-
path: z.string().optional().describe("The file path"),
|
|
3367
|
-
author: z.string().optional().describe("Search commits by commit author"),
|
|
3368
|
-
all: coerceBooleanString.optional().describe("Retrieve every commit from the repository"),
|
|
3369
|
-
with_stats: coerceBooleanString
|
|
3370
|
-
.optional()
|
|
3371
|
-
.describe("Stats about each commit are added to the response"),
|
|
3372
|
-
first_parent: coerceBooleanString
|
|
3373
|
-
.optional()
|
|
3374
|
-
.describe("Follow only the first parent commit upon seeing a merge commit"),
|
|
3375
|
-
order: z.enum(["default", "topo"]).optional().describe("List commits in order"),
|
|
3376
|
-
trailers: coerceBooleanString
|
|
3377
|
-
.optional()
|
|
3378
|
-
.describe("Parse and include Git trailers for every commit"),
|
|
3379
|
-
page: z.coerce.number().optional().describe("Page number for pagination (default: 1)"),
|
|
3380
|
-
per_page: z.coerce
|
|
3381
|
-
.number()
|
|
3382
|
-
.optional()
|
|
3383
|
-
.describe("Number of items per page (max: 100, default: 20)"),
|
|
3271
|
+
project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
|
|
3272
|
+
ref_name: z.string().optional().describe("Branch, tag, or revision range. Default: default branch."),
|
|
3273
|
+
since: z.string().optional().describe("Commits on or after this ISO 8601 datetime"),
|
|
3274
|
+
until: z.string().optional().describe("Commits on or before this ISO 8601 datetime"),
|
|
3275
|
+
path: z.string().optional().describe("File path"),
|
|
3276
|
+
author: z.string().optional().describe("Commit author"),
|
|
3277
|
+
all: coerceBooleanString.optional().describe("Every commit in the repository"),
|
|
3278
|
+
with_stats: coerceBooleanString.optional().describe("Include per-commit stats"),
|
|
3279
|
+
first_parent: coerceBooleanString.optional().describe("Follow only the first parent of merges"),
|
|
3280
|
+
order: z.enum(["default", "topo"]).optional().describe("default or topo"),
|
|
3281
|
+
trailers: coerceBooleanString.optional().describe("Include Git trailers"),
|
|
3282
|
+
page: z.coerce.number().optional().describe("Page number (default 1)"),
|
|
3283
|
+
per_page: z.coerce.number().optional().describe("Items per page (max 100, default 20)"),
|
|
3384
3284
|
});
|
|
3385
3285
|
export const GetCommitSchema = z.object({
|
|
3386
3286
|
project_id: z.coerce.string().describe("Project ID or complete URL-encoded path to project"),
|
package/build/server/mcp-help.js
CHANGED
|
@@ -12,8 +12,7 @@ export const HelpInputSchema = z.object({
|
|
|
12
12
|
topic: z
|
|
13
13
|
.enum(HELP_TOPICS)
|
|
14
14
|
.optional()
|
|
15
|
-
.describe("Guide to return. Omit for the overview and the list of topics.
|
|
16
|
-
"Values: overview, code-review, merge-requests, issues, pipelines, search, token-saving."),
|
|
15
|
+
.describe("Guide to return. Omit for the overview and the list of topics."),
|
|
17
16
|
});
|
|
18
17
|
export function isHelpTopic(value) {
|
|
19
18
|
for (const topic of HELP_TOPICS) {
|
|
@@ -30,7 +29,7 @@ const GUIDES = {
|
|
|
30
29
|
overview: [
|
|
31
30
|
"GitLab MCP workflow guide. Default tools/list is 38 core tools plus discover_tools and help (40).",
|
|
32
31
|
"Call help with topic: code-review, merge-requests, issues, pipelines, search, token-saving.",
|
|
33
|
-
"Activate more categories with discover_tools. api is explicit-only (GITLAB_TOOLSETS=api).",
|
|
32
|
+
"Activate more categories with discover_tools (session-only). Do not set GITLAB_TOOLSETS=all (loads ~all schemas). With OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS=core,<category> instead. api is explicit-only (GITLAB_TOOLSETS=api).",
|
|
34
33
|
"project_id is a numeric ID or URL-encoded path (group%2Fproject). MR !123 → merge_request_iid=123.",
|
|
35
34
|
].join("\n"),
|
|
36
35
|
"code-review": [
|
|
@@ -66,6 +65,10 @@ const GUIDES = {
|
|
|
66
65
|
"If you already have an id or path, use get_project / get_issue / get_merge_request instead.",
|
|
67
66
|
].join("\n"),
|
|
68
67
|
"token-saving": [
|
|
68
|
+
"Do not set GITLAB_TOOLSETS=all; it loads ~all schemas into tools/list.",
|
|
69
|
+
"Activate one category with discover_tools in a stateful session, or persist GITLAB_TOOLSETS=core,<category>.",
|
|
70
|
+
"With OAUTH_STATELESS_MODE=true set GITLAB_TOOLSETS=core,<category>; discover_tools does not survive the next request.",
|
|
71
|
+
"Or use the CLI/Skill path.",
|
|
69
72
|
"Do not dump get_merge_request_diffs for a whole MR. Use list_merge_request_changed_files",
|
|
70
73
|
"then batched get_merge_request_file_diff.",
|
|
71
74
|
"Pass jmespath on any tool to shrink JSON. GITLAB_MCP_COMPACT_RESULTS replaces oversized",
|
|
@@ -7,7 +7,7 @@ export const MCP_INSTRUCTIONS = [
|
|
|
7
7
|
"GitLab MCP. Default list: 38 core tools plus discover_tools and help (40). Call help for workflows.",
|
|
8
8
|
"MR review: list_merge_request_changed_files, then get_merge_request_file_diff for 3-5 files. Do not dump get_merge_request_diffs.",
|
|
9
9
|
"project_id: numeric ID or URL-encoded path (group%2Fproject). MR !123 uses merge_request_iid=123.",
|
|
10
|
-
"discover_tools: omit category to list; pass a category to activate for this session. api is explicit-only (GITLAB_TOOLSETS=api).",
|
|
10
|
+
"discover_tools: omit category to list; pass a category to activate for this session. Prefer this over GITLAB_TOOLSETS=all. Session-only; with OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS=core,<category>. api is explicit-only (GITLAB_TOOLSETS=api).",
|
|
11
11
|
"Shrink results: pass jmespath on any tool. Set GITLAB_MCP_COMPACT_RESULTS for oversized replies. Paginate get_pipeline_job_output.",
|
|
12
12
|
"Prefer typed tools over execute_graphql. Do not enable gitlab_api_request unless you accept allowlist and safety-check bypass. Prompt injection can drive it.",
|
|
13
13
|
"Destructive tools change GitLab state. Use the CLI (zereight-mcp-gitlab) for full diffs, logs, and artifacts.",
|
package/build/tools/registry.js
CHANGED
|
@@ -366,19 +366,17 @@ export const allTools = [
|
|
|
366
366
|
},
|
|
367
367
|
{
|
|
368
368
|
name: "get_issue",
|
|
369
|
-
description: "Get
|
|
369
|
+
description: "Get one issue. Slim nested milestone by default; full_response=true for the complete milestone",
|
|
370
370
|
inputSchema: toJSONSchema(GetIssueSchema),
|
|
371
371
|
},
|
|
372
372
|
{
|
|
373
373
|
name: "update_issue",
|
|
374
|
-
description: "Update an issue.
|
|
374
|
+
description: "Update an issue. Slim confirmation by default; full_response=true for the complete object",
|
|
375
375
|
inputSchema: toJSONSchema(UpdateIssueSchema),
|
|
376
376
|
},
|
|
377
377
|
{
|
|
378
378
|
name: "update_issue_description_patch",
|
|
379
|
-
description: "
|
|
380
|
-
"Reduces token usage by allowing small changes without sending the full description. " +
|
|
381
|
-
"Supports dry_run to preview changes and create_note to summarize updates.",
|
|
379
|
+
description: "Patch an issue description (search/replace or unified diff) without resending the full body. dry_run previews; create_note summarizes",
|
|
382
380
|
inputSchema: toJSONSchema(UpdateIssueDescriptionPatchSchema),
|
|
383
381
|
},
|
|
384
382
|
{
|
|
@@ -1070,7 +1068,7 @@ export const allTools = [
|
|
|
1070
1068
|
},
|
|
1071
1069
|
{
|
|
1072
1070
|
name: "health_check",
|
|
1073
|
-
description: "
|
|
1071
|
+
description: "Check auth and versions. Always includes mcp_server_version. When authenticated, also GitLab version, revision, and enterprise from GET /api/v4/version. Version lookup failures omit those fields instead of failing",
|
|
1074
1072
|
inputSchema: toJSONSchema(HealthCheckSchema),
|
|
1075
1073
|
},
|
|
1076
1074
|
{
|
|
@@ -1467,13 +1465,13 @@ export const allTools = [
|
|
|
1467
1465
|
// --- Meta tool: Dynamic tool discovery ---
|
|
1468
1466
|
{
|
|
1469
1467
|
name: "discover_tools",
|
|
1470
|
-
description: "
|
|
1468
|
+
description: "List or activate a toolset for this session. Omit category to list; pass one to enable. Session-only; with OAUTH_STATELESS_MODE=true persist `GITLAB_TOOLSETS=core,<category>` instead.",
|
|
1471
1469
|
inputSchema: {
|
|
1472
1470
|
type: "object",
|
|
1473
1471
|
properties: {
|
|
1474
1472
|
category: {
|
|
1475
1473
|
type: "string",
|
|
1476
|
-
description: "Toolset
|
|
1474
|
+
description: "Toolset to activate (e.g. pipelines, wiki). Omit to list. Prefer a category over GITLAB_TOOLSETS=all. Session-only; persist `GITLAB_TOOLSETS=core,<category>` when OAUTH_STATELESS_MODE=true.",
|
|
1477
1475
|
},
|
|
1478
1476
|
},
|
|
1479
1477
|
},
|
|
@@ -2347,7 +2345,7 @@ export function findSmallestToolsetForTool(toolName) {
|
|
|
2347
2345
|
// Update discover_tools description with all known categories (must be after TOOLSET_DEFINITIONS)
|
|
2348
2346
|
const discoverTool = allTools.find(t => t.name === "discover_tools");
|
|
2349
2347
|
if (discoverTool) {
|
|
2350
|
-
discoverTool.description = `
|
|
2348
|
+
discoverTool.description = `List or activate a toolset for this session. Omit category to list; pass one to enable. Prefer this over GITLAB_TOOLSETS=all (loads ~all schemas). Session-only; with OAUTH_STATELESS_MODE=true persist \`GITLAB_TOOLSETS=core,<category>\` instead. Categories: ${[...DISCOVERABLE_TOOLSET_IDS].join(", ")}. Response lists already-active ones. api is explicit-only.`;
|
|
2351
2349
|
}
|
|
2352
2350
|
const allToolNames = new Set(allTools.map(tool => tool.name));
|
|
2353
2351
|
for (const tool of allTools) {
|
|
@@ -9,9 +9,9 @@ const TOOL_GUIDANCE = {
|
|
|
9
9
|
create_or_update_file: "Create or update one repository file. Use `push_files` for a multi-file commit. Optional `encoding` (`text` or `base64`) defaults to `GITLAB_REPO_FILE_ENCODING`.",
|
|
10
10
|
push_files: "Commit several file changes atomically. Each file defaults to action `create`; optional per-file `action` (create/update/delete/move) and `encoding` (text/base64) are additive. `GITLAB_PERMISSION_MODE=modify` rejects `delete` and `move`.",
|
|
11
11
|
create_issue: "Open a new issue. Use `update_issue` for an existing issue and `create_issue_note` for discussion.",
|
|
12
|
-
list_issues: "Use this for issue management
|
|
13
|
-
my_issues: "Use this for issue management
|
|
14
|
-
get_issue: "Use this for issue management
|
|
12
|
+
list_issues: "Use this for issue management. Optional `project_id`. Use `get_issue` when the iid is known and `my_issues` for assignments.",
|
|
13
|
+
my_issues: "Use this for issue management. Use `list_issues` for project-wide listing and `get_issue` for one issue. Requires classic read_user or fine-grained User:Read.",
|
|
14
|
+
get_issue: "Use this for issue management. Use `list_issues` or `my_issues` to discover issues first.",
|
|
15
15
|
create_merge_request: "Open a merge request from an existing source branch to a target. Use `update_merge_request` after it exists.",
|
|
16
16
|
fork_repository: "Fork an existing project into the current user's namespace or a permitted namespace. Use `search_repositories` or `get_project` to inspect without copying.",
|
|
17
17
|
create_branch: "Create a branch from a source branch, tag, or commit. Use `protect_branch` after creation. Returns already-exists when the name is taken.",
|
|
@@ -39,7 +39,7 @@ const TOOL_GUIDANCE = {
|
|
|
39
39
|
download_attachment: "Retrieve a project attachment. Remote HTTP returns inline base64 or a URL; local stdio saves under GITLAB_DOWNLOAD_DIR and never overwrites.",
|
|
40
40
|
gitlab_api_request: "Send one GitLab REST call under /api/v4. Readonly allows GET only; modify rejects DELETE. Enable only by listing api in GITLAB_TOOLSETS; all, discover_tools, and GITLAB_TOOLS do not. Prompt injection can drive this tool, so operators who rely on group, project, or tool restrictions must not enable it. With GITLAB_ALLOWED_PROJECT_IDS or a session project scope, only /projects/:id paths for an allowed project are accepted; body and query parameters that name another project are not checked.",
|
|
41
41
|
execute_graphql: "Use only when no typed REST tool covers the operation. The query is sent directly and may include mutations.",
|
|
42
|
-
help: "
|
|
42
|
+
help: "Topics: code-review, merge-requests, issues, pipelines, search, token-saving. Prefer discover_tools over GITLAB_TOOLSETS=all. With OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS instead.",
|
|
43
43
|
whoami: "Requires classic read_user or fine-grained User:Read. Use `get_user` or `get_users` to look up another user.",
|
|
44
44
|
list_project_members: "Search project members by name or username. Use `list_group_members` for a group.",
|
|
45
45
|
get_commit_diff: "Return the file diffs for one commit. Use `get_commit` for metadata without the patch.",
|
package/package.json
CHANGED