@zereight/mcp-gitlab 2.2.3 → 2.2.5

package/README.ko.md

@@ -12,10 +12,16 @@
 
 `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`.
 
-| 클라이언트      | 설치                                                                                                                                                                              |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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` |
-| 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`                                  |
+토큰을 화면에 표시하지 않고 읽은 다음 export 하세요. 셸 기록에는 변수 이름만 남습니다.
+
+```bash
+read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
+```
+
+| 클라이언트      | 설치                                                                                                                                                                                             |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Claude Code     | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
+| Codex           | `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`                                  |
 | Cursor          | [Cursor 설정 가이드](./docs/clients/cursor.md)                                                                                                                                    |
 | VS Code         | [VS Code 설정 가이드](./docs/clients/vscode.md)                                                                                                                                   |
 | JSON 클라이언트 | [JSON 기반 MCP 클라이언트 설정 가이드](./docs/clients/json-clients.md)                                                                                                            |
@@ -30,7 +36,7 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
 
 ### 왜 이 GitLab MCP를 사용하나요?
 
-- **274개 도구: toolset 272개 + `execute_graphql` + `discover_tools`** — 작은 toolset으로 시작하고, 런타임에 카테고리 활성화
+- **275개 도구: toolset 273개 + `execute_graphql` + `discover_tools`** — 작은 toolset으로 시작하고, 런타임에 카테고리 활성화
 - **MR 2단계 리뷰** — `list_merge_request_changed_files` → 배치 `get_merge_request_file_diff`
 - **Agent Skill 내장** — `skills/gitlab-mcp/` 워크플로우 가이드
 - **유연한 인증** — Personal Access Token, 로컬 OAuth2 브라우저 플로우, MCP OAuth 프록시, 요청별 원격 인증
@@ -44,7 +50,7 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
 |                 | @zereight/mcp-gitlab                                             | GitLab MCP A (커뮤니티 CQRS형)             | GitLab 공식 MCP 서버                                                                                                                            |
 | --------------- | ---------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | **적합한 경우** | AI 에이전트 워크플로우                                           | 엔터프라이즈 멀티 인스턴스 / 그룹형 도구   | GitLab에 내장, 별도 설치 없음                                                                                                                   |
-| **도구 모델**   | 274개 도구: toolset 272개 + `execute_graphql` + `discover_tools` | ~50–60개 `browse_*` / `manage_*` 그룹 도구 | HTTP 헤더로 고르는 toolset                                                                                                                      |
+| **도구 모델**   | 275개 도구: toolset 273개 + `execute_graphql` + `discover_tools` | ~50–60개 `browse_*` / `manage_*` 그룹 도구 | HTTP 헤더로 고르는 toolset                                                                                                                      |
 | **MR 리뷰**     | 2단계 배치 diff                                                  | 서버마다 다름                              | `get_merge_request`에 diffs                                                                                                                     |
 | **Node.js**     | >=18.17                                                          | 보통 >=24                                  | stdio는 `mcp-remote`, Node.js 20+                                                                                                               |
 | **라이선스**    | MIT                                                              | 서버마다 다름                              | GitLab의 일부                                                                                                                                   |
@@ -84,7 +90,7 @@ GitLab은 [공식 MCP 서버](https://docs.gitlab.com/user/model_context_protoco
 
 **로컬/데스크톱 사용**(가장 일반적):
 
-1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — 가장 단순한 설정
+1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN` 또는 `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) — 가장 단순한 설정
 2. **OAuth2 — 로컬 브라우저** (`GITLAB_USE_OAUTH`) — 더 나은 보안을 위해 권장
 
 **서버/원격 배포**:
@@ -132,7 +138,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 
 예시는 기존 `mcp-gitlab`보다 충돌 가능성이 낮은 `zereight-mcp-gitlab` 별칭을 사용합니다. MCP 클라이언트가 찾지 못하면 `which zereight-mcp-gitlab`의 절대 경로를 사용하세요.
 
-전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.2.2`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.2.4`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
 
 #### CLI 인자 사용하기(환경 변수 문제가 있는 클라이언트용)
 
@@ -156,7 +162,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 - `--api-url` - GitLab API URL (`GITLAB_API_URL` 대체)
 - `--read-only=true` - Deprecated (removed in next major (v3.0.0)); `--permission-mode=readonly`를 사용 (`GITLAB_READ_ONLY_MODE` 대체)
 - `--permission-mode` - 권한 수준: `readonly`, `modify`(삭제/중단 도구 비활성), `full` (`GITLAB_PERMISSION_MODE` 대체, 기본값 `full`)
-- `--toolsets=all` - 지정한 툴셋 활성화 (`GITLAB_TOOLSETS` 대체, 미설정 시 lean `core` 기본값 사용)
+- `--toolsets=all` - 지정한 툴셋 활성화. 명시적 `api` 툴셋은 빠짐 (`GITLAB_TOOLSETS` 대체, 미설정 시 lean `core` 기본값 사용). `gitlab_api_request`는 `--toolsets=api`
 - `--tools=list_issues` - 개별 도구 추가 (`GITLAB_TOOLS` 대체)
 - `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); `--toolsets=core,wiki`를 사용 (`USE_GITLAB_WIKI` 대체)
 - `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); `--toolsets=core,milestones`를 사용 (`USE_MILESTONE` 대체)
