@zereight/mcp-gitlab 2.1.68 → 2.1.70

package/build/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { getConfig, ENABLE_DYNAMIC_API_URL, ENABLE_DYNAMIC_PROJECT_SCOPE, ENABLE_STRICT_PROJECT_SCOPE, GITLAB_AUTH_COOKIE_PATH, GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY, GITLAB_CA_CERT_PATH, GITLAB_JOB_TOKEN, GITLAB_MCP_OAUTH, GITLAB_OAUTH_APP_ID, GITLAB_OAUTH_SCOPES, GITLAB_OAUTH_CALLBACK_PROXY, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_POOL_MAX_SIZE, GITLAB_DISABLE_VERSION_CHECK, GITLAB_READ_ONLY_MODE, GITLAB_MASKING_ENABLED, GITLAB_MASKING_CONFIG, GITLAB_MASKING_POLICY_FILE, GITLAB_MASKING_WORKSPACE_DIR, GITLAB_PERMISSION_MODE, GITLAB_TOOLSETS_RAW, GITLAB_TOOLS_RAW, HOST, HTTP_PROXY, HTTPS_PROXY, IS_OLD, MCP_SERVER_URL, NODE_TLS_REJECT_UNAUTHORIZED, NO_PROXY, OAUTH_STATELESS_CLIENT_TTL_SECONDS, OAUTH_STATELESS_MODE, OAUTH_STATELESS_PENDING_TTL_SECONDS, OAUTH_STATELESS_SESSION_TTL_SECONDS, OAUTH_STATELESS_STORED_TTL_SECONDS, PORT, REMOTE_AUTHORIZATION, SESSION_TIMEOUT_SECONDS, SSE, STREAMABLE_HTTP, MCP_TRUST_PROXY, USE_GITLAB_WIKI, USE_MILESTONE, USE_OAUTH, USE_PIPELINE, GITLAB_TOOL_POLICY_APPROVE_RAW, GITLAB_TOOL_POLICY_HIDDEN_RAW, GITLAB_OAUTH_ALLOWED_GROUPS_RAW, GITLAB_ALLOWED_GROUPS_RAW, GITLAB_OAUTH_ALLOWED_GROUPS, } from "./config.js";
+import { getConfig, ENABLE_DYNAMIC_API_URL, ENABLE_DYNAMIC_PROJECT_SCOPE, ENABLE_STRICT_PROJECT_SCOPE, GITLAB_AUTH_COOKIE_PATH, GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY, GITLAB_CA_CERT_PATH, GITLAB_JOB_TOKEN, GITLAB_MCP_OAUTH, GITLAB_OAUTH_APP_ID, GITLAB_OAUTH_SCOPES, GITLAB_OAUTH_CALLBACK_PROXY, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_POOL_MAX_SIZE, GITLAB_DISABLE_VERSION_CHECK, GITLAB_READ_ONLY_MODE, GITLAB_MASKING_ENABLED, GITLAB_MASKING_CONFIG, GITLAB_MASKING_POLICY_FILE, GITLAB_MASKING_WORKSPACE_DIR, GITLAB_PERMISSION_MODE, GITLAB_TOOLSETS_RAW, GITLAB_TOOLS_RAW, HOST, HTTP_PROXY, HTTPS_PROXY, IS_OLD, MCP_SERVER_URL, NODE_TLS_REJECT_UNAUTHORIZED, NO_PROXY, OAUTH_STATELESS_CLIENT_TTL_SECONDS, OAUTH_STATELESS_MODE, OAUTH_STATELESS_PENDING_TTL_SECONDS, OAUTH_STATELESS_SESSION_TTL_SECONDS, OAUTH_STATELESS_STORED_TTL_SECONDS, PORT, REMOTE_AUTHORIZATION, SESSION_TIMEOUT_SECONDS, SSE, STREAMABLE_HTTP, MCP_TRUST_PROXY, USE_GITLAB_WIKI, USE_MILESTONE, USE_OAUTH, USE_PIPELINE, GITLAB_TOOL_POLICY_APPROVE_RAW, GITLAB_TOOL_POLICY_HIDDEN_RAW, GITLAB_OAUTH_ALLOWED_GROUPS_RAW, GITLAB_ALLOWED_GROUPS_RAW, GITLAB_OAUTH_ALLOWED_GROUPS, GITLAB_MCP_COMPACT_RESULTS, GITLAB_MCP_COMPACT_RESULT_CHARS, } from "./config.js";
 /** True when the server is running in remote/network mode (SSE or StreamableHTTP transport). */
 const IS_REMOTE = SSE || STREAMABLE_HTTP;
 const STREAMABLE_HTTP_AUTH_TOKEN = getConfig("streamable-http-auth-token", "STREAMABLE_HTTP_AUTH_TOKEN");
