@zereight/mcp-gitlab 2.1.70 → 2.2.1

package/build/index.js

@@ -1,5 +1,6 @@
 #!/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, GITLAB_MCP_COMPACT_RESULTS, GITLAB_MCP_COMPACT_RESULT_CHARS, } 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_PERMISSION_MODE_RAW, 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_GITLAB_WIKI_RAW, USE_MILESTONE, USE_MILESTONE_RAW, USE_OAUTH, USE_PIPELINE, USE_PIPELINE_RAW, 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, GITLAB_MCP_COMPACT_TOOL_NAMES, GITLAB_TOOL_PROFILE, } from "./config.js";
+import { getDeprecatedEnvWarnings } from "./deprecated-env.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");
@@ -60,17 +61,14 @@ function isConstantTimeSecretMatch(provided, expected) {
 }
 import { loadKeyMaterialFromEnv, looksLikeStatelessSessionId, mintSessionId, openSessionId, } from "./stateless/index.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { AsyncLocalStorage } from "node:async_hooks";
-import express from "express";
 import fetchCookie from "fetch-cookie";
 import fs from "node:fs";
 import { pipeline as streamPipeline } from "node:stream/promises";
 import os from "node:os";
-import { fetch as undiciFetch, File, FormData } from "undici";
+import { fetch as undiciFetch, File, FormData, } from "undici";
 import path from "node:path";
 import { CookieJar, parse as parseCookie } from "tough-cookie";
 import { URL } from "node:url";
@@ -83,12 +81,11 @@ 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";
 import { normalizeProxyClientIpForRateLimit } from "./utils/proxy-client-ip.js";
 import { getForwardedPublicBaseUrl, getForwardedRequestHost, } from "./utils/forwarded-public-base-url.js";
 import { registerDownloadProxy } from "./downloads/proxy.js";
 import { createDownloadToken } from "./utils/download-token.js";
+import { loadRemoteHttpStack } from "./server/remote-http-stack.js";
 import { determineTransportMode, TransportMode } from "./server/transport-mode.js";
 import { formatPrometheusMetrics } from "./server/metrics.js";
 import { SERVER_VERSION } from "./server/version.js";
