@zereight/mcp-gitlab 2.2.5 → 2.3.0

package/build/oauth.js

@@ -44,6 +44,117 @@ export function isAuthInvalidTokenResponse(status, bodyText) {
         return false;
     }
 }
+// Shared OAuth callback servers started by this process
+const sharedOAuthServers = new Set();
+/**
+ * Stop the shared OAuth callback servers started by this process.
+ */
+export async function closeSharedOAuthServersAsync() {
+    const servers = [...sharedOAuthServers];
+    sharedOAuthServers.clear();
+    await Promise.all(servers.map(server => new Promise(resolve => {
+        server.close(() => resolve());
+        server.closeAllConnections();
+    })));
+}
+const SHARED_OAUTH_KEY_HEADER = "x-gitlab-mcp-oauth-key";
+/**
+ * Key file for the shared OAuth callback server on `port`. Sibling processes
+ * compute the same path, so they need the same OS user and home directory.
+ */
+function sharedOAuthKeyPath(port) {
+    return path.join(os.homedir(), `.gitlab-mcp-oauth-${port}.key`);
+}
+/**
+ * Write the key to an owner-only file without following symlinks. The caller
+ * holds the port, so an existing regular file of ours is left from an earlier run.
+ */
+function writeSharedOAuthKey(keyPath, key) {
+    const flags = fs.constants.O_WRONLY |
+        fs.constants.O_CREAT |
+        fs.constants.O_EXCL |
+        (fs.constants.O_NOFOLLOW ?? 0);
+    let fd;
+    try {
+        fd = fs.openSync(keyPath, flags, 0o600);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        const stat = fs.lstatSync(keyPath);
+        const uid = process.getuid?.();
+        if (!stat.isFile() || (uid !== undefined && stat.uid !== uid)) {
+            throw new Error(`Refusing to replace ${keyPath}: not a regular file owned by the current user`);
+        }
+        fs.unlinkSync(keyPath);
+        fd = fs.openSync(keyPath, flags, 0o600);
+    }
+    try {
+        fs.writeSync(fd, key);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function removeSharedOAuthKey(keyPath, key) {
+    try {
+        if (fs.readFileSync(keyPath, "utf8").trim() === key) {
+            fs.unlinkSync(keyPath);
+        }
+    }
+    catch {
+        // Best effort
+    }
+}
+async function readSharedOAuthKeyAsync(port) {
+    const keyPath = sharedOAuthKeyPath(port);
+    let problem = "ENOENT";
+    // The other process writes its key right after it binds the port.
+    for (let attempt = 0; attempt < 5; attempt++) {
+        if (attempt > 0) {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        try {
+            const key = fs.readFileSync(keyPath, "utf8").trim();
+            if (/^[0-9a-f]{64}$/.test(key)) {
+                return key;
+            }
+            problem = "unexpected content";
+        }
+        catch (error) {
+            problem = error.code ?? String(error);
+            if (problem !== "ENOENT") {
+                break;
+            }
+        }
+    }
+    throw new Error(`cannot read OAuth server key ${keyPath} (${problem}); the process holding port ${port} ` +
+        "must run as the same OS user with the same home directory");
+}
+/**
+ * Host headers the shared OAuth callback server answers: loopback names with
+ * its port, plus the configured redirect URI host. The listener is bound to
+ * 127.0.0.1, so any other Host comes from a name that merely resolves there
+ * (DNS rebinding).
+ */
+function sharedOAuthAllowedHosts(port, redirectUri) {
+    const hosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+    try {
+        hosts.add(new URL(redirectUri).host.toLowerCase());
+    }
+    catch {
+        // Malformed redirectUri: loopback names only
+    }
+    return hosts;
+}
+function sharedOAuthKeyMatches(provided, expected) {
+    if (typeof provided !== "string") {
+        return false;
+    }
+    const digest = (value) => crypto.createHash("sha256").update(value).digest();
+    return crypto.timingSafeEqual(digest(provided), digest(expected));
+}
 /**
  * Check if a port is already in use
  */
@@ -69,12 +180,14 @@ async function isPortInUse(port) {
  * Request authentication from an existing OAuth server
  */
 async function requestAuthFromExistingServer(port, requestId) {
+    const key = await readSharedOAuthKeyAsync(port);
     return new Promise((resolve, reject) => {
         const options = {
             hostname: "127.0.0.1",
             port: port,
             path: `/auth-request?requestId=${requestId}`,
             method: "GET",
+            headers: { [SHARED_OAUTH_KEY_HEADER]: key },
         };
         const req = http.request(options, res => {
             let data = "";
@@ -91,6 +204,9 @@ async function requestAuthFromExistingServer(port, requestId) {
                         reject(new Error(`Failed to parse token data: ${error}`));
                     }
                 }
+                else if (res.statusCode === 403) {
+                    reject(new Error(`OAuth server on port ${port} rejected the request key; it may run as a different OS user or an older version`));
+                }
                 else {
                     reject(new Error(`Auth request failed with status ${res.statusCode}: ${data}`));
                 }
@@ -288,7 +404,8 @@ export class GitLabOAuth {
             }
             catch (error) {
                 logger.error({ err: error }, "Failed to connect to existing OAuth server");
-                throw new Error(`Port ${callbackPort} is in use but cannot connect to existing OAuth server. Please close other instances or use a different port.`);
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new Error(`Port ${callbackPort} is in use but cannot connect to existing OAuth server: ${reason}. Please close other instances or use a different port.`);
             }
         }
         // Port is free, start the shared OAuth server
@@ -300,6 +417,9 @@ export class GitLabOAuth {
     async startSharedOAuthServer(callbackPort, initialRequestId) {
         const stateToRequestId = new Map();
         const requestIdToOAuthInstance = new Map();
+        const allowedHosts = sharedOAuthAllowedHosts(callbackPort, this.config.redirectUri);
+        const keyPath = sharedOAuthKeyPath(callbackPort);
+        const key = crypto.randomBytes(32).toString("hex");
         return new Promise((resolve, reject) => {
             // Create initial request
             const state = crypto.randomUUID();
@@ -312,9 +432,20 @@ export class GitLabOAuth {
             pendingAuthRequests.set(initialRequestId, { resolve, reject, timeout });
             const server = http.createServer(async (req, res) => {
                 try {
+                    // Only answer requests addressed to this listener by an expected name
+                    if (!allowedHosts.has((req.headers.host || "").toLowerCase())) {
+                        res.writeHead(403, { "Content-Type": "text/plain" });
+                        res.end("Forbidden");
+                        return;
+                    }
                     const parsedUrl = url.parse(req.url || "", true);
                     // Handle auth requests from other MCP instances
                     if (parsedUrl.pathname === "/auth-request") {
+                        if (!sharedOAuthKeyMatches(req.headers[SHARED_OAUTH_KEY_HEADER], key)) {
+                            res.writeHead(403, { "Content-Type": "text/plain" });
+                            res.end("Forbidden");
+                            return;
+                        }
                         const newRequestId = parsedUrl.query.requestId;
                         if (!newRequestId) {
                             res.writeHead(400, { "Content-Type": "text/plain" });
@@ -331,7 +462,7 @@ export class GitLabOAuth {
                         const authUrl = await this.getAuthorizationUrl(newState);
                         logger.info("Opening browser for new authentication request...");
                         logger.info(`If browser doesn't open, visit: ${redactUrlSecretsInText(authUrl)}`);
-                        open(authUrl).catch(err => {
+                        (this.config.openBrowser ?? open)(authUrl).catch(err => {
                             logger.error({ err }, "Failed to open browser");
                             logger.info(`Please manually open: ${redactUrlSecretsInText(authUrl)}`);
                         });
@@ -483,11 +614,24 @@ export class GitLabOAuth {
                 }
             });
             server.listen(callbackPort, "127.0.0.1", async () => {
+                sharedOAuthServers.add(server);
+                try {
+                    writeSharedOAuthKey(keyPath, key);
+                    const removeKey = () => removeSharedOAuthKey(keyPath, key);
+                    process.once("exit", removeKey);
+                    server.once("close", () => {
+                        process.removeListener("exit", removeKey);
+                        removeKey();
+                    });
+                }
+                catch (error) {
+                    logger.warn({ err: error }, `Failed to write ${keyPath}; other MCP instances cannot use this OAuth callback server`);
+                }
                 logger.info(`Shared OAuth callback server listening on port ${callbackPort}`);
                 const authUrl = await this.getAuthorizationUrl(state);
                 logger.info("Opening browser for authentication...");
                 logger.info(`If browser doesn't open, visit: ${redactUrlSecretsInText(authUrl)}`);
-                open(authUrl).catch(err => {
+                (this.config.openBrowser ?? open)(authUrl).catch(err => {
                     logger.error({ err }, "Failed to open browser");
                     logger.info(`Please manually open: ${redactUrlSecretsInText(authUrl)}`);
                 });

package/build/schemas.js

@@ -2253,6 +2253,30 @@ export const ApproveMergeRequestSchema = ProjectParamsSchema.extend({
 export const UnapproveMergeRequestSchema = ProjectParamsSchema.extend({
     merge_request_iid: z.coerce.string().describe("The IID of the merge request to unapprove"),
 });
+export const RebaseMergeRequestSchema = ProjectParamsSchema.extend({
+    merge_request_iid: z.coerce.string().describe("The IID of the merge request to rebase"),
+    skip_ci: coerceBooleanString
+        .optional()
+        .describe("If true, GitLab does not create a CI pipeline for the rebased source branch"),
+    wait: coerceBooleanString
+        .optional()
+        .default(true)
+        .describe("If true, poll the merge request until the rebase ends or timeout_seconds passes. If false, return GitLab's enqueue response at once."),
+    timeout_seconds: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(600)
+        .optional()
+        .describe("Maximum seconds to wait for the rebase to end"),
+    poll_interval_seconds: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(30)
+        .optional()
+        .describe("Seconds between status polls while waiting for the rebase"),
+});
 // Merge Request Approval State response schema
 export const GitLabApprovalUserSchema = z.object({
     id: z.coerce.string(),
@@ -3450,7 +3474,7 @@ export const DownloadAttachmentSchema = z.object({
     local_path: z
         .string()
         .optional()
-        .describe("Local path to save the file (optional, defaults to current directory)"),
+        .describe("Subdirectory of the download directory to save the file in (optional, defaults to the download directory itself). Names starting with a dot are rejected"),
 });
 export const DownloadAttachmentRemoteSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path of the project"),

package/build/stateless/types.js

@@ -15,4 +15,6 @@ export const STATELESS_PURPOSES = {
     STORED_TOKENS: "pc",
     /** Sealed Mcp-Session-Id, carries session auth across pod hops. */
     SESSION_ID: "sid",
+    /** HMAC key for remembered callback-proxy consent cookies. */
+    OAUTH_CONSENT: "oc",
 };

package/build/tools/exposed-tools.js

@@ -38,3 +38,17 @@ export function selectExposedTools(input) {
     }
     return withoutHidden.filter(tool => !isExcludedBySlimProfile(tool.name, true, input.individuallyEnabledTools));
 }
+/**
+ * Hidden tools that would be listed if the hidden policy were ignored.
+ * Hiding a tool keeps it callable only while toolsets, `GITLAB_TOOLS`, legacy
+ * flags, permission mode, and the regex denylist still expose it.
+ */
+export function selectCallableHiddenToolNames(input) {
+    if (input.hiddenToolNames.size === 0) {
+        return new Set();
+    }
+    const exposedIgnoringHidden = selectExposedTools({ ...input, hiddenToolNames: new Set() });
+    return new Set(exposedIgnoringHidden
+        .map(tool => tool.name)
+        .filter(toolName => input.hiddenToolNames.has(toolName)));
+}

package/build/tools/registry.js

@@ -1,7 +1,7 @@
 import { toJSONSchema } from "../utils/schema.js";
 import { USE_GITLAB_WIKI, USE_MILESTONE, USE_PIPELINE, SSE, STREAMABLE_HTTP } from "../config.js";
 import { getToolDescription } from "./tool-descriptions.js";
-import { ApproveMergeRequestSchema, BulkPublishDraftNotesSchema, CancelPipelineJobSchema, ErasePipelineJobSchema, CancelPipelineSchema, ConvertWorkItemTypeSchema, CreateBranchSchema, CreateDraftNoteSchema, CreateGroupSchema, CreateGroupWikiPageSchema, CreateIssueLinkSchema, CreateIssueNoteSchema, CreateIssueSchema, CreateIssueEmojiReactionSchema, CreateIssueNoteEmojiReactionSchema, ListIssueEmojiReactionsSchema, ListIssueNoteEmojiReactionsSchema, CreateLabelSchema, MarkAllTodosDoneSchema, ListTodosSchema, MarkTodoDoneSchema, CreateMergeRequestDiscussionNoteSchema, CreateMergeRequestEmojiReactionSchema, ListMergeRequestEmojiReactionsSchema, ListMergeRequestNoteEmojiReactionsSchema, CreateMergeRequestNoteSchema, CreateMergeRequestNoteEmojiReactionSchema, CreateMergeRequestSchema, CreateMergeRequestThreadSchema, CreateNoteSchema, CreateCommitStatusSchema, CreateOrUpdateFileSchema, CreatePipelineSchema, CreateProjectMilestoneSchema, CreateGroupMilestoneSchema, CreateReleaseEvidenceSchema, CreateReleaseSchema, CreateRepositorySchema, CreateTagSchema, CreateTimelineEventSchema, CreateWebhookSchema, CreateWikiPageSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, CreateWorkItemSchema, DeleteBranchSchema, GetProtectedBranchSchema, ListProtectedBranchesSchema, ProtectBranchSchema, ProtectTagSchema, UnprotectBranchSchema, UnprotectTagSchema, UpdateDefaultBranchSchema, DeleteDraftNoteSchema, DeleteGroupMilestoneSchema, DeleteGroupWikiPageSchema, DeleteIssueLinkSchema, DeleteIssueSchema, DeleteIssueEmojiReactionSchema, DeleteIssueNoteEmojiReactionSchema, DeleteLabelSchema, DeleteMergeRequestDiscussionNoteSchema, DeleteMergeRequestNoteSchema, DeleteMergeRequestEmojiReactionSchema, DeleteMergeRequestNoteEmojiReactionSchema, DeleteProjectMilestoneSchema, DeleteReleaseSchema, DeleteTagSchema, DeleteWebhookSchema, DeleteWikiPageSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, DownloadAttachmentSchema, DownloadAttachmentRemoteSchema, DownloadJobArtifactsSchema, DownloadJobArtifactsRemoteSchema, DownloadReleaseAssetSchema, EditProjectMilestoneSchema, EditGroupMilestoneSchema, ExecuteGraphQLSchema, ForkRepositorySchema, HealthCheckSchema, GetBranchSchema, GetBranchDiffsSchema, GetCommitDiffSchema, GetCommitSchema, GetFileBlameSchema, GetDeploymentSchema, CreateDeploymentSchema, UpdateDeploymentSchema, DeploymentApprovalSchema, ListDeploymentMergeRequestsSchema, GetDraftNoteSchema, GetEnvironmentSchema, UpdateEnvironmentSchema, StopEnvironmentSchema, StopStaleEnvironmentsSchema, DeleteReviewAppEnvironmentsSchema, PipelineTriggerIdSchema, ListPipelineTriggersSchema, CreatePipelineTriggerSchema, UpdatePipelineTriggerSchema, TriggerPipelineSchema, GetFileContentsSchema, GetGroupWikiPageSchema, GetIssueLinkSchema, GetIssueSchema, GetJobArtifactFileSchema, GetLabelSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GetMergeRequestDiffsSchema, GetMergeRequestFileDiffSchema, GetMergeRequestDiscussionSchema, GetMergeRequestNoteSchema, GetMergeRequestNotesSchema, GetMergeRequestSchema, GetMergeRequestVersionSchema, GetMilestoneBurndownEventsSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, GetGroupMilestoneSchema, GetGroupMilestoneIssuesSchema, GetGroupMilestoneMergeRequestsSchema, GetGroupMilestoneBurndownEventsSchema, GetNamespaceSchema, GetPipelineJobOutputSchema, PipelineJobControlSchema, GetPipelineSchema, GetRunnerSchema, GetPipelineVariablesSchema, UpdatePipelineMetadataSchema, DeletePipelineSchema, PipelineReportSchema, WaitForPipelineSchema, WaitForPipelineJobSchema, PlayPipelineJobsSchema, GetProjectEventsSchema, GetProjectMilestoneSchema, GetProjectSchema, GetReleaseSchema, GetRepositoryTreeSchema, GetTagSchema, GetTagSignatureSchema, GetProtectedTagSchema, GetTimelineEventsSchema, GetUsersSchema, GetUserSchema, WhoAmISchema, GetWebhookEventSchema, GetWikiPageSchema, GetWorkItemSchema, ListBranchesSchema, ListCommitsSchema, ListCommitStatusesSchema, ListCustomFieldDefinitionsSchema, ListDeploymentsSchema, ListDraftNotesSchema, ListEnvironmentsSchema, ListEventsSchema, ListGroupIterationsSchema, ListGroupMilestonesSchema, ListGroupProjectsSchema, ListGroupWikiPagesSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListJobArtifactsSchema, ListLabelsSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiffsSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestVersionsSchema, ListMergeRequestsSchema, ListGroupMergeRequestsSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListCiCatalogResourcesSchema, GetCiCatalogResourceSchema, ListPipelinesSchema, ListPipelineSchedulesSchema, GetPipelineScheduleSchema, ListPipelineSchedulePipelinesSchema, CreatePipelineScheduleSchema, UpdatePipelineScheduleSchema, DeletePipelineScheduleSchema, PlayPipelineScheduleSchema, TakeOwnershipPipelineScheduleSchema, GetPipelineScheduleVariableSchema, CreatePipelineScheduleVariableSchema, UpdatePipelineScheduleVariableSchema, DeletePipelineScheduleVariableSchema, ListGroupMembersSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListProjectRunnersSchema, ListReleasesSchema, ListTagsSchema, ListProtectedTagsSchema, ListWebhookEventsSchema, ListWebhooksSchema, ListWikiPagesSchema, ListWorkItemNotesSchema, ListWorkItemStatusesSchema, ListWorkItemsSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, MergeMergeRequestSchema, MoveWorkItemSchema, MyIssuesSchema, OrbitQuerySchema, OrbitSchemaSchema, OrbitStatusSchema, OrbitToolsSchema, PlayPipelineJobSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PushFilesSchema, ResolveMergeRequestThreadSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, ListSnippetsSchema, GetSnippetSchema, CreateSnippetSchema, UpdateSnippetSchema, DeleteSnippetSchema, UnapproveMergeRequestSchema, UpdateDraftNoteSchema, UpdateGroupWikiPageSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateProjectSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestSchema, UpdateReleaseSchema, UpdateWebhookSchema, UpdateWikiPageSchema, UpdateWorkItemSchema, VerifyNamespaceSchema, ListProjectVariablesSchema, GetProjectVariableSchema, CreateProjectVariableSchema, UpdateProjectVariableSchema, DeleteProjectVariableSchema, ListGroupVariablesSchema, GetGroupVariableSchema, CreateGroupVariableSchema, UpdateGroupVariableSchema, DeleteGroupVariableSchema, GetDependencyProxySettingsSchema, UpdateDependencyProxySettingsSchema, ListDependencyProxyBlobsSchema, PurgeDependencyProxyCacheSchema, ListProjectVulnerabilitiesSchema, GetVulnerabilitySchema, DismissVulnerabilitySchema, ConfirmVulnerabilitySchema, } from "../schemas.js";
+import { ApproveMergeRequestSchema, BulkPublishDraftNotesSchema, CancelPipelineJobSchema, ErasePipelineJobSchema, CancelPipelineSchema, ConvertWorkItemTypeSchema, CreateBranchSchema, CreateDraftNoteSchema, CreateGroupSchema, CreateGroupWikiPageSchema, CreateIssueLinkSchema, CreateIssueNoteSchema, CreateIssueSchema, CreateIssueEmojiReactionSchema, CreateIssueNoteEmojiReactionSchema, ListIssueEmojiReactionsSchema, ListIssueNoteEmojiReactionsSchema, CreateLabelSchema, MarkAllTodosDoneSchema, ListTodosSchema, MarkTodoDoneSchema, CreateMergeRequestDiscussionNoteSchema, CreateMergeRequestEmojiReactionSchema, ListMergeRequestEmojiReactionsSchema, ListMergeRequestNoteEmojiReactionsSchema, CreateMergeRequestNoteSchema, CreateMergeRequestNoteEmojiReactionSchema, CreateMergeRequestSchema, CreateMergeRequestThreadSchema, CreateNoteSchema, CreateCommitStatusSchema, CreateOrUpdateFileSchema, CreatePipelineSchema, CreateProjectMilestoneSchema, CreateGroupMilestoneSchema, CreateReleaseEvidenceSchema, CreateReleaseSchema, CreateRepositorySchema, CreateTagSchema, CreateTimelineEventSchema, CreateWebhookSchema, CreateWikiPageSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, CreateWorkItemSchema, DeleteBranchSchema, GetProtectedBranchSchema, ListProtectedBranchesSchema, ProtectBranchSchema, ProtectTagSchema, UnprotectBranchSchema, UnprotectTagSchema, UpdateDefaultBranchSchema, DeleteDraftNoteSchema, DeleteGroupMilestoneSchema, DeleteGroupWikiPageSchema, DeleteIssueLinkSchema, DeleteIssueSchema, DeleteIssueEmojiReactionSchema, DeleteIssueNoteEmojiReactionSchema, DeleteLabelSchema, DeleteMergeRequestDiscussionNoteSchema, DeleteMergeRequestNoteSchema, DeleteMergeRequestEmojiReactionSchema, DeleteMergeRequestNoteEmojiReactionSchema, DeleteProjectMilestoneSchema, DeleteReleaseSchema, DeleteTagSchema, DeleteWebhookSchema, DeleteWikiPageSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, DownloadAttachmentSchema, DownloadAttachmentRemoteSchema, DownloadJobArtifactsSchema, DownloadJobArtifactsRemoteSchema, DownloadReleaseAssetSchema, EditProjectMilestoneSchema, EditGroupMilestoneSchema, ExecuteGraphQLSchema, ForkRepositorySchema, HealthCheckSchema, GetBranchSchema, GetBranchDiffsSchema, GetCommitDiffSchema, GetCommitSchema, GetFileBlameSchema, GetDeploymentSchema, CreateDeploymentSchema, UpdateDeploymentSchema, DeploymentApprovalSchema, ListDeploymentMergeRequestsSchema, GetDraftNoteSchema, GetEnvironmentSchema, UpdateEnvironmentSchema, StopEnvironmentSchema, StopStaleEnvironmentsSchema, DeleteReviewAppEnvironmentsSchema, PipelineTriggerIdSchema, ListPipelineTriggersSchema, CreatePipelineTriggerSchema, UpdatePipelineTriggerSchema, TriggerPipelineSchema, GetFileContentsSchema, GetGroupWikiPageSchema, GetIssueLinkSchema, GetIssueSchema, GetJobArtifactFileSchema, GetLabelSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GetMergeRequestDiffsSchema, GetMergeRequestFileDiffSchema, GetMergeRequestDiscussionSchema, GetMergeRequestNoteSchema, GetMergeRequestNotesSchema, GetMergeRequestSchema, GetMergeRequestVersionSchema, GetMilestoneBurndownEventsSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, GetGroupMilestoneSchema, GetGroupMilestoneIssuesSchema, GetGroupMilestoneMergeRequestsSchema, GetGroupMilestoneBurndownEventsSchema, GetNamespaceSchema, GetPipelineJobOutputSchema, PipelineJobControlSchema, GetPipelineSchema, GetRunnerSchema, GetPipelineVariablesSchema, UpdatePipelineMetadataSchema, DeletePipelineSchema, PipelineReportSchema, WaitForPipelineSchema, WaitForPipelineJobSchema, PlayPipelineJobsSchema, GetProjectEventsSchema, GetProjectMilestoneSchema, GetProjectSchema, GetReleaseSchema, GetRepositoryTreeSchema, GetTagSchema, GetTagSignatureSchema, GetProtectedTagSchema, GetTimelineEventsSchema, GetUsersSchema, GetUserSchema, WhoAmISchema, GetWebhookEventSchema, GetWikiPageSchema, GetWorkItemSchema, ListBranchesSchema, ListCommitsSchema, ListCommitStatusesSchema, ListCustomFieldDefinitionsSchema, ListDeploymentsSchema, ListDraftNotesSchema, ListEnvironmentsSchema, ListEventsSchema, ListGroupIterationsSchema, ListGroupMilestonesSchema, ListGroupProjectsSchema, ListGroupWikiPagesSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListJobArtifactsSchema, ListLabelsSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiffsSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestVersionsSchema, ListMergeRequestsSchema, ListGroupMergeRequestsSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListCiCatalogResourcesSchema, GetCiCatalogResourceSchema, ListPipelinesSchema, ListPipelineSchedulesSchema, GetPipelineScheduleSchema, ListPipelineSchedulePipelinesSchema, CreatePipelineScheduleSchema, UpdatePipelineScheduleSchema, DeletePipelineScheduleSchema, PlayPipelineScheduleSchema, TakeOwnershipPipelineScheduleSchema, GetPipelineScheduleVariableSchema, CreatePipelineScheduleVariableSchema, UpdatePipelineScheduleVariableSchema, DeletePipelineScheduleVariableSchema, ListGroupMembersSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListProjectRunnersSchema, ListReleasesSchema, ListTagsSchema, ListProtectedTagsSchema, ListWebhookEventsSchema, ListWebhooksSchema, ListWikiPagesSchema, ListWorkItemNotesSchema, ListWorkItemStatusesSchema, ListWorkItemsSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, MergeMergeRequestSchema, MoveWorkItemSchema, MyIssuesSchema, OrbitQuerySchema, OrbitSchemaSchema, OrbitStatusSchema, OrbitToolsSchema, PlayPipelineJobSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PushFilesSchema, ResolveMergeRequestThreadSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, ListSnippetsSchema, GetSnippetSchema, CreateSnippetSchema, UpdateSnippetSchema, DeleteSnippetSchema, UnapproveMergeRequestSchema, RebaseMergeRequestSchema, UpdateDraftNoteSchema, UpdateGroupWikiPageSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateProjectSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestSchema, UpdateReleaseSchema, UpdateWebhookSchema, UpdateWikiPageSchema, UpdateWorkItemSchema, VerifyNamespaceSchema, ListProjectVariablesSchema, GetProjectVariableSchema, CreateProjectVariableSchema, UpdateProjectVariableSchema, DeleteProjectVariableSchema, ListGroupVariablesSchema, GetGroupVariableSchema, CreateGroupVariableSchema, UpdateGroupVariableSchema, DeleteGroupVariableSchema, GetDependencyProxySettingsSchema, UpdateDependencyProxySettingsSchema, ListDependencyProxyBlobsSchema, PurgeDependencyProxyCacheSchema, ListProjectVulnerabilitiesSchema, GetVulnerabilitySchema, DismissVulnerabilitySchema, ConfirmVulnerabilitySchema, } from "../schemas.js";
 import { GitLabApiRequestSchema } from "./gitlab-api-request.js";
 const IS_REMOTE = SSE || STREAMABLE_HTTP;
 // Define all available tools
@@ -1007,7 +1007,7 @@ export const allTools = [
         name: "download_attachment",
         description: IS_REMOTE
             ? "Download an uploaded file from a project (images returned inline as base64, other files returned as download URL)"
-            : "Download an uploaded file from a project (images returned as base64; use local_path to save to disk)",
+            : "Download an uploaded file from a project (images returned as base64; other files, or images with local_path, are saved as new files under the download directory)",
         inputSchema: IS_REMOTE
             ? toJSONSchema(DownloadAttachmentRemoteSchema)
             : toJSONSchema(DownloadAttachmentSchema),
@@ -1397,6 +1397,11 @@ export const allTools = [
         description: "Get one runner by ID",
         inputSchema: toJSONSchema(GetRunnerSchema),
     },
+    {
+        name: "rebase_merge_request",
+        description: "Rebase the source branch of a merge request onto its target branch",
+        inputSchema: toJSONSchema(RebaseMergeRequestSchema),
+    },
     // --- Explicit opt-in raw API. Not in `all` and not activatable via discover_tools. ---
     {
         name: "gitlab_api_request",
@@ -1570,8 +1575,14 @@ export const readOnlyTools = new Set([
 // Stays in readOnlyTools so readonly mode can still run queries, but mutations
 // are allowed in other permission modes and rejected only at call time.
 const MIXED_ACCESS_TOOLS = new Set(["execute_graphql", "gitlab_api_request"]);
+// Read-only on GitLab, but in stdio mode they save files to the local disk. They stay
+// listed in readonly mode, where the handlers refuse anything that would write a file
+// (only inline images are returned), and never advertise readOnlyHint.
+const LOCAL_FILE_WRITE_TOOLS = new Set(IS_REMOTE ? [] : ["download_attachment", "download_job_artifacts"]);
 export function advertisesReadOnly(toolName) {
-    return readOnlyTools.has(toolName) && !MIXED_ACCESS_TOOLS.has(toolName);
+    return (readOnlyTools.has(toolName) &&
+        !MIXED_ACCESS_TOOLS.has(toolName) &&
+        !LOCAL_FILE_WRITE_TOOLS.has(toolName));
 }
 // Define which tools are destructive (data loss potential)
 export const destructiveTools = new Set([
@@ -1614,6 +1625,7 @@ export const destructiveTools = new Set([
     "protect_tag",
     "update_default_branch",
     "merge_merge_request",
+    "rebase_merge_request",
     "push_files",
     "delete_project_variable",
     "delete_group_variable",
@@ -1817,6 +1829,7 @@ export const TOOLSET_DEFINITIONS = [
         isDefault: false,
         tools: new Set([
             "merge_merge_request",
+            "rebase_merge_request",
             "approve_merge_request",
             "unapprove_merge_request",
             "get_merge_request_approval_state",
@@ -2254,8 +2267,15 @@ const discoverTool = allTools.find(t => t.name === "discover_tools");
 if (discoverTool) {
     discoverTool.description = `Discover and activate additional tool categories for this session. Available categories: ${[...DISCOVERABLE_TOOLSET_IDS].join(", ")}. Already-active categories are listed in the response. Explicit-only toolsets are omitted; list them in GITLAB_TOOLSETS.`;
 }
+function acceptsProjectOrGroupId(inputSchema) {
+    const properties = inputSchema?.properties;
+    return (typeof properties === "object" &&
+        properties !== null &&
+        ("project_id" in properties || "group_id" in properties));
+}
+const allToolNames = new Set(allTools.map(tool => tool.name));
 for (const tool of allTools) {
-    tool.description = getToolDescription(tool.name, tool.description, readOnlyTools.has(tool.name), destructiveTools.has(tool.name));
+    tool.description = getToolDescription(tool.name, tool.description, readOnlyTools.has(tool.name), destructiveTools.has(tool.name), acceptsProjectOrGroupId(tool.inputSchema), allToolNames);
 }
 export function parseEnabledToolsets(raw) {
     if (!raw || raw.trim() === "") {

package/build/tools/tool-descriptions.js

@@ -2,6 +2,7 @@ const TOOL_GUIDANCE = {
     merge_merge_request: "Use this only after checking the merge request approval, conflict, and pipeline state; use `approve_merge_request` to approve rather than merge. The operation changes repository state and may squash commits, schedule auto-merge, or delete the source branch, so it requires merge permission and returns GitLab's merge result or a mergeability error. Pass `sha` from `get_merge_request` (`sha` or `diff_refs.head_sha`); GitLab 19.2+ groups may reject merges without it.",
     approve_merge_request: "Use this to record an approval on an existing merge request; it does not merge the request or change its source branch. The operation changes review state, may require re-authentication or approval permission, and returns the updated approval result or a permission/state error.",
     unapprove_merge_request: "Use this to remove the current user's approval from an existing merge request; use `merge_merge_request` only when you intend to merge. The operation changes review state and requires approval permission, and GitLab returns the updated result or an error when the request or approval is unavailable.",
+    rebase_merge_request: "Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request: GitLab reports a failed rebase in `merge_error`, but that field can also keep a message from an earlier attempt, so compare `sha` with its value before the rebase. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.",
     get_merge_request_approval_state: "Use this to inspect approval rules and approvers before deciding whether a merge request can be merged; use `approve_merge_request` to change approval state. It is read-only and returns the approval-state response, while missing requests, unsupported GitLab versions, and permission failures are reported as errors.",
     get_merge_request_conflicts: "Use this to inspect merge conflicts before attempting `merge_merge_request`; it reports conflicts and does not resolve them. It is read-only, requires access to the project and merge request, and returns GitLab's conflict data or an error when the request cannot be evaluated.",
     list_merge_request_pipelines: "Use this to inspect pipelines associated with one merge request; use `list_pipelines` for project-wide pipeline filtering. It is read-only and paginated, requires project access, and returns pipeline records or GitLab errors for invalid identifiers, missing resources, or rate limits.",
@@ -34,8 +35,8 @@ const TOOL_GUIDANCE = {
     update_issue_description_patch: "Use this for a targeted search/replace or unified-diff change to an issue description; use `dry_run` before applying an uncertain patch and `create_note` when an audit summary is wanted. It changes the issue description when not dry-running, requires issue-edit permission, and returns the patch result or a mismatch/validation/permission error.",
     delete_issue: "Use this only after confirming the issue and intended permanent removal; use `update_issue` to close or edit an issue without deleting it. The operation permanently removes issue data, requires delete permission, and returns the deletion result or a missing-resource, permission, or policy error.",
     delete_issue_link: "Use this to remove an existing relationship between two issues; use `list_issue_links` or `get_issue_link` to verify the link first. The operation changes issue relationships, requires issue-edit permission, and returns the result or an error when the link is missing or access is denied.",
-    download_job_artifacts: "Use this to retrieve a pipeline job's artifact archive; remote HTTP mode returns a download URL while local mode saves the archive to a local path. It is read-only but may create a local file in stdio mode, requires job/project access, and returns the download result or an artifact/permission error.",
-    download_attachment: "Use this to retrieve a previously uploaded project attachment; remote mode returns inline base64 for images or a download URL, while local mode can save to a path. It is read-only with respect to GitLab, requires project access, and returns the file content or an attachment/permission error.",
+    download_job_artifacts: "Use this to retrieve a pipeline job's artifact archive; remote HTTP mode returns a download URL while local mode saves the archive to a local path. It is read-only on GitLab but creates a local file in stdio mode (rejected in readonly mode), requires job/project access, and returns the download result or an artifact/permission error.",
+    download_attachment: "Use this to retrieve a previously uploaded project attachment; remote mode returns inline base64 for images or a download URL, while local mode saves the file as a new file under the download directory (GITLAB_DOWNLOAD_DIR, default .gitlab-mcp-downloads). It is read-only with respect to GitLab but creates a local file in stdio mode (readonly mode returns images inline and rejects everything else), never replaces an existing file, requires project access, and returns the file content or an attachment/permission error.",
     gitlab_api_request: "Send one GitLab REST call under /api/v4. Readonly mode allows GET only, and modify mode rejects DELETE. Enable it only by listing api in GITLAB_TOOLSETS; all, discover_tools, and GITLAB_TOOLS do not. Prompt injection can drive this tool, so operators who rely on group, project, or tool restrictions must not enable it. GITLAB_ALLOWED_PROJECT_IDS is enforced only for /projects/:id paths; other endpoints are not constrained.",
     execute_graphql: "Use this only when a supported GitLab REST tool does not cover the requested operation; prefer a typed tool when one exists. The query is sent directly to GitLab and can include mutations when permission allows, so callers must treat it as potentially state-changing and handle GraphQL errors in the returned response.",
     discover_tools: "Use this when a needed opt-in category is not currently exposed; omit `category` to inspect available categories, then call it with a category to activate that group for the current session. It changes only the session's tool registry, returns the active-tool summary, and does not change GitLab data.",
@@ -62,46 +63,80 @@ const TOOL_GUIDANCE = {
     orbit_get_status: "Use this to check whether Orbit indexing has completed before trusting `orbit_query` results; results reflect the last index cycle, not real-time state. It is read-only and free of credit charges, and returns the indexing status or a permission error.",
     orbit_list_tools: "Use this to see which MCP tool definitions Orbit itself exposes; use `orbit_query` to run graph queries directly. It is read-only and free of credit charges, and returns the tool definition list or a permission error.",
 };
-const PARAMETER_GUIDANCE = "When `project_id` or `group_id` is accepted, provide the numeric ID or complete URL-encoded path described by the schema; use required identifiers and pagination fields exactly as documented.";
+const PARAMETER_GUIDANCE = "`project_id`/`group_id` take a numeric ID or URL-encoded path.";
 function ensureSentence(text) {
     const trimmed = text.trim();
     return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
 }
-function getLifecycleGuidance(name) {
+// Candidate get_* names for a list_* resource: list_pipelines -> get_pipeline,
+// list_branches -> get_branch, list_policies -> get_policy, list_diffs -> get_diffs.
+function matchingGetToolNames(resource) {
+    const candidates = [`get_${resource}`];
+    if (resource.endsWith("ies"))
+        candidates.push(`get_${resource.slice(0, -3)}y`);
+    if (resource.endsWith("es"))
+        candidates.push(`get_${resource.slice(0, -2)}`);
+    if (resource.endsWith("s"))
+        candidates.push(`get_${resource.slice(0, -1)}`);
+    return candidates;
+}
+// Candidate list_*/search_* names for a get_* resource: get_pipeline -> list_pipelines,
+// get_branch -> list_branches, get_policy -> list_policies, get_diffs -> list_diffs.
+function matchingDiscoveryToolNames(resource) {
+    const plurals = [resource, `${resource}s`, `${resource}es`];
+    if (resource.endsWith("y"))
+        plurals.push(`${resource.slice(0, -1)}ies`);
+    return plurals.flatMap(plural => [`list_${plural}`, `search_${plural}`]);
+}
+// Sibling hints are only added when the sibling tool exists, so a description
+// never points at a tool the server does not have.
+function getLifecycleGuidance(name, toolNames) {
     const verb = name.split("_")[0] ?? "use";
+    const resource = name.slice(verb.length + 1);
     if (verb === "list") {
-        return "Use this for a collection of resources; choose the corresponding get tool when you already know the single resource to inspect.";
+        return matchingGetToolNames(resource).some(candidate => toolNames.has(candidate))
+            ? "For one known resource, use the matching get tool."
+            : "";
     }
     if (verb === "get") {
-        return "Use this for a known resource or result; choose the corresponding list or search tool when you need to discover multiple resources.";
+        return matchingDiscoveryToolNames(resource).some(candidate => toolNames.has(candidate))
+            ? "To find resources, use the matching list or search tool."
+            : "";
     }
     if (verb === "create") {
-        return "Use this for a new resource or action; choose the corresponding update or edit tool when the resource already exists.";
+        return toolNames.has(`update_${resource}`) || toolNames.has(`edit_${resource}`)
+            ? "If the resource already exists, use the update tool."
+            : "";
     }
     if (verb === "update" || verb === "edit") {
-        return "Use this for an existing resource; choose the corresponding create tool for a new resource and a note tool for discussion-only text.";
+        if (!toolNames.has(`create_${resource}`)) {
+            return "";
+        }
+        return toolNames.has(`create_${resource}_note`)
+            ? "Use the create tool for new resources and a note tool for comments."
+            : "Use the create tool for new resources.";
     }
     if (verb === "delete" || verb === "remove") {
-        return "Use this only after verifying the target; choose a get or list tool first when you need to inspect state without changing it.";
+        return "Verify the target first with a get or list tool.";
     }
     if (verb === "search") {
-        return "Use this to discover matching content; choose a typed get or list tool when the target identifier is already known.";
+        return "If the identifier is known, use a typed get or list tool.";
     }
     if (verb === "validate") {
-        return "Use this to check configuration without applying it; choose a create or update tool only after validation succeeds.";
+        return "Checks without applying; create or update only after it passes.";
     }
-    return "Use this for the specific operation described; choose a sibling tool when you need a different resource or lifecycle action.";
+    return "";
 }
 function getBehaviorGuidance(readOnly, destructive) {
     if (readOnly) {
-        return "It is read-only and does not mutate GitLab data; missing resources, invalid identifiers, insufficient permission, and rate limits are returned as errors.";
+        return "Read-only; missing resources, denied access, and rate limits return errors.";
     }
     if (destructive) {
-        return "It changes or removes remote GitLab data and may be irreversible; it requires the necessary project or group permission and returns validation, conflict, permission, or rate-limit errors.";
+        return "Changes or removes GitLab data and may be irreversible; needs permission.";
     }
-    return "It changes remote GitLab state and requires the necessary project or group permission; GitLab returns validation, conflict, permission, or rate-limit errors instead of silently applying an invalid request.";
+    return "Changes GitLab data; needs permission and returns validation or conflict errors.";
 }
-export function getToolDescription(name, baseDescription, readOnly, destructive) {
+export function getToolDescription(name, baseDescription, readOnly, destructive, acceptsProjectOrGroupId, toolNames) {
     const explicitGuidance = TOOL_GUIDANCE[name];
     if (explicitGuidance) {
         return `${ensureSentence(baseDescription)} ${explicitGuidance}`;
@@ -110,5 +145,12 @@ export function getToolDescription(name, baseDescription, readOnly, destructive)
     if (normalizedDescription.length >= 180) {
         return normalizedDescription;
     }
-    return `${normalizedDescription} ${getLifecycleGuidance(name)} ${getBehaviorGuidance(readOnly, destructive)} ${PARAMETER_GUIDANCE}`;
+    return [
+        normalizedDescription,
+        getLifecycleGuidance(name, toolNames),
+        getBehaviorGuidance(readOnly, destructive),
+        acceptsProjectOrGroupId ? PARAMETER_GUIDANCE : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
 }

package/build/utils/graphql-query.js

@@ -112,8 +112,7 @@ function skipInsignificantGraphQL(source, index) {
 function extractTopLevelMutationFields(normalized) {
     const fields = [];
     const mutationRegex = /(?:^|[;},]\s*)mutation\b[^({]*(?:\([^)]*\))?\s*\{/g;
-    let match;
-    while ((match = mutationRegex.exec(normalized)) !== null) {
+    while (mutationRegex.exec(normalized) !== null) {
         let i = mutationRegex.lastIndex;
         let braceDepth = 1;
         let parenDepth = 0;

package/build/utils/helpers.js

@@ -82,8 +82,11 @@ export function resolveSafeExistingPath(inputPath, label = "path", baseDir) {
  * it if needed. Rejects symlink components and verifies the final real path
  * remains inside the base.
  */
-export function resolveSafeOutputDir(inputDir, label = "local_path", baseDir) {
+export function resolveSafeOutputDir(inputDir, label = "local_path", baseDir, options = {}) {
     const relative = assertSafeRelativePath(inputDir, label);
+    if (options.rejectDotNames && relative.split(path.sep).some(isDotName)) {
+        throw new Error(`Invalid ${label}: names starting with a dot are not allowed.`);
+    }
     const baseReal = resolveTrustedBaseDir(baseDir);
     assertNoSymlinkComponents(baseReal, relative, label);
     const absolute = path.resolve(baseReal, relative);
@@ -136,6 +139,11 @@ const WRITE_OPEN_FLAGS = fs.constants.O_WRONLY |
     fs.constants.O_CREAT |
     fs.constants.O_TRUNC |
     (fs.constants.O_NOFOLLOW ?? 0);
+// O_EXCL also refuses a symlink in the final component.
+const EXCLUSIVE_WRITE_OPEN_FLAGS = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL;
+function isDotName(part) {
+    return part.startsWith(".") && part !== ".";
+}
 /**
  * Validate and read a file in one step so callers never reuse a path string
  * after a symlink swap (final-component TOCTOU mitigation via O_NOFOLLOW).
@@ -171,7 +179,7 @@ export function readSafeExistingFile(inputPath, label = "path", baseDir) {
  * Validate an output destination and open a write stream immediately so the
  * path is not handed back for a separate createWriteStream call.
  */
-export function openSafeOutputWriteStream(filename, inputDir, label = "local_path", baseDir) {
+export function openSafeOutputWriteStream(filename, inputDir, label = "local_path", baseDir, options = {}) {
     if (!filename ||
         filename === "." ||
         filename === ".." ||
@@ -180,10 +188,27 @@ export function openSafeOutputWriteStream(filename, inputDir, label = "local_pat
         filename.includes(path.sep)) {
         throw new Error(`Invalid ${label}: directory separators are not allowed in filename.`);
     }
+    if (options.rejectDotNames && isDotName(filename)) {
+        throw new Error("Invalid filename: names starting with a dot are not allowed.");
+    }
     const dirReal = inputDir
-        ? resolveSafeOutputDir(inputDir, label, baseDir)
+        ? resolveSafeOutputDir(inputDir, label, baseDir, options)
         : resolveTrustedBaseDir(baseDir);
     const dest = path.join(dirReal, filename);
+    if (options.exclusive) {
+        let fd;
+        try {
+            fd = fs.openSync(dest, EXCLUSIVE_WRITE_OPEN_FLAGS, 0o666);
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                throw new Error(`${dest} already exists. Choose another ${label} or remove the file first.`);
+            }
+            throw err;
+        }
+        const stream = fs.createWriteStream(null, { fd, autoClose: true });
+        return { stream, path: dest };
+    }
     try {
         const st = fs.lstatSync(dest);
         if (st.isSymbolicLink()) {
@@ -203,6 +228,40 @@ export function openSafeOutputWriteStream(filename, inputDir, label = "local_pat
     });
     return { stream, path: dest };
 }
+export const DEFAULT_DOWNLOAD_DIR = ".gitlab-mcp-downloads";
+/**
+ * Resolve (and create on first use) the directory that downloads are saved under.
+ * The default sits in the working directory, which may be a cloned repository, so it
+ * must be a real directory rather than a symlink planted there. A directory the
+ * server creates gets a `.gitignore` so its contents are never committed by accident.
+ */
+export function resolveDownloadRoot(configured) {
+    const root = path.resolve(configured || DEFAULT_DOWNLOAD_DIR);
+    let st;
+    try {
+        st = fs.lstatSync(root);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    if (st?.isSymbolicLink() && !configured) {
+        throw new Error(`Invalid download directory: ${root} is a symbolic link. Remove it or set GITLAB_DOWNLOAD_DIR.`);
+    }
+    if (!st) {
+        fs.mkdirSync(root, { recursive: true });
+        try {
+            fs.writeFileSync(path.join(root, ".gitignore"), "*\n", { flag: "wx" });
+        }
+        catch (err) {
+            if (err.code !== "EEXIST") {
+                throw err;
+            }
+        }
+    }
+    return fs.realpathSync(root);
+}
 /**
  * Estimate the number of merge commits that will be added based on the merge method.
  */
@@ -245,7 +304,7 @@ export function filterDiffsByPatterns(diffs, excludedFilePatterns) {
         try {
             return new RegExp(pattern);
         }
-        catch (e) {
+        catch {
             console.warn(`Invalid regex pattern ignored: ${pattern}`);
             return null;
         }