@@ -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);
             }
@@ -74,9 +75,13 @@ import path from "node:path";
 import { CookieJar, parse as parseCookie } from "tough-cookie";
 import { URL } from "node:url";
 import { z } from "zod";
-import { initializeOAuthClient } from "./oauth.js";
+import { createGitLabOAuthClient, ensureOAuthToken } from "./oauth.js";
 import { getPositionalCliCommand } from "./cli-command.js";
 import { runAuthCommandAsync } from "./auth-cli.js";
+import { isCliInvocation, resolveCli } from "./cli/router.js";
+import { formatCliError, formatToolOutput } from "./cli/output.js";
+import { compactMcpToolResult, readOwnRecord } from "./cli/compact-mcp-result.js";
+import { compileDeniedToolsRegex } from "./tools/denied-regex.js";
 import { createGitLabOAuthProvider } from "./oauth-proxy.js";
 import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import rateLimit, { ipKeyGenerator } from "express-rate-limit";
@@ -89,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";
@@ -179,6 +184,7 @@ const MCP_PROMPTS = [
  * Each transport connection gets its own Server instance to prevent
  * cross-client data leakage (GHSA-345p-7cg4-v4c7).
  */
+/** Builds an MCP server with the tool list filtered by toolsets, permission mode, and policy. */
 function createServer() {
     // Precompute filtered tool list once at server creation (Steps 1–5 are static)
     // Step 1: Toolset filter — keep tools in enabled toolsets
@@ -329,11 +335,18 @@ function createServer() {
                     ? (value) => maskingEngine.maskValue(value)
                     : undefined,
             });
-            return maskingEngine
+            const masked = maskingEngine
                 ? maskingEngine.maskToolResult(filtered, {
                     textFormat: isPlainTextResult ? "plain" : "json",
                 })
                 : filtered;
+            return compactMcpToolResult({
+                result: masked,
+                enabled: GITLAB_MCP_COMPACT_RESULTS,
+                maxChars: GITLAB_MCP_COMPACT_RESULT_CHARS,
+                toolName,
+                args: readOwnRecord(request.params.arguments),
+            });
         };
         const logError = (error) => {
             const durationMs = Date.now() - start;
@@ -344,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
@@ -398,6 +411,16 @@ function createServer() {
             if (jmespathSyntaxError) {
                 return logCompletion({ content: [{ type: "text", text: jmespathSyntaxError }], isError: true }, { skipJmespath: true });
             }
+            // Enforce list-time filtering on direct calls: clients can call names that tools/list omits.
+            // filteredTools is extended by discover_tools; hidden-policy tools stay callable by design,
+            // but GITLAB_DENIED_TOOLS_REGEX always wins over the hidden exemption.
+            // Permission-mode denials fall through so handleToolCall reports its mode-specific error.
+            const hiddenAndNotDenied = hiddenToolSet.has(toolName) && !GITLAB_DENIED_TOOLS_REGEX?.test(toolName);
+            if (isToolAllowedByPermissionMode(toolName) &&
+                !hiddenAndNotDenied &&
+                !filteredTools.some(t => t.name === toolName)) {
+                throw new Error(`Tool "${toolName}" is not available on this server`);
+            }
             // Handle discover_tools meta-tool directly (needs access to mcpServer and filteredTools)
             if (toolName === "discover_tools") {
                 const category = request.params.arguments?.category?.trim()?.toLowerCase();
@@ -525,7 +548,20 @@ function createServer() {
             return logCompletion(result);
         }
         catch (error) {
-            logError(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;
@@ -846,15 +882,10 @@ export function hasStatelessSessionId(req) {
  * This avoids background timers that cause issues with multiple instances.
  */
 async function ensureValidOAuthToken() {
-    if (!oauthClient)
-        return;
-    if (oauthClient.hasValidToken())
-        return;
     try {
-        logger.info("OAuth token expired or missing, refreshing...");
-        const freshToken = await oauthClient.getAccessToken();
-        OAUTH_ACCESS_TOKEN = freshToken;
-        logger.info("OAuth token refreshed successfully");
+        await ensureOAuthToken(oauthClient, OAUTH_ACCESS_TOKEN, token => {
+            OAUTH_ACCESS_TOKEN = token;
+        });
     }
     catch (error) {
         logger.error({ err: error }, "Failed to refresh OAuth token");
@@ -873,33 +904,11 @@ function isToolAllowedByPermissionMode(toolName) {
     }
 }
 const GITLAB_DENIED_TOOLS_REGEX = (() => {
-    const pattern = getConfig("denied-tools-regex", "GITLAB_DENIED_TOOLS_REGEX");
-    if (!pattern)
-        return undefined;
-    // Reject patterns that are too long (potential ReDoS vector)
-    const MAX_PATTERN_LENGTH = 200;
-    if (pattern.length > MAX_PATTERN_LENGTH) {
-        logger.error(`GITLAB_DENIED_TOOLS_REGEX pattern exceeds ${MAX_PATTERN_LENGTH} chars. Ignoring.`);
-        return undefined;
-    }
-    // Reject patterns with nested quantifiers that can cause catastrophic backtracking (ReDoS)
-    // e.g., (a+)+, (a*)+, (a+)*, (a{1,})+
-    // Note: lookahead (?!), (?=), lookbehind (?<), and named groups (?<name>) are safe and allowed
-    const NESTED_QUANTIFIER_PATTERN = /(\(.*[+*?].*\)|\[.*\])[+*?]/;
-    if (NESTED_QUANTIFIER_PATTERN.test(pattern)) {
-        logger.error(`GITLAB_DENIED_TOOLS_REGEX contains potentially unsafe nested quantifiers. Ignoring.`);
-        return undefined;
-    }
-    try {
-        const regex = new RegExp(pattern);
-        // Dry-run against a sample string to catch immediate issues
-        regex.test("sample_tool_name");
-        return regex;
-    }
-    catch {
-        logger.error(`Invalid GITLAB_DENIED_TOOLS_REGEX pattern: "${pattern}". Ignoring.`);
-        return undefined;
+    const compiled = compileDeniedToolsRegex(getConfig("denied-tools-regex", "GITLAB_DENIED_TOOLS_REGEX"));
+    if (compiled.error) {
+        logger.error(compiled.error);
     }
+    return compiled.regex;
 })();
 // ---------------------------------------------------------------------------
 // Tool policy: approve / hidden sets
@@ -1101,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) {
@@ -1317,7 +1329,7 @@ if (GITLAB_MCP_OAUTH) {
     }
     logger.info("MCP OAuth enabled: GitLab OAuth proxy active (Private-Token/JOB-TOKEN headers bypass OAuth)");
 }
-if (getPositionalCliCommand(process.argv) !== "auth" &&
+if (!isCliInvocation(process.argv) &&
     !REMOTE_AUTHORIZATION &&
     !GITLAB_MCP_OAUTH &&
     !USE_OAUTH &&
@@ -1329,6 +1341,12 @@ if (getPositionalCliCommand(process.argv) !== "auth" &&
     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)
@@ -1345,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;
         }
     }
@@ -1415,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();
@@ -1486,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();
@@ -1519,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();
@@ -1755,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) {
@@ -3204,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);
@@ -3296,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}`);
     }
 }
 /**
@@ -3456,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) ---
@@ -3627,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);
@@ -3656,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);
@@ -3686,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);
@@ -3773,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);
@@ -4199,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);
@@ -4432,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();
 }
@@ -4447,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);
@@ -4461,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);
@@ -4496,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);
@@ -4531,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);
@@ -4552,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}`);
     }
 }
 /**
@@ -4571,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();
@@ -4652,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();
@@ -4683,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}`);
     }
 }
 /**
@@ -5275,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();
@@ -5348,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();
@@ -5400,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();
@@ -5453,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();
@@ -5476,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();
@@ -5490,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();
@@ -5518,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();
@@ -5580,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();
@@ -5600,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`;
@@ -5626,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();
@@ -6042,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);
@@ -11991,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
@@ -12003,11 +12037,8 @@ async function runServer() {
         if (USE_OAUTH) {
             logger.info("Using OAuth authentication...");
             try {
-                const gitlabBaseUrl = GITLAB_API_URL.replace(/\/api\/v4$/, "");
-                const oauthResult = await initializeOAuthClient(gitlabBaseUrl);
-                oauthClient = oauthResult.client;
-                OAUTH_ACCESS_TOKEN = oauthResult.accessToken;
-                logger.info("OAuth authentication successful");
+                initOAuthClient();
+                logger.info("OAuth enabled; token acquired lazily on first use.");
             }
             catch (error) {
                 logger.error({ err: error }, "OAuth authentication failed");
@@ -12049,7 +12080,16 @@ async function runServer() {
     }
 }
 async function main() {
-    if (getPositionalCliCommand(process.argv) === "auth") {
+    const cli = resolveCli(process.argv);
+    if (cli.kind === "help") {
+        process.stdout.write(cli.text);
+        process.exit(0);
+    }
+    if (cli.kind === "usage" || cli.kind === "refused") {
+        process.stderr.write(`${cli.message}\n`);
+        process.exit(2);
+    }
+    if (cli.kind === "auth" || getPositionalCliCommand(process.argv) === "auth") {
         try {
             await runAuthCommandAsync();
             process.exit(0);
@@ -12061,8 +12101,54 @@ async function main() {
             process.exit(1);
         }
     }
+    if (cli.kind === "run") {
+        if (!hasCliCredentials()) {
+            process.stderr.write("Missing GitLab credentials. Set --token or GITLAB_PERSONAL_ACCESS_TOKEN, or run `auth` with GITLAB_USE_OAUTH=true.\n");
+            process.exit(2);
+        }
+        try {
+            initOAuthClient();
+            const result = await handleToolCall({ name: cli.toolName, arguments: cli.args });
+            const masked = maskCliToolResult(cli.toolName, result);
+            const formatted = formatToolOutput({
+                result: masked,
+                mode: cli.output,
+                tableSpec: cli.tableSpec,
+            });
+            if (formatted.stderr) {
+                process.stderr.write(formatted.stderr);
+            }
+            process.stdout.write(formatted.stdout);
+            process.exit(formatted.isError ? 1 : 0);
+        }
+        catch (error) {
+            process.stderr.write(formatCliError(error));
+            logger.error({ err: error }, "cli command failed");
+            process.exit(1);
+        }
+    }
     await runServer();
 }
+function hasCliCredentials() {
+    return Boolean(GITLAB_PERSONAL_ACCESS_TOKEN || GITLAB_JOB_TOKEN || GITLAB_AUTH_COOKIE_PATH || USE_OAUTH);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function maskCliToolResult(toolName, result) {
+    const gitlabInstance = getConfig("api-url", "GITLAB_API_URL") || "https://gitlab.com";
+    const engine = maskingPolicyResolver?.select({
+        gitlabInstance,
+        allowBuiltinForUnscoped: true,
+    });
+    if (!engine || !isRecord(result)) {
+        return result;
+    }
+    const isPlainText = toolName === "get_pipeline_job_output" ||
+        toolName === "get_job_artifact_file" ||
+        (toolName === "download_release_asset" && !IS_REMOTE);
+    return engine.maskToolResult(result, { textFormat: isPlainText ? "plain" : "json" });
+}
 main().catch(error => {
     logger.fatal({ err: error }, "Fatal error in main()");
     process.exit(1);