@@ -109,9 +106,13 @@ import { buildBulkPublishDraftNotesBody, needsGitLab19_2BulkPublish, } from "./u
 import { appendFilterParam, appendFilterParams, cleanMutuallyExclusiveIdUsernameOptions, dropBlankArrayEntries, isBlankFilterValue, LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS, sanitizeToolArguments, } from "./utils/tool-args.js";
 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 { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { GitLabClientPool } from "./gitlab-client-pool.js";
-import { allTools, readOnlyTools, destructiveTools, deleteTools, parseEnabledToolsets, parseIndividualTools, buildFeatureFlagOverrides, isToolInEnabledToolset, TOOLSET_DEFINITIONS, ALL_TOOLSET_IDS, } from "./tools/registry.js";
+import { advertisesReadOnly, allTools, readOnlyTools, destructiveTools, deleteTools, parseEnabledToolsets, parseIndividualTools, buildFeatureFlagOverrides, isToolInEnabledToolset, findSmallestToolsetForTool, isToolsetFullyActive, listDiscoverableCategories, TOOLSET_DEFINITIONS, ALL_TOOLSET_IDS, } from "./tools/registry.js";
+import { buildUnavailableToolMessage, isSkippedByDiscoverActivation, } from "./tools/discover-activation.js";
+import { selectExposedTools } from "./tools/exposed-tools.js";
+import { createListedToolsCache, decorateToolsForList, } from "./tools/listed-tools.js";
+import { isExcludedBySlimProfile, shouldApplySlimToolProfile } from "./tools/tool-profile.js";
+import { shouldCompactToolResult } from "./utils/compact-tool-allowlist.js";
 import { BulkPublishDraftNotesSchema, CancelPipelineJobSchema, ErasePipelineJobSchema, CancelPipelineSchema, CreateBranchSchema, CreateDraftNoteSchema, CreateIssueLinkSchema, CreateIssueNoteSchema, CreateIssueSchema, CreateIssueEmojiReactionSchema, CreateIssueNoteEmojiReactionSchema, ListIssueEmojiReactionsSchema, ListIssueNoteEmojiReactionsSchema, CreateLabelSchema, // Added
 CreateMergeRequestNoteSchema, CreateMergeRequestDiscussionNoteSchema, CreateMergeRequestEmojiReactionSchema, CreateMergeRequestNoteEmojiReactionSchema, ListMergeRequestEmojiReactionsSchema, ListMergeRequestNoteEmojiReactionsSchema, CreateMergeRequestSchema, CreateMergeRequestThreadSchema, CreateNoteSchema, CreateCommitStatusSchema, CreateOrUpdateFileSchema, CreatePipelineSchema, CreateProjectMilestoneSchema, CreateGroupMilestoneSchema, CreateRepositorySchema, CreateGroupSchema, CreateWikiPageSchema, CreateGroupWikiPageSchema, DeleteBranchSchema, GetProtectedBranchSchema, ListProtectedBranchesSchema, ProtectBranchSchema, UnprotectBranchSchema, UpdateDefaultBranchSchema, DeleteDraftNoteSchema, DeleteGroupMilestoneSchema, DeleteGroupWikiPageSchema, DeleteIssueLinkSchema, DeleteIssueSchema, DeleteIssueEmojiReactionSchema, DeleteIssueNoteEmojiReactionSchema, DeleteLabelSchema, DeleteProjectMilestoneSchema, DeleteWikiPageSchema, DeleteMergeRequestNoteSchema, DeleteMergeRequestEmojiReactionSchema, DeleteMergeRequestNoteEmojiReactionSchema, EditProjectMilestoneSchema, EditGroupMilestoneSchema, ForkRepositorySchema, GetBranchDiffsSchema, GetBranchSchema, GetCommitDiffSchema, GetCommitSchema, GetFileBlameSchema, GitLabBlameEntrySchema, GetDraftNoteSchema, GetFileContentsSchema, GetIssueLinkSchema, GetIssueSchema, GetLabelSchema, GetMergeRequestDiffsSchema, GetMergeRequestSchema, GetMilestoneBurndownEventsSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, GetGroupMilestoneSchema, GetGroupMilestoneIssuesSchema, GetGroupMilestoneMergeRequestsSchema, GetGroupMilestoneBurndownEventsSchema, GetDeploymentSchema, CreateDeploymentSchema, UpdateDeploymentSchema, DeploymentApprovalSchema, ListDeploymentMergeRequestsSchema, GetEnvironmentSchema, UpdateEnvironmentSchema, StopEnvironmentSchema, StopStaleEnvironmentsSchema, DeleteReviewAppEnvironmentsSchema, PipelineTriggerIdSchema, ListPipelineTriggersSchema, CreatePipelineTriggerSchema, UpdatePipelineTriggerSchema, TriggerPipelineSchema, GetNamespaceSchema, GitLabCiLintResultSchema, GetPipelineJobOutputSchema, PipelineJobControlSchema, GetPipelineSchema, GetPipelineVariablesSchema, UpdatePipelineMetadataSchema, DeletePipelineSchema, PipelineReportSchema, WaitForPipelineSchema, WaitForPipelineJobSchema, PlayPipelineJobsSchema, GetProjectMilestoneSchema, GetProjectSchema, GetRepositoryTreeSchema, GetUsersSchema, GetUserSchema, GitLabUserFullSchema, WhoAmISchema, GitLabCurrentUserSchema, GetWikiPageSchema, GitLabCommitSchema, GitLabCommitStatusSchema, GitLabCompareResultSchema, GitLabContentSchema, GitLabCreateUpdateFileResponseSchema, GitLabDiffSchema, 
 // Discussion Schemas
@@ -149,7 +150,7 @@ const MCP_PROMPTS = [
         render: (args) => `Review merge request !${args.merge_request_iid ?? "<iid>"} in project ${args.project_id ?? "<project_id>"}:\n` +
             `1. Call list_merge_request_changed_files to get the changed file list (use excluded_file_patterns for lockfiles/dist/generated files).\n` +
             `2. Call get_merge_request_file_diff in batches of 3-5 files, prioritizing source over config/tests.\n` +
-            `3. Leave findings with create_merge_request_thread (inline, position: new_path/new_line) or create_merge_request_note (general).\n` +
+            `3. Leave inline findings with create_merge_request_thread (position: new_path/new_line). For a general note, call discover_tools with category "merge_requests", then create_merge_request_note.\n` +
             `4. Summarize the review verdict in a final top-level note.`,
     },
     {
@@ -179,6 +180,20 @@ const MCP_PROMPTS = [
             `3. Propose a remediation order, calling out any critical/high items with no available fix.`,
     },
 ];
+/**
+ * Error text for a call to a tool that tools/list omits.
+ * Suggests `discover_tools` only when that call would add the tool.
+ * Regex-denied tools stay blocked, and slim-excluded tools are not activated.
+ */
+function buildToolUnavailableMessage(toolName) {
+    return buildUnavailableToolMessage({
+        toolName,
+        toolset: findSmallestToolsetForTool(toolName),
+        deniedByRegex: GITLAB_DENIED_TOOLS_REGEX?.test(toolName) === true,
+        excludedBySlimProfile: isExcludedFromToolsetListing(toolName),
+        enabledByCurrentToolsets: isToolInEnabledToolset(toolName, enabledToolsets),
+    });
+}
 /**
  * Create a new MCP Server instance with request handlers registered.
  * Each transport connection gets its own Server instance to prevent
@@ -186,44 +201,26 @@ const MCP_PROMPTS = [
  */
 /** 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
-    const toolsAfterToolsets = allTools.filter(tool => isToolInEnabledToolset(tool.name, enabledToolsets));
-    // Step 2: Add GITLAB_TOOLS (individual tools bypass toolset filter)
-    const toolsetToolNames = new Set(toolsAfterToolsets.map(t => t.name));
-    const toolsAfterIndividual = [
-        ...toolsAfterToolsets,
-        ...allTools.filter(tool => individuallyEnabledTools.has(tool.name) && !toolsetToolNames.has(tool.name)),
-    ];
-    // Step 3: Add legacy flag overrides (USE_PIPELINE, USE_MILESTONE, USE_GITLAB_WIKI)
-    const afterIndividualNames = new Set(toolsAfterIndividual.map(t => t.name));
-    const toolsAfterLegacy = [
-        ...toolsAfterIndividual,
-        ...allTools.filter(tool => featureFlagOverrides.has(tool.name) && !afterIndividualNames.has(tool.name)),
-    ];
-    // Step 4: Permission mode filter (readonly / modify / full)
-    const toolsAfterReadOnly = GITLAB_PERMISSION_MODE === "full"
-        ? toolsAfterLegacy
-        : toolsAfterLegacy.filter(tool => isToolAllowedByPermissionMode(tool.name));
-    // Step 5: Regex denial filter
-    let filteredTools = GITLAB_DENIED_TOOLS_REGEX
-        ? toolsAfterReadOnly.filter(tool => !GITLAB_DENIED_TOOLS_REGEX.test(tool.name))
-        : [...toolsAfterReadOnly];
-    // Step 5.5: Always include discover_tools meta-tool (bypasses toolset filter)
-    const discoverTool = allTools.find(t => t.name === "discover_tools");
-    const filteredToolNames = new Set(filteredTools.map(t => t.name));
-    if (discoverTool && !filteredToolNames.has("discover_tools")) {
-        // Respect permission mode and regex denial filters
-        const passesPermissionMode = isToolAllowedByPermissionMode("discover_tools");
-        const passesRegex = !GITLAB_DENIED_TOOLS_REGEX?.test("discover_tools");
-        if (passesPermissionMode && passesRegex) {
-            filteredTools.push(discoverTool);
-        }
-    }
-    // Step 5.7: Remove hidden policy tools
-    if (hiddenToolSet.size > 0) {
-        filteredTools = filteredTools.filter(tool => !hiddenToolSet.has(tool.name));
-    }
+    const filteredTools = selectExposedTools({
+        tools: allTools,
+        isInEnabledToolset: toolName => isToolInEnabledToolset(toolName, enabledToolsets),
+        individuallyEnabledTools,
+        featureFlagOverrides,
+        isAllowedByPermissionMode: isToolAllowedByPermissionMode,
+        deniedToolsRegex: GITLAB_DENIED_TOOLS_REGEX,
+        hiddenToolNames: hiddenToolSet,
+        applySlimProfile,
+    });
+    const listedToolDecoration = {
+        readOnlyToolNames: new Set([...readOnlyTools].filter(toolName => advertisesReadOnly(toolName))),
+        destructiveToolNames: destructiveTools,
+        approveToolNames: approveToolSet,
+        jmespathArgument: JMESPATH_TOOL_ARGUMENT,
+        jmespathArgumentDescription: JMESPATH_TOOL_ARGUMENT_DESCRIPTION,
+    };
+    const listedToolsCache = { revision: 0 };
+    const decorateListedTools = (tools) => decorateToolsForList(tools, listedToolDecoration);
+    const getListedTools = createListedToolsCache(decorateListedTools);
     const mcpServer = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION,
@@ -262,57 +259,8 @@ function createServer() {
         };
     });
     mcpServer.server.setRequestHandler(ListToolsRequestSchema, async () => {
-        // Step 6: Gemini $schema cleanup + annotations (only dynamic step per request)
-        // <<< START: Remove $schema for Gemini compatibility >>>
-        const tools = filteredTools.map(tool => {
-            const modified = { ...tool };
-            // Safety net: remove $schema if present (toJSONSchema strips it for zod schemas,
-            // but manually-defined schemas like discover_tools may still have it)
-            if (modified.inputSchema &&
-                typeof modified.inputSchema === "object" &&
-                modified.inputSchema !== null) {
-                if ("$schema" in modified.inputSchema) {
-                    modified.inputSchema = { ...modified.inputSchema };
-                    delete modified.inputSchema.$schema;
-                }
-            }
-            // Add MCP tool annotations
-            modified.annotations = {
-                ...(readOnlyTools.has(tool.name) ? { readOnlyHint: true } : {}),
-                ...(destructiveTools.has(tool.name) ? { destructiveHint: true } : {}),
-                ...(approveToolSet.has(tool.name) ? { confirmationHint: true } : {}),
-                openWorldHint: true,
-            };
-            // Inject _confirmed optional parameter for approve-policy tools
-            if (approveToolSet.has(tool.name) && modified.inputSchema?.properties) {
-                modified.inputSchema = {
-                    ...modified.inputSchema,
-                    properties: {
-                        ...modified.inputSchema.properties,
-                        _confirmed: {
-                            type: "boolean",
-                            description: "Set to true to confirm execution of this approval-required tool.",
-                        },
-                    },
-                };
-            }
-            if (modified.inputSchema && typeof modified.inputSchema === "object") {
-                const properties = modified.inputSchema.properties && typeof modified.inputSchema.properties === "object"
-                    ? { ...modified.inputSchema.properties }
-                    : {};
-                if (!(JMESPATH_TOOL_ARGUMENT in properties)) {
-                    properties[JMESPATH_TOOL_ARGUMENT] = {
-                        type: "string",
-                        description: JMESPATH_TOOL_ARGUMENT_DESCRIPTION,
-                    };
-                    modified.inputSchema = { ...modified.inputSchema, properties };
-                }
-            }
-            return modified;
-        });
-        // <<< END: Remove $schema for Gemini compatibility >>>
         return {
-            tools, // return tool list with $schema removed
+            tools: getListedTools(filteredTools, listedToolsCache.revision),
         };
     });
     mcpServer.server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -331,9 +279,7 @@ function createServer() {
                 (toolName === "download_release_asset" && !IS_REMOTE);
             const filtered = applyJmespathToToolResult(result, jmespathExpression, {
                 ...completionOptions,
-                maskValue: maskingEngine
-                    ? (value) => maskingEngine.maskValue(value)
-                    : undefined,
+                maskValue: maskingEngine ? (value) => maskingEngine.maskValue(value) : undefined,
             });
             const masked = maskingEngine
                 ? maskingEngine.maskToolResult(filtered, {
@@ -342,7 +288,7 @@ function createServer() {
                 : filtered;
             return compactMcpToolResult({
                 result: masked,
-                enabled: GITLAB_MCP_COMPACT_RESULTS,
+                enabled: shouldCompactToolResult(toolName, GITLAB_MCP_COMPACT_RESULTS, GITLAB_MCP_COMPACT_TOOL_NAMES),
                 maxChars: GITLAB_MCP_COMPACT_RESULT_CHARS,
                 toolName,
                 args: readOwnRecord(request.params.arguments),
@@ -419,25 +365,34 @@ function createServer() {
             if (isToolAllowedByPermissionMode(toolName) &&
                 !hiddenAndNotDenied &&
                 !filteredTools.some(t => t.name === toolName)) {
-                throw new Error(`Tool "${toolName}" is not available on this server`);
+                throw new Error(buildToolUnavailableMessage(toolName));
             }
             // Handle discover_tools meta-tool directly (needs access to mcpServer and filteredTools)
             if (toolName === "discover_tools") {
                 const category = request.params.arguments?.category?.trim()?.toLowerCase();
                 const currentToolNames = new Set(filteredTools.map(t => t.name));
+                const isNotActivatable = (name) => isSkippedByDiscoverActivation({
+                    allowedByPermissionMode: isToolAllowedByPermissionMode(name),
+                    deniedByRegex: GITLAB_DENIED_TOOLS_REGEX?.test(name) === true,
+                    hidden: hiddenToolSet.has(name),
+                    excludedBySlimProfile: isExcludedFromToolsetListing(name),
+                });
                 if (!category) {
-                    // List available categories with activation status
-                    const categories = TOOLSET_DEFINITIONS.map(def => ({
-                        id: def.id,
-                        toolCount: def.tools.size,
-                        active: [...def.tools].some(t => currentToolNames.has(t)),
-                        isDefault: def.isDefault,
-                    }));
+                    // Fully listed only. Partial overlap with `core` must stay inactive so
+                    // clients still call discover_tools to add the missing tools. Tools this
+                    // handler skips (slim profile, regex, permission mode, hidden) do not
+                    // keep a toolset inactive.
+                    const categories = listDiscoverableCategories(currentToolNames, isNotActivatable);
                     return logCompletion({
-                        content: [{
+                        content: [
+                            {
                                 type: "text",
-                                text: JSON.stringify({ categories, hint: "Call discover_tools with a category name to activate it" }),
-                            }],
+                                text: JSON.stringify({
+                                    categories,
+                                    hint: "Call discover_tools with a category name to activate it",
+                                }),
+                            },
+                        ],
                     });
                 }
                 if (!ALL_TOOLSET_IDS.has(category)) {
@@ -458,8 +413,8 @@ function createServer() {
                         isError: true,
                     });
                 }
-                // Check if already fully active
-                const alreadyActive = [...toolsetDef.tools].every(t => currentToolNames.has(t));
+                // Same predicate as the category listing `active` flag.
+                const alreadyActive = isToolsetFullyActive(toolsetDef.tools, currentToolNames, isNotActivatable);
                 if (alreadyActive) {
                     return logCompletion({
                         content: [
@@ -477,11 +432,7 @@ function createServer() {
                         continue;
                     if (currentToolNames.has(tool.name))
                         continue;
-                    if (!isToolAllowedByPermissionMode(tool.name))
-                        continue;
-                    if (GITLAB_DENIED_TOOLS_REGEX?.test(tool.name))
-                        continue;
-                    if (hiddenToolSet.has(tool.name))
+                    if (isNotActivatable(tool.name))
                         continue;
                     newTools.push(tool);
                 }
@@ -496,6 +447,7 @@ function createServer() {
                     });
                 }
                 filteredTools.push(...newTools);
+                listedToolsCache.revision += 1;
                 // Notify client that tool list has changed
                 try {
                     await mcpServer.server.sendToolListChanged();
@@ -506,14 +458,16 @@ function createServer() {
                 const addedNames = newTools.map(t => t.name);
                 logger.info({ event: "toolset_activated", category, toolCount: addedNames.length }, `Activated toolset: ${category} (+${addedNames.length} tools)`);
                 return logCompletion({
-                    content: [{
+                    content: [
+                        {
                             type: "text",
                             text: JSON.stringify({
                                 activated: category,
                                 addedTools: addedNames,
                                 totalTools: filteredTools.length,
                             }),
-                        }],
+                        },
+                    ],
                 });
             }
             // Check approve policy: tool is exposed but requires explicit confirmation
@@ -548,9 +502,9 @@ function createServer() {
             return logCompletion(result);
         }
         catch (error) {
-            const isGitLabApiError = error instanceof GitLabApiError;
+            const isRecoverableToolError = error instanceof GitLabApiError || error instanceof ToolInputError;
             const safeError = logError(error);
-            if (isGitLabApiError) {
+            if (isRecoverableToolError) {
                 return {
                     content: [
                         {
@@ -570,7 +524,10 @@ function createServer() {
  * Validate configuration at startup
  */
 function isLoopbackBindHost(host) {
-    const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    const normalized = host
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "");
     const isIpv4Loopback = /^127(?:\.\d{1,3}){3}$/.test(normalized);
     return (normalized === "localhost" ||
         isIpv4Loopback ||
@@ -578,7 +535,10 @@ function isLoopbackBindHost(host) {
         normalized === "0:0:0:0:0:0:0:1");
 }
 function formatHostWithPort(host, port) {
-    const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    const normalized = host
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "");
     if (!normalized || normalized === "0.0.0.0" || normalized === "::")
         return null;
     if (normalized.includes(":"))
@@ -929,6 +889,12 @@ const hiddenToolSet = new Set((GITLAB_TOOL_POLICY_HIDDEN_RAW || "")
             logger.warn({ event: "unknown_approve_tool", name }, `GITLAB_TOOL_POLICY_APPROVE contains unknown tool: "${name}"`);
         }
     }
+    if (GITLAB_MCP_COMPACT_TOOL_NAMES.size > 0) {
+        const unknownCompactTools = [...GITLAB_MCP_COMPACT_TOOL_NAMES].filter(name => !knownToolNames.has(name));
+        if (unknownCompactTools.length > 0) {
+            logger.warn(`Unknown tool names in GITLAB_MCP_COMPACT_TOOLS (will be ignored): ${unknownCompactTools.join(", ")}`);
+        }
+    }
     for (const name of hiddenToolSet) {
         if (!knownToolNames.has(name)) {
             logger.warn({ event: "unknown_hidden_tool", name }, `GITLAB_TOOL_POLICY_HIDDEN contains unknown tool: "${name}"`);
@@ -1228,6 +1194,13 @@ const downloadRedirectOptions = () => ({
 const enabledToolsets = parseEnabledToolsets(GITLAB_TOOLSETS_RAW);
 const individuallyEnabledTools = parseIndividualTools(GITLAB_TOOLS_RAW);
 const featureFlagOverrides = buildFeatureFlagOverrides();
+const applySlimProfile = shouldApplySlimToolProfile(GITLAB_TOOL_PROFILE, GITLAB_TOOLSETS_RAW);
+if (GITLAB_TOOL_PROFILE === "slim" && !applySlimProfile) {
+    logger.warn("GITLAB_TOOL_PROFILE=slim is ignored because GITLAB_TOOLSETS is set");
+}
+function isExcludedFromToolsetListing(toolName) {
+    return isExcludedBySlimProfile(toolName, applySlimProfile, individuallyEnabledTools);
+}
 // Warn about potentially confusing configuration
 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). " +
@@ -1347,6 +1320,13 @@ class GitLabApiError extends Error {
         this.name = "GitLabApiError";
     }
 }
+class ToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolInputError";
+    }
+}
+const MERGE_REQUEST_IDENTIFIER_REQUIRED = "Either merge_request_iid or source_branch must be provided";
 /**
  * Utility function for handling GitLab API errors
  * API 에러 처리를 위한 유틸리티 함수 (Utility function for handling API errors)
@@ -1373,6 +1353,39 @@ async function handleGitLabError(response) {
         }
     }
 }
+const USER_API_INSUFFICIENT_SCOPE_MESSAGE = "GitLab API error: 403 Forbidden on GET /api/v4/user (insufficient scope). The token was accepted, but read_user (classic PAT) or User API read (fine-grained User:Read) is required for whoami, my_issues, and other current-user tools.";
+const USER_API_HEALTH_WARNING = "GET /api/v4/user returned 403 (insufficient scope). The token was accepted and other tools may still work. Grant read_user (classic) or User:Read (fine-grained) for whoami, my_issues, and version metadata.";
+function isGitLabUserApiRateLimitBody(errorBody) {
+    return errorBody.includes("User API Key Rate limit exceeded");
+}
+function isGitLabInsufficientUserScopeBody(errorBody) {
+    // Fine-grained PATs use insufficient_granular_scope, which does not contain insufficient_scope.
+    return (errorBody.includes("insufficient_granular_scope") || errorBody.includes("insufficient_scope"));
+}
+async function isInsufficientUserScopeForbiddenAsync(response) {
+    if (response.status !== 403) {
+        return false;
+    }
+    const errorBody = await response.text();
+    return isGitLabInsufficientUserScopeBody(errorBody);
+}
+async function throwUserApiScopeErrorUnlessRateLimitedAsync(response) {
+    const errorBody = await response.clone().text();
+    // Rate-limit and other 403s keep the upstream body via handleGitLabError.
+    if (isGitLabUserApiRateLimitBody(errorBody) || !isGitLabInsufficientUserScopeBody(errorBody)) {
+        return;
+    }
+    throw new GitLabApiError(USER_API_INSUFFICIENT_SCOPE_MESSAGE);
+}
+async function authenticateWithJobTokenFallbackAsync(response) {
+    if (response.ok ||
+        (response.status !== 401 && response.status !== 403) ||
+        !(GITLAB_JOB_TOKEN || usesJobTokenHeader())) {
+        return false;
+    }
+    const jobResponse = await fetch(`${getEffectiveApiUrl()}/job`, getFetchConfig());
+    return jobResponse.ok;
+}
 /**
  * @param {string} projectId - The project ID parameter passed to the function
  * @returns {string} The project ID to use for the API call
@@ -1812,7 +1825,9 @@ async function resolveNamesToIds(projectPath, namespaceKind, labelNames, usernam
     // One alias per label — exact title match via the `title` argument, includes ancestor
     // group labels, single round trip with no pagination needed.
     const varDefs = labelNames.map((_, i) => `$l${i}: String!`).join(", ");
-    const aliases = labelNames.map((_, i) => `l${i}: labels(title: $l${i}, includeAncestorGroups: true, first: 1) { nodes { id } }`).join(" ");
+    const aliases = labelNames
+        .map((_, i) => `l${i}: labels(title: $l${i}, includeAncestorGroups: true, first: 1) { nodes { id } }`)
+        .join(" ");
     const rootField = namespaceKind === "group" ? "group" : "project";
     const data = await executeGraphQL(`query($path: ID!, $usernames: [String!]!${varDefs ? `, ${varDefs}` : ""}) {
       ${rootField}(fullPath: $path) { ${aliases || "__typename"} }
@@ -3407,7 +3422,9 @@ async function updateIssueNote(projectId, issueIid, discussionId, noteId, body,
 async function createIssueNote(projectId, issueIid, discussionId, body, createdAt) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     const basePath = `${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(getEffectiveProjectId(projectId))}/issues/${encodeGitLabPathSegment(issueIid)}`;
-    const url = new URL(discussionId ? `${basePath}/discussions/${encodeGitLabPathSegment(discussionId)}/notes` : `${basePath}/notes`);
+    const url = new URL(discussionId
+        ? `${basePath}/discussions/${encodeGitLabPathSegment(discussionId)}/notes`
+        : `${basePath}/notes`);
     const payload = { body };
     if (createdAt) {
         payload.created_at = createdAt;
@@ -3816,7 +3833,7 @@ async function getMergeRequest(projectId, mergeRequestIid, branchName) {
         url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(getEffectiveProjectId(projectId))}/merge_requests?source_branch=${encodeURIComponent(branchName)}`);
     }
     else {
-        throw new Error("Either mergeRequestIid or branchName must be provided");
+        throw new ToolInputError(MERGE_REQUEST_IDENTIFIER_REQUIRED);
     }
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
@@ -4050,7 +4067,7 @@ async function buildMergeRequestDeploymentSummary(projectId, mergeRequest) {
 async function getMergeRequestDiffs(projectId, mergeRequestIid, branchName, view) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     if (!mergeRequestIid && !branchName) {
-        throw new Error("Either mergeRequestIid or branchName must be provided");
+        throw new ToolInputError(MERGE_REQUEST_IDENTIFIER_REQUIRED);
     }
     if (branchName && !mergeRequestIid) {
         const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
@@ -4080,7 +4097,7 @@ async function getMergeRequestDiffs(projectId, mergeRequestIid, branchName, view
 async function listMergeRequestDiffs(projectId, mergeRequestIid, branchName, page, perPage, unidiff) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     if (!mergeRequestIid && !branchName) {
-        throw new Error("Either mergeRequestIid or branchName must be provided");
+        throw new ToolInputError(MERGE_REQUEST_IDENTIFIER_REQUIRED);
     }
     if (branchName && !mergeRequestIid) {
         const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
@@ -4116,7 +4133,7 @@ async function listMergeRequestDiffs(projectId, mergeRequestIid, branchName, pag
 async function listMergeRequestChangedFiles(projectId, mergeRequestIid, branchName, excludedFilePatterns) {
     projectId = decodeURIComponent(projectId);
     if (!mergeRequestIid && !branchName) {
-        throw new Error("Either mergeRequestIid or branchName must be provided");
+        throw new ToolInputError(MERGE_REQUEST_IDENTIFIER_REQUIRED);
     }
     if (branchName && !mergeRequestIid) {
         const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
@@ -4150,7 +4167,7 @@ async function listMergeRequestChangedFiles(projectId, mergeRequestIid, branchNa
 async function getMergeRequestFileDiff(projectId, filePaths, mergeRequestIid, branchName, unidiff) {
     projectId = decodeURIComponent(projectId);
     if (!mergeRequestIid && !branchName) {
-        throw new Error("Either mergeRequestIid or branchName must be provided");
+        throw new ToolInputError(MERGE_REQUEST_IDENTIFIER_REQUIRED);
     }
     if (branchName && !mergeRequestIid) {
         const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
@@ -4235,7 +4252,7 @@ async function getBranchDiffs(projectId, from, to, straight) {
 async function updateMergeRequest(projectId, options, mergeRequestIid, branchName) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     if (!mergeRequestIid && !branchName) {
-        throw new Error("Either mergeRequestIid or branchName must be provided");
+        throw new ToolInputError(MERGE_REQUEST_IDENTIFIER_REQUIRED);
     }
     if (branchName && !mergeRequestIid) {
         const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
@@ -5380,7 +5397,8 @@ async function deploymentRequest(projectId, path = "", method = "GET", body, que
             url.searchParams.set(key, String(value));
     }
     const response = await fetch(url.toString(), {
-        ...getFetchConfig(), method,
+        ...getFetchConfig(),
+        method,
         body: body === undefined ? undefined : JSON.stringify(body),
     });
     await handleGitLabError(response);
@@ -5430,7 +5448,11 @@ async function environmentRequest(projectId, path, method, body, query) {
     for (const [key, value] of Object.entries(query ?? {}))
         if (value !== undefined)
             url.searchParams.set(key, String(value));
-    const response = await fetch(url.toString(), { ...getFetchConfig(), method, body: body === undefined ? undefined : JSON.stringify(body) });
+    const response = await fetch(url.toString(), {
+        ...getFetchConfig(),
+        method,
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
     await handleGitLabError(response);
     return response.status === 204 ? { success: true } : response.json();
 }
@@ -5450,7 +5472,11 @@ async function triggerPipeline(projectId, token, ref, variables, inputs) {
         body.variables = variables;
     if (inputs)
         body.inputs = inputs;
-    const response = await fetch(url.toString(), { ...getFetchConfig(), method: "POST", body: Object.keys(body).length ? JSON.stringify(body) : undefined });
+    const response = await fetch(url.toString(), {
+        ...getFetchConfig(),
+        method: "POST",
+        body: Object.keys(body).length ? JSON.stringify(body) : undefined,
+    });
     await handleGitLabError(response);
     return response.json();
 }
@@ -6607,6 +6633,9 @@ async function getCurrentUser() {
             }
         }
     }
+    if (response.status === 403) {
+        await throwUserApiScopeErrorUnlessRateLimitedAsync(response);
+    }
     await handleGitLabError(response);
     throw new Error(`GitLab API error: ${response.status} ${response.statusText}`);
 }
@@ -8021,8 +8050,7 @@ async function handleToolCall(params) {
             }
             case "push_files": {
                 const args = PushFilesSchema.parse(params.arguments);
-                if (GITLAB_PERMISSION_MODE === "modify" &&
-                    fileOperationsIncludeDeleteOrMove(args.files)) {
+                if (GITLAB_PERMISSION_MODE === "modify" && fileOperationsIncludeDeleteOrMove(args.files)) {
                     throw new Error("push_files does not allow delete or move actions in modify mode");
                 }
                 const result = await createCommit(args.project_id, args.commit_message, args.branch, args.files.map(f => ({
@@ -8527,6 +8555,9 @@ async function handleToolCall(params) {
                 const response = await fetch(url.toString(), {
                     ...getFetchConfig(),
                 });
+                if (response.status === 403) {
+                    await throwUserApiScopeErrorUnlessRateLimitedAsync(response);
+                }
                 await handleGitLabError(response);
                 const data = await response.json();
                 const user = GitLabCurrentUserSchema.parse(data);
@@ -8893,7 +8924,14 @@ async function handleToolCall(params) {
                 const args = DeleteWorkItemEmojiReactionSchema.parse(params.arguments);
                 const { workItemGID } = await resolveWorkItemGID(args.project_id, args.iid);
                 const result = await removeGraphQLAwardEmoji(workItemGID, args.name);
-                return { content: [{ type: "text", text: JSON.stringify(result ?? { status: "success", message: "Work item emoji reaction removed" }) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result ?? { status: "success", message: "Work item emoji reaction removed" }),
+                        },
+                    ],
+                };
             }
             case "create_work_item_note_emoji_reaction": {
                 const args = CreateWorkItemNoteEmojiReactionSchema.parse(params.arguments);
@@ -8903,7 +8941,14 @@ async function handleToolCall(params) {
             case "delete_work_item_note_emoji_reaction": {
                 const args = DeleteWorkItemNoteEmojiReactionSchema.parse(params.arguments);
                 const result = await removeGraphQLAwardEmoji(args.note_id, args.name);
-                return { content: [{ type: "text", text: JSON.stringify(result ?? { status: "success", message: "Work item note emoji reaction removed" }) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result ?? { status: "success", message: "Work item note emoji reaction removed" }),
+                        },
+                    ],
+                };
             }
             case "get_timeline_events": {
                 const args = GetTimelineEventsSchema.parse(params.arguments);
@@ -9106,23 +9151,55 @@ async function handleToolCall(params) {
             }
             case "get_pipeline_variables": {
                 const { project_id, pipeline_id, page, per_page } = GetPipelineVariablesSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await getPipelineVariables(project_id, pipeline_id, page, per_page)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await getPipelineVariables(project_id, pipeline_id, page, per_page)),
+                        },
+                    ],
+                };
             }
             case "get_pipeline_test_report": {
                 const { project_id, pipeline_id, page, per_page } = PipelineReportSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await getPipelineReport(project_id, pipeline_id, false, page, per_page)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await getPipelineReport(project_id, pipeline_id, false, page, per_page)),
+                        },
+                    ],
+                };
             }
             case "get_pipeline_test_report_summary": {
                 const { project_id, pipeline_id, page, per_page } = PipelineReportSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await getPipelineReport(project_id, pipeline_id, true, page, per_page)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await getPipelineReport(project_id, pipeline_id, true, page, per_page)),
+                        },
+                    ],
+                };
             }
             case "delete_pipeline": {
                 const { project_id, pipeline_id } = DeletePipelineSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await deletePipeline(project_id, pipeline_id)) }] };
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await deletePipeline(project_id, pipeline_id)) },
+                    ],
+                };
             }
             case "update_pipeline_metadata": {
                 const { project_id, pipeline_id, name } = UpdatePipelineMetadataSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await updatePipelineMetadata(project_id, pipeline_id, name)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await updatePipelineMetadata(project_id, pipeline_id, name)),
+                        },
+                    ],
+                };
             }
             case "list_deployments": {
                 const args = ListDeploymentsSchema.parse(params.arguments);
@@ -9141,23 +9218,58 @@ async function handleToolCall(params) {
             }
             case "create_deployment": {
                 const { project_id, ...body } = CreateDeploymentSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await deploymentRequest(project_id, "", "POST", body)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await deploymentRequest(project_id, "", "POST", body)),
+                        },
+                    ],
+                };
             }
             case "update_deployment": {
                 const { project_id, deployment_id, ...body } = UpdateDeploymentSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}`, "PUT", body)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}`, "PUT", body)),
+                        },
+                    ],
+                };
             }
             case "delete_deployment": {
                 const { project_id, deployment_id } = GetDeploymentSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}`, "DELETE")) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}`, "DELETE")),
+                        },
+                    ],
+                };
             }
             case "list_deployment_merge_requests": {
                 const { project_id, deployment_id, ...query } = ListDeploymentMergeRequestsSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}/merge_requests`, "GET", undefined, query)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}/merge_requests`, "GET", undefined, query)),
+                        },
+                    ],
+                };
             }
             case "approve_deployment": {
                 const { project_id, deployment_id, ...body } = DeploymentApprovalSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}/approval`, "POST", body)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await deploymentRequest(project_id, `/${encodeGitLabPathSegment(deployment_id)}/approval`, "POST", body)),
+                        },
+                    ],
+                };
             }
             case "list_environments": {
                 const args = ListEnvironmentsSchema.parse(params.arguments);
@@ -9176,47 +9288,124 @@ async function handleToolCall(params) {
             }
             case "update_environment": {
                 const { project_id, environment_id, ...body } = UpdateEnvironmentSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await environmentRequest(project_id, `/${encodeGitLabPathSegment(environment_id)}`, "PUT", body)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await environmentRequest(project_id, `/${encodeGitLabPathSegment(environment_id)}`, "PUT", body)),
+                        },
+                    ],
+                };
             }
             case "delete_environment": {
                 const { project_id, environment_id } = GetEnvironmentSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await environmentRequest(project_id, `/${encodeGitLabPathSegment(environment_id)}`, "DELETE")) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await environmentRequest(project_id, `/${encodeGitLabPathSegment(environment_id)}`, "DELETE")),
+                        },
+                    ],
+                };
             }
             case "stop_environment": {
                 const { project_id, environment_id, force } = StopEnvironmentSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await environmentRequest(project_id, `/${encodeGitLabPathSegment(environment_id)}/stop`, "POST", undefined, { force })) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await environmentRequest(project_id, `/${encodeGitLabPathSegment(environment_id)}/stop`, "POST", undefined, { force })),
+                        },
+                    ],
+                };
             }
             case "stop_stale_environments": {
                 const { project_id, before } = StopStaleEnvironmentsSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await environmentRequest(project_id, "/stop_stale", "POST", undefined, { before })) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await environmentRequest(project_id, "/stop_stale", "POST", undefined, { before })),
+                        },
+                    ],
+                };
             }
             case "delete_review_app_environments": {
                 const { project_id, ...query } = DeleteReviewAppEnvironmentsSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await environmentRequest(project_id, "/review_apps", "DELETE", undefined, query)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await environmentRequest(project_id, "/review_apps", "DELETE", undefined, query)),
+                        },
+                    ],
+                };
             }
             case "list_pipeline_triggers": {
                 const { project_id } = ListPipelineTriggersSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(redactSensitiveGitLabFields(await pipelineTriggerRequest(project_id))) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(redactSensitiveGitLabFields(await pipelineTriggerRequest(project_id))),
+                        },
+                    ],
+                };
             }
             case "get_pipeline_trigger": {
                 const { project_id, trigger_id } = PipelineTriggerIdSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(redactSensitiveGitLabFields(await pipelineTriggerRequest(project_id, `/${encodeGitLabPathSegment(trigger_id)}`))) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(redactSensitiveGitLabFields(await pipelineTriggerRequest(project_id, `/${encodeGitLabPathSegment(trigger_id)}`))),
+                        },
+                    ],
+                };
             }
             case "create_pipeline_trigger": {
                 const { project_id, ...body } = CreatePipelineTriggerSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await pipelineTriggerRequest(project_id, "", "POST", body)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await pipelineTriggerRequest(project_id, "", "POST", body)),
+                        },
+                    ],
+                };
             }
             case "update_pipeline_trigger": {
                 const { project_id, trigger_id, ...body } = UpdatePipelineTriggerSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(redactSensitiveGitLabFields(await pipelineTriggerRequest(project_id, `/${encodeGitLabPathSegment(trigger_id)}`, "PUT", body))) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(redactSensitiveGitLabFields(await pipelineTriggerRequest(project_id, `/${encodeGitLabPathSegment(trigger_id)}`, "PUT", body))),
+                        },
+                    ],
+                };
             }
             case "delete_pipeline_trigger": {
                 const { project_id, trigger_id } = PipelineTriggerIdSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await pipelineTriggerRequest(project_id, `/${encodeGitLabPathSegment(trigger_id)}`, "DELETE")) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await pipelineTriggerRequest(project_id, `/${encodeGitLabPathSegment(trigger_id)}`, "DELETE")),
+                        },
+                    ],
+                };
             }
             case "trigger_pipeline": {
                 const { project_id, token, ref, variables, inputs } = TriggerPipelineSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await triggerPipeline(project_id, token, ref, variables, inputs)) }] };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await triggerPipeline(project_id, token, ref, variables, inputs)),
+                        },
+                    ],
+                };
             }
             case "list_pipeline_jobs": {
                 const { project_id, pipeline_id, ...options } = ListPipelineJobsSchema.parse(params.arguments);
@@ -9583,7 +9772,7 @@ async function handleToolCall(params) {
                 };
             }
             case "play_pipeline_jobs": {
-                const { project_id, job_ids, job_variables_attributes, timeout_seconds, poll_interval_seconds } = PlayPipelineJobsSchema.parse(params.arguments);
+                const { project_id, job_ids, job_variables_attributes, timeout_seconds, poll_interval_seconds, } = PlayPipelineJobsSchema.parse(params.arguments);
                 const jobs = await playPipelineJobs(project_id, job_ids, job_variables_attributes, timeout_seconds, poll_interval_seconds);
                 return { content: [{ type: "text", text: JSON.stringify(jobs) }] };
             }
@@ -9613,7 +9802,11 @@ async function handleToolCall(params) {
             }
             case "erase_pipeline_job": {
                 const { project_id, job_id } = ErasePipelineJobSchema.parse(params.arguments);
-                return { content: [{ type: "text", text: JSON.stringify(await erasePipelineJob(project_id, job_id)) }] };
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await erasePipelineJob(project_id, job_id)) },
+                    ],
+                };
             }
             case "wait_for_pipeline": {
                 const { project_id, pipeline_id, timeout_seconds, poll_interval_seconds } = WaitForPipelineSchema.parse(params.arguments);
@@ -9645,7 +9838,15 @@ async function handleToolCall(params) {
                     }
                     const downloadUrl = buildDownloadUrl("job-artifacts", { project_id, job_id });
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ download_url: downloadUrl, filename: `artifacts_job_${job_id}.zip` }) }],
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    download_url: downloadUrl,
+                                    filename: `artifacts_job_${job_id}.zip`,
+                                }),
+                            },
+                        ],
                     };
                 }
                 const filePath = await downloadJobArtifacts(project_id, job_id, local_path);
@@ -10148,7 +10349,12 @@ async function handleToolCall(params) {
                         filename: args.filename,
                     });
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ download_url: downloadUrl, filename: args.filename }) }],
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ download_url: downloadUrl, filename: args.filename }),
+                            },
+                        ],
                     };
                 }
                 const result = await downloadAttachment(args.project_id, args.secret, args.filename, args.local_path);
@@ -10254,7 +10460,15 @@ async function handleToolCall(params) {
                         direct_asset_path: args.direct_asset_path,
                     });
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ download_url: downloadUrl, filename: args.direct_asset_path.split("/").pop() || args.direct_asset_path }) }],
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    download_url: downloadUrl,
+                                    filename: args.direct_asset_path.split("/").pop() || args.direct_asset_path,
+                                }),
+                            },
+                        ],
                     };
                 }
                 const assetContent = await downloadReleaseAsset(args.project_id, args.tag_name, args.direct_asset_path);
@@ -10437,17 +10651,13 @@ async function handleToolCall(params) {
                 HealthCheckSchema.parse(params.arguments ?? {});
                 const url = new URL(`${getEffectiveApiUrl()}/user`);
                 const response = await fetch(url.toString(), getFetchConfig());
-                let authenticated = response.ok;
-                if (!authenticated &&
-                    (response.status === 401 || response.status === 403) &&
-                    (GITLAB_JOB_TOKEN || usesJobTokenHeader())) {
-                    const jobUrl = new URL(`${getEffectiveApiUrl()}/job`);
-                    const jobResponse = await fetch(jobUrl.toString(), getFetchConfig());
-                    authenticated = jobResponse.ok;
-                }
-                const versionMetadata = authenticated
-                    ? await fetchGitLabVersionMetadata()
-                    : null;
+                const jobAuthenticated = await authenticateWithJobTokenFallbackAsync(response);
+                // insufficient_scope and insufficient_granular_scope mean the token was accepted
+                // but User API scope is missing.
+                // Rate-limit and authentication-ban 403s stay unauthenticated.
+                const insufficientUserScope = !jobAuthenticated && (await isInsufficientUserScopeForbiddenAsync(response));
+                const authenticated = response.ok || jobAuthenticated || insufficientUserScope;
+                const versionMetadata = authenticated && !insufficientUserScope ? await fetchGitLabVersionMetadata() : null;
                 return {
                     content: [
                         {
@@ -10457,6 +10667,7 @@ async function handleToolCall(params) {
                                 authenticated,
                                 gitlab_url: getEffectiveApiUrl(),
                                 mcp_server_version: SERVER_VERSION,
+                                ...(insufficientUserScope ? { user_api_warning: USER_API_HEALTH_WARNING } : {}),
                                 ...(versionMetadata ?? {}),
                             }),
                         },
@@ -10510,7 +10721,9 @@ async function handleToolCall(params) {
                 });
                 await handleGitLabError(response);
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ status: "deleted", branch: args.branch_name }) }],
+                    content: [
+                        { type: "text", text: JSON.stringify({ status: "deleted", branch: args.branch_name }) },
+                    ],
                 };
             }
             case "list_protected_branches": {
@@ -10585,7 +10798,12 @@ async function handleToolCall(params) {
                 });
                 await handleGitLabError(response);
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ status: "unprotected", branch: args.branch_name }) }],
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ status: "unprotected", branch: args.branch_name }),
+                        },
+                    ],
                 };
             }
             case "update_default_branch": {
@@ -10601,7 +10819,16 @@ async function handleToolCall(params) {
                 await handleGitLabError(response);
                 const data = await response.json();
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ status: "updated", default_branch: args.default_branch, project: data }) }],
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "updated",
+                                default_branch: args.default_branch,
+                                project: data,
+                            }),
+                        },
+                    ],
                 };
             }
             default:
@@ -10656,6 +10883,7 @@ function buildDownloadProxyDeps() {
  * Start server with traditional SSE transport
  */
 async function startSSEServer() {
+    const { express, rateLimit, ipKeyGenerator, SSEServerTransport } = await loadRemoteHttpStack();
     const app = express();
     const sseAuthToken = getConfig("sse-auth-token", "SSE_AUTH_TOKEN");
     if (MCP_TRUST_PROXY) {
@@ -10692,7 +10920,8 @@ async function startSSEServer() {
         const host = req.headers.host;
         const forwardedHost = MCP_TRUST_PROXY ? getForwardedRequestHost(req, true) : undefined;
         const requestHosts = [host, forwardedHost].filter((value) => Boolean(value));
-        if (requestHosts.length === 0 || !requestHosts.some(requestHost => effectiveHosts.has(requestHost))) {
+        if (requestHosts.length === 0 ||
+            !requestHosts.some(requestHost => effectiveHosts.has(requestHost))) {
             res.status(403).json({ error: "Invalid Host header" });
             return;
         }
@@ -10867,6 +11096,7 @@ async function startSSEServer() {
  * Start server with Streamable HTTP transport
  */
 async function startStreamableHTTPServer() {
+    const { express, rateLimit, ipKeyGenerator, StreamableHTTPServerTransport, mcpAuthRouter, requireBearerAuth, } = await loadRemoteHttpStack();
     const app = express();
     // Session IDs are untrusted map keys. A null prototype prevents inherited
     // names such as "constructor" from masquerading as live transports.
@@ -11399,9 +11629,7 @@ async function startStreamableHTTPServer() {
         // ipKeyGenerator for correct IPv6 subnet handling.
         const rateLimitOptions = { keyGenerator: mcpRateLimitKeyGenerator };
         const parsedRegisterLimit = Number(process.env.OAUTH_REGISTER_RATE_LIMIT_PER_HOUR);
-        const OAUTH_REGISTER_RATE_LIMIT_PER_HOUR = Number.isInteger(parsedRegisterLimit) && parsedRegisterLimit >= 1
-            ? parsedRegisterLimit
-            : 20;
+        const OAUTH_REGISTER_RATE_LIMIT_PER_HOUR = Number.isInteger(parsedRegisterLimit) && parsedRegisterLimit >= 1 ? parsedRegisterLimit : 20;
         const clientRegistrationRateLimitOptions = {
             ...rateLimitOptions,
             windowMs: 60 * 60 * 1000, // 1 hour
@@ -11501,9 +11729,7 @@ async function startStreamableHTTPServer() {
             ? staticMcpBearerAuth
             : (_req, _res, next) => next();
     const rejectUnknownStatefulSession = (req, res, next) => {
-        const usesStatelessSessions = OAUTH_STATELESS_MODE &&
-            STATELESS_MATERIAL &&
-            (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH);
+        const usesStatelessSessions = OAUTH_STATELESS_MODE && STATELESS_MATERIAL && (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH);
         const sessionId = readMcpSessionIdHeader(req);
         if (!usesStatelessSessions && sessionId && !streamableTransports[sessionId]) {
             res.status(404).json({ error: "Session not found" });
@@ -11521,7 +11747,9 @@ async function startStreamableHTTPServer() {
         // entirely and derive the session auth from either the current request
         // headers (init) or a sealed Mcp-Session-Id (subsequent requests).
         // Rate limiting is disabled here because there is no shared counter.
-        if (OAUTH_STATELESS_MODE && STATELESS_MATERIAL && (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH)) {
+        if (OAUTH_STATELESS_MODE &&
+            STATELESS_MATERIAL &&
+            (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH)) {
             await handleStatelessMcpRequest(req, res, STATELESS_MATERIAL, OAUTH_STATELESS_SESSION_TTL_SECONDS);
             return;
         }
@@ -11802,7 +12030,9 @@ async function startStreamableHTTPServer() {
             });
             return;
         }
-        if (OAUTH_STATELESS_MODE && STATELESS_MATERIAL && (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH)) {
+        if (OAUTH_STATELESS_MODE &&
+            STATELESS_MATERIAL &&
+            (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH)) {
             res.setHeader("Allow", "POST");
             res.status(405).json({
                 error: "Method Not Allowed",
@@ -12059,16 +12289,16 @@ async function runServer() {
         }
         logger.info(`Configured GitLab API URLs: ${GITLAB_API_URLS.join(", ")}`);
         logger.info(`Default GitLab API URL: ${GITLAB_API_URL}`);
-        if (GITLAB_ALLOWED_GROUPS_RAW) {
-            if (GITLAB_OAUTH_ALLOWED_GROUPS_RAW) {
-                logger.warn("GITLAB_ALLOWED_GROUPS is set but ignored — GITLAB_OAUTH_ALLOWED_GROUPS takes precedence.");
-            }
-            else {
-                logger.warn("GITLAB_ALLOWED_GROUPS is deprecated. Use GITLAB_OAUTH_ALLOWED_GROUPS instead.");
-            }
-        }
-        if (GITLAB_READ_ONLY_MODE) {
-            logger.warn("GITLAB_READ_ONLY_MODE is deprecated. Use GITLAB_PERMISSION_MODE=readonly or --permission-mode=readonly instead.");
+        for (const warning of getDeprecatedEnvWarnings({
+            readOnlyMode: GITLAB_READ_ONLY_MODE,
+            permissionModeRaw: GITLAB_PERMISSION_MODE_RAW,
+            allowedGroupsRaw: GITLAB_ALLOWED_GROUPS_RAW,
+            oauthAllowedGroupsRaw: GITLAB_OAUTH_ALLOWED_GROUPS_RAW,
+            useWikiRaw: USE_GITLAB_WIKI_RAW,
+            useMilestoneRaw: USE_MILESTONE_RAW,
+            usePipelineRaw: USE_PIPELINE_RAW,
+        })) {
+            logger.warn(warning);
         }
         if (GITLAB_OAUTH_ALLOWED_GROUPS) {
             logger.info(`Group access control enabled for: ${GITLAB_OAUTH_ALLOWED_GROUPS.join(", ")}`);