@zereight/mcp-gitlab 2.1.69 → 2.1.70

package/README.pt-BR.md

@@ -17,7 +17,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 
 ### Por que usar este GitLab MCP?
 
-- **261 ferramentas + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
+- **267 ferramentas + `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
@@ -31,7 +31,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 |                           | @zereight/mcp-gitlab                           | GitLab MCP A (comunidade, estilo CQRS)                    |
 | ------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
 | **Mais indicado para**    | Workflows de agentes de IA                     | Múltiplas instâncias corporativas / ferramentas agrupadas |
-| **Modelo de ferramentas** | ~261 ferramentas granulares + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      |
+| **Modelo de ferramentas** | ~267 ferramentas granulares + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      |
 | **Revisão de MR**         | Diff em lote em 2 etapas                       | Varia                                                     |
 | **Node.js**               | >=18.17                                        | Frequentemente >=24                                       |
 | **Licença**               | MIT                                            | Varia                                                     |
@@ -111,7 +111,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.1.68`. 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.1.69`. 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)
 
@@ -150,7 +150,7 @@ Os argumentos de CLI têm precedência sobre as variáveis de ambiente.
 
 `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).
 
-O mesmo binário também é uma CLI do GitLab no estilo `gh` (`tool <name>` ou formas curadas como `mr list`). Use-o para ver a carga completa no terminal. As respostas do MCP permanecem no chat, a menos que você defina `GITLAB_MCP_COMPACT_RESULTS=true` (ou `--compact-results`), o que substitui respostas grandes de ferramentas por uma prévia e um comando CLI. A CLI humana nunca é compactada. Os mesmos filtros de permission mode, toolsets, denied-tools regex e tool-policy se aplicam. Ferramentas destrutivas e ferramentas com `GITLAB_TOOL_POLICY_APPROVE` exigem `--yes`. Consulte [CLI Humana](./docs/getting-started/cli-arguments.md#human-cli).
+O mesmo binário também é uma CLI do GitLab no estilo `gh` (`tool <name>` ou formas curadas como `mr list`). **Não é necessário registrar o MCP** — defina um PAT, ou execute `auth` e defina `GITLAB_USE_OAUTH=true`: veja [CLI sem MCP](./docs/getting-started/cli-without-mcp.md). Use-o para ver a carga completa no terminal. As respostas do MCP permanecem no chat, a menos que você defina `GITLAB_MCP_COMPACT_RESULTS=true` (ou `--compact-results`), o que substitui respostas grandes de ferramentas por uma prévia e um comando CLI. A CLI humana nunca é compactada. Os mesmos filtros de permission mode, toolsets, denied-tools regex e tool-policy se aplicam. Ferramentas destrutivas e ferramentas com `GITLAB_TOOL_POLICY_APPROVE` exigem `--yes`. Consulte [CLI Humana](./docs/getting-started/cli-arguments.md#human-cli).
 
 > **Filtragem granular de ferramentas:** use `GITLAB_PERMISSION_MODE=modify` para permitir criação/atualização enquanto
 > bloqueia todas as ferramentas de exclusão e as ferramentas destrutivas de teardown (`cancel_pipeline`,

package/README.zh-CN.md

@@ -17,7 +17,7 @@
 
 ### 为什么使用这个 GitLab MCP？
 
-- **266 个工具 + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
+- **267 个工具 + `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 代理、按请求远程授权
@@ -31,7 +31,7 @@
 | | @zereight/mcp-gitlab | GitLab MCP A（社区 CQRS 型） |
 |---|----------------------|------------------------------|
 | **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 |
-| **工具模型** | ~266 个细粒度工具 + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
+| **工具模型** | ~267 个细粒度工具 + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
 | **MR 审查** | 两步批量 diff | 因服务器而异 |
 | **Node.js** | >=18.17 | 通常 >=24 |
 | **许可证** | MIT | 因服务器而异 |
@@ -111,7 +111,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.1.68`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.69`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -150,7 +150,7 @@ CLI 参数优先于环境变量。
 
 `zereight-mcp-gitlab auth` 是子命令，不是 MCP 服务器参数。它运行 GitLab device flow 后退出。参见 [CLI 参数](./docs/getting-started/cli-arguments.md#auth)。
 
-同一二进制也是 `gh` 风格的 GitLab CLI（`tool <name>`，或 `mr list` 这类 curated 命令）。完整结果在终端用 CLI 查看。MCP 回复仍进入对话。设置 `GITLAB_MCP_COMPACT_RESULTS=true`（或 `--compact-results`）后，过大的工具回复会变成预览加上 CLI 命令。Human CLI 本身不会被 compact。permission mode、toolsets、denied-tools regex 和 tool-policy 与 MCP 相同。破坏性工具以及 `GITLAB_TOOL_POLICY_APPROVE` 工具需要 `--yes`。参见 [Human CLI](./docs/getting-started/cli-arguments.md#human-cli)。
+同一二进制也是 `gh` 风格的 GitLab CLI（`tool <name>`，或 `mr list` 这类 curated 命令）。**无需注册 MCP**——设置 PAT，或运行 `auth` 后设置 `GITLAB_USE_OAUTH=true`：参见 [无需 MCP 使用 CLI](./docs/getting-started/cli-without-mcp.md)。完整结果在终端用 CLI 查看。MCP 回复仍进入对话。设置 `GITLAB_MCP_COMPACT_RESULTS=true`（或 `--compact-results`）后，过大的工具回复会变成预览加上 CLI 命令。Human CLI 本身不会被 compact。permission mode、toolsets、denied-tools regex 和 tool-policy 与 MCP 相同。破坏性工具以及 `GITLAB_TOOL_POLICY_APPROVE` 工具需要 `--yes`。参见 [Human CLI](./docs/getting-started/cli-arguments.md#human-cli)。
 
 > **细粒度工具过滤：**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新，同时阻止所有删除工具以及
 > 破坏性的拆除（teardown）工具（`cancel_pipeline`、`cancel_pipeline_job`、`stop_environment`、

package/build/index.js

@@ -38,7 +38,8 @@ function buildDownloadUrl(type, params) {
                 header = "JOB-TOKEN";
                 headerValue = String(staticToken);
             }
-            else if (IS_OLD) {
+            else if (IS_OLD && !OAUTH_ACCESS_TOKEN) {
+                // OAuth tokens always use Bearer (see buildAuthHeaders)
                 header = "Private-Token";
                 headerValue = String(staticToken);
             }
@@ -93,7 +94,7 @@ import { formatPrometheusMetrics } from "./server/metrics.js";
 import { SERVER_VERSION } from "./server/version.js";
 import { isInitializationRequestBody, isUnauthenticatedDiscoveryRequestBody, readAcceptHeader, readMcpSessionIdHeader, redactSessionIdForLog, } from "./server/request-helpers.js";
 export { readMcpSessionIdHeader } from "./server/request-helpers.js";
-import { encodeGitLabPath, encodeGitLabPathSegment, normalizeGitLabApiUrl, } from "./utils/url.js";
+import { encodeGitLabPath, encodeGitLabPathSegment, isCleartextRemoteUrl, normalizeGitLabApiUrl, } from "./utils/url.js";
 import { estimateMergeCommitCount, filterDiffsByPatterns, openSafeOutputWriteStream, readSafeExistingFile, summarizeWebhookEvents, } from "./utils/helpers.js";
 import { graphqlQueryContainsWriteOperation, graphqlQueryContainsDeleteOperation, } from "./utils/graphql-query.js";
 import { resolveNestedWikiUpdateTitle } from "./utils/wiki-title.js";
@@ -356,7 +357,7 @@ function createServer() {
                 durationMs,
                 error: safeError instanceof Error ? safeError.message : String(safeError),
             }, `tool_call_error: ${toolName} (${durationMs}ms)`);
-            throw safeError;
+            return safeError;
         };
         try {
             const authData = (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) && sessionId
@@ -547,8 +548,20 @@ function createServer() {
             return logCompletion(result);
         }
         catch (error) {
-            logError(error);
-            throw error;
+            const isGitLabApiError = error instanceof GitLabApiError;
+            const safeError = logError(error);
+            if (isGitLabApiError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: safeError instanceof Error ? safeError.message : String(safeError),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            throw safeError;
         }
     });
     return mcpServer;
@@ -1097,12 +1110,15 @@ function buildAuthHeaders() {
     // OAuth token takes priority over PAT when both are set.
     // NOTE: Changed in PR #400 — previously GITLAB_JOB_TOKEN had highest priority.
     // If both GITLAB_PERSONAL_ACCESS_TOKEN and GITLAB_JOB_TOKEN are set, PAT wins.
-    const token = OAUTH_ACCESS_TOKEN || GITLAB_PERSONAL_ACCESS_TOKEN;
-    if (IS_OLD && token) {
-        return { "Private-Token": String(token) };
+    // OAuth tokens always travel as `Authorization: Bearer`, even with GITLAB_IS_OLD: the HTTP
+    // client strips `Authorization` on cross-origin redirects but not `Private-Token`.
+    if (OAUTH_ACCESS_TOKEN) {
+        return { Authorization: `Bearer ${OAUTH_ACCESS_TOKEN}` };
     }
-    if (token) {
-        return { Authorization: `Bearer ${token}` };
+    if (GITLAB_PERSONAL_ACCESS_TOKEN) {
+        return IS_OLD
+            ? { "Private-Token": String(GITLAB_PERSONAL_ACCESS_TOKEN) }
+            : { Authorization: `Bearer ${GITLAB_PERSONAL_ACCESS_TOKEN}` };
     }
     // Fall back to CI job token
     if (GITLAB_JOB_TOKEN) {
@@ -1325,6 +1341,12 @@ if (!isCliInvocation(process.argv) &&
     logger.info("Either set GITLAB_PERSONAL_ACCESS_TOKEN or enable OAuth with GITLAB_USE_OAUTH=true");
     process.exit(1);
 }
+class GitLabApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitLabApiError";
+    }
+}
 /**
  * Utility function for handling GitLab API errors
  * API 에러 처리를 위한 유틸리티 함수 (Utility function for handling API errors)
@@ -1341,12 +1363,12 @@ async function handleGitLabError(response) {
             // before the common tool-call boundary returns/logs it.
             logger.error("GitLab API Rate Limit Exceeded");
             logger.error("User API Key Rate limit exceeded. Please try again later.");
-            const error = new Error(`GitLab API Rate Limit Exceeded: ${errorBody}`);
+            const error = new GitLabApiError(`GitLab API Rate Limit Exceeded: ${errorBody}`);
             throw error;
         }
         else {
             // Handle other API errors
-            const error = new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+            const error = new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
             throw error;
         }
     }
@@ -1411,7 +1433,7 @@ async function forkProject(projectId, namespace) {
     });
     // Handle case where project already exists
     if (response.status === 409) {
-        throw new Error("Project already exists in the target namespace");
+        throw new GitLabApiError("Project already exists in the target namespace");
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -1482,7 +1504,7 @@ async function getFileContents(projectId, filePath, ref) {
     });
     // Handle file not found
     if (response.status === 404) {
-        throw new Error(`File not found: ${filePath}`);
+        throw new GitLabApiError(`File not found: ${filePath}`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -1515,7 +1537,7 @@ async function createIssue(projectId, options) {
     // Handle bad request
     if (response.status === 400) {
         const errorBody = await response.text();
-        throw new Error(`Invalid request: ${errorBody}`);
+        throw new GitLabApiError(`Invalid request: ${errorBody}`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -1751,7 +1773,7 @@ async function executeGraphQL(query, variables = {}) {
     });
     if (!response.ok) {
         const errorBody = await response.text();
-        throw new Error(`GraphQL request failed (${response.status}): ${errorBody}`);
+        throw new GitLabApiError(`GraphQL request failed (${response.status}): ${errorBody}`);
     }
     const json = await response.json();
     if (json.errors && json.errors.length > 0) {
@@ -3200,11 +3222,11 @@ async function createMergeRequest(projectId, options) {
     });
     if (response.status === 400) {
         const errorBody = await response.text();
-        throw new Error(`Invalid request: ${errorBody}`);
+        throw new GitLabApiError(`Invalid request: ${errorBody}`);
     }
     if (!response.ok) {
         const errorBody = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
     }
     const data = await response.json();
     return GitLabMergeRequestSchema.parse(data);
@@ -3292,7 +3314,7 @@ async function deleteMergeRequestDiscussionNote(projectId, mergeRequestIid, disc
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
 }
 /**
@@ -3452,7 +3474,7 @@ async function deleteMergeRequestNote(projectId, mergeRequestIid, noteId) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
 }
 // --- Emoji Reactions (REST) ---
@@ -3623,7 +3645,7 @@ async function createOrUpdateFile(projectId, filePath, content, commitMessage, b
     });
     if (!response.ok) {
         const errorBody = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
     }
     const data = await response.json();
     return GitLabCreateUpdateFileResponseSchema.parse(data);
@@ -3652,11 +3674,11 @@ async function createCommit(projectId, message, branch, actions) {
     });
     if (response.status === 400) {
         const errorBody = await response.text();
-        throw new Error(`Invalid request: ${errorBody}`);
+        throw new GitLabApiError(`Invalid request: ${errorBody}`);
     }
     if (!response.ok) {
         const errorBody = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
     }
     const data = await response.json();
     return GitLabCommitSchema.parse(data);
@@ -3682,7 +3704,7 @@ async function searchProjects(query, page = 1, perPage = 20) {
     });
     if (!response.ok) {
         const errorBody = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
     }
     const unfiltered = (await response.json());
     const projects = filterProjectsByAllowlist(unfiltered);
@@ -3769,7 +3791,7 @@ async function createRepository(options) {
     });
     if (!response.ok) {
         const errorBody = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
     }
     const data = await response.json();
     return GitLabRepositorySchema.parse(data);
@@ -4195,7 +4217,7 @@ async function getBranchDiffs(projectId, from, to, straight) {
     });
     if (!response.ok) {
         const errorBody = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
     }
     const data = await response.json();
     return GitLabCompareResultSchema.parse(data);
@@ -4428,7 +4450,7 @@ noteableIid, body) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
     return await response.json();
 }
@@ -4443,7 +4465,7 @@ async function getDraftNote(project_id, merge_request_iid, draft_note_id) {
     const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/merge_requests/${encodeGitLabPathSegment(merge_request_iid)}/draft_notes/${encodeGitLabPathSegment(draft_note_id)}`, { ...getFetchConfig() });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
     const data = await response.json();
     return GitLabDraftNoteSchema.parse(data);
@@ -4457,7 +4479,7 @@ async function listDraftNotes(projectId, mergeRequestIid) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
     const data = await response.json();
     return z.array(GitLabDraftNoteSchema).parse(data);
@@ -4492,7 +4514,7 @@ async function createDraftNote(projectId, mergeRequestIid, body, inReplyToDiscus
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
     const data = await response.json();
     return GitLabDraftNoteSchema.parse(data);
@@ -4527,7 +4549,7 @@ async function updateDraftNote(projectId, mergeRequestIid, draftNoteId, body, po
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
     const data = await response.json();
     return GitLabDraftNoteSchema.parse(data);
@@ -4548,7 +4570,7 @@ async function deleteDraftNote(projectId, mergeRequestIid, draftNoteId) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
 }
 /**
@@ -4567,7 +4589,7 @@ async function publishDraftNote(projectId, mergeRequestIid, draftNoteId) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
     // Handle empty response (204 No Content) or successful response
     const responseText = await response.text();
@@ -4648,7 +4670,7 @@ async function bulkPublishDraftNotes(projectId, mergeRequestIid, options = {}) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
     // Handle empty response (204 No Content) or successful response
     const responseText = await response.text();
@@ -4679,7 +4701,7 @@ async function resolveMergeRequestThread(projectId, mergeRequestIid, discussionI
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
+        throw new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
 }
 /**
@@ -5271,7 +5293,7 @@ async function getPipeline(projectId, pipelineId, signal) {
         signal,
     });
     if (response.status === 404) {
-        throw new Error(`Pipeline not found`);
+        throw new GitLabApiError(`Pipeline not found`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -5344,7 +5366,7 @@ async function getDeployment(projectId, deploymentId) {
         ...getFetchConfig(),
     });
     if (response.status === 404) {
-        throw new Error(`Deployment not found`);
+        throw new GitLabApiError(`Deployment not found`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -5396,7 +5418,7 @@ async function getEnvironment(projectId, environmentId) {
         ...getFetchConfig(),
     });
     if (response.status === 404) {
-        throw new Error(`Environment not found`);
+        throw new GitLabApiError(`Environment not found`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -5449,7 +5471,7 @@ async function listPipelineJobs(projectId, pipelineId, options = {}) {
         ...getFetchConfig(),
     });
     if (response.status === 404) {
-        throw new Error(`Pipeline not found`);
+        throw new GitLabApiError(`Pipeline not found`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -5472,7 +5494,7 @@ async function listPipelineTriggerJobs(projectId, pipelineId, options = {}) {
         ...getFetchConfig(),
     });
     if (response.status === 404) {
-        throw new Error(`Pipeline not found`);
+        throw new GitLabApiError(`Pipeline not found`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -5486,7 +5508,7 @@ async function getPipelineJob(projectId, jobId, signal) {
         signal,
     });
     if (response.status === 404) {
-        throw new Error(`Job not found`);
+        throw new GitLabApiError(`Job not found`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -5514,7 +5536,7 @@ async function getPipelineJobOutput(projectId, jobId, limit, offset) {
         },
     });
     if (response.status === 404) {
-        throw new Error(`Job trace not found or job is not finished yet`);
+        throw new GitLabApiError(`Job trace not found or job is not finished yet`);
     }
     await handleGitLabError(response);
     const fullTrace = await response.text();
@@ -5576,7 +5598,7 @@ async function listJobArtifacts(projectId, jobId, options = {}) {
         ...getFetchConfig(),
     });
     if (response.status === 404) {
-        throw new Error(`Job artifacts not found. The job may not have produced artifacts or the job ID is invalid.`);
+        throw new GitLabApiError(`Job artifacts not found. The job may not have produced artifacts or the job ID is invalid.`);
     }
     await handleGitLabError(response);
     const data = await response.json();
@@ -5596,7 +5618,7 @@ async function downloadJobArtifacts(projectId, jobId, localPath) {
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/jobs/${encodeGitLabPathSegment(jobId)}/artifacts`);
     const response = await fetchWithValidatedRedirects(url.toString(), downloadRedirectOptions());
     if (response.status === 404) {
-        throw new Error(`Job artifacts not found. The job may not have produced artifacts or the job ID is invalid.`);
+        throw new GitLabApiError(`Job artifacts not found. The job may not have produced artifacts or the job ID is invalid.`);
     }
     await handleGitLabError(response);
     const filename = `artifacts_job_${encodeGitLabPathSegment(jobId)}.zip`;
@@ -5622,7 +5644,7 @@ async function getJobArtifactFile(projectId, jobId, artifactPath) {
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/jobs/${encodeGitLabPathSegment(jobId)}/artifacts/${encodedArtifactPath}`);
     const response = await fetchWithValidatedRedirects(url.toString(), downloadRedirectOptions());
     if (response.status === 404) {
-        throw new Error(`Artifact file not found: ${artifactPath}`);
+        throw new GitLabApiError(`Artifact file not found: ${artifactPath}`);
     }
     await handleGitLabError(response);
     return await response.text();
@@ -6038,10 +6060,10 @@ async function getRepositoryTree(options) {
         queryParams.append("pagination", options.pagination);
     const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(getEffectiveProjectId(options.project_id))}/repository/tree?${queryParams.toString()}`, { ...getFetchConfig() });
     if (response.status === 404) {
-        throw new Error("Repository or path not found");
+        throw new GitLabApiError("Repository or path not found");
     }
     if (!response.ok) {
-        throw new Error(`Failed to get repository tree: ${response.statusText}`);
+        throw new GitLabApiError(`Failed to get repository tree: ${response.statusText}`);
     }
     const data = await response.json();
     const items = z.array(GitLabTreeItemSchema).parse(data);
@@ -11987,6 +12009,22 @@ async function initializeServerByTransportMode(mode) {
         }
     }
 }
+/**
+ * Construct the OAuth client when OAuth is enabled. No network: the token is
+ * acquired lazily on the first tool call via ensureValidOAuthToken, which
+ * avoids blocking startup and opening a browser on transient boot-time errors.
+ * Shared by the MCP server and the human CLI.
+ */
+function initOAuthClient() {
+    if (!USE_OAUTH) {
+        return;
+    }
+    if (isCleartextRemoteUrl(GITLAB_API_URL)) {
+        throw new Error(`Refusing to send OAuth tokens over cleartext HTTP to ${GITLAB_API_URL}. ` +
+            "Use an https:// GITLAB_API_URL (http:// is only allowed for localhost).");
+    }
+    oauthClient = createGitLabOAuthClient(GITLAB_API_URL.replace(/\/api\/v4$/, ""));
+}
 /**
  * Initialize and run the server
  * Main entry point for server startup
@@ -11999,12 +12037,7 @@ async function runServer() {
         if (USE_OAUTH) {
             logger.info("Using OAuth authentication...");
             try {
-                const gitlabBaseUrl = GITLAB_API_URL.replace(/\/api\/v4$/, "");
-                // Construct the client synchronously (no network). The token is
-                // acquired lazily on the first tool call via ensureValidOAuthToken,
-                // by which point the network is ready. This avoids blocking startup
-                // and avoids opening a browser on transient boot-time network errors.
-                oauthClient = createGitLabOAuthClient(gitlabBaseUrl);
+                initOAuthClient();
                 logger.info("OAuth enabled; token acquired lazily on first use.");
             }
             catch (error) {
@@ -12074,6 +12107,7 @@ async function main() {
             process.exit(2);
         }
         try {
+            initOAuthClient();
             const result = await handleToolCall({ name: cli.toolName, arguments: cli.args });
             const masked = maskCliToolResult(cli.toolName, result);
             const formatted = formatToolOutput({

package/build/test/cli/credentials.test.js

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as url from "node:url";
+import { describe, it } from "node:test";
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const CLI_ENTRY = path.resolve(__dirname, "../../build/index.js");
+const CLI_TIMEOUT_MS = 30_000;
+const MR_FIXTURE = {
+    id: 1,
+    iid: 1,
+    project_id: 7,
+    title: "Hello MR",
+    description: "d",
+    state: "opened",
+    web_url: "http://example.test/mr/1",
+    source_branch: "feature",
+    target_branch: "main",
+    author: { id: 1, username: "u", name: "U", state: "active", avatar_url: null, web_url: "http://example.test/u" },
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    merged_at: null,
+    closed_at: null,
+    merge_commit_sha: null,
+};
+function buildCleanEnv(extra) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined && !key.startsWith("GITLAB_")) {
+            env[key] = value;
+        }
+    }
+    return { ...env, ...extra };
+}
+function startFakeGitLabAsync(onRequest) {
+    const server = http.createServer((req, res) => {
+        onRequest(req.headers.authorization);
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify(MR_FIXTURE));
+    });
+    return new Promise(resolve => server.listen(0, "127.0.0.1", () => resolve(server)));
+}
+function getPort(server) {
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("fake GitLab server is not listening on a TCP port");
+    }
+    return address.port;
+}
+function runCliAsync(env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [CLI_ENTRY, "mr", "view", "--project-id", "g/p", "--mr-iid", "1"], {
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: CLI_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", chunk => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", chunk => {
+            stderr += String(chunk);
+        });
+        child.on("error", reject);
+        child.on("close", exitCode => resolve({ exitCode, stdout, stderr }));
+    });
+}
+function buildOAuthEnv(apiUrl, tmpDir) {
+    const tokenPath = path.join(tmpDir, "token.json");
+    fs.writeFileSync(tokenPath, JSON.stringify({
+        access_token: "oauth-cli-test",
+        refresh_token: "refresh",
+        expires_in: 7200,
+        created_at: Date.now(),
+        token_type: "Bearer",
+    }));
+    return {
+        GITLAB_API_URL: apiUrl,
+        GITLAB_USE_OAUTH: "true",
+        GITLAB_OAUTH_CLIENT_ID: "client-id",
+        GITLAB_OAUTH_TOKEN_PATH: tokenPath,
+    };
+}
+async function runMrViewAgainstFakeGitLabAsync(buildEnv) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "gitlab-cli-credentials-"));
+    let authorization;
+    const server = await startFakeGitLabAsync(value => {
+        authorization = value;
+    });
+    try {
+        const apiUrl = `http://127.0.0.1:${getPort(server)}/api/v4`;
+        const result = await runCliAsync(buildCleanEnv(buildEnv(apiUrl, tmpDir)));
+        return { ...result, authorization };
+    }
+    finally {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+describe("When the human CLI runs without an MCP client", () => {
+    describe("with a personal access token in the environment", () => {
+        it("should send the token as a bearer credential", async () => {
+            const run = await runMrViewAgainstFakeGitLabAsync(apiUrl => ({
+                GITLAB_API_URL: apiUrl,
+                GITLAB_PERSONAL_ACCESS_TOKEN: "glpat-cli-test",
+            }));
+            assert.equal(run.exitCode, 0);
+            assert.equal(run.authorization, "Bearer glpat-cli-test");
+        });
+    });
+    describe("with an OAuth token stored by the auth command", () => {
+        it("should send the stored token as a bearer credential", async () => {
+            const run = await runMrViewAgainstFakeGitLabAsync(buildOAuthEnv);
+            assert.equal(run.exitCode, 0);
+            assert.equal(run.authorization, "Bearer oauth-cli-test");
+        });
+    });
+    describe("with an OAuth token and GITLAB_IS_OLD enabled", () => {
+        it("should still send the token as a bearer credential", async () => {
+            const run = await runMrViewAgainstFakeGitLabAsync((apiUrl, tmpDir) => ({
+                ...buildOAuthEnv(apiUrl, tmpDir),
+                GITLAB_IS_OLD: "true",
+            }));
+            assert.equal(run.exitCode, 0);
+            assert.equal(run.authorization, "Bearer oauth-cli-test");
+        });
+    });
+    describe("with OAuth enabled against a cleartext remote URL", () => {
+        it("should refuse to run before any network call", async () => {
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "gitlab-cli-credentials-"));
+            try {
+                const result = await runCliAsync(buildCleanEnv(buildOAuthEnv("http://gitlab.example.invalid/api/v4", tmpDir)));
+                assert.equal(result.exitCode, 1);
+                assert.match(result.stderr, /cleartext HTTP/);
+            }
+            finally {
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+        });
+    });
+    describe("with no credentials at all", () => {
+        it("should exit with a usage error before any network call", async () => {
+            const run = await runMrViewAgainstFakeGitLabAsync(apiUrl => ({ GITLAB_API_URL: apiUrl }));
+            assert.equal(run.exitCode, 2);
+            assert.equal(run.authorization, undefined);
+        });
+    });
+});