@zereight/mcp-gitlab 2.1.69 → 2.2.0

package/build/oauth-device-flow.js

@@ -19,7 +19,84 @@ const TokenResponseSchema = z.object({
     refresh_token: z.string().min(1).optional(),
     expires_in: z.number().positive().optional(),
     token_type: z.string().min(1).optional(),
+    scope: z.string().nullish(),
 });
+/**
+ * Extra scopes that may accompany a matching grant without forcing a new login.
+ * Each one is read-only in GitLab's OAuth scope table. Write-capable scopes
+ * (`api`, `write_repository`, `sudo`, runner/admin scopes) and anything not
+ * listed here are unapproved and must be authorized again.
+ */
+const APPROVED_EXTRA_READ_SCOPES = new Set([
+    "read_api",
+    "read_user",
+    "read_repository",
+    "read_registry",
+    "read_virtual_registry",
+    "read_observability",
+    "openid",
+    "profile",
+    "email",
+]);
+/**
+ * Scopes GitLab actually returned.
+ * A missing or blank `scope` field is not an observation. Keep a grant this
+ * process already recorded; otherwise leave the grant unknown instead of
+ * copying the scopes we requested.
+ */
+export function grantedOAuthScopes(scopeField, recordedScopes) {
+    if (typeof scopeField === "string") {
+        const scopes = scopeField.split(/\s+/).filter(scope => scope.length > 0);
+        if (scopes.length > 0) {
+            return scopes;
+        }
+    }
+    if (recordedScopes !== undefined && recordedScopes.length > 0) {
+        return [...recordedScopes];
+    }
+    return undefined;
+}
+/**
+ * True when a stored grant cannot be reused for the scopes this process requires.
+ * A missing or empty scope list is a pre-upgrade file. Those tokens keep working:
+ * a missing field is not a known mismatch, and forcing a browser login hangs
+ * headless and device-flow users. The next refresh records the scopes GitLab returns.
+ * Extra scopes stay valid only when they are on the approved read-only list, so a
+ * GitLab response that adds `read_user` does not force a login loop.
+ */
+export function oauthTokenNeedsReauthorization(storedScopes, expectedScopes) {
+    if (storedScopes === undefined || storedScopes.length === 0) {
+        return false;
+    }
+    const stored = new Set(storedScopes);
+    const expected = new Set(expectedScopes);
+    for (const scope of expected) {
+        if (!stored.has(scope)) {
+            return true;
+        }
+    }
+    for (const scope of stored) {
+        if (!expected.has(scope) && !APPROVED_EXTRA_READ_SCOPES.has(scope)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function formatOAuthScopes(scopes) {
+    if (scopes === undefined || scopes.length === 0) {
+        return "missing";
+    }
+    return scopes.map(scope => scope.replace(/[\r\n]/g, "")).join(" ");
+}
+export function oauthScopeMismatchError(grantedScopes, expectedScopes) {
+    return new Error(`OAuth authorization granted scopes (${formatOAuthScopes(grantedScopes)}), ` +
+        `which do not match required scopes (${formatOAuthScopes(expectedScopes)}).`);
+}
+function assertGrantedScopesMatchRequest(grantedScopes, expectedScopes) {
+    if (oauthTokenNeedsReauthorization(grantedScopes, expectedScopes)) {
+        throw oauthScopeMismatchError(grantedScopes, expectedScopes);
+    }
+}
 function delayAsync(ms) {
     return new Promise(resolve => {
         setTimeout(resolve, ms);
@@ -124,12 +201,15 @@ export async function runDeviceAuthorizationGrantAsync(input) {
             if (!token.success) {
                 throw new Error("Token endpoint returned an invalid response.");
             }
+            const scopes = grantedOAuthScopes(token.data.scope);
+            assertGrantedScopesMatchRequest(scopes, input.scopes);
             return {
                 access_token: token.data.access_token,
                 refresh_token: token.data.refresh_token,
                 expires_in: token.data.expires_in,
                 created_at: now(),
                 token_type: token.data.token_type ?? "Bearer",
+                ...(scopes === undefined ? {} : { scopes }),
             };
         }
         const tokenError = DeviceTokenErrorSchema.safeParse(tokenBody);

package/build/oauth.js

@@ -10,7 +10,9 @@ import { promisify } from "util";
 import open from "open";
 import pkceChallenge from "pkce-challenge";
 import { createLogger } from "./utils/logger.js";
-import { runDeviceAuthorizationGrantAsync } from "./oauth-device-flow.js";
+import { GITLAB_PERMISSION_MODE } from "./config.js";
+import { formatOAuthScopes, grantedOAuthScopes, oauthScopeMismatchError, oauthTokenNeedsReauthorization, runDeviceAuthorizationGrantAsync, } from "./oauth-device-flow.js";
+export { oauthTokenNeedsReauthorization };
 const logger = createLogger("gitlab-mcp-oauth");
 const execFileAsync = promisify(execFile);
 function escapeHtml(str) {
@@ -162,19 +164,27 @@ export class GitLabOAuth {
             const errorText = await response.text();
             throw new Error(`Token exchange failed: ${response.status} ${errorText}`);
         }
-        const data = (await response.json());
-        return {
+        const body = await response.json();
+        const data = readOAuthTokenBody(body);
+        const tokenData = {
             access_token: data.access_token,
             refresh_token: data.refresh_token,
             expires_in: data.expires_in,
             created_at: Date.now(),
             token_type: data.token_type,
+            scopes: data.scopes,
         };
+        // Throw before the callback writes the file. A stored token with no scopes
+        // stays valid; only a grant that records a mismatch is rejected.
+        if (oauthTokenNeedsReauthorization(tokenData.scopes, this.config.scopes)) {
+            throw oauthScopeMismatchError(tokenData.scopes, this.config.scopes);
+        }
+        return tokenData;
     }
     /**
      * Refresh the access token using the refresh token
      */
-    async refreshAccessToken(refreshToken) {
+    async refreshAccessToken(refreshToken, recordedScopes) {
         const tokenUrl = `${this.config.gitlabUrl}/oauth/token`;
         const params = new URLSearchParams({
             client_id: this.config.clientId,
@@ -201,13 +211,15 @@ export class GitLabOAuth {
                 authInvalid,
             });
         }
-        const data = (await response.json());
+        const body = await response.json();
+        const data = readOAuthTokenBody(body, recordedScopes);
         return {
             access_token: data.access_token,
             refresh_token: data.refresh_token || refreshToken,
             expires_in: data.expires_in,
             created_at: Date.now(),
             token_type: data.token_type,
+            scopes: data.scopes,
         };
     }
     /**
@@ -233,7 +245,8 @@ export class GitLabOAuth {
                 return null;
             }
             const data = fs.readFileSync(this.tokenStoragePath, "utf8");
-            return JSON.parse(data);
+            const parsed = JSON.parse(data);
+            return parseStoredToken(parsed);
         }
         catch (error) {
             logger.error({ err: error }, "Failed to load token");
@@ -548,36 +561,62 @@ export class GitLabOAuth {
             return (await this.getScriptToken()).access_token;
         }
         let tokenData = this.loadToken();
-        // If no token or expired (or forced), start OAuth flow or refresh
+        const expectedScopes = this.config.scopes;
+        // Refresh cannot change GitLab scopes. A stored grant that records a different
+        // scope has to be authorized again, or a readonly switch keeps an `api` token.
+        // Files written before scope tracking omit `scopes` and stay usable.
         if (!tokenData) {
             logger.info("No stored token found. Starting OAuth flow...");
-            tokenData = await this.startOAuthFlow();
+            tokenData = await this.authorizeMatchingScopes();
+        }
+        else if (oauthTokenNeedsReauthorization(tokenData.scopes, expectedScopes)) {
+            logger.warn(`Stored OAuth token scopes (${formatOAuthScopes(tokenData.scopes)}) do not match ` +
+                `${formatOAuthScopes(expectedScopes)} for the current permission mode. Starting a new authorization flow...`);
+            tokenData = await this.authorizeMatchingScopes();
         }
         else if (force || this.isTokenExpired(tokenData)) {
             logger.info(force && !this.isTokenExpired(tokenData) ? "Force-refreshing OAuth token..." : "Token expired. Refreshing...");
             if (tokenData.refresh_token) {
                 try {
-                    tokenData = await this.refreshAccessToken(tokenData.refresh_token);
-                    this.saveToken(tokenData);
+                    tokenData = await this.refreshAccessToken(tokenData.refresh_token, tokenData.scopes);
                 }
                 catch (error) {
-                    if (error.authInvalid === true) {
+                    if (isAuthInvalidError(error)) {
                         logger.error({ err: error }, "Refresh token invalid, starting new OAuth flow...");
-                        tokenData = await this.startOAuthFlow();
-                    }
-                    else {
-                        logger.error({ err: error }, "Token refresh failed (transient/network), not opening browser.");
-                        throw error;
+                        return (await this.authorizeMatchingScopes()).access_token;
                     }
+                    logger.error({ err: error }, "Token refresh failed (transient/network), not opening browser.");
+                    throw error;
+                }
+                // GitLab revokes the previous refresh token when this call succeeds.
+                // Persist the rotated grant before a browser retry so a failed or busy
+                // callback does not leave only the revoked token on disk. Callers still
+                // do not receive a mismatched access token: a recorded mismatch is
+                // rejected before refresh on the next start, and a later callback overwrites this file.
+                this.saveToken(tokenData);
+                if (oauthTokenNeedsReauthorization(tokenData.scopes, expectedScopes)) {
+                    logger.warn(`Refreshed OAuth token scopes (${formatOAuthScopes(tokenData.scopes)}) do not match ` +
+                        `${formatOAuthScopes(expectedScopes)}. Starting a new authorization flow...`);
+                    tokenData = await this.authorizeMatchingScopes();
                 }
             }
             else {
                 logger.info("No refresh token available. Starting new OAuth flow...");
-                tokenData = await this.startOAuthFlow();
+                tokenData = await this.authorizeMatchingScopes();
             }
         }
         return tokenData.access_token;
     }
+    /**
+     * Browser or device-callback login, rejected when GitLab grants a different scope.
+     */
+    async authorizeMatchingScopes() {
+        const tokenData = await this.startOAuthFlow();
+        if (oauthTokenNeedsReauthorization(tokenData.scopes, this.config.scopes)) {
+            throw oauthScopeMismatchError(tokenData.scopes, this.config.scopes);
+        }
+        return tokenData;
+    }
     /**
      * Clear stored token
      */
@@ -603,6 +642,9 @@ export class GitLabOAuth {
         if (!tokenData) {
             return false;
         }
+        if (oauthTokenNeedsReauthorization(tokenData.scopes, this.config.scopes)) {
+            return false;
+        }
         return !this.isTokenExpired(tokenData);
     }
     /**
@@ -625,6 +667,81 @@ export class GitLabOAuth {
         return tokenData;
     }
 }
+/** Read-only permission mode only needs the `read_api` scope; every other mode needs `api`. */
+export function getOAuthScopes(permissionMode) {
+    return [permissionMode === "readonly" ? "read_api" : "api"];
+}
+function isAuthInvalidError(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    return Reflect.get(error, "authInvalid") === true;
+}
+function readOAuthTokenBody(value, recordedScopes) {
+    if (typeof value !== "object" || value === null) {
+        throw new Error("Token endpoint returned an invalid response.");
+    }
+    const accessToken = Reflect.get(value, "access_token");
+    const refreshToken = Reflect.get(value, "refresh_token");
+    const expiresIn = Reflect.get(value, "expires_in");
+    const tokenType = Reflect.get(value, "token_type");
+    const scope = Reflect.get(value, "scope");
+    if (typeof accessToken !== "string" || accessToken.length === 0) {
+        throw new Error("Token endpoint returned an invalid response.");
+    }
+    return {
+        access_token: accessToken,
+        refresh_token: typeof refreshToken === "string" ? refreshToken : undefined,
+        expires_in: typeof expiresIn === "number" ? expiresIn : undefined,
+        token_type: typeof tokenType === "string" && tokenType.length > 0 ? tokenType : "Bearer",
+        scopes: grantedOAuthScopes(scope, recordedScopes),
+    };
+}
+function parseStoredToken(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const accessToken = Reflect.get(value, "access_token");
+    const createdAt = Reflect.get(value, "created_at");
+    const tokenType = Reflect.get(value, "token_type");
+    const refreshToken = Reflect.get(value, "refresh_token");
+    const expiresIn = Reflect.get(value, "expires_in");
+    if (typeof accessToken !== "string" || accessToken.length === 0) {
+        return null;
+    }
+    if (typeof createdAt !== "number" || !Number.isFinite(createdAt)) {
+        return null;
+    }
+    const token = {
+        access_token: accessToken,
+        created_at: createdAt,
+        token_type: typeof tokenType === "string" && tokenType.length > 0 ? tokenType : "Bearer",
+    };
+    if (typeof refreshToken === "string") {
+        token.refresh_token = refreshToken;
+    }
+    if (typeof expiresIn === "number") {
+        token.expires_in = expiresIn;
+    }
+    const scopes = parseStoredScopes(Reflect.get(value, "scopes"));
+    if (scopes !== undefined) {
+        token.scopes = scopes;
+    }
+    return token;
+}
+function parseStoredScopes(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const scopes = [];
+    for (const item of value) {
+        if (typeof item !== "string" || item.trim() === "") {
+            return undefined;
+        }
+        scopes.push(item.trim());
+    }
+    return scopes.length > 0 ? scopes : undefined;
+}
 /**
  * Construct a GitLabOAuth client from environment configuration.
  * Does NOT perform any network access — no token is acquired here.
@@ -644,7 +761,7 @@ export function createGitLabOAuthClient(gitlabUrl = "https://gitlab.com") {
         clientSecret,
         redirectUri,
         gitlabUrl,
-        scopes: [process.env.GITLAB_READ_ONLY_MODE === "true" ? "read_api" : "api"],
+        scopes: getOAuthScopes(GITLAB_PERMISSION_MODE),
         tokenStoragePath,
         tokenScript,
     });

package/build/schemas.js

@@ -2513,7 +2513,7 @@ export const ListGroupMergeRequestsSchema = ListMergeRequestsSchema.omit({
 export const GetIssueSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
     issue_iid: z.coerce.string().describe("The internal ID of the project issue"),
-    full_response: flexibleBooleanOptional.describe("If true, return the complete issue object including the full milestone description. Default returns a slim milestone (id, iid, title, state, web_url) to reduce token usage."),
+    full_response: flexibleBooleanOptional.describe("If true, include the complete milestone object, including its description, on the returned issue. Default returns the issue with a slim milestone (id, iid, title, state, web_url) to reduce token usage."),
 });
 export const UpdateIssueSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),

package/build/server/remote-http-stack.js

@@ -0,0 +1,39 @@
+function isExpressFactory(value) {
+    return typeof value === "function" && "json" in value;
+}
+function loadExpressFactory(moduleNamespace) {
+    if (isExpressFactory(moduleNamespace)) {
+        return moduleNamespace;
+    }
+    if (typeof moduleNamespace === "object" &&
+        moduleNamespace !== null &&
+        "default" in moduleNamespace &&
+        isExpressFactory(moduleNamespace.default)) {
+        return moduleNamespace.default;
+    }
+    throw new Error("express did not export an application factory");
+}
+const remoteHttpStackCache = {};
+export async function loadRemoteHttpStack() {
+    if (remoteHttpStackCache.current) {
+        return remoteHttpStackCache.current;
+    }
+    const [expressModule, rateLimitModule, sseModule, streamableModule, authRouterModule, bearerModule,] = await Promise.all([
+        import("express"),
+        import("express-rate-limit"),
+        import("@modelcontextprotocol/sdk/server/sse.js"),
+        import("@modelcontextprotocol/sdk/server/streamableHttp.js"),
+        import("@modelcontextprotocol/sdk/server/auth/router.js"),
+        import("@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js"),
+    ]);
+    remoteHttpStackCache.current = {
+        express: loadExpressFactory(expressModule),
+        rateLimit: rateLimitModule.default,
+        ipKeyGenerator: rateLimitModule.ipKeyGenerator,
+        SSEServerTransport: sseModule.SSEServerTransport,
+        StreamableHTTPServerTransport: streamableModule.StreamableHTTPServerTransport,
+        mcpAuthRouter: authRouterModule.mcpAuthRouter,
+        requireBearerAuth: bearerModule.requireBearerAuth,
+    };
+    return remoteHttpStackCache.current;
+}

package/build/tools/discover-activation.js

@@ -0,0 +1,38 @@
+/**
+ * Same skips `discover_tools` uses when it adds tools: permission mode, regex
+ * denial, hidden policy, and the slim profile. Those tools never join the list.
+ */
+export function isSkippedByDiscoverActivation(input) {
+    if (!input.allowedByPermissionMode) {
+        return true;
+    }
+    if (input.deniedByRegex) {
+        return true;
+    }
+    if (input.hidden) {
+        return true;
+    }
+    return input.excludedBySlimProfile;
+}
+/**
+ * Hint for a direct call to a tool `tools/list` omitted.
+ * `discover_tools` is mentioned only when activation would add the tool.
+ */
+export function buildUnavailableToolMessage(input) {
+    const base = `Tool "${input.toolName}" is not available on this server`;
+    const toolset = input.toolset;
+    if (toolset === undefined || input.deniedByRegex) {
+        return base;
+    }
+    if (input.excludedBySlimProfile) {
+        return `${base}. ${slimExclusionGuidance(input.toolName, toolset, input.enabledByCurrentToolsets)}`;
+    }
+    return `${base}. It belongs to the "${toolset}" toolset, which is not enabled: call discover_tools with category "${toolset}" or add "${toolset}" to GITLAB_TOOLSETS.`;
+}
+function slimExclusionGuidance(toolName, toolset, enabledByCurrentToolsets) {
+    const viaToolsets = `add "${toolset}" to GITLAB_TOOLSETS (setting GITLAB_TOOLSETS disables the slim profile)`;
+    if (enabledByCurrentToolsets) {
+        return `The slim tool profile excludes it. Add "${toolName}" to GITLAB_TOOLS, set GITLAB_TOOL_PROFILE=full, or ${viaToolsets}.`;
+    }
+    return `The slim tool profile excludes it. Add "${toolName}" to GITLAB_TOOLS, or ${viaToolsets}.`;
+}

package/build/tools/exposed-tools.js

@@ -0,0 +1,35 @@
+import { isExcludedBySlimProfile } from "./tool-profile.js";
+export function selectExposedTools(input) {
+    const toolsAfterToolsets = input.tools.filter(tool => input.isInEnabledToolset(tool.name));
+    const toolsetToolNames = new Set(toolsAfterToolsets.map(tool => tool.name));
+    const toolsAfterIndividual = [
+        ...toolsAfterToolsets,
+        ...input.tools.filter(tool => input.individuallyEnabledTools.has(tool.name) && !toolsetToolNames.has(tool.name)),
+    ];
+    const afterIndividualNames = new Set(toolsAfterIndividual.map(tool => tool.name));
+    const toolsAfterLegacy = [
+        ...toolsAfterIndividual,
+        ...input.tools.filter(tool => input.featureFlagOverrides.has(tool.name) && !afterIndividualNames.has(tool.name)),
+    ];
+    const toolsAfterPermission = toolsAfterLegacy.filter(tool => input.isAllowedByPermissionMode(tool.name));
+    const deniedToolsRegex = input.deniedToolsRegex;
+    const toolsAfterRegex = deniedToolsRegex
+        ? toolsAfterPermission.filter(tool => !deniedToolsRegex.test(tool.name))
+        : [...toolsAfterPermission];
+    const filteredToolNames = new Set(toolsAfterRegex.map(tool => tool.name));
+    const discoverTool = input.tools.find(tool => tool.name === "discover_tools");
+    if (discoverTool && !filteredToolNames.has("discover_tools")) {
+        const passesPermissionMode = input.isAllowedByPermissionMode("discover_tools");
+        const passesRegex = deniedToolsRegex ? !deniedToolsRegex.test("discover_tools") : true;
+        if (passesPermissionMode && passesRegex) {
+            toolsAfterRegex.push(discoverTool);
+        }
+    }
+    const withoutHidden = input.hiddenToolNames.size > 0
+        ? toolsAfterRegex.filter(tool => !input.hiddenToolNames.has(tool.name))
+        : toolsAfterRegex;
+    if (!input.applySlimProfile) {
+        return withoutHidden;
+    }
+    return withoutHidden.filter(tool => !isExcludedBySlimProfile(tool.name, true, input.individuallyEnabledTools));
+}

package/build/tools/listed-tools.js

@@ -0,0 +1,76 @@
+const CONFIRMED_ARGUMENT = "_confirmed";
+const CONFIRMED_ARGUMENT_DESCRIPTION = "Set to true to confirm execution of this approval-required tool.";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneSchema(schema) {
+    const clone = { ...schema };
+    if ("$schema" in clone) {
+        delete clone.$schema;
+    }
+    return clone;
+}
+function withConfirmedArgument(schema, toolName, context) {
+    if (!context.approveToolNames.has(toolName) || !isRecord(schema.properties)) {
+        return schema;
+    }
+    return {
+        ...schema,
+        properties: {
+            ...schema.properties,
+            [CONFIRMED_ARGUMENT]: {
+                type: "boolean",
+                description: CONFIRMED_ARGUMENT_DESCRIPTION,
+            },
+        },
+    };
+}
+function withJmespathArgument(schema, context) {
+    const properties = isRecord(schema.properties) ? { ...schema.properties } : {};
+    if (context.jmespathArgument in properties) {
+        return schema;
+    }
+    properties[context.jmespathArgument] = {
+        type: "string",
+        description: context.jmespathArgumentDescription,
+    };
+    return { ...schema, properties };
+}
+function decorateInputSchema(schema, toolName, context) {
+    if (!isRecord(schema)) {
+        return undefined;
+    }
+    return withJmespathArgument(withConfirmedArgument(cloneSchema(schema), toolName, context), context);
+}
+export function decorateToolForList(tool, context) {
+    const inputSchema = decorateInputSchema(tool.inputSchema, tool.name, context);
+    const annotations = { openWorldHint: true };
+    if (context.readOnlyToolNames.has(tool.name)) {
+        annotations.readOnlyHint = true;
+    }
+    if (context.destructiveToolNames.has(tool.name)) {
+        annotations.destructiveHint = true;
+    }
+    if (context.approveToolNames.has(tool.name)) {
+        annotations.confirmationHint = true;
+    }
+    if (inputSchema) {
+        return { ...tool, inputSchema, annotations };
+    }
+    return { ...tool, annotations };
+}
+export function decorateToolsForList(tools, context) {
+    return tools.map(tool => decorateToolForList(tool, context));
+}
+export function createListedToolsCache(decorate) {
+    const cache = { revision: -1 };
+    return function getListedTools(tools, revision) {
+        if (cache.tools !== undefined && cache.revision === revision) {
+            return cache.tools;
+        }
+        const decorated = decorate(tools);
+        cache.tools = decorated;
+        cache.revision = revision;
+        return decorated;
+    };
+}