@@ -196,12 +202,18 @@ CLI 인자는 환경 변수보다 우선합니다.
 > [Tools Reference](./docs/tools/index.md#feature-toggles)와
 > [Environment Variables](./docs/configuration/environment-variables.md)를 참고하세요.
 
+> [!CAUTION]
+> `gitlab_api_request`(`api` 툴셋)는 `GITLAB_ALLOWED_GROUPS`와 그 밖의 그룹 제한, 프로젝트 허용 목록, 도구 단위 제한(`GITLAB_TOOLS`, 다른 도구에 걸린 `GITLAB_DENIED_TOOLS_REGEX`), 개별 도구 안전 검사를 우회합니다. 토큰 권한 범위 전체가 노출됩니다. 프롬프트 인젝션이 이 도구를 호출할 수 있습니다. 이런 제한에 의존하는 운영자는 켜면 안 됩니다.
+> `GITLAB_TOOLSETS`에 `api`를 직접 적을 때만 켜집니다 (`GITLAB_TOOLSETS=all`, `discover_tools`, `GITLAB_TOOLS`, 레거시 `USE_*`, `GITLAB_TOOL_PROFILE`로는 안 됩니다). `GITLAB_ALLOWED_PROJECT_IDS`는 `/projects/:id` 경로만 검사합니다. `/search`, `/users`, `/groups/:id`, `/runners` 같은 엔드포인트는 제한되지 않습니다. `GITLAB_PROJECT_ID`와 OAuth 그룹 허용 목록은 이 도구가 검사하지 않습니다.
+
 - sse
 
+변수 이름만 넘기세요. Docker 클라이언트는 export한 `GITLAB_PERSONAL_ACCESS_TOKEN` 값을 컨테이너로 복사합니다.
+
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \
-  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
+  -e GITLAB_PERSONAL_ACCESS_TOKEN \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
   -e GITLAB_PERMISSION_MODE=readonly \
   -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \

package/README.md

@@ -17,10 +17,16 @@ Install `@zereight/mcp-gitlab` with the recommended local personal-access-token
 
 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`.
 
-| Client       | Install                                                                                                                                                                           |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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` |
-| 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`                                  |
+Read the token without echo, then export it. The shell history keeps the variable name.
+
+```bash
+read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
+```
+
+| Client       | Install                                                                                                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Claude Code  | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
+| Codex        | `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`                                  |
 | Cursor       | [Cursor setup guide](./docs/clients/cursor.md)                                                                                                                                    |
 | VS Code      | [VS Code setup guide](./docs/clients/vscode.md)                                                                                                                                   |
 | JSON clients | [JSON-based MCP clients setup guide](./docs/clients/json-clients.md)                                                                                                              |
@@ -35,7 +41,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
 
 ### Why use this GitLab MCP?
 
-- **274 tools: 272 in toolsets + `execute_graphql` + `discover_tools`** — start with a small toolset; activate more at runtime without CQRS-style grouping
+- **275 tools: 273 in toolsets + `execute_graphql` + `discover_tools`** — start with a small toolset; activate more at runtime without CQRS-style grouping
 - **MR 2-step review** — `list_merge_request_changed_files` → batched `get_merge_request_file_diff`
 - **Agent Skill built in** — workflow guidance in `skills/gitlab-mcp/`
 - **Flexible auth** — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
@@ -49,7 +55,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
 |                | @zereight/mcp-gitlab                                              | GitLab MCP A (community CQRS-style)          | GitLab official MCP server                                                                                                                       |
 | -------------- | ----------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Best for**   | AI agent workflows                                                | Enterprise multi-instance / grouped tools    | Built into GitLab, no separate install                                                                                                           |
-| **Tool model** | 274 tools: 272 in toolsets + `execute_graphql` + `discover_tools` | ~50–60 grouped `browse_*` / `manage_*` tools | Toolsets chosen with an HTTP header                                                                                                              |
+| **Tool model** | 275 tools: 273 in toolsets + `execute_graphql` + `discover_tools` | ~50–60 grouped `browse_*` / `manage_*` tools | Toolsets chosen with an HTTP header                                                                                                              |
 | **MR review**  | 2-step batched diff                                               | Varies                                       | `get_merge_request` with diffs                                                                                                                   |
 | **Node.js**    | >=18.17                                                           | Often >=24                                   | Node.js 20+ for stdio via `mcp-remote`                                                                                                           |
 | **License**    | MIT                                                               | Varies                                       | Part of GitLab                                                                                                                                   |
@@ -89,7 +95,7 @@ The server supports four authentication methods:
 
 **For local/desktop use** (most common):
 
-1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — simplest setup
+1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN` or `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) — simplest setup
 2. **OAuth2 — Local Browser** (`GITLAB_USE_OAUTH`) — recommended for better security
 
 **For server/remote deployments**:
@@ -137,7 +143,7 @@ The store path is pinned by your lock file; update it with `nix flake update git
 
 The examples use `zereight-mcp-gitlab`, a less collision-prone alias for the legacy `mcp-gitlab` binary. If your MCP client cannot find it, use the absolute path from `which zereight-mcp-gitlab`.
 
-No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.2.2`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
+No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.2.4`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
 
 #### Using CLI Arguments (for clients with env var issues)
 
@@ -161,7 +167,7 @@ Some MCP clients (like GitHub Copilot CLI) have issues with environment variable
 - `--api-url` - GitLab API URL (replaces `GITLAB_API_URL`)
 - `--read-only=true` - Deprecated (removed in next major (v3.0.0)); use `--permission-mode=readonly` instead (replaces `GITLAB_READ_ONLY_MODE`)
 - `--permission-mode` - Permission level: `readonly`, `modify` (no delete or teardown tools), or `full` (replaces `GITLAB_PERMISSION_MODE`, default `full`)
-- `--toolsets=all` - Enable named toolsets (replaces `GITLAB_TOOLSETS`; unset uses the lean `core` default)
+- `--toolsets=all` - Enable named toolsets except the explicit-only `api` toolset (replaces `GITLAB_TOOLSETS`; unset uses the lean `core` default). `gitlab_api_request` needs `--toolsets=api`
 - `--tools=list_issues` - Add individual tools (replaces `GITLAB_TOOLS`)
 - `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,wiki` instead (replaces `USE_GITLAB_WIKI`)
 - `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,milestones` instead (replaces `USE_MILESTONE`)
@@ -202,12 +208,18 @@ The same binary is also a `gh`-style GitLab CLI (`tool <name>` or curated forms
 > See [Tools Reference](./docs/tools/index.md#feature-toggles) and
 > [Environment Variables](./docs/configuration/environment-variables.md).
 
+> [!CAUTION]
+> `gitlab_api_request` (toolset `api`) bypasses `GITLAB_ALLOWED_GROUPS` and other group restrictions, project allowlists, tool-level restrictions (`GITLAB_TOOLS`, `GITLAB_DENIED_TOOLS_REGEX` on other tools), and individual tool safety checks. The full token permission scope is exposed. Prompt injection can drive this tool. Operators who rely on these restrictions must NOT enable it.
+> Enable it only by listing `api` in `GITLAB_TOOLSETS` (`GITLAB_TOOLSETS=all`, `discover_tools`, `GITLAB_TOOLS`, legacy `USE_*` flags, and `GITLAB_TOOL_PROFILE` do not). `GITLAB_ALLOWED_PROJECT_IDS` is checked only for `/projects/:id` paths. Endpoints such as `/search`, `/users`, `/groups/:id`, and `/runners` are not constrained. `GITLAB_PROJECT_ID` and OAuth group allowlists are not enforced.
+
 - sse
 
+Pass the variable name only. The Docker client copies the exported `GITLAB_PERSONAL_ACCESS_TOKEN` into the container.
+
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \
-  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
+  -e GITLAB_PERSONAL_ACCESS_TOKEN \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
   -e GITLAB_PERMISSION_MODE=readonly \
   -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
@@ -910,7 +922,8 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
 271. `delete_snippet` - Delete a snippet
 272. `list_project_runners` - List runners available to a project (type, status, paused, tag_list). Omits registration and authentication tokens.
 273. `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.
-274. `discover_tools` - Discover and activate additional tool categories for this session. Available categories: core, merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, snippets, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities, orbit. Already-active categories are listed in the response.
+274. `gitlab_api_request` - Send one GitLab REST call under /api/v4. Enabled only when GITLAB_TOOLSETS lists api. Readonly allows GET; modify rejects DELETE.
+275. `discover_tools` - Discover and activate additional tool categories for this session. Available categories: core, merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, snippets, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities, orbit. Already-active categories are listed in the response.
 
 <!-- TOOLS-END -->
 

package/README.pt-BR.md

@@ -12,10 +12,16 @@ Instalação local recomendada com PAT para `@zereight/mcp-gitlab`. Os argumento
 
 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`.
 
-| Cliente       | Instalação                                                                                                                                                                        |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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` |
-| 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`                                  |
+Leia o token sem eco e exporte. O histórico do shell fica só com o nome da variável.
+
+```bash
+read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
+```
+
+| Cliente       | Instalação                                                                                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Claude Code   | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
+| Codex         | `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`                                  |
 | Cursor        | [Guia de configuração do Cursor](./docs/clients/cursor.md)                                                                                                                        |
 | VS Code       | [Guia de configuração do VS Code](./docs/clients/vscode.md)                                                                                                                       |
 | Clientes JSON | [Guia para clientes MCP baseados em JSON](./docs/clients/json-clients.md)                                                                                                         |
@@ -30,7 +36,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 
 ### Por que usar este GitLab MCP?
 
-- **274 ferramentas: 272 em toolsets + `execute_graphql` + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
+- **275 ferramentas: 273 em toolsets + `execute_graphql` + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
 - **Revisão de MR em 2 etapas** — `list_merge_request_changed_files` → `get_merge_request_file_diff` em lote
 - **Agent Skill integrado** — orientação de workflows em `skills/gitlab-mcp/`
 - **Autenticação flexível** — Personal Access Token, fluxo OAuth2 local no navegador, proxy MCP OAuth e autorização remota por requisição
@@ -44,7 +50,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 |                           | @zereight/mcp-gitlab                                                    | GitLab MCP A (comunidade, estilo CQRS)                    | Servidor MCP oficial do GitLab                                                                                                                                 |
 | ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Mais indicado para**    | Workflows de agentes de IA                                              | Múltiplas instâncias corporativas / ferramentas agrupadas | Integrado ao GitLab, sem instalação separada                                                                                                                   |
-| **Modelo de ferramentas** | 274 ferramentas: 272 em toolsets + `execute_graphql` + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      | Toolsets escolhidos por cabeçalho HTTP                                                                                                                         |
+| **Modelo de ferramentas** | 275 ferramentas: 273 em toolsets + `execute_graphql` + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      | Toolsets escolhidos por cabeçalho HTTP                                                                                                                         |
 | **Revisão de MR**         | Diff em lote em 2 etapas                                                | Varia                                                     | `get_merge_request` com diffs                                                                                                                                  |
 | **Node.js**               | >=18.17                                                                 | Frequentemente >=24                                       | Node.js 20+ para stdio via `mcp-remote`                                                                                                                        |
 | **Licença**               | MIT                                                                     | Varia                                                     | Parte do GitLab                                                                                                                                                |
@@ -84,7 +90,7 @@ O servidor suporta quatro métodos de autenticação.
 
 **Para uso local/desktop** (mais comum):
 
-1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — configuração mais simples
+1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN` ou `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) — configuração mais simples
 2. **OAuth2 — navegador local** (`GITLAB_USE_OAUTH`) — recomendado para maior segurança
 
 **Para implantações em servidor/remotas**:
@@ -132,7 +138,7 @@ O caminho no store é fixado pelo seu lock file; atualize-o com `nix flake updat
 
 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`.
 
-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`).
+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.4`. 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`).
 
 #### Usando argumentos de CLI (para clientes com problemas com variáveis de ambiente)
 
@@ -156,7 +162,7 @@ Alguns clientes MCP, como o GitHub Copilot CLI, têm problemas com variáveis de
 - `--api-url` - URL da API do GitLab (substitui `GITLAB_API_URL`)
 - `--read-only=true` - Deprecated (removed in next major (v3.0.0)); use `--permission-mode=readonly` (substitui `GITLAB_READ_ONLY_MODE`)
 - `--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`)
-- `--toolsets=all` - ativa toolsets nomeados (substitui `GITLAB_TOOLSETS`; sem valor usa o padrão enxuto `core`)
+- `--toolsets=all` - ativa toolsets nomeados, exceto o toolset explícito `api` (substitui `GITLAB_TOOLSETS`; sem valor usa o padrão enxuto `core`). `gitlab_api_request` exige `--toolsets=api`
 - `--tools=list_issues` - adiciona ferramentas individuais (substitui `GITLAB_TOOLS`)
 - `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,wiki` (substitui `USE_GITLAB_WIKI`)
 - `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,milestones` (substitui `USE_MILESTONE`)
@@ -196,12 +202,18 @@ O mesmo binário também é uma CLI do GitLab no estilo `gh` (`tool <name>` ou f
 > Consulte a [Referência de ferramentas](./docs/tools/index.md#feature-toggles) e
 > [Variáveis de ambiente](./docs/configuration/environment-variables.md).
 
+> [!CAUTION]
+> `gitlab_api_request` (toolset `api`) ignora `GITLAB_ALLOWED_GROUPS` e outras restrições de grupo, allowlists de projeto, restrições por ferramenta (`GITLAB_TOOLS`, `GITLAB_DENIED_TOOLS_REGEX` nas outras ferramentas) e as checagens de segurança de cada ferramenta. O escopo completo do token fica exposto. Prompt injection pode acionar esta ferramenta. Operadores que dependem dessas restrições NÃO devem habilitá-la.
+> Ela só liga quando `api` está listado em `GITLAB_TOOLSETS` (`GITLAB_TOOLSETS=all`, `discover_tools`, `GITLAB_TOOLS`, flags legadas `USE_*` e `GITLAB_TOOL_PROFILE` não ligam). `GITLAB_ALLOWED_PROJECT_IDS` vale só para caminhos `/projects/:id`. Endpoints como `/search`, `/users`, `/groups/:id` e `/runners` não são restringidos. `GITLAB_PROJECT_ID` e allowlists de grupo OAuth não são aplicados por esta ferramenta.
+
 - sse
 
+Passe só o nome da variável. O cliente Docker copia o `GITLAB_PERSONAL_ACCESS_TOKEN` exportado para o contêiner.
+
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \
-  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
+  -e GITLAB_PERSONAL_ACCESS_TOKEN \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
   -e GITLAB_PERMISSION_MODE=readonly \
   -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \

package/README.zh-CN.md

@@ -12,10 +12,16 @@
 
 先安装 `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`。
 
-| 客户端      | 安装                                                                                                                                                                              |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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` |
-| 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`                                  |
+先不回显地读取令牌，再 export。shell 历史里只保留变量名。
+
+```bash
+read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
+```
+
+| 客户端      | 安装                                                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
+| Codex       | `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`                                  |
 | Cursor      | [Cursor 设置指南](./docs/clients/cursor.md)                                                                                                                                       |
 | VS Code     | [VS Code 设置指南](./docs/clients/vscode.md)                                                                                                                                      |
 | JSON 客户端 | [基于 JSON 的 MCP 客户端设置指南](./docs/clients/json-clients.md)                                                                                                                 |
@@ -30,7 +36,7 @@
 
 ### 为什么使用这个 GitLab MCP？
 
-- **274 个工具：toolset 中 272 个 + `execute_graphql` + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
+- **275 个工具：toolset 中 273 个 + `execute_graphql` + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
 - **MR 两步审查** — `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff`
 - **内置 Agent Skill** — `skills/gitlab-mcp/` 工作流指南
 - **认证灵活** — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
@@ -44,7 +50,7 @@
 |              | @zereight/mcp-gitlab                                                 | GitLab MCP A（社区 CQRS 型）               | GitLab 官方 MCP 服务器                                                                                                                  |
 | ------------ | -------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
 | **更适合**   | AI 代理工作流                                                        | 企业多实例 / 分组工具                      | 内置于 GitLab，无需单独安装                                                                                                             |
-| **工具模型** | 274 个工具：toolset 中 272 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 | 用 HTTP 头选择 toolset                                                                                                                  |
+| **工具模型** | 275 个工具：toolset 中 273 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 | 用 HTTP 头选择 toolset                                                                                                                  |
 | **MR 审查**  | 两步批量 diff                                                        | 因服务器而异                               | `get_merge_request` 带 diffs                                                                                                            |
 | **Node.js**  | >=18.17                                                              | 通常 >=24                                  | stdio 经 `mcp-remote`，需要 Node.js 20+                                                                                                 |
 | **许可证**   | MIT                                                                  | 因服务器而异                               | GitLab 的一部分                                                                                                                         |
@@ -84,7 +90,7 @@ GitLab 还提供[官方 MCP 服务器](https://docs.gitlab.com/user/model_contex
 
 **本地/桌面使用**（最常见）：
 
-1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — 最简单的设置
+1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN` 或 `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) — 最简单的设置
 2. **OAuth2 — 本地浏览器** (`GITLAB_USE_OAUTH`) — 推荐用于更好的安全性
 
 **服务器/远程部署**：
@@ -132,7 +138,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 
 示例使用 `zereight-mcp-gitlab`，这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它，请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
 
-如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.2.2`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.2.4`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -156,7 +162,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 - `--api-url` - GitLab API URL（替代 `GITLAB_API_URL`）
 - `--read-only=true` - Deprecated (removed in next major (v3.0.0))；请改用 `--permission-mode=readonly`（替代 `GITLAB_READ_ONLY_MODE`）
 - `--permission-mode` - 权限级别：`readonly`、`modify`（禁用删除/拆除工具）或 `full`（替代 `GITLAB_PERMISSION_MODE`，默认 `full`）
-- `--toolsets=all` - 启用指定工具集（替代 `GITLAB_TOOLSETS`；未设置时使用精简 `core` 默认值）
+- `--toolsets=all` - 启用指定工具集，但不包括必须显式列出的 `api`（替代 `GITLAB_TOOLSETS`；未设置时使用精简 `core` 默认值）。`gitlab_api_request` 需要 `--toolsets=api`
 - `--tools=list_issues` - 添加单个工具（替代 `GITLAB_TOOLS`）
 - `--use-wiki=true` - Deprecated (removed in next major (v3.0.0))；请改用 `--toolsets=core,wiki`（替代 `USE_GITLAB_WIKI`）
 - `--use-milestone=true` - Deprecated (removed in next major (v3.0.0))；请改用 `--toolsets=core,milestones`（替代 `USE_MILESTONE`）
@@ -195,12 +201,18 @@ CLI 参数优先于环境变量。
 > 参见 [Tools Reference](./docs/tools/index.md#feature-toggles) 和
 > [Environment Variables](./docs/configuration/environment-variables.md)。
 
+> [!CAUTION]
+> `gitlab_api_request`（`api` 工具集）会绕过 `GITLAB_ALLOWED_GROUPS` 及其他群组限制、项目允许列表、工具级限制（`GITLAB_TOOLS`、作用在其他工具上的 `GITLAB_DENIED_TOOLS_REGEX`）以及各个工具自己的安全检查。令牌的完整权限范围都会暴露。提示注入可以驱动这个工具。依赖这些限制的运维人员不得启用它。
+> 只有在 `GITLAB_TOOLSETS` 中显式写入 `api` 时才会启用（`GITLAB_TOOLSETS=all`、`discover_tools`、`GITLAB_TOOLS`、旧版 `USE_*`、`GITLAB_TOOL_PROFILE` 都不会）。`GITLAB_ALLOWED_PROJECT_IDS` 只检查 `/projects/:id` 路径。`/search`、`/users`、`/groups/:id`、`/runners` 等端点不受约束。`GITLAB_PROJECT_ID` 和 OAuth 群组允许列表不会被此工具强制执行。
+
 - sse
 
+只传变量名。Docker 客户端把已 export 的 `GITLAB_PERSONAL_ACCESS_TOKEN` 复制进容器。
+
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \
-  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
+  -e GITLAB_PERSONAL_ACCESS_TOKEN \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
   -e GITLAB_PERMISSION_MODE=readonly \
   -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \

package/build/cli/exposure.js

@@ -1,6 +1,6 @@
 import { GITLAB_TOOL_POLICY_APPROVE_RAW, GITLAB_TOOL_POLICY_HIDDEN_RAW, GITLAB_TOOLS_RAW, GITLAB_TOOLSETS_RAW, getConfig, } from "../config.js";
 import { compileDeniedToolsRegex } from "../tools/denied-regex.js";
-import { buildFeatureFlagOverrides, isToolInEnabledToolset, parseEnabledToolsets, parseIndividualTools, } from "../tools/registry.js";
+import { buildFeatureFlagOverrides, isExplicitToolsetOnlyTool, isToolInEnabledToolset, parseEnabledToolsets, parseIndividualTools, } from "../tools/registry.js";
 export function parseToolNameSet(raw) {
     if (!raw || raw.trim() === "") {
         return new Set();
@@ -20,6 +20,9 @@ export function isToolExposed(input) {
     if (isToolInEnabledToolset(input.toolName, input.enabledToolsets)) {
         return true;
     }
+    if (isExplicitToolsetOnlyTool(input.toolName)) {
+        return false;
+    }
     if (input.individuallyEnabledTools.has(input.toolName)) {
         return true;
     }
@@ -35,6 +38,9 @@ export function exposureRefusalMessage(input) {
     if (isToolExposed(input)) {
         return undefined;
     }
+    if (isExplicitToolsetOnlyTool(input.toolName)) {
+        return `${input.toolName} is enabled only by listing its toolset in GITLAB_TOOLSETS. GITLAB_TOOLS, GITLAB_TOOLSETS=all, and discover_tools do not enable it.`;
+    }
     return `${input.toolName} is not enabled by GITLAB_TOOLSETS, GITLAB_TOOLS, or legacy wiki/milestone/pipeline flags`;
 }
 export function liveCliExposure() {

package/build/config.js

@@ -1,7 +1,9 @@
 import { parseCliArgs } from "./cli-boolean-flags.js";
 import { deprecatedEnvInputFromSources } from "./deprecated-env.js";
+import { readPersonalAccessTokenFile, resolvePersonalAccessToken, } from "./personal-access-token.js";
 import { parseToolProfile } from "./tools/tool-profile.js";
 import { parseCompactToolAllowlist } from "./utils/compact-tool-allowlist.js";
+import { createLogger, flushStartupLogs } from "./utils/logger.js";
 // Parse CLI arguments before anything else
 export const cliArgs = parseCliArgs(process.argv.slice(2));
 export function getConfig(cliKey, envKey, defaultValue) {
@@ -10,7 +12,19 @@ export function getConfig(cliKey, envKey, defaultValue) {
 // ---------------------------------------------------------------------------
 // Authentication
 // ---------------------------------------------------------------------------
-export const GITLAB_PERSONAL_ACCESS_TOKEN = getConfig("token", "GITLAB_PERSONAL_ACCESS_TOKEN");
+function warnIgnoredPersonalAccessTokenFile(message) {
+    const startupLogger = createLogger();
+    startupLogger.warn(message);
+    flushStartupLogs(startupLogger);
+}
+// Read once at module load. Later auth checks use this constant and do not reopen the file.
+export const GITLAB_PERSONAL_ACCESS_TOKEN = resolvePersonalAccessToken({
+    cliToken: cliArgs.token,
+    envToken: process.env.GITLAB_PERSONAL_ACCESS_TOKEN,
+    filePath: process.env.GITLAB_PERSONAL_ACCESS_TOKEN_FILE,
+    readFile: readPersonalAccessTokenFile,
+    warn: warnIgnoredPersonalAccessTokenFile,
+});
 export const GITLAB_JOB_TOKEN = getConfig("job-token", "GITLAB_JOB_TOKEN");
 export const GITLAB_AUTH_COOKIE_PATH = getConfig("cookie-path", "GITLAB_AUTH_COOKIE_PATH");
 export const USE_OAUTH = getConfig("use-oauth", "GITLAB_USE_OAUTH") === "true";

package/build/index.js

@@ -109,7 +109,8 @@ import { appendFilterParam, appendFilterParams, cleanMutuallyExclusiveIdUsername
 import { applyJmespathToToolResult, getJmespathSyntaxError, JMESPATH_TOOL_ARGUMENT, JMESPATH_TOOL_ARGUMENT_DESCRIPTION, omitJmespathArgument, readJmespathExpression, } from "./utils/jmespath-tool-result.js";
 import { parseSearchReplaceBlocks, applySearchReplace, applyUnifiedDiff, } from "./utils/patch-helper.js";
 import { GitLabClientPool } from "./gitlab-client-pool.js";
-import { advertisesReadOnly, allTools, readOnlyTools, destructiveTools, deleteTools, parseEnabledToolsets, parseIndividualTools, buildFeatureFlagOverrides, isToolInEnabledToolset, findSmallestToolsetForTool, isToolsetFullyActive, listDiscoverableCategories, TOOLSET_DEFINITIONS, ALL_TOOLSET_IDS, } from "./tools/registry.js";
+import { advertisesReadOnly, allTools, readOnlyTools, destructiveTools, deleteTools, parseEnabledToolsets, parseIndividualTools, buildFeatureFlagOverrides, isToolInEnabledToolset, findSmallestToolsetForTool, isExplicitOnlyToolsetId, isExplicitToolsetOnlyTool, isToolsetFullyActive, listDiscoverableCategories, TOOLSET_DEFINITIONS, DISCOVERABLE_TOOLSET_IDS, } from "./tools/registry.js";
+import { executeGitLabApiRequestAsync, GitLabApiRequestHttpError, GitLabApiRequestInputError, } from "./tools/gitlab-api-request.js";
 import { buildUnavailableToolMessage, isSkippedByDiscoverActivation, } from "./tools/discover-activation.js";
 import { selectExposedTools } from "./tools/exposed-tools.js";
 import { createListedToolsCache, decorateToolsForList, } from "./tools/listed-tools.js";
@@ -192,12 +193,14 @@ const MCP_PROMPTS = [
  * Regex-denied tools stay blocked, and slim-excluded tools are not activated.
  */
 function buildToolUnavailableMessage(toolName) {
+    const toolset = findSmallestToolsetForTool(toolName);
     return buildUnavailableToolMessage({
         toolName,
-        toolset: findSmallestToolsetForTool(toolName),
+        toolset,
         deniedByRegex: GITLAB_DENIED_TOOLS_REGEX?.test(toolName) === true,
         excludedBySlimProfile: isExcludedFromToolsetListing(toolName),
         enabledByCurrentToolsets: isToolInEnabledToolset(toolName, enabledToolsets),
+        explicitToolsetOnly: toolset !== undefined && isExplicitOnlyToolsetId(toolset),
     });
 }
 /**
@@ -216,6 +219,7 @@ function createServer() {
         deniedToolsRegex: GITLAB_DENIED_TOOLS_REGEX,
         hiddenToolNames: hiddenToolSet,
         applySlimProfile,
+        isAdditiveEnablementAllowed: toolName => !isExplicitToolsetOnlyTool(toolName),
     });
     const listedToolDecoration = {
         readOnlyToolNames: new Set([...readOnlyTools].filter(toolName => advertisesReadOnly(toolName))),
@@ -402,12 +406,29 @@ function createServer() {
                         ],
                     });
                 }
-                if (!ALL_TOOLSET_IDS.has(category)) {
+                if (isExplicitOnlyToolsetId(category)) {
                     return logCompletion({
                         content: [
                             {
                                 type: "text",
-                                text: `Unknown category "${category}". Available: ${[...ALL_TOOLSET_IDS].join(", ")}`,
+                                text: `Category "${category}" cannot be activated with discover_tools. Add "${category}" to GITLAB_TOOLSETS. GITLAB_TOOLSETS=all does not enable it.`,
+                            },
+                        ],
+                        isError: true,
+                    });
+                }
+                let discoverableCategory = false;
+                for (const id of DISCOVERABLE_TOOLSET_IDS) {
+                    if (id === category) {
+                        discoverableCategory = true;
+                    }
+                }
+                if (!discoverableCategory) {
+                    return logCompletion({
+                        content: [
+                            {
+                                type: "text",
+                                text: `Unknown category "${category}". Available: ${[...DISCOVERABLE_TOOLSET_IDS].join(", ")}`,
                             },
                         ],
                         isError: true,
@@ -743,7 +764,8 @@ function validateConfiguration() {
     // Validate auth configuration
     const remoteAuth = getConfig("remote-auth", "REMOTE_AUTHORIZATION") === "true";
     const useOAuth = getConfig("use-oauth", "GITLAB_USE_OAUTH") === "true";
-    const hasToken = !!getConfig("token", "GITLAB_PERSONAL_ACCESS_TOKEN");
+    // getConfig() would ignore GITLAB_PERSONAL_ACCESS_TOKEN_FILE.
+    const hasToken = !!GITLAB_PERSONAL_ACCESS_TOKEN;
     const hasJobToken = !!getConfig("job-token", "GITLAB_JOB_TOKEN");
     const hasCookie = !!getConfig("cookie-path", "GITLAB_AUTH_COOKIE_PATH");
     const mcpOAuth = getConfig("mcp-oauth", "GITLAB_MCP_OAUTH") === "true";
@@ -1238,6 +1260,15 @@ if (GITLAB_TOOLSETS_RAW && (USE_PIPELINE || USE_MILESTONE || USE_GITLAB_WIKI)) {
     logger.warn("GITLAB_TOOLSETS is set alongside legacy flags (USE_PIPELINE, USE_MILESTONE, USE_GITLAB_WIKI). " +
         "Legacy flags add tools additively on top of the toolset selection and may produce unexpected results.");
 }
+if (enabledToolsets.has("api")) {
+    logger.warn("gitlab_api_request is enabled because GITLAB_TOOLSETS lists api. " +
+        "This tool can bypass tool allowlists (GITLAB_TOOLS, GITLAB_TOOLSETS selection, GITLAB_DENIED_TOOLS_REGEX for other tools), " +
+        "group and project restrictions, and per-tool safety checks. It exposes the full token scope.");
+}
+const ignoredExplicitTools = [...individuallyEnabledTools].filter(name => isExplicitToolsetOnlyTool(name) && !isToolInEnabledToolset(name, enabledToolsets));
+if (ignoredExplicitTools.length > 0) {
+    logger.warn(`GITLAB_TOOLS names ${ignoredExplicitTools.join(", ")}, but that tool is enabled only when its toolset is listed in GITLAB_TOOLSETS. The GITLAB_TOOLS entry is ignored.`);
+}
 const MERGE_REQUEST_DEPLOYMENT_SUMMARY_LIMIT = 10;
 function toAllowedGitLabApiUrl(value) {
     const trimmed = value.trim();
@@ -8091,6 +8122,29 @@ async function handleToolCall(params) {
                     clearTimeout(timeout);
                 }
             }
+            case "gitlab_api_request": {
+                try {
+                    return await executeGitLabApiRequestAsync({
+                        args: params.arguments,
+                        apiBaseUrl: getEffectiveApiUrl(),
+                        permissionMode: GITLAB_PERMISSION_MODE,
+                        allowedProjectIds: getEffectiveAllowedProjectIds(),
+                        fetchImpl: fetch,
+                        unauthenticatedFetchImpl: undiciFetch,
+                        isTrustedRedirectHost: isTrustedGitLabRedirectHost,
+                        fetchConfig: getFetchConfig,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof GitLabApiRequestInputError) {
+                        throw new ToolInputError(error.message);
+                    }
+                    if (error instanceof GitLabApiRequestHttpError) {
+                        throw new GitLabApiError(error.message);
+                    }
+                    throw error;
+                }
+            }
             case "fork_repository": {
                 rejectIfProjectScopedDeployment("fork_repository");
                 const forkArgs = ForkRepositorySchema.parse(params.arguments);

package/build/personal-access-token.js

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+const EMPTY_FILE_CODE = "EMPTY";
+export class PersonalAccessTokenFileError extends Error {
+    code;
+    filePath;
+    constructor(filePath, code) {
+        super(`Cannot load GITLAB_PERSONAL_ACCESS_TOKEN_FILE at ${filePath} (${code})`);
+        this.name = "PersonalAccessTokenFileError";
+        this.filePath = filePath;
+        this.code = code;
+    }
+}
+function presentInlineToken(value) {
+    if (value === undefined || value.length === 0) {
+        return undefined;
+    }
+    return value;
+}
+function configuredFilePath(filePath) {
+    if (filePath === undefined) {
+        return undefined;
+    }
+    const trimmed = filePath.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    return trimmed;
+}
+function errnoCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return "EIO";
+    }
+    const code = error.code;
+    if (typeof code !== "string" || code.length === 0) {
+        return "EIO";
+    }
+    return code;
+}
+export function readPersonalAccessTokenFile(filePath) {
+    return readFileSync(filePath, { encoding: "utf8" });
+}
+function ignoredFileWarning(filePath) {
+    return `Ignoring GITLAB_PERSONAL_ACCESS_TOKEN_FILE at ${filePath} because an inline personal access token is set`;
+}
+function readTokenFile(source, filePath) {
+    try {
+        return source.readFile(filePath);
+    }
+    catch (error) {
+        throw new PersonalAccessTokenFileError(filePath, errnoCode(error));
+    }
+}
+/**
+ * Resolve the personal access token once.
+ * `--token` wins, then a non-empty GITLAB_PERSONAL_ACCESS_TOKEN, then the file.
+ * Job tokens, OAuth, cookies, and remote authorization are not inputs.
+ */
+export function resolvePersonalAccessToken(source) {
+    const inline = presentInlineToken(source.cliToken) ?? presentInlineToken(source.envToken);
+    const filePath = configuredFilePath(source.filePath);
+    if (inline !== undefined) {
+        if (filePath !== undefined) {
+            source.warn(ignoredFileWarning(filePath));
+        }
+        return inline;
+    }
+    if (filePath === undefined) {
+        return undefined;
+    }
+    const token = readTokenFile(source, filePath).trim();
+    if (token.length === 0) {
+        throw new PersonalAccessTokenFileError(filePath, EMPTY_FILE_CODE);
+    }
+    return token;
+}

package/build/tools/discover-activation.js

@@ -27,6 +27,9 @@ export function buildUnavailableToolMessage(input) {
     if (input.excludedBySlimProfile) {
         return `${base}. ${slimExclusionGuidance(input.toolName, toolset, input.enabledByCurrentToolsets)}`;
     }
+    if (input.explicitToolsetOnly) {
+        return `${base}. The "${toolset}" toolset is not enabled. discover_tools cannot activate it. Add "${toolset}" to GITLAB_TOOLSETS. GITLAB_TOOLSETS=all, GITLAB_TOOLS, and GITLAB_TOOL_PROFILE do not enable it.`;
+    }
     return `${base}. It belongs to the "${toolset}" toolset, which is not enabled: call discover_tools with category "${toolset}" or add "${toolset}" to GITLAB_TOOLSETS.`;
 }
 function slimExclusionGuidance(toolName, toolset, enabledByCurrentToolsets) {

package/build/tools/exposed-tools.js

@@ -1,15 +1,20 @@
 import { isExcludedBySlimProfile } from "./tool-profile.js";
 export function selectExposedTools(input) {
+    const additiveAllowed = input.isAdditiveEnablementAllowed ?? (() => true);
     const toolsAfterToolsets = input.tools.filter(tool => input.isInEnabledToolset(tool.name));
     const toolsetToolNames = new Set(toolsAfterToolsets.map(tool => tool.name));
     const toolsAfterIndividual = [
         ...toolsAfterToolsets,
-        ...input.tools.filter(tool => input.individuallyEnabledTools.has(tool.name) && !toolsetToolNames.has(tool.name)),
+        ...input.tools.filter(tool => input.individuallyEnabledTools.has(tool.name) &&
+            !toolsetToolNames.has(tool.name) &&
+            additiveAllowed(tool.name)),
     ];
     const afterIndividualNames = new Set(toolsAfterIndividual.map(tool => tool.name));
     const toolsAfterLegacy = [
         ...toolsAfterIndividual,
-        ...input.tools.filter(tool => input.featureFlagOverrides.has(tool.name) && !afterIndividualNames.has(tool.name)),
+        ...input.tools.filter(tool => input.featureFlagOverrides.has(tool.name) &&
+            !afterIndividualNames.has(tool.name) &&
+            additiveAllowed(tool.name)),
     ];
     const toolsAfterPermission = toolsAfterLegacy.filter(tool => input.isAllowedByPermissionMode(tool.name));
     const deniedToolsRegex = input.deniedToolsRegex;

package/build/tools/gitlab-api-request.js

@@ -0,0 +1,256 @@
+import { z } from "zod";
+import { redactSensitiveGitLabFields, redactSensitiveGitLabText, } from "../utils/redact-sensitive.js";
+import { fetchWithValidatedRedirects, UnsafeRedirectError, } from "../utils/safe-redirect-fetch.js";
+import { normalizeGitLabApiRelativePath, readProjectIdFromApiRelativePath, resolveGitLabApiRequestUrl, } from "../utils/url.js";
+/**
+ * Methods this tool will send. HEAD is omitted: callers do not need it, and
+ * a smaller allowlist is easier to gate. DELETE stays in the schema so
+ * `modify` can reject it at call time instead of hiding the whole tool.
+ */
+export const GITLAB_API_REQUEST_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+const QUERY_SCALAR = z.union([z.string(), z.number(), z.boolean()]);
+export const GitLabApiRequestSchema = z.object({
+    method: z
+        .enum(GITLAB_API_REQUEST_METHODS)
+        .optional()
+        .describe("HTTP method. Defaults to GET. Non-GET requires a permission mode that allows writes. DELETE is rejected in modify mode."),
+    path: z
+        .string()
+        .min(1)
+        .describe("Path relative to /api/v4, such as projects/1 or /projects/1/issues. Absolute URLs are rejected."),
+    query: z
+        .record(z.string(), z.union([QUERY_SCALAR, z.array(QUERY_SCALAR)]))
+        .optional()
+        .describe("Query string parameters. Arrays are repeated as separate keys."),
+    body: z
+        .unknown()
+        .optional()
+        .describe("JSON request body for POST, PUT, PATCH, and DELETE. Rejected on GET."),
+});
+export class GitLabApiRequestInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitLabApiRequestInputError";
+    }
+}
+export class GitLabApiRequestHttpError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitLabApiRequestHttpError";
+    }
+}
+const REQUEST_TIMEOUT_MS = 45_000;
+export function assertGitLabApiRequestMethodAllowed(method, permissionMode) {
+    if (method === "GET") {
+        return;
+    }
+    if (permissionMode === "readonly") {
+        throw new GitLabApiRequestInputError("gitlab_api_request allows only GET when GITLAB_READ_ONLY_MODE=true or GITLAB_PERMISSION_MODE=readonly");
+    }
+    if (permissionMode === "modify" && method === "DELETE") {
+        throw new GitLabApiRequestInputError("gitlab_api_request rejects DELETE when GITLAB_PERMISSION_MODE=modify (delete operations are disabled)");
+    }
+}
+function assertBodyAllowed(method, body) {
+    if (method === "GET" && body !== undefined) {
+        throw new GitLabApiRequestInputError("gitlab_api_request rejects a body on GET");
+    }
+}
+function projectAllowed(projectId, rawSegment, allowlist) {
+    const candidates = new Set([projectId, rawSegment]);
+    for (const entry of allowlist) {
+        if (candidates.has(entry)) {
+            return true;
+        }
+        try {
+            if (candidates.has(decodeURIComponent(entry))) {
+                return true;
+            }
+        }
+        catch {
+            // An undecodable allowlist entry cannot match this path.
+        }
+    }
+    return false;
+}
+function apiRelativePathFromRedirect(apiBaseUrl, target, trustedAlternateHost) {
+    const base = new URL(apiBaseUrl.endsWith("/") ? apiBaseUrl : `${apiBaseUrl}/`);
+    if (target.origin !== base.origin && !trustedAlternateHost) {
+        return undefined;
+    }
+    const basePrefix = base.pathname.endsWith("/") ? base.pathname : `${base.pathname}/`;
+    if (!target.pathname.startsWith(basePrefix)) {
+        return undefined;
+    }
+    return target.pathname.slice(basePrefix.length);
+}
+function assertRedirectedApiPathAllowed(apiBaseUrl, allowlist, target, trustedAlternateHost) {
+    const relative = apiRelativePathFromRedirect(apiBaseUrl, target, trustedAlternateHost);
+    const apiBase = new URL(apiBaseUrl.endsWith("/") ? apiBaseUrl : `${apiBaseUrl}/`);
+    // Same-origin hops and trusted alternate hosts keep credential headers. A path
+    // outside the API base must be refused before the allowlist short-circuit,
+    // including when the allowlist is empty.
+    if (relative === undefined && (target.origin === apiBase.origin || trustedAlternateHost)) {
+        throw new GitLabApiRequestInputError("Redirect target must remain under the GitLab API base path");
+    }
+    if (allowlist.length === 0) {
+        return;
+    }
+    if (relative === undefined || relative.length === 0) {
+        return;
+    }
+    let normalized;
+    try {
+        normalized = normalizeGitLabApiRelativePath(relative);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GitLabApiRequestInputError(message);
+    }
+    assertProjectAllowlist(normalized, allowlist);
+}
+function assertProjectAllowlist(relativePath, allowlist) {
+    if (allowlist.length === 0) {
+        return;
+    }
+    let projectId;
+    try {
+        projectId = readProjectIdFromApiRelativePath(relativePath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GitLabApiRequestInputError(message);
+    }
+    if (projectId === undefined) {
+        return;
+    }
+    const rawSegment = relativePath.split("/")[1] ?? projectId;
+    if (!projectAllowed(projectId, rawSegment, allowlist)) {
+        throw new GitLabApiRequestInputError(`Access denied: Project ${projectId} is not in the allowed project list: ${allowlist.join(", ")}`);
+    }
+}
+function isHeaderList(headers) {
+    return !Array.isArray(headers) && "forEach" in headers && typeof headers.forEach === "function";
+}
+function headerRecord(headers) {
+    if (!headers) {
+        return {};
+    }
+    if (Array.isArray(headers)) {
+        const record = {};
+        for (const [name, value] of headers) {
+            if (typeof value === "string") {
+                record[name] = value;
+            }
+        }
+        return record;
+    }
+    if (isHeaderList(headers)) {
+        const record = {};
+        headers.forEach((value, key) => {
+            record[key] = value;
+        });
+        return record;
+    }
+    const record = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === "string") {
+            record[key] = value;
+        }
+    }
+    return record;
+}
+function appendQuery(url, query) {
+    if (!query) {
+        return;
+    }
+    for (const [key, value] of Object.entries(query)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                url.searchParams.append(key, String(item));
+            }
+            continue;
+        }
+        url.searchParams.append(key, String(value));
+    }
+}
+function formatHttpError(status, statusText, rawBody) {
+    const trimmed = rawBody.trim();
+    if (trimmed.length === 0) {
+        return `GitLab API error: ${status} ${statusText}`;
+    }
+    try {
+        const parsed = JSON.parse(rawBody);
+        redactSensitiveGitLabFields(parsed);
+        return `GitLab API error: ${status} ${statusText}\n${JSON.stringify(parsed)}`;
+    }
+    catch {
+        return `GitLab API error: ${status} ${statusText}\n${redactSensitiveGitLabText(rawBody)}`;
+    }
+}
+function formatSuccessBody(rawBody) {
+    const trimmed = rawBody.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    try {
+        const parsed = JSON.parse(rawBody);
+        redactSensitiveGitLabFields(parsed);
+        return JSON.stringify(parsed, null, 2);
+    }
+    catch {
+        return redactSensitiveGitLabText(rawBody);
+    }
+}
+export async function executeGitLabApiRequestAsync(input) {
+    const args = GitLabApiRequestSchema.parse(input.args);
+    const method = args.method ?? "GET";
+    assertGitLabApiRequestMethodAllowed(method, input.permissionMode);
+    assertBodyAllowed(method, args.body);
+    let url;
+    let relative;
+    try {
+        relative = normalizeGitLabApiRelativePath(args.path);
+        url = resolveGitLabApiRequestUrl(input.apiBaseUrl, args.path);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GitLabApiRequestInputError(message);
+    }
+    assertProjectAllowlist(relative, input.allowedProjectIds);
+    appendQuery(url, args.query);
+    const config = input.fetchConfig();
+    const headers = headerRecord(config.headers);
+    const body = method === "GET" || args.body === undefined ? undefined : JSON.stringify(args.body);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetchWithValidatedRedirects(url.toString(), {
+            headers,
+            dispatcher: config.dispatcher,
+            signal: controller.signal,
+            method,
+            ...(body === undefined ? {} : { body }),
+            fetchImpl: input.fetchImpl,
+            unauthenticatedFetchImpl: input.unauthenticatedFetchImpl,
+            isTrustedRedirectHost: input.isTrustedRedirectHost,
+            validateRedirectTarget: target => {
+                assertRedirectedApiPathAllowed(input.apiBaseUrl, input.allowedProjectIds, target, input.isTrustedRedirectHost?.(target.host) === true);
+            },
+        });
+        const rawBody = await response.text();
+        if (!response.ok) {
+            throw new GitLabApiRequestHttpError(formatHttpError(response.status, response.statusText, rawBody));
+        }
+        return { content: [{ type: "text", text: formatSuccessBody(rawBody) }] };
+    }
+    catch (error) {
+        if (error instanceof UnsafeRedirectError) {
+            throw new GitLabApiRequestHttpError(error.message);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/build/tools/registry.js

@@ -2,6 +2,7 @@ import { toJSONSchema } from "../utils/schema.js";
 import { USE_GITLAB_WIKI, USE_MILESTONE, USE_PIPELINE, SSE, STREAMABLE_HTTP } from "../config.js";
 import { getToolDescription } from "./tool-descriptions.js";
 import { ApproveMergeRequestSchema, BulkPublishDraftNotesSchema, CancelPipelineJobSchema, ErasePipelineJobSchema, CancelPipelineSchema, ConvertWorkItemTypeSchema, CreateBranchSchema, CreateDraftNoteSchema, CreateGroupSchema, CreateGroupWikiPageSchema, CreateIssueLinkSchema, CreateIssueNoteSchema, CreateIssueSchema, CreateIssueEmojiReactionSchema, CreateIssueNoteEmojiReactionSchema, ListIssueEmojiReactionsSchema, ListIssueNoteEmojiReactionsSchema, CreateLabelSchema, MarkAllTodosDoneSchema, ListTodosSchema, MarkTodoDoneSchema, CreateMergeRequestDiscussionNoteSchema, CreateMergeRequestEmojiReactionSchema, ListMergeRequestEmojiReactionsSchema, ListMergeRequestNoteEmojiReactionsSchema, CreateMergeRequestNoteSchema, CreateMergeRequestNoteEmojiReactionSchema, CreateMergeRequestSchema, CreateMergeRequestThreadSchema, CreateNoteSchema, CreateCommitStatusSchema, CreateOrUpdateFileSchema, CreatePipelineSchema, CreateProjectMilestoneSchema, CreateGroupMilestoneSchema, CreateReleaseEvidenceSchema, CreateReleaseSchema, CreateRepositorySchema, CreateTagSchema, CreateTimelineEventSchema, CreateWebhookSchema, CreateWikiPageSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, CreateWorkItemSchema, DeleteBranchSchema, GetProtectedBranchSchema, ListProtectedBranchesSchema, ProtectBranchSchema, ProtectTagSchema, UnprotectBranchSchema, UnprotectTagSchema, UpdateDefaultBranchSchema, DeleteDraftNoteSchema, DeleteGroupMilestoneSchema, DeleteGroupWikiPageSchema, DeleteIssueLinkSchema, DeleteIssueSchema, DeleteIssueEmojiReactionSchema, DeleteIssueNoteEmojiReactionSchema, DeleteLabelSchema, DeleteMergeRequestDiscussionNoteSchema, DeleteMergeRequestNoteSchema, DeleteMergeRequestEmojiReactionSchema, DeleteMergeRequestNoteEmojiReactionSchema, DeleteProjectMilestoneSchema, DeleteReleaseSchema, DeleteTagSchema, DeleteWebhookSchema, DeleteWikiPageSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, DownloadAttachmentSchema, DownloadAttachmentRemoteSchema, DownloadJobArtifactsSchema, DownloadJobArtifactsRemoteSchema, DownloadReleaseAssetSchema, EditProjectMilestoneSchema, EditGroupMilestoneSchema, ExecuteGraphQLSchema, ForkRepositorySchema, HealthCheckSchema, GetBranchSchema, GetBranchDiffsSchema, GetCommitDiffSchema, GetCommitSchema, GetFileBlameSchema, GetDeploymentSchema, CreateDeploymentSchema, UpdateDeploymentSchema, DeploymentApprovalSchema, ListDeploymentMergeRequestsSchema, GetDraftNoteSchema, GetEnvironmentSchema, UpdateEnvironmentSchema, StopEnvironmentSchema, StopStaleEnvironmentsSchema, DeleteReviewAppEnvironmentsSchema, PipelineTriggerIdSchema, ListPipelineTriggersSchema, CreatePipelineTriggerSchema, UpdatePipelineTriggerSchema, TriggerPipelineSchema, GetFileContentsSchema, GetGroupWikiPageSchema, GetIssueLinkSchema, GetIssueSchema, GetJobArtifactFileSchema, GetLabelSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GetMergeRequestDiffsSchema, GetMergeRequestFileDiffSchema, GetMergeRequestDiscussionSchema, GetMergeRequestNoteSchema, GetMergeRequestNotesSchema, GetMergeRequestSchema, GetMergeRequestVersionSchema, GetMilestoneBurndownEventsSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, GetGroupMilestoneSchema, GetGroupMilestoneIssuesSchema, GetGroupMilestoneMergeRequestsSchema, GetGroupMilestoneBurndownEventsSchema, GetNamespaceSchema, GetPipelineJobOutputSchema, PipelineJobControlSchema, GetPipelineSchema, GetRunnerSchema, GetPipelineVariablesSchema, UpdatePipelineMetadataSchema, DeletePipelineSchema, PipelineReportSchema, WaitForPipelineSchema, WaitForPipelineJobSchema, PlayPipelineJobsSchema, GetProjectEventsSchema, GetProjectMilestoneSchema, GetProjectSchema, GetReleaseSchema, GetRepositoryTreeSchema, GetTagSchema, GetTagSignatureSchema, GetProtectedTagSchema, GetTimelineEventsSchema, GetUsersSchema, GetUserSchema, WhoAmISchema, GetWebhookEventSchema, GetWikiPageSchema, GetWorkItemSchema, ListBranchesSchema, ListCommitsSchema, ListCommitStatusesSchema, ListCustomFieldDefinitionsSchema, ListDeploymentsSchema, ListDraftNotesSchema, ListEnvironmentsSchema, ListEventsSchema, ListGroupIterationsSchema, ListGroupMilestonesSchema, ListGroupProjectsSchema, ListGroupWikiPagesSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListJobArtifactsSchema, ListLabelsSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiffsSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestVersionsSchema, ListMergeRequestsSchema, ListGroupMergeRequestsSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListCiCatalogResourcesSchema, GetCiCatalogResourceSchema, ListPipelinesSchema, ListPipelineSchedulesSchema, GetPipelineScheduleSchema, ListPipelineSchedulePipelinesSchema, CreatePipelineScheduleSchema, UpdatePipelineScheduleSchema, DeletePipelineScheduleSchema, PlayPipelineScheduleSchema, TakeOwnershipPipelineScheduleSchema, GetPipelineScheduleVariableSchema, CreatePipelineScheduleVariableSchema, UpdatePipelineScheduleVariableSchema, DeletePipelineScheduleVariableSchema, ListGroupMembersSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListProjectRunnersSchema, ListReleasesSchema, ListTagsSchema, ListProtectedTagsSchema, ListWebhookEventsSchema, ListWebhooksSchema, ListWikiPagesSchema, ListWorkItemNotesSchema, ListWorkItemStatusesSchema, ListWorkItemsSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, MergeMergeRequestSchema, MoveWorkItemSchema, MyIssuesSchema, OrbitQuerySchema, OrbitSchemaSchema, OrbitStatusSchema, OrbitToolsSchema, PlayPipelineJobSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PushFilesSchema, ResolveMergeRequestThreadSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, ListSnippetsSchema, GetSnippetSchema, CreateSnippetSchema, UpdateSnippetSchema, DeleteSnippetSchema, UnapproveMergeRequestSchema, UpdateDraftNoteSchema, UpdateGroupWikiPageSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateProjectSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestSchema, UpdateReleaseSchema, UpdateWebhookSchema, UpdateWikiPageSchema, UpdateWorkItemSchema, VerifyNamespaceSchema, ListProjectVariablesSchema, GetProjectVariableSchema, CreateProjectVariableSchema, UpdateProjectVariableSchema, DeleteProjectVariableSchema, ListGroupVariablesSchema, GetGroupVariableSchema, CreateGroupVariableSchema, UpdateGroupVariableSchema, DeleteGroupVariableSchema, GetDependencyProxySettingsSchema, UpdateDependencyProxySettingsSchema, ListDependencyProxyBlobsSchema, PurgeDependencyProxyCacheSchema, ListProjectVulnerabilitiesSchema, GetVulnerabilitySchema, DismissVulnerabilitySchema, ConfirmVulnerabilitySchema, } from "../schemas.js";
+import { GitLabApiRequestSchema } from "./gitlab-api-request.js";
 const IS_REMOTE = SSE || STREAMABLE_HTTP;
 // Define all available tools
 export const allTools = [
@@ -1396,6 +1397,12 @@ export const allTools = [
         description: "Get one runner by ID",
         inputSchema: toJSONSchema(GetRunnerSchema),
     },
+    // --- Explicit opt-in raw API. Not in `all` and not activatable via discover_tools. ---
+    {
+        name: "gitlab_api_request",
+        description: "DANGER: bypasses group and project restrictions, tool allowlists (GITLAB_TOOLS and GITLAB_DENIED_TOOLS_REGEX on other tools), and individual tool safety checks. The full token scope is exposed.",
+        inputSchema: toJSONSchema(GitLabApiRequestSchema),
+    },
     // --- Meta tool: Dynamic tool discovery ---
     {
         name: "discover_tools",
@@ -1420,6 +1427,8 @@ export const readOnlyTools = new Set([
     "search_project_code",
     "search_group_code",
     "execute_graphql",
+    // Mixed-access: listed in readonly so GET still works. Writes are rejected in the handler.
+    "gitlab_api_request",
     "get_file_contents",
     "get_merge_request",
     "get_merge_request_diffs",
@@ -1560,7 +1569,7 @@ export const readOnlyTools = new Set([
 ]);
 // Stays in readOnlyTools so readonly mode can still run queries, but mutations
 // are allowed in other permission modes and rejected only at call time.
-const MIXED_ACCESS_TOOLS = new Set(["execute_graphql"]);
+const MIXED_ACCESS_TOOLS = new Set(["execute_graphql", "gitlab_api_request"]);
 export function advertisesReadOnly(toolName) {
     return readOnlyTools.has(toolName) && !MIXED_ACCESS_TOOLS.has(toolName);
 }
@@ -1611,6 +1620,9 @@ export const destructiveTools = new Set([
     "delete_pipeline_schedule",
     "delete_pipeline_schedule_variable",
     "purge_dependency_proxy_cache",
+    // Can DELETE (and other writes). Hint is true; modify mode still lists the tool and
+    // the handler rejects DELETE. Putting it in deleteTools would hide GET/POST too.
+    "gitlab_api_request",
 ]);
 // Tools blocked in "modify" permission mode: permanent deletions plus destructive
 // teardown verbs that do not start with `delete_` (see the comment inside).
@@ -2189,6 +2201,12 @@ export const TOOLSET_DEFINITIONS = [
         isDefault: false,
         tools: new Set(["orbit_query", "orbit_get_schema", "orbit_get_status", "orbit_list_tools"]),
     },
+    {
+        id: "api",
+        isDefault: false,
+        explicitOnly: true,
+        tools: new Set(["gitlab_api_request"]),
+    },
 ];
 // Derived lookup: tool name → toolset IDs. Most tools belong to one category.
 // The default `core` toolset intentionally overlaps with the full opt-in
@@ -2204,6 +2222,24 @@ for (const def of TOOLSET_DEFINITIONS) {
 }
 export const DEFAULT_TOOLSET_IDS = new Set(TOOLSET_DEFINITIONS.filter(d => d.isDefault).map(d => d.id));
 export const ALL_TOOLSET_IDS = new Set(TOOLSET_DEFINITIONS.map(d => d.id));
+/** Toolsets `GITLAB_TOOLSETS=all` and `discover_tools` may enable. Excludes explicitOnly. */
+export const DISCOVERABLE_TOOLSET_IDS = new Set(TOOLSET_DEFINITIONS.filter(definition => definition.explicitOnly !== true).map(definition => definition.id));
+export function isExplicitOnlyToolsetId(id) {
+    return TOOLSET_DEFINITIONS.some(definition => definition.id === id && definition.explicitOnly === true);
+}
+/** True when every toolset that contains the tool is explicit-only. */
+export function isExplicitToolsetOnlyTool(toolName) {
+    const toolsetIds = TOOLSETS_BY_TOOL_NAME.get(toolName);
+    if (toolsetIds === undefined || toolsetIds.size === 0) {
+        return false;
+    }
+    for (const toolsetId of toolsetIds) {
+        if (!isExplicitOnlyToolsetId(toolsetId)) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * Smallest toolset containing the tool, i.e. the cheapest category to activate for it.
  * Returns undefined for tools outside every toolset (e.g. `execute_graphql`) and unknown names.
@@ -2216,7 +2252,7 @@ export function findSmallestToolsetForTool(toolName) {
 // Update discover_tools description with all known categories (must be after TOOLSET_DEFINITIONS)
 const discoverTool = allTools.find(t => t.name === "discover_tools");
 if (discoverTool) {
-    discoverTool.description = `Discover and activate additional tool categories for this session. Available categories: ${[...ALL_TOOLSET_IDS].join(", ")}. Already-active categories are listed in the response.`;
+    discoverTool.description = `Discover and activate additional tool categories for this session. Available categories: ${[...DISCOVERABLE_TOOLSET_IDS].join(", ")}. Already-active categories are listed in the response. Explicit-only toolsets are omitted; list them in GITLAB_TOOLSETS.`;
 }
 for (const tool of allTools) {
     tool.description = getToolDescription(tool.name, tool.description, readOnlyTools.has(tool.name), destructiveTools.has(tool.name));
@@ -2227,7 +2263,7 @@ export function parseEnabledToolsets(raw) {
     }
     const trimmed = raw.trim().toLowerCase();
     if (trimmed === "all") {
-        return ALL_TOOLSET_IDS;
+        return DISCOVERABLE_TOOLSET_IDS;
     }
     const selected = new Set(trimmed
         .split(",")
@@ -2299,7 +2335,7 @@ export function isToolsetFullyActive(tools, currentToolNames, isExcluded) {
 }
 /** Category listing returned by `discover_tools` when no category argument is given. */
 export function listDiscoverableCategories(currentToolNames, isExcluded) {
-    return TOOLSET_DEFINITIONS.map(def => ({
+    return TOOLSET_DEFINITIONS.filter(def => def.explicitOnly !== true).map(def => ({
         id: def.id,
         toolCount: def.tools.size,
         active: isToolsetFullyActive(def.tools, currentToolNames, isExcluded),

package/build/tools/tool-descriptions.js

@@ -36,6 +36,7 @@ const TOOL_GUIDANCE = {
     delete_issue_link: "Use this to remove an existing relationship between two issues; use `list_issue_links` or `get_issue_link` to verify the link first. The operation changes issue relationships, requires issue-edit permission, and returns the result or an error when the link is missing or access is denied.",
     download_job_artifacts: "Use this to retrieve a pipeline job's artifact archive; remote HTTP mode returns a download URL while local mode saves the archive to a local path. It is read-only but may create a local file in stdio mode, requires job/project access, and returns the download result or an artifact/permission error.",
     download_attachment: "Use this to retrieve a previously uploaded project attachment; remote mode returns inline base64 for images or a download URL, while local mode can save to a path. It is read-only with respect to GitLab, requires project access, and returns the file content or an attachment/permission error.",
+    gitlab_api_request: "Send one GitLab REST call under /api/v4. Readonly mode allows GET only, and modify mode rejects DELETE. Enable it 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. GITLAB_ALLOWED_PROJECT_IDS is enforced only for /projects/:id paths; other endpoints are not constrained.",
     execute_graphql: "Use this only when a supported GitLab REST tool does not cover the requested operation; prefer a typed tool when one exists. The query is sent directly to GitLab and can include mutations when permission allows, so callers must treat it as potentially state-changing and handle GraphQL errors in the returned response.",
     discover_tools: "Use this when a needed opt-in category is not currently exposed; omit `category` to inspect available categories, then call it with a category to activate that group for the current session. It changes only the session's tool registry, returns the active-tool summary, and does not change GitLab data.",
     health_check: "Use this to verify server connectivity and authentication before making GitLab requests; use `whoami` when the authenticated user's identity is the goal. A 403 from GET /user with an insufficient_scope error means the token is accepted but User API scope is missing (read_user or fine-grained User:Read); the check stays ok, sets user_api_warning, and omits version metadata. Rate-limit and authentication-ban 403 responses stay unauthenticated. It does not mutate GitLab state and returns server/authentication status plus GitLab version details when available. Connection failures with no HTTP response return status error, authenticated false, and an error object (kind tls, dns, timeout, or network, plus code and message) instead of a protocol error.",

package/build/utils/redact-sensitive.js

@@ -36,3 +36,14 @@ export function redactSensitiveGitLabFields(data) {
     }
     return data;
 }
+const SENSITIVE_ASSIGNMENT_PATTERN = /(["']?\b(?:runners_token|import_url|token)\b["']?\s*[:=]\s*)(?:"(?:[^"\\\r\n]|\\.)*"|'(?:[^'\\\r\n]|\\.)*'|\S+)/gi;
+const GITLAB_TOKEN_PATTERN = /\bgl(?:pat|dt|rt|pt|ft|oas|soat)-[A-Za-z0-9._-]+/gi;
+/**
+ * Redacts the same secret fields when GitLab returns a non-JSON body.
+ * JSON responses keep using {@link redactSensitiveGitLabFields}.
+ */
+export function redactSensitiveGitLabText(text) {
+    return text
+        .replace(SENSITIVE_ASSIGNMENT_PATTERN, "$1[REDACTED]")
+        .replace(GITLAB_TOKEN_PATTERN, "[REDACTED]");
+}

package/build/utils/safe-redirect-fetch.js

@@ -220,8 +220,17 @@ async function assertRedirectTargetAllowed(target, trusted, options) {
             "Add the host to GITLAB_ALLOWED_HOSTS if the redirect target is trusted.");
     }
 }
+function methodAfterRedirect(status, method) {
+    if ((status === 301 || status === 302) && method === "POST") {
+        return { method: "GET", dropBody: true };
+    }
+    if (status === 303 && method !== "GET" && method !== "HEAD") {
+        return { method: "GET", dropBody: true };
+    }
+    return { method, dropBody: false };
+}
 /**
- * Perform a GET request that validates every redirect hop before following it.
+ * Perform a request that validates every redirect hop before following it.
  *
  * The HTTP client default follows redirects without re-validating the destination,
  * which lets an upstream response redirect the server to an arbitrary host
@@ -261,6 +270,8 @@ export async function fetchWithValidatedRedirects(url, options) {
     let currentUrl = url;
     let currentProtocol = new URL(url).protocol;
     let currentHeaders = options.headers;
+    let currentMethod = (options.method ?? "GET").toUpperCase();
+    let currentBody = options.body;
     // Set once a hop outside the origin has been followed without the credentials, so a
     // later hop back to the origin cannot re-attach them.
     let credentialsWithheld = false;
@@ -268,8 +279,9 @@ export async function fetchWithValidatedRedirects(url, options) {
         // A stripped hop must not go through a client that can add credentials again.
         const hopFetch = credentialsWithheld ? unauthenticatedFetch : authenticatedFetch;
         const response = await hopFetch(currentUrl, {
-            method: "GET",
+            method: currentMethod,
             headers: currentHeaders,
+            ...(currentBody === undefined ? {} : { body: currentBody }),
             dispatcher: options.dispatcher,
             signal: options.signal,
             redirect: "manual",
@@ -314,6 +326,12 @@ export async function fetchWithValidatedRedirects(url, options) {
             credentialsWithheld ||= !trusted;
             currentHeaders = credentialsWithheld ? withoutCredentialHeaders(options) : options.headers;
         }
+        await options.validateRedirectTarget?.(target);
+        const rewritten = methodAfterRedirect(response.status, currentMethod);
+        currentMethod = rewritten.method;
+        if (rewritten.dropBody) {
+            currentBody = undefined;
+        }
         currentUrl = target.toString();
         currentProtocol = target.protocol;
     }

package/build/utils/url.js

@@ -134,3 +134,91 @@ export function encodeGitLabPath(value) {
     }
     return segments.map(encodeGitLabPathSegment).join("/");
 }
+const ABSOLUTE_URL_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+function looksLikeAbsoluteApiReference(value) {
+    return value.includes("://") || value.startsWith("//") || ABSOLUTE_URL_PATTERN.test(value);
+}
+/**
+ * Normalize a caller path so it can only name a resource under `/api/v4`.
+ * Rejects absolute URLs, protocol-relative hosts, backslashes, dot segments
+ * (including percent-encoded ones), and control characters. A single leading
+ * or trailing slash is removed so `/projects/1` and `projects/1` are the same
+ * relative path.
+ */
+export function normalizeGitLabApiRelativePath(rawPath) {
+    const trimmed = rawPath.trim();
+    if (trimmed.length === 0) {
+        throw new Error("GitLab API path is empty");
+    }
+    if (CONTROL_CHARACTER_PATTERN.test(trimmed) ||
+        trimmed.includes("\\") ||
+        looksLikeAbsoluteApiReference(trimmed)) {
+        throw new Error("GitLab API path must be a relative path under /api/v4 (absolute URLs, protocol-relative hosts, backslashes, and control characters are rejected)");
+    }
+    const withoutLeadingSlash = trimmed.startsWith("/") ? trimmed.slice(1) : trimmed;
+    const relative = withoutLeadingSlash.endsWith("/")
+        ? withoutLeadingSlash.slice(0, -1)
+        : withoutLeadingSlash;
+    if (relative.length === 0 || relative.startsWith("/")) {
+        throw new Error("GitLab API path must be a relative path under /api/v4");
+    }
+    const decoded = decodeFully(relative);
+    if (decoded === null ||
+        CONTROL_CHARACTER_PATTERN.test(decoded) ||
+        decoded.includes("\\") ||
+        looksLikeAbsoluteApiReference(decoded)) {
+        throw new Error("GitLab API path must be a relative path under /api/v4 (absolute URLs, protocol-relative hosts, backslashes, and control characters are rejected)");
+    }
+    // encodeGitLabPath rejects `.` / `..` segments, including percent-encoded forms.
+    encodeGitLabPath(relative);
+    return relative;
+}
+/**
+ * Resolve `rawPath` against the configured GitLab API base (`.../api/v4`).
+ * The result is the same origin and stays under that base path.
+ */
+export function resolveGitLabApiRequestUrl(apiBase, rawPath) {
+    const relative = normalizeGitLabApiRelativePath(rawPath);
+    const encoded = encodeGitLabPath(relative);
+    const base = new URL(apiBase.endsWith("/") ? apiBase : `${apiBase}/`);
+    const resolved = new URL(encoded, base);
+    if (resolved.origin !== base.origin || resolved.username !== "" || resolved.password !== "") {
+        throw new Error("GitLab API path escapes the configured API origin");
+    }
+    const basePath = base.pathname.endsWith("/") ? base.pathname : `${base.pathname}/`;
+    const staysUnderBase = resolved.pathname === base.pathname.replace(/\/$/, "") ||
+        resolved.pathname.startsWith(basePath);
+    if (!staysUnderBase || resolved.search !== "" || resolved.hash !== "") {
+        throw new Error("GitLab API path escapes the configured /api/v4 base");
+    }
+    return resolved;
+}
+function decodeApiPathSegment(segment) {
+    const decoded = decodeFully(segment);
+    if (decoded === null) {
+        throw new Error("GitLab API path has an invalid project id encoding");
+    }
+    return decoded;
+}
+/**
+ * Project id from `projects/:id` or `projects/:id/...`.
+ *
+ * Segments are percent-decoded until stable, the same way the outgoing request
+ * is built. An encoded `projects` prefix still selects this route. A slash
+ * encoded inside the id (`group%2Fproj`) stays part of that one id.
+ * Other paths return undefined.
+ */
+export function readProjectIdFromApiRelativePath(relativePath) {
+    const segments = relativePath.split("/");
+    if (segments.length < 2) {
+        return undefined;
+    }
+    if (decodeApiPathSegment(segments[0]) !== "projects") {
+        return undefined;
+    }
+    const projectId = decodeApiPathSegment(segments[1]);
+    if (projectId.length === 0) {
+        return undefined;
+    }
+    return projectId;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "mcpName": "io.github.zereight/gitlab-mcp",
   "description": "GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more",
   "keywords": [