@zereight/mcp-gitlab 2.2.1 → 2.2.3

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.pt-BR.md CHANGED
@@ -1,12 +1,25 @@
1
1
  # GitLab MCP Server
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
4
- [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_GitLab_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22zereight.gitlab-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)
4
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_GitLab_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=zereight.gitlab-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)
5
+ [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0IiwiR0lUTEFCX1BFUk1JU1NJT05fTU9ERSI6ImZ1bGwifX0%3D)
5
6
 
6
7
  [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
7
8
 
8
9
  📖 **[Documentação →](https://zereight.github.io/gitlab-mcp/)** Guias de configuração, variáveis de ambiente e a referência completa de ferramentas estão disponíveis no site de documentação.
9
10
 
11
+ Instalação local recomendada com PAT para `@zereight/mcp-gitlab`. Os argumentos são os mesmos dos guias de [Claude Code](./docs/clients/claude-code.md) e [Codex](./docs/clients/codex.md).
12
+
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`.
14
+
15
+ | Cliente | Instalação |
16
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
+ | Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
18
+ | Codex | `codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
19
+ | Cursor | [Guia de configuração do Cursor](./docs/clients/cursor.md) |
20
+ | VS Code | [Guia de configuração do VS Code](./docs/clients/vscode.md) |
21
+ | Clientes JSON | [Guia para clientes MCP baseados em JSON](./docs/clients/json-clients.md) |
22
+
10
23
  [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
11
24
 
12
25
  ## @zereight/mcp-gitlab
@@ -17,7 +30,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
17
30
 
18
31
  ### Por que usar este GitLab MCP?
19
32
 
20
- - **268 ferramentas: 266 em toolsets + `execute_graphql` + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
33
+ - **274 ferramentas: 272 em toolsets + `execute_graphql` + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
21
34
  - **Revisão de MR em 2 etapas** — `list_merge_request_changed_files` → `get_merge_request_file_diff` em lote
22
35
  - **Agent Skill integrado** — orientação de workflows em `skills/gitlab-mcp/`
23
36
  - **Autenticação flexível** — Personal Access Token, fluxo OAuth2 local no navegador, proxy MCP OAuth e autorização remota por requisição
@@ -28,15 +41,23 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
28
41
 
29
42
  ### Comparação
30
43
 
31
- | | @zereight/mcp-gitlab | GitLab MCP A (comunidade, estilo CQRS) |
32
- | ------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
33
- | **Mais indicado para** | Workflows de agentes de IA | Múltiplas instâncias corporativas / ferramentas agrupadas |
34
- | **Modelo de ferramentas** | 268 ferramentas: 266 em toolsets + `execute_graphql` + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*` |
35
- | **Revisão de MR** | Diff em lote em 2 etapas | Varia |
36
- | **Node.js** | >=18.17 | Frequentemente >=24 |
37
- | **Licença** | MIT | Varia |
44
+ | | @zereight/mcp-gitlab | GitLab MCP A (comunidade, estilo CQRS) | Servidor MCP oficial do GitLab |
45
+ | ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46
+ | **Mais indicado para** | Workflows de agentes de IA | Múltiplas instâncias corporativas / ferramentas agrupadas | Integrado ao GitLab, sem instalação separada |
47
+ | **Modelo de ferramentas** | 274 ferramentas: 272 em toolsets + `execute_graphql` + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*` | Toolsets escolhidos por cabeçalho HTTP |
48
+ | **Revisão de MR** | Diff em lote em 2 etapas | Varia | `get_merge_request` com diffs |
49
+ | **Node.js** | >=18.17 | Frequentemente >=24 | Node.js 20+ para stdio via `mcp-remote` |
50
+ | **Licença** | MIT | Varia | Parte do GitLab |
38
51
 
39
- [Comparação completa →](./docs/comparison/community-gitlab-mcp-a.md)
52
+ [Comparação completa com o GitLab MCP A →](./docs/comparison/community-gitlab-mcp-a.md)
53
+
54
+ O GitLab também inclui um [servidor MCP oficial](https://docs.gitlab.com/user/model_context_protocol/mcp_server/).
55
+
56
+ - Free, Premium e Ultimate. Passou de Premium para Free no GitLab 19.2. Disponibilidade geral no GitLab 19.5.
57
+ - No GitLab.com, o Owner do grupo de nível superior permite o acesso ao servidor MCP. No GitLab Self-Managed e no GitLab Dedicated, um administrador controla a configuração da instância. As regras padrão estão na página oficial.
58
+ - Clientes remotos usam HTTP `https://<gitlab.example.com>/api/v4/mcp` com OAuth 2.0 dynamic client registration.
59
+ - O stdio passa por `mcp-remote` e exige Node.js 20 ou posterior.
60
+ - Os toolsets usam o cabeçalho `X-Gitlab-Enabled-Mcp-Server-Toolsets`. O cabeçalho opcional `X-Gitlab-Mcp-Server-Tool-Name-Prefix` mantém os primeiros 32 caracteres de um prefixo de nome de ferramenta.
40
61
 
41
62
  Início rápido: escolha abaixo uma configuração com Personal Access Token ou OAuth2, instale `@zereight/mcp-gitlab` e use `zereight-mcp-gitlab` na configuração do seu cliente MCP.
42
63
 
@@ -111,7 +132,7 @@ O caminho no store é fixado pelo seu lock file; atualize-o com `nix flake updat
111
132
 
112
133
  Os exemplos usam `zereight-mcp-gitlab`, um alias com menor chance de conflito que o binário legado `mcp-gitlab`. Se o seu cliente MCP não o encontrar, use o caminho absoluto retornado por `which zereight-mcp-gitlab`.
113
134
 
114
- Não quer instalar globalmente? Fixe o `npx` na versão estável anterior (a versão recomendada por esta documentação), por exemplo `npx -y @zereight/mcp-gitlab@2.2.0`. Se quiser sempre a versão mais recente, use `npx -y @zereight/mcp-gitlab@latest`. O servidor exibe um aviso no stderr durante a inicialização quando existe uma versão mais nova disponível (desative com `GITLAB_DISABLE_VERSION_CHECK=true`).
135
+ Não quer instalar globalmente? Fixe o `npx` na versão estável anterior (a versão recomendada por esta documentação), por exemplo `npx -y @zereight/mcp-gitlab@2.2.2`. Se quiser sempre a versão mais recente, use `npx -y @zereight/mcp-gitlab@latest`. O servidor exibe um aviso no stderr durante a inicialização quando existe uma versão mais nova disponível (desative com `GITLAB_DISABLE_VERSION_CHECK=true`).
115
136
 
116
137
  #### Usando argumentos de CLI (para clientes com problemas com variáveis de ambiente)
117
138
 
@@ -133,13 +154,13 @@ Alguns clientes MCP, como o GitHub Copilot CLI, têm problemas com variáveis de
133
154
 
134
155
  - `--token` - GitLab Personal Access Token (substitui `GITLAB_PERSONAL_ACCESS_TOKEN`)
135
156
  - `--api-url` - URL da API do GitLab (substitui `GITLAB_API_URL`)
136
- - `--read-only=true` - ativa o modo somente leitura (substitui `GITLAB_READ_ONLY_MODE`, obsoleto — prefira `--permission-mode=readonly`)
157
+ - `--read-only=true` - Deprecated (removed in next major (v3.0.0)); use `--permission-mode=readonly` (substitui `GITLAB_READ_ONLY_MODE`)
137
158
  - `--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`)
138
159
  - `--toolsets=all` - ativa toolsets nomeados (substitui `GITLAB_TOOLSETS`; sem valor usa o padrão enxuto `core`)
139
160
  - `--tools=list_issues` - adiciona ferramentas individuais (substitui `GITLAB_TOOLS`)
140
- - `--use-wiki=true` - ativa a API de Wiki (substitui `USE_GITLAB_WIKI`, legado — prefira `GITLAB_TOOLSETS=wiki`)
141
- - `--use-milestone=true` - ativa a API de milestones (substitui `USE_MILESTONE`, legado — prefira `GITLAB_TOOLSETS=milestones`)
142
- - `--use-pipeline=true` - ativa a API de pipelines (substitui `USE_PIPELINE`, legado — prefira `GITLAB_TOOLSETS=pipelines`)
161
+ - `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,wiki` (substitui `USE_GITLAB_WIKI`)
162
+ - `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,milestones` (substitui `USE_MILESTONE`)
163
+ - `--use-pipeline=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,pipelines` e acrescente `validate_ci_lint,validate_project_ci_lint` à lista `--tools` existente (ou defina `--tools=validate_ci_lint,validate_project_ci_lint` se ela não existir) (substitui `USE_PIPELINE`)
143
164
  - `--disable-version-check=true` - desativa o aviso de nova versão na inicialização (substitui `GITLAB_DISABLE_VERSION_CHECK`)
144
165
  - `--masking-enabled=true` - ativa o mascaramento de respostas de texto (substitui `GITLAB_MASKING_ENABLED`)
145
166
  - `--masking-config` - caminho para um arquivo de configuração de mascaramento (substitui `GITLAB_MASKING_CONFIG`)
@@ -150,6 +171,8 @@ Alguns clientes MCP, como o GitHub Copilot CLI, têm problemas com variáveis de
150
171
  - `--compact-tools` - nomes de ferramentas separados por vírgula para compactar quando a resposta for grande, sem ativar o compact global (substitui `GITLAB_MCP_COMPACT_TOOLS`)
151
172
  - `--tool-profile` - `full` (padrão) ou `slim`. `slim` remove draft notes, reações com emoji, labels, ferramentas do catálogo de CI e `create_group` da lista inicial. Ignorado apenas quando `GITLAB_TOOLSETS` tem um valor não em branco (substitui `GITLAB_TOOL_PROFILE`)
152
173
 
174
+ Se você já definiu `GITLAB_TOOLSETS` ou `--toolsets`, acrescente `wiki`, `milestones` ou `pipelines` a essa lista em vez de substituí-la. Se você já definiu `GITLAB_TOOLS` ou `--tools`, acrescente `validate_ci_lint` e `validate_project_ci_lint` a essa lista em vez de substituí-la. Uma lista explícita substitui o toolset padrão `core`; ela não é mesclada.
175
+
153
176
  Os argumentos de CLI têm precedência sobre as variáveis de ambiente.
154
177
 
155
178
  `zereight-mcp-gitlab auth` é um subcomando, não uma flag do servidor MCP. Ele executa o device flow do GitLab e encerra. Veja [Argumentos de CLI](./docs/getting-started/cli-arguments.md#auth).
@@ -158,13 +181,18 @@ O mesmo binário também é uma CLI do GitLab no estilo `gh` (`tool <name>` ou f
158
181
 
159
182
  > **Filtragem granular de ferramentas:** use `GITLAB_PERMISSION_MODE=modify` para permitir criação/atualização enquanto
160
183
  > bloqueia todas as ferramentas de exclusão e as ferramentas destrutivas de teardown (`cancel_pipeline`,
161
- > `cancel_pipeline_job`, `stop_environment`, `stop_stale_environments`, `unprotect_branch`) —
184
+ > `cancel_pipeline_job`, `stop_environment`, `stop_stale_environments`, `unprotect_branch`,
185
+ > `unprotect_tag`) —
162
186
  > incluindo mutations destrutivas (verbos de exclusão e teardown) por meio de `execute_graphql` e
163
187
  > ações `delete`/`move` do `push_files` — ou use `GITLAB_PERMISSION_MODE=readonly` para acesso somente leitura.
164
188
  > Também é possível habilitar grupos de ferramentas com `GITLAB_TOOLSETS=<group,…>`, permitir ferramentas individuais com
165
189
  > `GITLAB_TOOLS=<tool,…>` (por exemplo, grupos somente leitura mais algumas ferramentas específicas de escrita) e
166
190
  > bloquear por padrão usando `GITLAB_DENIED_TOOLS_REGEX`. As flags legadas `USE_GITLAB_WIKI` /
167
- > `USE_MILESTONE` / `USE_PIPELINE` são mantidas apenas para compatibilidade retroativa.
191
+ > `USE_MILESTONE` / `USE_PIPELINE` estão deprecated (removed in next major (v3.0.0)).
192
+ > Use `GITLAB_TOOLSETS=core,wiki`, `core,milestones` ou `core,pipelines`
193
+ > (`USE_PIPELINE` também precisa acrescentar `validate_ci_lint,validate_project_ci_lint` à lista `GITLAB_TOOLS` existente em vez de substituí-la).
194
+ > Se você já definiu `GITLAB_TOOLSETS`, acrescente o toolset à lista existente em vez de substituí-la.
195
+ > Se `GITLAB_TOOLS` não estiver definido, defina `GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint`. Se já estiver definido, acrescente `validate_ci_lint,validate_project_ci_lint` à lista existente em vez de substituí-la.
168
196
  > Consulte a [Referência de ferramentas](./docs/tools/index.md#feature-toggles) e
169
197
  > [Variáveis de ambiente](./docs/configuration/environment-variables.md).
170
198
 
@@ -176,7 +204,7 @@ docker run -i --rm \
176
204
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
177
205
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
178
206
  -e GITLAB_PERMISSION_MODE=readonly \
179
- -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
207
+ -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
180
208
  -e SSE=true \
181
209
  -e SSE_AUTH_TOKEN=your_mcp_sse_token \
182
210
  -p 3333:3002 \
@@ -205,7 +233,7 @@ docker run -i --rm \
205
233
  -e REMOTE_AUTHORIZATION=true \
206
234
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
207
235
  -e GITLAB_PERMISSION_MODE=readonly \
208
- -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
236
+ -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
209
237
  -e STREAMABLE_HTTP=true \
210
238
  -p 3333:3002 \
211
239
  zereight050/gitlab-mcp
@@ -525,7 +553,7 @@ Não é necessário definir `headers`. O Claude.ai obtém o token via OAuth.
525
553
  | `MCP_SERVER_URL` | sim | URL HTTPS pública do servidor MCP |
526
554
  | `GITLAB_API_URL` | sim | URL da API da instância GitLab (por exemplo, `https://gitlab.com/api/v4`) |
527
555
  | `STREAMABLE_HTTP` | sim | Deve ser `true` (SSE não é suportado) |
528
- | `GITLAB_OAUTH_SCOPES` | não | Scopes do GitLab a solicitar, separados por vírgula. O padrão é `api`, ou `read_api` quando `GITLAB_READ_ONLY_MODE=true`. O aplicativo previamente registrado deve ter pelo menos esses scopes configurados. |
556
+ | `GITLAB_OAUTH_SCOPES` | não | Scopes do GitLab a solicitar, separados por vírgula. O padrão é `api`, ou `read_api` quando o permission mode efetivo é `readonly`. O aplicativo previamente registrado deve ter pelo menos esses scopes configurados. |
529
557
  | `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR` | não | Limite rolling de Dynamic Client Registration (`POST /register`) por IP do cliente. Padrão `20`/hora, intervalo `1`–`1000`. Aumente se múltiplas janelas de IDE estiverem atingindo o limite. Não está relacionado aos limites da API do GitLab. |
530
558
  | `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | não | Apenas para desenvolvimento local via HTTP |
531
559
 
package/README.zh-CN.md CHANGED
@@ -1,12 +1,25 @@
1
1
  # GitLab MCP Server
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
4
- [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_GitLab_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22zereight.gitlab-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)
4
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_GitLab_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=zereight.gitlab-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)
5
+ [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0IiwiR0lUTEFCX1BFUk1JU1NJT05fTU9ERSI6ImZ1bGwifX0%3D)
5
6
 
6
7
  [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
7
8
 
8
9
  📖 **[文档 →](https://zereight.github.io/gitlab-mcp/)** 设置指南、环境变量和完整工具参考请查看托管文档站点。
9
10
 
11
+ 下面是 `@zereight/mcp-gitlab` 的推荐本地 PAT 安装。命令参数与 [Claude Code](./docs/clients/claude-code.md) 和 [Codex](./docs/clients/codex.md) 指南相同。
12
+
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`。
14
+
15
+ | 客户端 | 安装 |
16
+ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
+ | Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
18
+ | Codex | `codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
19
+ | Cursor | [Cursor 设置指南](./docs/clients/cursor.md) |
20
+ | VS Code | [VS Code 设置指南](./docs/clients/vscode.md) |
21
+ | JSON 客户端 | [基于 JSON 的 MCP 客户端设置指南](./docs/clients/json-clients.md) |
22
+
10
23
  [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
11
24
 
12
25
  ## @zereight/mcp-gitlab
@@ -17,7 +30,7 @@
17
30
 
18
31
  ### 为什么使用这个 GitLab MCP?
19
32
 
20
- - **268 个工具:toolset 中 266 个 + `execute_graphql` + `discover_tools`** — 从小型 toolset 开始,运行时按需激活类别
33
+ - **274 个工具:toolset 中 272 个 + `execute_graphql` + `discover_tools`** — 从小型 toolset 开始,运行时按需激活类别
21
34
  - **MR 两步审查** — `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff`
22
35
  - **内置 Agent Skill** — `skills/gitlab-mcp/` 工作流指南
23
36
  - **认证灵活** — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
@@ -28,15 +41,23 @@
28
41
 
29
42
  ### 对比摘要
30
43
 
31
- | | @zereight/mcp-gitlab | GitLab MCP A(社区 CQRS 型) |
32
- |---|----------------------|------------------------------|
33
- | **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 |
34
- | **工具模型** | 268 个工具:toolset 中 266 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
35
- | **MR 审查** | 两步批量 diff | 因服务器而异 |
36
- | **Node.js** | >=18.17 | 通常 >=24 |
37
- | **许可证** | MIT | 因服务器而异 |
44
+ | | @zereight/mcp-gitlab | GitLab MCP A(社区 CQRS 型) | GitLab 官方 MCP 服务器 |
45
+ | ------------ | -------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
46
+ | **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 | 内置于 GitLab,无需单独安装 |
47
+ | **工具模型** | 274 个工具:toolset 中 272 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 | 用 HTTP 头选择 toolset |
48
+ | **MR 审查** | 两步批量 diff | 因服务器而异 | `get_merge_request` 带 diffs |
49
+ | **Node.js** | >=18.17 | 通常 >=24 | stdio 经 `mcp-remote`,需要 Node.js 20+ |
50
+ | **许可证** | MIT | 因服务器而异 | GitLab 的一部分 |
38
51
 
39
- [完整对比 →](./docs/comparison/community-gitlab-mcp-a.md)
52
+ [与 GitLab MCP A 的完整对比 →](./docs/comparison/community-gitlab-mcp-a.md)
53
+
54
+ GitLab 还提供[官方 MCP 服务器](https://docs.gitlab.com/user/model_context_protocol/mcp_server/)。
55
+
56
+ - Free、Premium、Ultimate。GitLab 19.2 从 Premium 移到 Free。GitLab 19.5 正式可用。
57
+ - 在 GitLab.com 上,顶级群组 Owner 允许访问 MCP 服务器。GitLab Self-Managed 和 GitLab Dedicated 使用实例设置。默认规则见官方页面。
58
+ - 远程客户端使用 HTTP `https://<gitlab.example.com>/api/v4/mcp` 和 OAuth 2.0 动态客户端注册。
59
+ - stdio 通过 `mcp-remote`,需要 Node.js 20 或更高版本。
60
+ - Toolset 使用请求头 `X-Gitlab-Enabled-Mcp-Server-Toolsets`。可选请求头 `X-Gitlab-Mcp-Server-Tool-Name-Prefix` 只保留工具名前缀的前 32 个字符。
40
61
 
41
62
  快速开始:在下面选择 Personal Access Token 或 OAuth2 设置,安装 `@zereight/mcp-gitlab`,并在 MCP 客户端配置中使用 `zereight-mcp-gitlab`。
42
63
 
@@ -111,7 +132,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
111
132
 
112
133
  示例使用 `zereight-mcp-gitlab`,这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它,请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
113
134
 
114
- 如果不想全局安装,请将 `npx` 固定到上一个稳定版本(即文档推荐的版本),例如 `npx -y @zereight/mcp-gitlab@2.2.0`。如果始终想使用最新版本,请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时,服务器会在启动时通过 stderr 提示(可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭)。
135
+ 如果不想全局安装,请将 `npx` 固定到上一个稳定版本(即文档推荐的版本),例如 `npx -y @zereight/mcp-gitlab@2.2.2`。如果始终想使用最新版本,请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时,服务器会在启动时通过 stderr 提示(可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭)。
115
136
 
116
137
  #### 使用 CLI 参数(适用于环境变量有问题的客户端)
117
138
 
@@ -133,13 +154,13 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
133
154
 
134
155
  - `--token` - GitLab Personal Access Token(替代 `GITLAB_PERSONAL_ACCESS_TOKEN`)
135
156
  - `--api-url` - GitLab API URL(替代 `GITLAB_API_URL`)
136
- - `--read-only=true` - 启用只读模式(替代 `GITLAB_READ_ONLY_MODE`,已弃用 — 推荐 `--permission-mode=readonly`)
157
+ - `--read-only=true` - Deprecated (removed in next major (v3.0.0));请改用 `--permission-mode=readonly`(替代 `GITLAB_READ_ONLY_MODE`)
137
158
  - `--permission-mode` - 权限级别:`readonly`、`modify`(禁用删除/拆除工具)或 `full`(替代 `GITLAB_PERMISSION_MODE`,默认 `full`)
138
159
  - `--toolsets=all` - 启用指定工具集(替代 `GITLAB_TOOLSETS`;未设置时使用精简 `core` 默认值)
139
160
  - `--tools=list_issues` - 添加单个工具(替代 `GITLAB_TOOLS`)
140
- - `--use-wiki=true` - 启用 Wiki API(替代 `USE_GITLAB_WIKI`,旧版 — 推荐 `GITLAB_TOOLSETS=wiki`)
141
- - `--use-milestone=true` - 启用里程碑 API(替代 `USE_MILESTONE`,旧版 — 推荐 `GITLAB_TOOLSETS=milestones`)
142
- - `--use-pipeline=true` - 启用流水线 API(替代 `USE_PIPELINE`,旧版 — 推荐 `GITLAB_TOOLSETS=pipelines`)
161
+ - `--use-wiki=true` - Deprecated (removed in next major (v3.0.0));请改用 `--toolsets=core,wiki`(替代 `USE_GITLAB_WIKI`)
162
+ - `--use-milestone=true` - Deprecated (removed in next major (v3.0.0));请改用 `--toolsets=core,milestones`(替代 `USE_MILESTONE`)
163
+ - `--use-pipeline=true` - Deprecated (removed in next major (v3.0.0));请改用 `--toolsets=core,pipelines`,并把 `validate_ci_lint,validate_project_ci_lint` 追加到现有 `--tools` 列表(如果还没有该列表,则设置 `--tools=validate_ci_lint,validate_project_ci_lint`)(替代 `USE_PIPELINE`)
143
164
  - `--disable-version-check=true` - 关闭启动时的新版本提示(替代 `GITLAB_DISABLE_VERSION_CHECK`)
144
165
  - `--masking-enabled=true` - 启用文本响应掩码(替代 `GITLAB_MASKING_ENABLED`)
145
166
  - `--masking-config` - 掩码配置文件路径(替代 `GITLAB_MASKING_CONFIG`)
@@ -150,6 +171,8 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
150
171
  - `--compact-tools` - 以逗号分隔的工具名,仅在回复过大时对这些工具进行 compact,而不开启全局 compact(替代 `GITLAB_MCP_COMPACT_TOOLS`)
151
172
  - `--tool-profile` - `full`(默认)或 `slim`。`slim` 会从初始列表中移除 draft note、表情回应、标签、CI 目录工具以及 `create_group`。仅当 `GITLAB_TOOLSETS` 设置为非空白值时忽略(替代 `GITLAB_TOOL_PROFILE`)
152
173
 
174
+ 如果已经设置了 `GITLAB_TOOLSETS` 或 `--toolsets`,请把 `wiki`、`milestones` 或 `pipelines` 追加到该列表,不要整段替换。如果已经设置了 `GITLAB_TOOLS` 或 `--tools`,请把 `validate_ci_lint` 和 `validate_project_ci_lint` 追加到该列表,不要整段替换。显式列表会替换默认的 `core` toolset,不会合并。
175
+
153
176
  CLI 参数优先于环境变量。
154
177
 
155
178
  `zereight-mcp-gitlab auth` 是子命令,不是 MCP 服务器参数。它运行 GitLab device flow 后退出。参见 [CLI 参数](./docs/getting-started/cli-arguments.md#auth)。
@@ -158,12 +181,17 @@ CLI 参数优先于环境变量。
158
181
 
159
182
  > **细粒度工具过滤:**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新,同时阻止所有删除工具以及
160
183
  > 破坏性的拆除(teardown)工具(`cancel_pipeline`、`cancel_pipeline_job`、`stop_environment`、
161
- > `stop_stale_environments`、`unprotect_branch`)(包括通过 `execute_graphql` 的破坏性 mutation
184
+ > `stop_stale_environments`、`unprotect_branch`、`unprotect_tag`)(包括通过 `execute_graphql` 的破坏性 mutation
162
185
  > —— 删除与拆除动词 —— 以及 `push_files` 的 `delete`/`move`),或使用
163
186
  > `GITLAB_PERMISSION_MODE=readonly` 只读运行。还可以用
164
187
  > `GITLAB_TOOLSETS=<group,…>` 启用工具分组,用 `GITLAB_TOOLS=<tool,…>` 白名单启用单个工具
165
188
  > (例如:只读分组 + 少数几个写工具),用 `GITLAB_DENIED_TOOLS_REGEX` 按正则屏蔽工具。
166
- > 旧版 `USE_GITLAB_WIKI` / `USE_MILESTONE` / `USE_PIPELINE` 标志仅为向后兼容保留。
189
+ > 旧版 `USE_GITLAB_WIKI` / `USE_MILESTONE` / `USE_PIPELINE` 已弃用
190
+ > (Deprecated, removed in next major (v3.0.0))。
191
+ > 请改用 `GITLAB_TOOLSETS=core,wiki`、`core,milestones` 或 `core,pipelines`
192
+ > (`USE_PIPELINE` 还需要把 `validate_ci_lint,validate_project_ci_lint` 追加到现有 `GITLAB_TOOLS`,不要整段替换)。
193
+ > 如果已经设置了 `GITLAB_TOOLSETS`,请把 toolset 追加到现有列表,不要整段替换。
194
+ > 如果未设置 `GITLAB_TOOLS`,请设置 `GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint`。如果已经设置,请把 `validate_ci_lint,validate_project_ci_lint` 追加到现有列表,不要整段替换。
167
195
  > 参见 [Tools Reference](./docs/tools/index.md#feature-toggles) 和
168
196
  > [Environment Variables](./docs/configuration/environment-variables.md)。
169
197
 
@@ -175,7 +203,7 @@ docker run -i --rm \
175
203
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
176
204
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
177
205
  -e GITLAB_PERMISSION_MODE=readonly \
178
- -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
206
+ -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
179
207
  -e SSE=true \
180
208
  -e SSE_AUTH_TOKEN=your_mcp_sse_token \
181
209
  -p 3333:3002 \
@@ -204,7 +232,7 @@ docker run -i --rm \
204
232
  -e REMOTE_AUTHORIZATION=true \
205
233
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
206
234
  -e GITLAB_PERMISSION_MODE=readonly \
207
- -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
235
+ -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
208
236
  -e STREAMABLE_HTTP=true \
209
237
  -p 3333:3002 \
210
238
  zereight050/gitlab-mcp
@@ -524,7 +552,7 @@ node build/index.js
524
552
  | `MCP_SERVER_URL` | 是 | MCP 服务器的公开 HTTPS URL |
525
553
  | `GITLAB_API_URL` | 是 | GitLab 实例 API URL(例如 `https://gitlab.com/api/v4`) |
526
554
  | `STREAMABLE_HTTP` | 是 | 必须为 `true`(不支持 SSE) |
527
- | `GITLAB_OAUTH_SCOPES` | 否 | 要请求的 GitLab scopes,以逗号分隔。默认值为 `api`,当 `GITLAB_READ_ONLY_MODE=true` 时为 `read_api`。预注册应用必须配置至少这些 scopes。 |
555
+ | `GITLAB_OAUTH_SCOPES` | 否 | 要请求的 GitLab scopes,以逗号分隔。默认值为 `api`;有效 permission mode 为 `readonly` 时为 `read_api`。预注册应用必须配置至少这些 scopes。 |
528
556
  | `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR` | 否 | Dynamic Client Registration(`POST /register`)的每客户端 IP rolling 限制。默认 `20`/小时,范围 `1`–`1000`。多个 IDE 窗口等导致注册被限流时可调高。与 GitLab API 限额无关。 |
529
557
  | `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | 否 | 仅用于本地 HTTP 开发 |
530
558
 
package/build/auth-cli.js CHANGED
@@ -1,7 +1,9 @@
1
1
  import * as os from "os";
2
2
  import * as path from "path";
3
+ import { parseCliArgs } from "./cli-boolean-flags.js";
4
+ import { deprecatedEnvInputFromSources, getDeprecatedEnvWarnings } from "./deprecated-env.js";
3
5
  import { GitLabOAuth } from "./oauth.js";
4
- import { createLogger } from "./utils/logger.js";
6
+ import { createLogger, flushStartupLogs } from "./utils/logger.js";
5
7
  const logger = createLogger("gitlab-mcp-auth");
6
8
  const DEFAULT_API_URL = "https://gitlab.com";
7
9
  const DEFAULT_REDIRECT_URI = "http://127.0.0.1:8888/callback";
@@ -42,12 +44,12 @@ function readFlag(argv, name) {
42
44
  function wantsHelp(argv) {
43
45
  return argv.includes("--help") || argv.includes("-h");
44
46
  }
45
- function isReadOnlyMode(argv, env) {
46
- const readOnly = readFlag(argv, "read-only") ?? env.GITLAB_READ_ONLY_MODE;
47
+ function isReadOnlyMode(parsedArgs, env) {
48
+ const readOnly = parsedArgs["read-only"] ?? env.GITLAB_READ_ONLY_MODE;
47
49
  if (readOnly === "true") {
48
50
  return true;
49
51
  }
50
- return (readFlag(argv, "permission-mode") ?? env.GITLAB_PERMISSION_MODE) === "readonly";
52
+ return (parsedArgs["permission-mode"] ?? env.GITLAB_PERMISSION_MODE) === "readonly";
51
53
  }
52
54
  export function gitlabOriginFromApiUrl(apiUrl) {
53
55
  return apiUrl.replace(/\/api\/v4\/?$/, "");
@@ -56,6 +58,14 @@ export async function runAuthCommandAsync(input = {}) {
56
58
  const argv = input.argv ?? process.argv;
57
59
  const env = input.env ?? process.env;
58
60
  const stdout = input.stdout ?? process.stdout;
61
+ const parsedArgs = parseCliArgs(argv.slice(2));
62
+ const warnings = getDeprecatedEnvWarnings(deprecatedEnvInputFromSources(parsedArgs, env));
63
+ for (const warning of warnings) {
64
+ logger.warn(warning);
65
+ }
66
+ if (warnings.length > 0) {
67
+ flushStartupLogs(logger);
68
+ }
59
69
  if (wantsHelp(argv)) {
60
70
  stdout.write(AUTH_CLI_HELP);
61
71
  return;
@@ -69,7 +79,7 @@ export async function runAuthCommandAsync(input = {}) {
69
79
  env.GITLAB_OAUTH_TOKEN_PATH ??
70
80
  path.join(os.homedir(), ".gitlab-mcp-token.json");
71
81
  const gitlabUrl = gitlabOriginFromApiUrl(apiUrl);
72
- const scopes = [isReadOnlyMode(argv, env) ? "read_api" : "api"];
82
+ const scopes = [isReadOnlyMode(parsedArgs, env) ? "read_api" : "api"];
73
83
  const oauth = new GitLabOAuth({
74
84
  clientId,
75
85
  clientSecret: env.GITLAB_OAUTH_CLIENT_SECRET,
@@ -36,3 +36,37 @@ export function nextBooleanFlagValue(nextToken) {
36
36
  }
37
37
  return { value: "true", consumeNext: false };
38
38
  }
39
+ /** Same flag parse as startup config: CLI values only, positionals ignored. */
40
+ export function parseCliArgs(argv) {
41
+ const parsed = {};
42
+ for (let index = 0; index < argv.length; index++) {
43
+ const arg = argv[index];
44
+ if (!arg.startsWith("--")) {
45
+ continue;
46
+ }
47
+ const eqIndex = arg.indexOf("=");
48
+ if (eqIndex !== -1) {
49
+ const key = arg.slice(2, eqIndex);
50
+ const value = arg.slice(eqIndex + 1);
51
+ if (value) {
52
+ parsed[key] = value;
53
+ }
54
+ continue;
55
+ }
56
+ const key = arg.slice(2);
57
+ if (BOOLEAN_CLI_FLAG_NAMES.has(key)) {
58
+ const next = nextBooleanFlagValue(argv[index + 1]);
59
+ parsed[key] = next.value;
60
+ if (next.consumeNext) {
61
+ index += 1;
62
+ }
63
+ continue;
64
+ }
65
+ const next = argv[index + 1];
66
+ if (next !== undefined && !next.startsWith("--")) {
67
+ index += 1;
68
+ parsed[key] = next;
69
+ }
70
+ }
71
+ return parsed;
72
+ }
package/build/config.js CHANGED
@@ -1,35 +1,9 @@
1
- import { BOOLEAN_CLI_FLAG_NAMES, nextBooleanFlagValue } from "./cli-boolean-flags.js";
1
+ import { parseCliArgs } from "./cli-boolean-flags.js";
2
+ import { deprecatedEnvInputFromSources } from "./deprecated-env.js";
2
3
  import { parseToolProfile } from "./tools/tool-profile.js";
3
4
  import { parseCompactToolAllowlist } from "./utils/compact-tool-allowlist.js";
4
5
  // Parse CLI arguments before anything else
5
- const args = process.argv.slice(2);
6
- export const cliArgs = {};
7
- for (let i = 0; i < args.length; i++) {
8
- const arg = args[i];
9
- if (arg.startsWith("--")) {
10
- const eqIndex = arg.indexOf("=");
11
- if (eqIndex !== -1) {
12
- const key = arg.slice(2, eqIndex);
13
- const value = arg.slice(eqIndex + 1);
14
- if (value) {
15
- cliArgs[key] = value;
16
- }
17
- }
18
- else {
19
- const key = arg.slice(2);
20
- if (BOOLEAN_CLI_FLAG_NAMES.has(key)) {
21
- const parsed = nextBooleanFlagValue(args[i + 1]);
22
- cliArgs[key] = parsed.value;
23
- if (parsed.consumeNext) {
24
- i += 1;
25
- }
26
- }
27
- else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
28
- cliArgs[key] = args[++i];
29
- }
30
- }
31
- }
32
- }
6
+ export const cliArgs = parseCliArgs(process.argv.slice(2));
33
7
  export function getConfig(cliKey, envKey, defaultValue) {
34
8
  return cliArgs[cliKey] || process.env[envKey] || defaultValue;
35
9
  }
@@ -103,7 +77,7 @@ export const GITLAB_OAUTH_SCOPES = GITLAB_OAUTH_SCOPES_RAW
103
77
  .filter(Boolean)
104
78
  : undefined;
105
79
  export const GITLAB_OAUTH_CALLBACK_PROXY = getConfig("oauth-callback-proxy", "GITLAB_OAUTH_CALLBACK_PROXY") === "true";
106
- /** @deprecated Use GITLAB_OAUTH_ALLOWED_GROUPS_RAW instead. Will be removed in the next major version. */
80
+ /** @deprecated Use GITLAB_OAUTH_ALLOWED_GROUPS_RAW instead. Will be removed in v3.0.0. */
107
81
  export const GITLAB_ALLOWED_GROUPS_RAW = getConfig("allowed-groups", "GITLAB_ALLOWED_GROUPS");
108
82
  export const GITLAB_OAUTH_ALLOWED_GROUPS_RAW = getConfig("oauth-allowed-groups", "GITLAB_OAUTH_ALLOWED_GROUPS");
109
83
  export const GITLAB_OAUTH_ALLOWED_GROUPS = (() => {
@@ -202,5 +176,13 @@ export const HTTPS_PROXY = getConfig("https-proxy", "HTTPS_PROXY");
202
176
  export const NO_PROXY = getConfig("no-proxy", "NO_PROXY");
203
177
  export const NODE_TLS_REJECT_UNAUTHORIZED = getConfig("tls-reject-unauthorized", "NODE_TLS_REJECT_UNAUTHORIZED");
204
178
  export const GITLAB_CA_CERT_PATH = getConfig("ca-cert-path", "GITLAB_CA_CERT_PATH");
179
+ /**
180
+ * Snapshot of deprecated settings for startup warnings.
181
+ * CLI flags win over env vars, matching getConfig, so the warning can name
182
+ * the flag the user actually passed.
183
+ */
184
+ export function buildDeprecatedEnvInput() {
185
+ return deprecatedEnvInputFromSources(cliArgs, process.env);
186
+ }
205
187
  const _poolMaxSizeRaw = getConfig("pool-max-size", "GITLAB_POOL_MAX_SIZE");
206
188
  export const GITLAB_POOL_MAX_SIZE = _poolMaxSizeRaw ? Number.parseInt(_poolMaxSizeRaw, 10) : 100;