@zereight/mcp-gitlab 2.1.68 → 2.1.70

package/build/oauth.js

@@ -19,6 +19,28 @@ function escapeHtml(str) {
 }
 // Track pending auth requests across multiple MCP instances
 const pendingAuthRequests = new Map();
+const OAUTH_REFRESH_TIMEOUT_MS = 10000;
+/**
+ * Decide whether a failed token-refresh response means the refresh token is
+ * genuinely dead (interactive re-login would fix it) versus a transient or
+ * configuration problem (where opening a browser is wrong).
+ *
+ * Returns true ONLY for a 400/401 whose JSON body has error "invalid_grant"
+ * or "invalid_token". Everything else — config errors (invalid_client,
+ * invalid_request), 5xx, 429, and non-JSON bodies — returns false.
+ */
+export function isAuthInvalidTokenResponse(status, bodyText) {
+    if (status !== 400 && status !== 401) {
+        return false;
+    }
+    try {
+        const body = JSON.parse(bodyText);
+        return body.error === "invalid_grant" || body.error === "invalid_token";
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Check if a port is already in use
  */
@@ -170,10 +192,14 @@ export class GitLabOAuth {
                 "Content-Type": "application/x-www-form-urlencoded",
             },
             body: params.toString(),
+            signal: AbortSignal.timeout(OAUTH_REFRESH_TIMEOUT_MS),
         });
         if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Token refresh failed: ${response.status} ${errorText}`);
+            const bodyText = await response.text();
+            const authInvalid = isAuthInvalidTokenResponse(response.status, bodyText);
+            throw Object.assign(new Error(`Token refresh failed: ${response.status} ${bodyText}`), {
+                authInvalid,
+            });
         }
         const data = (await response.json());
         return {
@@ -230,7 +256,13 @@ export class GitLabOAuth {
      * Uses a shared server if port is already in use
      */
     async startOAuthFlow() {
-        const callbackPort = parseInt(new URL(this.config.redirectUri).port || "8888");
+        let callbackPort = 8888;
+        try {
+            callbackPort = parseInt(new URL(this.config.redirectUri).port || "8888", 10);
+        }
+        catch {
+            // Fallback to default port on malformed redirectUri
+        }
         const requestId = crypto.randomUUID();
         // Check if port is already in use
         const portInUse = await isPortInUse(callbackPort);
@@ -529,8 +561,14 @@ export class GitLabOAuth {
                     this.saveToken(tokenData);
                 }
                 catch (error) {
-                    logger.error({ err: error }, "Token refresh failed. Starting new OAuth flow...");
-                    tokenData = await this.startOAuthFlow();
+                    if (error.authInvalid === true) {
+                        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;
+                    }
                 }
             }
             else {
@@ -588,11 +626,11 @@ export class GitLabOAuth {
     }
 }
 /**
- * Create and initialize a GitLabOAuth client.
- * Performs initial authentication (triggers browser flow if needed).
- * Returns the client instance and the initial access token.
+ * Construct a GitLabOAuth client from environment configuration.
+ * Does NOT perform any network access — no token is acquired here.
+ * Throws if neither GITLAB_OAUTH_CLIENT_ID nor GITLAB_OAUTH_TOKEN_SCRIPT is set.
  */
-export async function initializeOAuthClient(gitlabUrl = "https://gitlab.com") {
+export function createGitLabOAuthClient(gitlabUrl = "https://gitlab.com") {
     const clientId = process.env.GITLAB_OAUTH_CLIENT_ID;
     const clientSecret = process.env.GITLAB_OAUTH_CLIENT_SECRET;
     const redirectUri = process.env.GITLAB_OAUTH_REDIRECT_URI || "http://127.0.0.1:8888/callback";
@@ -601,7 +639,7 @@ export async function initializeOAuthClient(gitlabUrl = "https://gitlab.com") {
     if (!clientId && !tokenScript) {
         throw new Error("GITLAB_OAUTH_CLIENT_ID or GITLAB_OAUTH_TOKEN_SCRIPT environment variable is required for OAuth authentication");
     }
-    const oauth = new GitLabOAuth({
+    return new GitLabOAuth({
         clientId: clientId || "external-token-script",
         clientSecret,
         redirectUri,
@@ -610,6 +648,51 @@ export async function initializeOAuthClient(gitlabUrl = "https://gitlab.com") {
         tokenStoragePath,
         tokenScript,
     });
+}
+const inFlightTokenPromises = new WeakMap();
+/**
+ * Ensure the caller holds a usable OAuth access token, delivering it via onToken.
+ * Returns cached token without network when still valid.
+ *
+ * NOTE: the fast path requires BOTH a held token and a valid stored token.
+ * Returning early on hasValidToken() alone would skip onToken after lazy
+ * startup (caller holds nothing yet) and leave requests unauthenticated.
+ * Concurrent callers coalesce on an in-flight promise to avoid racing
+ * duplicate refresh requests (which would fail on token rotation).
+ */
+export async function ensureOAuthToken(client, currentToken, onToken) {
+    if (!client)
+        return;
+    // Fast path: token already resolved for this process and still valid.
+    if (currentToken && client.hasValidToken())
+        return;
+    let promise = inFlightTokenPromises.get(client);
+    if (!promise) {
+        const needsRefresh = !client.hasValidToken();
+        if (needsRefresh) {
+            logger.info("OAuth token expired or missing, refreshing...");
+        }
+        promise = (async () => {
+            const token = await client.getAccessToken();
+            if (needsRefresh) {
+                logger.info("OAuth token refreshed successfully");
+            }
+            return token;
+        })().finally(() => {
+            inFlightTokenPromises.delete(client);
+        });
+        inFlightTokenPromises.set(client, promise);
+    }
+    const token = await promise;
+    onToken(token);
+}
+/**
+ * Create and initialize a GitLabOAuth client.
+ * Performs initial authentication (triggers browser flow if needed).
+ * Returns the client instance and the initial access token.
+ */
+export async function initializeOAuthClient(gitlabUrl = "https://gitlab.com") {
+    const oauth = createGitLabOAuthClient(gitlabUrl);
     // Single call: triggers browser flow if needed, or reads cached token
     const accessToken = await oauth.getAccessToken();
     return { client: oauth, accessToken };

package/build/scripts/generate-tool-docs.js

@@ -24,13 +24,14 @@ const LEGACY_TOGGLE_ENV = {
 function isDefaultToolset(id) {
     return TOOLSET_DEFINITIONS.find(d => d.id === id)?.isDefault ?? false;
 }
+/** Returns the availability note for a toolset group, or undefined when it is on by default. */
 function computeToggleNote(id) {
     if (isDefaultToolset(id))
         return undefined;
     // Synthetic group for tools not in any TOOLSET_DEFINITIONS entry.
     // discover_tools is always exposed; execute_graphql is opt-in via GITLAB_TOOLS.
     if (id === "meta") {
-        return "Mixed availability. `discover_tools` is always exposed (the server re-adds it after every toolset filter). `execute_graphql` is not part of any toolset — enable it explicitly with `GITLAB_TOOLS=execute_graphql`.";
+        return "Mixed availability. `discover_tools` is always exposed (the server re-adds it after every toolset filter). `execute_graphql` is not part of any toolset — enable it explicitly with `GITLAB_TOOLS=execute_graphql`. Tools excluded from the list (toolset / `GITLAB_TOOLS` / `GITLAB_DENIED_TOOLS_REGEX`) are also rejected on direct calls; `GITLAB_TOOL_POLICY_HIDDEN` tools stay callable unless they match `GITLAB_DENIED_TOOLS_REGEX`.";
     }
     const legacy = LEGACY_TOGGLE_ENV[id];
     if (legacy) {

package/build/test/cli/args.test.js

@@ -0,0 +1,175 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { allTools } from "../../tools/registry.js";
+import { CreateWebhookSchema, GetPipelineJobOutputSchema, ProtectBranchSchema, } from "../../schemas.js";
+import { applyFlagAliases, CliUsageError, parseArgv, parseToolArgs } from "../../cli/args.js";
+function argv(...args) {
+    return ["node", "index.js", ...args];
+}
+function schemaFor(toolName) {
+    const tool = allTools.find(entry => entry.name === toolName);
+    assert.ok(tool, `missing tool ${toolName}`);
+    return tool.inputSchema;
+}
+describe("When parseArgv reads a command line", () => {
+    describe("with a generic tool invocation", () => {
+        it("should keep positionals and kebab flags as snake_case tool args", () => {
+            const parsed = parseArgv(argv("tool", "list_issues", "--project-id", "123", "--state", "opened"));
+            assert.deepEqual(parsed.positionals, ["tool", "list_issues"]);
+            assert.equal(parsed.toolFlags.project_id, "123");
+            assert.equal(parsed.toolFlags.state, "opened");
+            assert.equal(parsed.output, undefined);
+        });
+    });
+    describe("with global flags mixed in", () => {
+        it("should not treat --token --output --yes as tool flags", () => {
+            const parsed = parseArgv(argv("tool", "whoami", "--token", "glpat-xxxxxxxxxxxxxxxxxxxx", "--output=json", "--yes"));
+            assert.equal(parsed.output, "json");
+            assert.equal(parsed.yes, true);
+            assert.deepEqual(parsed.toolFlags, {});
+        });
+    });
+    describe("with --args-json", () => {
+        it("should parse the object and ignore prototype keys", () => {
+            const parsed = parseArgv(argv("tool", "create_issue", "--args-json", '{"title":"bug","__proto__":{"x":1}}'));
+            assert.equal(parsed.argsJson?.title, "bug");
+            assert.equal(Object.prototype.hasOwnProperty.call(parsed.argsJson, "__proto__"), false);
+        });
+    });
+    describe("with --use-oauth before a curated command", () => {
+        it("should keep mr list as positionals instead of consuming mr as the flag value", () => {
+            const parsed = parseArgv(argv("--use-oauth", "mr", "list"));
+            assert.deepEqual(parsed.positionals, ["mr", "list"]);
+        });
+    });
+    describe("with --read-only false before a curated command", () => {
+        it("should keep false as the flag value and mr list as positionals", () => {
+            const parsed = parseArgv(argv("--read-only", "false", "mr", "list"));
+            assert.deepEqual(parsed.positionals, ["mr", "list"]);
+        });
+    });
+});
+describe("When parseToolArgs validates a real schema", () => {
+    describe("with whoami", () => {
+        it("should accept an empty flag set", () => {
+            const args = parseToolArgs({
+                schema: schemaFor("whoami"),
+                flags: {},
+                argsJson: undefined,
+                extraArgs: undefined,
+            });
+            assert.deepEqual(args, {});
+        });
+    });
+    describe("with create_issue missing title", () => {
+        it("should throw a usage error for the required flag", () => {
+            assert.throws(() => parseToolArgs({
+                schema: schemaFor("create_issue"),
+                flags: { project_id: "123" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            }), (error) => error instanceof CliUsageError && error.message.includes("--title"));
+        });
+    });
+    describe("with flags overlaying --args-json", () => {
+        it("should let flags win", () => {
+            const args = parseToolArgs({
+                schema: schemaFor("create_issue"),
+                flags: { title: "from-flag" },
+                argsJson: { project_id: "123", title: "from-json" },
+                extraArgs: undefined,
+            });
+            assert.equal(args.project_id, "123");
+            assert.equal(args.title, "from-flag");
+        });
+    });
+    describe("with an unknown flag", () => {
+        it("should throw a usage error", () => {
+            assert.throws(() => parseToolArgs({
+                schema: schemaFor("whoami"),
+                flags: { nope: "1" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            }), (error) => error instanceof CliUsageError && error.message === "Unknown flag: --nope");
+        });
+    });
+});
+describe("When parseToolArgs coerces scalar flags from the schema", () => {
+    describe("with a number flag", () => {
+        it("should pass a number that the tool schema accepts", () => {
+            const args = parseToolArgs({
+                schema: schemaFor("get_pipeline_job_output"),
+                flags: { project_id: "1", job_id: "9", limit: "10" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            });
+            assert.equal(GetPipelineJobOutputSchema.safeParse(args).success, true);
+        });
+    });
+    describe("with a boolean flag", () => {
+        it("should pass a boolean that the tool schema accepts", () => {
+            const args = parseToolArgs({
+                schema: schemaFor("create_webhook"),
+                flags: { project_id: "1", url: "https://example.com/hook", push_events: "false" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            });
+            assert.equal(CreateWebhookSchema.safeParse(args).success, true);
+        });
+    });
+    describe("with an integer flag", () => {
+        it("should pass an integer that the tool schema accepts", () => {
+            const args = parseToolArgs({
+                schema: schemaFor("protect_branch"),
+                flags: { project_id: "1", branch_name: "main", push_access_level: "40" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            });
+            assert.strictEqual(args.push_access_level, 40);
+            assert.equal(ProtectBranchSchema.safeParse(args).success, true);
+        });
+    });
+    describe("with a field that also accepts strings", () => {
+        it("should keep the raw string", () => {
+            const args = parseToolArgs({
+                schema: schemaFor("list_webhook_events"),
+                flags: { project_id: "1", hook_id: "2", status: "500" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            });
+            assert.equal(args.status, "500");
+        });
+    });
+    describe("with a non-boolean value for a boolean flag", () => {
+        it("should throw a usage error", () => {
+            assert.throws(() => parseToolArgs({
+                schema: schemaFor("create_webhook"),
+                flags: { project_id: "1", url: "https://example.com/hook", push_events: "yes" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            }), (error) => error instanceof CliUsageError && error.message === "--push-events must be true or false");
+        });
+    });
+    describe("with a fraction for an integer flag", () => {
+        it("should throw a usage error", () => {
+            assert.throws(() => parseToolArgs({
+                schema: schemaFor("protect_branch"),
+                flags: { project_id: "1", branch_name: "main", push_access_level: "40.5" },
+                argsJson: undefined,
+                extraArgs: undefined,
+            }), (error) => error instanceof CliUsageError &&
+                error.message === "--push-access-level must be an integer");
+        });
+    });
+});
+describe("When applyFlagAliases rewrites curated shorts", () => {
+    describe("with --mr-iid", () => {
+        it("should map onto merge_request_iid", () => {
+            const mapped = applyFlagAliases({ mr_iid: "45", project_id: "123" }, {
+                mr_iid: "merge_request_iid",
+            });
+            assert.equal(mapped.merge_request_iid, "45");
+            assert.equal(mapped.project_id, "123");
+        });
+    });
+});

package/build/test/cli/boolean-flags.test.js

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import * as path from "node:path";
+import * as url from "node:url";
+import { describe, it } from "node:test";
+import { isBooleanFlagLiteral, nextBooleanFlagValue } from "../../cli-boolean-flags.js";
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const SNAPSHOT_PATH = path.resolve(__dirname, "load-config-snapshot.ts");
+function loadConfig(argv) {
+    const childEnv = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            childEnv[key] = value;
+        }
+    }
+    delete childEnv.GITLAB_READ_ONLY_MODE;
+    delete childEnv.GITLAB_USE_OAUTH;
+    const stdout = execFileSync(process.execPath, ["--import", "tsx/esm", SNAPSHOT_PATH, ...argv], {
+        env: childEnv,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return readBooleanConfigSnapshot(JSON.parse(stdout));
+}
+function readBooleanConfigSnapshot(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("config snapshot was not an object");
+    }
+    if (!("GITLAB_READ_ONLY_MODE" in value) || typeof value.GITLAB_READ_ONLY_MODE !== "boolean") {
+        throw new Error("GITLAB_READ_ONLY_MODE missing");
+    }
+    if (!("USE_OAUTH" in value) || typeof value.USE_OAUTH !== "boolean") {
+        throw new Error("USE_OAUTH missing");
+    }
+    return {
+        GITLAB_READ_ONLY_MODE: value.GITLAB_READ_ONLY_MODE,
+        USE_OAUTH: value.USE_OAUTH,
+    };
+}
+describe("When nextBooleanFlagValue reads the following token", () => {
+    describe("with a positional command", () => {
+        it("should treat the flag as true and leave the command", () => {
+            assert.deepEqual(nextBooleanFlagValue("mr"), { value: "true", consumeNext: false });
+        });
+    });
+    describe("with an explicit false", () => {
+        it("should consume the literal", () => {
+            assert.deepEqual(nextBooleanFlagValue("false"), { value: "false", consumeNext: true });
+        });
+    });
+    describe("with a missing token", () => {
+        it("should default to true", () => {
+            assert.deepEqual(nextBooleanFlagValue(undefined), { value: "true", consumeNext: false });
+        });
+    });
+});
+describe("When isBooleanFlagLiteral inspects a token", () => {
+    describe("with true", () => {
+        it("should accept it", () => {
+            assert.equal(isBooleanFlagLiteral("true"), true);
+        });
+    });
+    describe("with a command name", () => {
+        it("should reject it", () => {
+            assert.equal(isBooleanFlagLiteral("mr"), false);
+        });
+    });
+});
+describe("When config.ts parses space-separated boolean flags", () => {
+    describe("with --read-only as the last argument", () => {
+        it("should turn read-only mode on", () => {
+            const cfg = loadConfig(["--read-only"]);
+            assert.equal(cfg.GITLAB_READ_ONLY_MODE, true);
+        });
+    });
+    describe("with --read-only followed by another flag", () => {
+        it("should turn read-only mode on", () => {
+            const cfg = loadConfig(["--read-only", "--use-pipeline"]);
+            assert.equal(cfg.GITLAB_READ_ONLY_MODE, true);
+        });
+    });
+    describe("with an empty --read-only= assignment", () => {
+        it("should leave read-only mode off", () => {
+            const cfg = loadConfig(["--read-only="]);
+            assert.equal(cfg.GITLAB_READ_ONLY_MODE, false);
+        });
+    });
+    describe("with --read-only false", () => {
+        it("should keep read-only off", () => {
+            const cfg = loadConfig(["--read-only", "false"]);
+            assert.equal(cfg.GITLAB_READ_ONLY_MODE, false);
+        });
+    });
+    describe("with --read-only before a command", () => {
+        it("should turn read-only on without consuming mr", () => {
+            const cfg = loadConfig(["--read-only", "mr", "list"]);
+            assert.equal(cfg.GITLAB_READ_ONLY_MODE, true);
+        });
+    });
+    describe("with --use-oauth false", () => {
+        it("should keep oauth off", () => {
+            const cfg = loadConfig(["--use-oauth", "false"]);
+            assert.equal(cfg.USE_OAUTH, false);
+        });
+    });
+});

package/build/test/cli/compact-mcp-result.test.js

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { compactMcpToolResult } from "../../cli/compact-mcp-result.js";
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+describe("When compactMcpToolResult wraps an MCP tool reply", () => {
+    describe("with compact mode disabled", () => {
+        it("should return the original result", () => {
+            const result = textResult("[]");
+            const compacted = compactMcpToolResult({
+                result,
+                enabled: false,
+                maxChars: 1,
+                toolName: "list_issues",
+                args: { project_id: "1" },
+            });
+            assert.equal(compacted, result);
+        });
+    });
+    describe("with a small payload", () => {
+        it("should leave the result alone", () => {
+            const result = textResult('{"iid":1}');
+            const compacted = compactMcpToolResult({
+                result,
+                enabled: true,
+                maxChars: 4000,
+                toolName: "get_issue",
+                args: { project_id: "1", issue_iid: 1 },
+            });
+            assert.equal(compacted, result);
+        });
+    });
+    describe("with a long issue list", () => {
+        it("should keep a preview and a CLI replay command", () => {
+            const issues = Array.from({ length: 20 }, (_, index) => ({ iid: index + 1, title: "x".repeat(80) }));
+            const compacted = compactMcpToolResult({
+                result: textResult(JSON.stringify(issues)),
+                enabled: true,
+                maxChars: 200,
+                toolName: "list_issues",
+                args: { project_id: "123", state: "opened" },
+            });
+            assert.ok(isRecord(compacted));
+            assert.equal(Object.prototype.hasOwnProperty.call(compacted, "structuredContent"), false);
+            const content = compacted.content;
+            assert.ok(Array.isArray(content));
+            const block = content[0];
+            assert.ok(isRecord(block) && typeof block.text === "string");
+            const payload = JSON.parse(block.text);
+            assert.ok(isRecord(payload));
+            assert.equal(payload.compact, true);
+            assert.equal(payload.tool, "list_issues");
+            assert.equal(payload.items_total, 20);
+            assert.ok(Array.isArray(payload.preview));
+            assert.equal(payload.preview.length, 5);
+            assert.equal(payload.cli, "zereight-mcp-gitlab tool list_issues --project-id 123 --state opened");
+        });
+    });
+    describe("with structuredContent on a large payload", () => {
+        it("should drop structuredContent so the full object cannot leak", () => {
+            const issues = Array.from({ length: 20 }, (_, index) => ({ iid: index + 1, title: "x".repeat(80) }));
+            const compacted = compactMcpToolResult({
+                result: {
+                    content: [{ type: "text", text: JSON.stringify(issues) }],
+                    structuredContent: issues,
+                },
+                enabled: true,
+                maxChars: 200,
+                toolName: "list_issues",
+                args: { project_id: "1" },
+            });
+            assert.ok(isRecord(compacted));
+            assert.equal(Object.prototype.hasOwnProperty.call(compacted, "structuredContent"), false);
+        });
+    });
+    describe("with an error result", () => {
+        it("should not compact", () => {
+            const result = { content: [{ type: "text", text: "boom".repeat(500) }], isError: true };
+            const compacted = compactMcpToolResult({
+                result,
+                enabled: true,
+                maxChars: 10,
+                toolName: "list_issues",
+                args: {},
+            });
+            assert.equal(compacted, result);
+        });
+    });
+});
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}