@zereight/mcp-gitlab 2.1.13 → 2.1.14

package/build/index.js

@@ -1,5 +1,111 @@
 #!/usr/bin/env node
 import { getConfig, ENABLE_DYNAMIC_API_URL, GITLAB_AUTH_COOKIE_PATH, GITLAB_CA_CERT_PATH, GITLAB_JOB_TOKEN, GITLAB_MCP_OAUTH, GITLAB_OAUTH_APP_ID, GITLAB_OAUTH_SCOPES, GITLAB_OAUTH_CALLBACK_PROXY, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_POOL_MAX_SIZE, GITLAB_READ_ONLY_MODE, GITLAB_TOOLSETS_RAW, GITLAB_TOOLS_RAW, HOST, HTTP_PROXY, HTTPS_PROXY, IS_OLD, MCP_SERVER_URL, NODE_TLS_REJECT_UNAUTHORIZED, NO_PROXY, OAUTH_STATELESS_CLIENT_TTL_SECONDS, OAUTH_STATELESS_MODE, OAUTH_STATELESS_PENDING_TTL_SECONDS, OAUTH_STATELESS_SESSION_TTL_SECONDS, OAUTH_STATELESS_STORED_TTL_SECONDS, PORT, REMOTE_AUTHORIZATION, SESSION_TIMEOUT_SECONDS, SSE, STREAMABLE_HTTP, USE_GITLAB_WIKI, USE_MILESTONE, USE_OAUTH, USE_PIPELINE, GITLAB_TOOL_POLICY_APPROVE_RAW, GITLAB_TOOL_POLICY_HIDDEN_RAW, } from "./config.js";
+/** True when the server is running in remote/network mode (SSE or StreamableHTTP transport). */
+const IS_REMOTE = SSE || STREAMABLE_HTTP;
+/**
+ * Encryption key for download tokens. When DOWNLOAD_TOKEN_SECRET is set
+ * (recommended for HA deployments behind a load balancer) the key is
+ * derived from that value so all replicas share the same key. Otherwise
+ * a random key is generated per process (tokens are not portable across
+ * restarts or replicas).
+ */
+const DOWNLOAD_TOKEN_KEY = (() => {
+    const secret = process.env.DOWNLOAD_TOKEN_SECRET;
+    if (secret) {
+        return createHash("sha256").update(secret).digest();
+    }
+    return randomBytes(32);
+})();
+/** Download token TTL in seconds (default 5 minutes). */
+const DOWNLOAD_TOKEN_TTL = Number.parseInt(process.env.DOWNLOAD_TOKEN_TTL || "300", 10);
+function createDownloadToken(header, token, apiUrl, resource) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", DOWNLOAD_TOKEN_KEY, iv);
+    const payload = JSON.stringify({
+        h: header,
+        t: token,
+        e: Math.floor(Date.now() / 1000) + DOWNLOAD_TOKEN_TTL,
+        ...(apiUrl ? { u: apiUrl } : {}),
+        ...(resource ? { r: resource.type, p: resource.params } : {}),
+    });
+    const encrypted = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, encrypted]).toString("base64url");
+}
+function decryptDownloadToken(tokenStr) {
+    try {
+        const buf = Buffer.from(tokenStr, "base64url");
+        if (buf.length < 29)
+            return null;
+        const iv = buf.subarray(0, 12);
+        const tag = buf.subarray(12, 28);
+        const encrypted = buf.subarray(28);
+        const decipher = createDecipheriv("aes-256-gcm", DOWNLOAD_TOKEN_KEY, iv);
+        decipher.setAuthTag(tag);
+        const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+        const payload = JSON.parse(decrypted.toString("utf8"));
+        // Check TTL
+        if (payload.e && Math.floor(Date.now() / 1000) > payload.e) {
+            return null; // expired
+        }
+        return {
+            header: payload.h,
+            token: payload.t,
+            ...(payload.u ? { apiUrl: payload.u } : {}),
+            ...(payload.r ? { resourceType: payload.r, resourceParams: payload.p } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a URL pointing to the download proxy endpoint.
+ * Embeds an encrypted auth token (and API URL for dynamic routing)
+ * from the current session so the URL works standalone.
+ */
+function buildDownloadUrl(type, params) {
+    const base = MCP_SERVER_URL || `http://${HOST}:${PORT}`;
+    const baseUrl = new URL(base);
+    // Preserve any path prefix (e.g. /gitlab-mcp) from the base URL
+    const basePath = baseUrl.pathname.replace(/\/+$/, "");
+    const url = new URL(`${basePath}/downloads/${type}`, baseUrl.origin);
+    for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+    }
+    // Embed auth (and apiUrl when dynamic routing is active) from current session or static config
+    // Token is bound to the specific resource (type + params) to prevent URL tampering
+    const resource = { type, params };
+    const ctx = sessionAuthStore.getStore();
+    if (ctx?.token) {
+        const headerValue = ctx.header === "Authorization" ? `Bearer ${ctx.token}` : ctx.token;
+        const apiUrl = ENABLE_DYNAMIC_API_URL && ctx.apiUrl !== GITLAB_API_URL ? ctx.apiUrl : undefined;
+        url.searchParams.set("_token", createDownloadToken(ctx.header, headerValue, apiUrl, resource));
+    }
+    else {
+        // Fallback for SSE/static-token mode (no session auth context)
+        // Priority matches buildAuthHeaders: OAuth > PAT > JOB token
+        const staticToken = OAUTH_ACCESS_TOKEN || GITLAB_PERSONAL_ACCESS_TOKEN || GITLAB_JOB_TOKEN;
+        if (staticToken) {
+            let header;
+            let headerValue;
+            if (GITLAB_JOB_TOKEN && !GITLAB_PERSONAL_ACCESS_TOKEN && !OAUTH_ACCESS_TOKEN) {
+                header = "JOB-TOKEN";
+                headerValue = String(staticToken);
+            }
+            else if (IS_OLD) {
+                header = "Private-Token";
+                headerValue = String(staticToken);
+            }
+            else {
+                header = "Authorization";
+                headerValue = `Bearer ${staticToken}`;
+            }
+            url.searchParams.set("_token", createDownloadToken(header, headerValue, undefined, resource));
+        }
+    }
+    return url.toString();
+}
 import { loadKeyMaterialFromEnv, looksLikeStatelessSessionId, mintSessionId, openSessionId, } from "./stateless/index.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
@@ -10,6 +116,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import express from "express";
 import fetchCookie from "fetch-cookie";
 import fs from "node:fs";
+import { pipeline as streamPipeline } from "node:stream/promises";
 import os from "node:os";
 import nodeFetch from "node-fetch";
 import path, { dirname } from "node:path";
@@ -32,8 +139,8 @@ GitLabDiscussionNoteSchema, // Added
 GitLabDiscussionSchema, 
 // Draft Notes Schemas
 GitLabDraftNoteSchema, GitLabForkSchema, GitLabBranchSchema, GitLabGroupSchema, GitLabIssueLinkSchema, GitLabIssueSchema, GitLabIssueWithLinkDetailsSchema, GitLabMarkdownUploadSchema, GitLabMergeRequestPipelineSchema, GitLabMergeRequestSchema, GitLabMilestonesSchema, GitLabNamespaceExistsResponseSchema, GitLabNamespaceSchema, GitLabPipelineJobSchema, GitLabDeploymentSchema, GitLabEnvironmentSchema, GitLabPipelineSchema, GitLabPipelineTriggerJobSchema, GitLabProjectMemberSchema, GitLabProjectSchema, GitLabTodoSchema, GitLabReferenceSchema, GitLabRepositorySchema, GitLabSearchBlobResultSchema, GitLabSearchResponseSchema, GitLabTreeItemSchema, GitLabUserSchema, GitLabUsersResponseSchema, GitLabWikiPageSchema, GroupIteration, ListCommitStatusesSchema, ListBranchesSchema, ListCommitsSchema, ListDraftNotesSchema, ListGroupIterationsSchema, ListGroupProjectsSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListTodosSchema, ListLabelsSchema, ListMergeRequestDiffsSchema, // Added
-GetMergeRequestFileDiffSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListWikiPagesSchema, GetGroupWikiPageSchema, ListGroupWikiPagesSchema, UpdateGroupWikiPageSchema, MarkdownUploadSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GitLabMergeRequestApprovalsResponseSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, MarkAllTodosDoneSchema, MarkTodoDoneSchema, PaginatedDiscussionsResponseSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, UpdateWikiPageSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, ListTagsSchema, GetTagSchema, CreateTagSchema, DeleteTagSchema, GetTagSignatureSchema, GitLabTagSchema, GitLabTagSignatureSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, GetWorkItemSchema, ListWorkItemsSchema, CreateWorkItemSchema, UpdateWorkItemSchema, ConvertWorkItemTypeSchema, ListWorkItemStatusesSchema, ListWorkItemNotesSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, MoveWorkItemSchema, ListCustomFieldDefinitionsSchema, GetTimelineEventsSchema, CreateTimelineEventSchema, ListWebhooksSchema, ListWebhookEventsSchema, GetWebhookEventSchema, HealthCheckSchema, } from "./schemas.js";
-import { randomUUID } from "node:crypto";
+GetMergeRequestFileDiffSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListWikiPagesSchema, GetGroupWikiPageSchema, ListGroupWikiPagesSchema, UpdateGroupWikiPageSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GitLabMergeRequestApprovalsResponseSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, MarkAllTodosDoneSchema, MarkTodoDoneSchema, PaginatedDiscussionsResponseSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, UpdateWikiPageSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, ListTagsSchema, GetTagSchema, CreateTagSchema, DeleteTagSchema, GetTagSignatureSchema, GitLabTagSchema, GitLabTagSignatureSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, GetWorkItemSchema, ListWorkItemsSchema, CreateWorkItemSchema, UpdateWorkItemSchema, ConvertWorkItemTypeSchema, ListWorkItemStatusesSchema, ListWorkItemNotesSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, MoveWorkItemSchema, ListCustomFieldDefinitionsSchema, GetTimelineEventsSchema, CreateTimelineEventSchema, ListWebhooksSchema, ListWebhookEventsSchema, GetWebhookEventSchema, HealthCheckSchema, } from "./schemas.js";
+import { randomUUID, createCipheriv, createDecipheriv, randomBytes, createHash } from "node:crypto";
 import { pino } from "pino";
 const logger = pino({
     level: process.env.LOG_LEVEL || "info",
@@ -4916,11 +5023,13 @@ async function downloadJobArtifacts(projectId, jobId, localPath) {
         throw new Error(`Job artifacts not found. The job may not have produced artifacts or the job ID is invalid.`);
     }
     await handleGitLabError(response);
-    const buffer = await response.arrayBuffer();
     const filename = `artifacts_job_${jobId}.zip`;
     const savePath = localPath ? path.join(localPath, filename) : filename;
     fs.mkdirSync(path.dirname(savePath), { recursive: true });
-    fs.writeFileSync(savePath, Buffer.from(buffer));
+    if (!response.body) {
+        throw new Error("No response body from GitLab");
+    }
+    await streamPipeline(response.body, fs.createWriteStream(savePath));
     return savePath;
 }
 /**
@@ -5626,22 +5735,42 @@ async function listGroupIterations(groupId, options = {}) {
     return z.array(GroupIteration).parse(data);
 }
 /**
- * Upload a file to a GitLab project for use in markdown content
+ * Upload a file to a GitLab project for use in markdown content.
+ *
+ * Accepts either a local file path or inline base64-encoded content
+ * (the latter is useful for remote deployments where the client cannot
+ * write to the server's filesystem).
  *
  * @param {string} projectId - The ID or URL-encoded path of the project
- * @param {string} filePath - Path to the local file to upload
+ * @param {string} filePath - Path to the local file to upload (optional if content provided)
+ * @param {string} content - Base64-encoded file content (optional if filePath provided)
+ * @param {string} filename - Filename for the uploaded content (required when content provided)
  * @returns {Promise<GitLabMarkdownUpload>} The upload response
  */
-async function markdownUpload(projectId, filePath) {
+async function markdownUpload(projectId, filePath, content, filename) {
     projectId = decodeURIComponent(projectId);
     const effectiveProjectId = getEffectiveProjectId(projectId);
-    // Check if file exists
-    if (!fs.existsSync(filePath)) {
-        throw new Error(`File not found: ${filePath}`);
+    let fileBuffer;
+    let fileName;
+    if (IS_REMOTE && filePath) {
+        throw new Error("file_path cannot be used in remote mode. Provide base64-encoded content and filename instead.");
+    }
+    if (content) {
+        // Inline content mode (remote deployments)
+        fileBuffer = Buffer.from(content, "base64");
+        fileName = filename || "upload";
+    }
+    else if (filePath) {
+        // Local file mode
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        fileBuffer = fs.readFileSync(filePath);
+        fileName = path.basename(filePath);
+    }
+    else {
+        throw new Error("Either file_path or content must be provided");
     }
-    // Read the file
-    const fileBuffer = fs.readFileSync(filePath);
-    const fileName = path.basename(filePath);
     // Create form data
     const FormData = (await import("form-data")).default;
     const form = new FormData();
@@ -5687,8 +5816,6 @@ async function downloadAttachment(projectId, secret, filename, localPath) {
     if (!response.ok) {
         await handleGitLabError(response);
     }
-    // Get the file content as buffer
-    const buffer = Buffer.from(await response.arrayBuffer());
     const mimeType = getImageMimeType(filename);
     // For non-image files, always save to disk.
     // For image files, only save to disk if local_path is explicitly provided.
@@ -5711,9 +5838,15 @@ async function downloadAttachment(projectId, secret, filename, localPath) {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
-        fs.writeFileSync(savePath, buffer);
-        return { buffer, filename, mimeType, savedPath: savePath };
+        // Stream directly to disk instead of buffering in memory
+        if (!response.body) {
+            throw new Error("No response body from GitLab");
+        }
+        await streamPipeline(response.body, fs.createWriteStream(savePath));
+        return { buffer: Buffer.alloc(0), filename, mimeType, savedPath: savePath };
     }
+    // Images returned inline — buffer into memory for base64 encoding
+    const buffer = Buffer.from(await response.arrayBuffer());
     return { buffer, filename, mimeType };
 }
 /**
@@ -7355,6 +7488,15 @@ async function handleToolCall(params) {
             }
             case "download_job_artifacts": {
                 const { project_id, job_id, local_path } = DownloadJobArtifactsSchema.parse(params.arguments);
+                if (IS_REMOTE) {
+                    if (local_path) {
+                        throw new Error("local_path cannot be used in remote mode — use the returned download_url instead");
+                    }
+                    const downloadUrl = buildDownloadUrl("job-artifacts", { project_id, job_id });
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ download_url: downloadUrl, filename: `artifacts_job_${job_id}.zip` }, null, 2) }],
+                    };
+                }
                 const filePath = await downloadJobArtifacts(project_id, job_id, local_path);
                 return {
                     content: [
@@ -7560,6 +7702,13 @@ async function handleToolCall(params) {
                 };
             }
             case "upload_markdown": {
+                if (IS_REMOTE) {
+                    const args = MarkdownUploadRemoteSchema.parse(params.arguments);
+                    const upload = await markdownUpload(args.project_id, undefined, args.content, args.filename);
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(upload, null, 2) }],
+                    };
+                }
                 const args = MarkdownUploadSchema.parse(params.arguments);
                 const upload = await markdownUpload(args.project_id, args.file_path);
                 return {
@@ -7568,6 +7717,19 @@ async function handleToolCall(params) {
             }
             case "download_attachment": {
                 const args = DownloadAttachmentSchema.parse(params.arguments);
+                if (IS_REMOTE && args.local_path) {
+                    throw new Error("local_path cannot be used in remote mode — use the returned download_url instead");
+                }
+                // In remote mode for non-image files, return proxy URL
+                const mimeType = getImageMimeType(args.filename);
+                if (IS_REMOTE && !mimeType) {
+                    const downloadUrl = buildDownloadUrl("attachment", {
+                        project_id: args.project_id, secret: args.secret, filename: args.filename,
+                    });
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ download_url: downloadUrl, filename: args.filename }, null, 2) }],
+                    };
+                }
                 const result = await downloadAttachment(args.project_id, args.secret, args.filename, args.local_path);
                 if (result.mimeType && !args.local_path) {
                     // Return image inline as base64 so the AI can see it
@@ -7663,6 +7825,14 @@ async function handleToolCall(params) {
             }
             case "download_release_asset": {
                 const args = DownloadReleaseAssetSchema.parse(params.arguments);
+                if (IS_REMOTE) {
+                    const downloadUrl = buildDownloadUrl("release-asset", {
+                        project_id: args.project_id, tag_name: args.tag_name, direct_asset_path: args.direct_asset_path,
+                    });
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ download_url: downloadUrl, filename: args.direct_asset_path.split("/").pop() || args.direct_asset_path }, null, 2) }],
+                    };
+                }
                 const assetContent = await downloadReleaseAsset(args.project_id, args.tag_name, args.direct_asset_path);
                 return {
                     content: [{ type: "text", text: assetContent }],
@@ -7859,6 +8029,182 @@ async function startStdioServer() {
     };
     await serverInstance.connect(transport);
 }
+/**
+ * Register the /downloads/:type proxy endpoint on an Express app.
+ * Streams GitLab API responses directly to the client. Auth is read from
+ * an encrypted `_token` query param (self-contained URL) or from request headers.
+ */
+function registerDownloadProxy(app, maxRequestsPerMinute = Number.parseInt(process.env.MAX_REQUESTS_PER_MINUTE || "60", 10)) {
+    const downloadRateLimits = {};
+    let lastEviction = Date.now();
+    const checkDownloadRateLimit = (token) => {
+        const now = Date.now();
+        // Evict expired entries every 60s to prevent unbounded growth
+        if (now - lastEviction > 60000) {
+            for (const key of Object.keys(downloadRateLimits)) {
+                if (now > downloadRateLimits[key].resetAt)
+                    delete downloadRateLimits[key];
+            }
+            lastEviction = now;
+        }
+        const entry = downloadRateLimits[token];
+        if (!entry || now > entry.resetAt) {
+            downloadRateLimits[token] = { count: 1, resetAt: now + 60000 };
+            return true;
+        }
+        if (entry.count >= maxRequestsPerMinute)
+            return false;
+        entry.count++;
+        return true;
+    };
+    app.get("/downloads/:type", async (req, res) => {
+        const headers = { Accept: "application/octet-stream" };
+        let rateLimitKey;
+        // Try embedded encrypted token first (self-contained URL), then headers
+        const encryptedToken = req.query._token;
+        let tokenApiUrl;
+        if (encryptedToken) {
+            const decrypted = decryptDownloadToken(encryptedToken);
+            if (!decrypted) {
+                res.status(401).json({ error: "Invalid or expired download token" });
+                return;
+            }
+            // Verify resource binding — token must match the requested type and params
+            if (decrypted.resourceType || decrypted.resourceParams) {
+                const { type } = req.params;
+                const queryParams = {};
+                for (const [k, v] of Object.entries(req.query)) {
+                    if (k !== "_token" && typeof v === "string")
+                        queryParams[k] = v;
+                }
+                if (decrypted.resourceType !== type ||
+                    JSON.stringify(decrypted.resourceParams) !== JSON.stringify(queryParams)) {
+                    res.status(403).json({ error: "Download token does not match the requested resource" });
+                    return;
+                }
+            }
+            headers[decrypted.header] = decrypted.token;
+            rateLimitKey = decrypted.token;
+            tokenApiUrl = decrypted.apiUrl;
+        }
+        else {
+            const privateToken = req.headers["private-token"];
+            const jobToken = req.headers["job-token"];
+            const authHeader = req.headers["authorization"];
+            if (privateToken) {
+                headers["Private-Token"] = privateToken;
+                rateLimitKey = privateToken;
+            }
+            else if (jobToken) {
+                headers["JOB-TOKEN"] = jobToken;
+                rateLimitKey = jobToken;
+            }
+            else if (authHeader) {
+                headers["Authorization"] = authHeader;
+                rateLimitKey = authHeader;
+            }
+            else {
+                res.status(401).json({ error: "Authentication required" });
+                return;
+            }
+        }
+        if (!checkDownloadRateLimit(rateLimitKey)) {
+            res.status(429).json({ error: "Rate limit exceeded" });
+            return;
+        }
+        // API URL: prefer token-embedded URL, then X-GitLab-API-URL header, then default
+        let apiUrl = tokenApiUrl || GITLAB_API_URL;
+        if (!tokenApiUrl) {
+            const dynamicApiUrl = req.headers["x-gitlab-api-url"]?.trim();
+            if (ENABLE_DYNAMIC_API_URL && dynamicApiUrl) {
+                try {
+                    new URL(dynamicApiUrl);
+                    apiUrl = normalizeGitLabApiUrl(dynamicApiUrl);
+                }
+                catch {
+                    res.status(400).json({ error: "Invalid X-GitLab-API-URL" });
+                    return;
+                }
+            }
+        }
+        const { type } = req.params;
+        let gitlabUrl;
+        try {
+            switch (type) {
+                case "job-artifacts": {
+                    const { project_id, job_id } = req.query;
+                    if (!project_id || !job_id) {
+                        res.status(400).json({ error: "project_id and job_id are required" });
+                        return;
+                    }
+                    const effectiveProjectId = getEffectiveProjectId(decodeURIComponent(project_id));
+                    gitlabUrl = `${apiUrl}/projects/${encodeURIComponent(effectiveProjectId)}/jobs/${job_id}/artifacts`;
+                    break;
+                }
+                case "attachment": {
+                    const { project_id, secret, filename } = req.query;
+                    if (!project_id || !secret || !filename) {
+                        res.status(400).json({ error: "project_id, secret, and filename are required" });
+                        return;
+                    }
+                    const effectiveProjectId = getEffectiveProjectId(decodeURIComponent(project_id));
+                    gitlabUrl = `${apiUrl}/projects/${encodeURIComponent(effectiveProjectId)}/uploads/${secret}/${filename}`;
+                    break;
+                }
+                case "release-asset": {
+                    const { project_id, tag_name, direct_asset_path } = req.query;
+                    if (!project_id || !tag_name || !direct_asset_path) {
+                        res.status(400).json({ error: "project_id, tag_name, and direct_asset_path are required" });
+                        return;
+                    }
+                    const effectiveProjectId = getEffectiveProjectId(decodeURIComponent(project_id));
+                    gitlabUrl = `${apiUrl}/projects/${encodeURIComponent(effectiveProjectId)}/releases/${encodeURIComponent(tag_name)}/downloads/${direct_asset_path}`;
+                    break;
+                }
+                default:
+                    res.status(400).json({ error: `Unknown download type: ${type}` });
+                    return;
+            }
+        }
+        catch (e) {
+            // getEffectiveProjectId throws on access-denied
+            const message = e instanceof Error ? e.message : "Invalid parameters";
+            res.status(403).json({ error: message });
+            return;
+        }
+        try {
+            const agent = clientPool.getAgentFunctionForUrl(apiUrl);
+            const gitlabResponse = await nodeFetch(gitlabUrl, { headers, agent });
+            if (!gitlabResponse.ok) {
+                res.status(gitlabResponse.status).json({
+                    error: `GitLab API error: ${gitlabResponse.status} ${gitlabResponse.statusText}`,
+                });
+                return;
+            }
+            const contentType = gitlabResponse.headers.get("content-type");
+            const contentDisposition = gitlabResponse.headers.get("content-disposition");
+            const contentLength = gitlabResponse.headers.get("content-length");
+            if (contentType)
+                res.setHeader("Content-Type", contentType);
+            if (contentDisposition)
+                res.setHeader("Content-Disposition", contentDisposition);
+            if (contentLength)
+                res.setHeader("Content-Length", contentLength);
+            if (gitlabResponse.body) {
+                gitlabResponse.body.pipe(res);
+            }
+            else {
+                res.status(502).json({ error: "No response body from GitLab" });
+            }
+        }
+        catch (error) {
+            logger.error("Download proxy error:", error);
+            if (!res.headersSent) {
+                res.status(502).json({ error: "Failed to proxy download from GitLab" });
+            }
+        }
+    });
+}
 /**
  * Start server with traditional SSE transport
  */
@@ -7885,6 +8231,7 @@ async function startSSEServer() {
             res.status(400).send("No transport found for sessionId");
         }
     });
+    registerDownloadProxy(app);
     app.get("/health", (_, res) => {
         res.status(200).json({
             status: "healthy",
@@ -8254,6 +8601,7 @@ async function startStreamableHTTPServer() {
     };
     // Configure Express middleware
     app.use(express.json());
+    registerDownloadProxy(app);
     // MCP OAuth — mount auth router and prepare bearer-auth middleware
     if (GITLAB_MCP_OAUTH) {
         // Trust first proxy so express-rate-limit uses X-Forwarded-For for real client IP.

package/build/schemas.js

@@ -2590,6 +2590,11 @@ export const MarkdownUploadSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path of the project"),
     file_path: z.string().describe("Path to the file to upload"),
 });
+export const MarkdownUploadRemoteSchema = z.object({
+    project_id: z.string().describe("Project ID or URL-encoded path of the project"),
+    content: z.string().describe("File content as base64-encoded string"),
+    filename: z.string().describe("Filename for the uploaded content"),
+});
 export const DownloadAttachmentSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path of the project"),
     secret: z.string().describe("The 32-character secret of the upload"),
@@ -2599,6 +2604,11 @@ export const DownloadAttachmentSchema = z.object({
         .optional()
         .describe("Local path to save the file (optional, defaults to current directory)"),
 });
+export const DownloadAttachmentRemoteSchema = z.object({
+    project_id: z.string().describe("Project ID or URL-encoded path of the project"),
+    secret: z.string().describe("The 32-character secret of the upload"),
+    filename: z.string().describe("The filename of the upload"),
+});
 export const GroupIteration = z.object({
     id: z.coerce.string(),
     iid: z.coerce.string(),
@@ -2943,6 +2953,10 @@ export const DownloadJobArtifactsSchema = z.object({
         .optional()
         .describe("Local directory to save the artifact archive (defaults to current directory)"),
 });
+export const DownloadJobArtifactsRemoteSchema = z.object({
+    project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
+    job_id: z.coerce.string().describe("The ID of the job"),
+});
 export const GetJobArtifactFileSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
     job_id: z.coerce.string().describe("The ID of the job"),

package/build/test/test-remote-downloads.js

@@ -0,0 +1,336 @@
+/**
+ * Remote Mode Download Proxy & Upload Tests
+ *
+ * Tests the /downloads/:type proxy endpoint and verifies that download/upload
+ * tools behave correctly in remote (StreamableHTTP) mode:
+ *   - download_job_artifacts returns a download_url
+ *   - download_attachment for non-image returns a download_url
+ *   - download_attachment for image returns inline base64
+ *   - upload_markdown with content+filename works
+ *   - upload_markdown with file_path is rejected
+ */
+import { describe, test, before, after } from 'node:test';
+import assert from 'node:assert';
+import { launchServer, TransportMode, HOST } from './utils/server-launcher.js';
+import { MockGitLabServer, findMockServerPort } from './utils/mock-gitlab-server.js';
+const MOCK_TOKEN = 'glpat-mock-token-12345';
+const TEST_PROJECT_ID = '123';
+const TEST_JOB_ID = '456';
+const TEST_SECRET = 'testsecret';
+// Minimal 1x1 transparent PNG
+const MINIMAL_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64');
+const LARGE_FILE_TOKEN = 'glpat-largefile-test-token';
+const FAKE_ZIP = Buffer.from('PK\x03\x04fake-zip-content-for-testing');
+const MOCK_UPLOAD_RESPONSE = {
+    id: 99,
+    alt: 'test-file.txt',
+    url: '/uploads/abc123secret/test-file.txt',
+    full_path: '/test-group/test-project/uploads/abc123secret/test-file.txt',
+    markdown: '[test-file.txt](/uploads/abc123secret/test-file.txt)',
+};
+function parseSSE(text) {
+    const lines = text.split('\n');
+    const dataLines = lines.filter(l => l.startsWith('data: '));
+    return dataLines.map(l => JSON.parse(l.slice(6)));
+}
+// --- Test suites ---
+describe('Remote Downloads - Download Proxy Endpoint', { timeout: 30_000 }, () => {
+    let mockGitLab;
+    let server;
+    let serverPort;
+    before(async () => {
+        const mockPort = await findMockServerPort(9300);
+        mockGitLab = new MockGitLabServer({
+            port: mockPort,
+            validTokens: [MOCK_TOKEN, LARGE_FILE_TOKEN],
+        });
+        // Mock artifact download
+        mockGitLab.addMockHandler('get', `/projects/${TEST_PROJECT_ID}/jobs/${TEST_JOB_ID}/artifacts`, (_req, res) => {
+            res.set('Content-Type', 'application/zip');
+            res.set('Content-Disposition', `attachment; filename="artifacts_job_${TEST_JOB_ID}.zip"`);
+            res.send(FAKE_ZIP);
+        });
+        // Mock image attachment
+        mockGitLab.addMockHandler('get', `/projects/${TEST_PROJECT_ID}/uploads/${TEST_SECRET}/image.png`, (_req, res) => {
+            res.set('Content-Type', 'image/png');
+            res.send(MINIMAL_PNG);
+        });
+        // Mock text attachment
+        mockGitLab.addMockHandler('get', `/projects/${TEST_PROJECT_ID}/uploads/${TEST_SECRET}/document.txt`, (_req, res) => {
+            res.set('Content-Type', 'text/plain');
+            res.send('hello document content');
+        });
+        // Mock large artifact (2MB) to verify streaming works for big files
+        mockGitLab.addMockHandler('get', `/projects/${TEST_PROJECT_ID}/jobs/999/artifacts`, (_req, res) => {
+            res.set('Content-Type', 'application/zip');
+            res.set('Content-Disposition', 'attachment; filename="large_artifacts.zip"');
+            // Send 2MB of data in chunks
+            const chunk = Buffer.alloc(64 * 1024, 0x42); // 64KB of 'B'
+            res.writeHead(200);
+            let sent = 0;
+            const total = 2 * 1024 * 1024; // 2MB
+            const sendChunk = () => {
+                while (sent < total) {
+                    const size = Math.min(chunk.length, total - sent);
+                    const ok = res.write(chunk.subarray(0, size));
+                    sent += size;
+                    if (!ok) {
+                        res.once('drain', sendChunk);
+                        return;
+                    }
+                }
+                res.end();
+            };
+            sendChunk();
+        });
+        await mockGitLab.start();
+        serverPort = 3500;
+        server = await launchServer({
+            mode: TransportMode.STREAMABLE_HTTP,
+            port: serverPort,
+            timeout: 10_000,
+            env: {
+                STREAMABLE_HTTP: 'true',
+                REMOTE_AUTHORIZATION: 'true',
+                GITLAB_API_URL: `${mockGitLab.getUrl()}/api/v4`,
+                USE_PIPELINE: 'true',
+                MAX_REQUESTS_PER_MINUTE: '2',
+            },
+        });
+    });
+    after(async () => {
+        if (server)
+            server.kill();
+        if (mockGitLab)
+            await mockGitLab.stop();
+    });
+    test('returns 401 without auth headers', async () => {
+        const res = await fetch(`http://${HOST}:${serverPort}/downloads/job-artifacts?project_id=${TEST_PROJECT_ID}&job_id=${TEST_JOB_ID}`);
+        assert.strictEqual(res.status, 401);
+        const body = await res.json();
+        assert.ok(body.error.toLowerCase().includes('auth'));
+    });
+    test('returns 400 for missing parameters', async () => {
+        const res = await fetch(`http://${HOST}:${serverPort}/downloads/job-artifacts?project_id=${TEST_PROJECT_ID}`, { headers: { 'Private-Token': MOCK_TOKEN } });
+        assert.strictEqual(res.status, 400);
+        const body = await res.json();
+        assert.ok(body.error.includes('required'));
+    });
+    test('returns 400 for unknown download types', async () => {
+        const res = await fetch(`http://${HOST}:${serverPort}/downloads/unknown-type?project_id=${TEST_PROJECT_ID}`, { headers: { 'Private-Token': MOCK_TOKEN } });
+        assert.strictEqual(res.status, 400);
+        const body = await res.json();
+        assert.ok(body.error.toLowerCase().includes('unknown'));
+    });
+    test('streams large file (2MB) without buffering issues', async () => {
+        // Use a dedicated token to avoid rate limit interference from other tests
+        const largeFileToken = 'glpat-largefile-test-token';
+        const res = await fetch(`http://${HOST}:${serverPort}/downloads/job-artifacts?project_id=${TEST_PROJECT_ID}&job_id=999`, { headers: { 'Private-Token': largeFileToken } });
+        assert.strictEqual(res.status, 200, 'Should stream large file successfully');
+        const buf = Buffer.from(await res.arrayBuffer());
+        const expectedSize = 2 * 1024 * 1024;
+        assert.strictEqual(buf.length, expectedSize, `Should receive full 2MB (got ${buf.length} bytes)`);
+    });
+    test('returns 429 after exceeding rate limit', async () => {
+        // Use a different token to get a fresh rate limit counter
+        const rateLimitToken = 'glpat-ratelimit-test-token';
+        let got429 = false;
+        for (let i = 0; i < 10; i++) {
+            const res = await fetch(`http://${HOST}:${serverPort}/downloads/job-artifacts?project_id=${TEST_PROJECT_ID}&job_id=${TEST_JOB_ID}`, { headers: { 'Private-Token': rateLimitToken } });
+            if (res.status === 429) {
+                got429 = true;
+                const body = await res.json();
+                assert.ok(body.error.toLowerCase().includes('rate limit'));
+                break;
+            }
+            // consume body (might be 401/403 from GitLab mock, but rate limit still increments)
+            await res.arrayBuffer();
+        }
+        assert.ok(got429, 'Should have received 429 within 10 requests (rate limit is 2/min)');
+    });
+});
+describe('Remote Downloads - Tool Behavior via MCP Protocol', { timeout: 60_000 }, () => {
+    let mockGitLab;
+    let server;
+    let serverPort;
+    let sessionId;
+    before(async () => {
+        const mockPort = await findMockServerPort(9310);
+        mockGitLab = new MockGitLabServer({
+            port: mockPort,
+            validTokens: [MOCK_TOKEN],
+        });
+        // Mock artifact download
+        mockGitLab.addMockHandler('get', `/projects/${TEST_PROJECT_ID}/jobs/${TEST_JOB_ID}/artifacts`, (_req, res) => {
+            res.set('Content-Type', 'application/zip');
+            res.set('Content-Disposition', `attachment; filename="artifacts_job_${TEST_JOB_ID}.zip"`);
+            res.send(FAKE_ZIP);
+        });
+        // Mock image attachment
+        mockGitLab.addMockHandler('get', `/projects/${TEST_PROJECT_ID}/uploads/${TEST_SECRET}/image.png`, (_req, res) => {
+            res.set('Content-Type', 'image/png');
+            res.send(MINIMAL_PNG);
+        });
+        // Mock text attachment
+        mockGitLab.addMockHandler('get', `/projects/${TEST_PROJECT_ID}/uploads/${TEST_SECRET}/document.txt`, (_req, res) => {
+            res.set('Content-Type', 'text/plain');
+            res.send('hello document content');
+        });
+        // Mock upload endpoint
+        mockGitLab.addMockHandler('post', `/projects/${TEST_PROJECT_ID}/uploads`, (req, res) => {
+            res.status(201).json(MOCK_UPLOAD_RESPONSE);
+        });
+        await mockGitLab.start();
+        serverPort = 3510;
+        server = await launchServer({
+            mode: TransportMode.STREAMABLE_HTTP,
+            port: serverPort,
+            timeout: 10_000,
+            env: {
+                STREAMABLE_HTTP: 'true',
+                REMOTE_AUTHORIZATION: 'true',
+                GITLAB_API_URL: `${mockGitLab.getUrl()}/api/v4`,
+                USE_PIPELINE: 'true',
+            },
+        });
+        // Initialize MCP session
+        const initRes = await fetch(`http://${HOST}:${serverPort}/mcp`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json, text/event-stream',
+                'Private-Token': MOCK_TOKEN,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-03-26',
+                    capabilities: {},
+                    clientInfo: { name: 'test-remote-downloads', version: '1.0' },
+                },
+            }),
+        });
+        assert.strictEqual(initRes.status, 200, 'Initialize should succeed');
+        sessionId = initRes.headers.get('mcp-session-id');
+        assert.ok(sessionId, 'Should receive a session ID');
+    });
+    after(async () => {
+        if (server)
+            server.kill();
+        if (mockGitLab)
+            await mockGitLab.stop();
+    });
+    async function callTool(id, name, args) {
+        const res = await fetch(`http://${HOST}:${serverPort}/mcp`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json, text/event-stream',
+                'Private-Token': MOCK_TOKEN,
+                'mcp-session-id': sessionId,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id,
+                method: 'tools/call',
+                params: { name, arguments: args },
+            }),
+        });
+        assert.strictEqual(res.status, 200, `Tool call ${name} should return 200`);
+        const text = await res.text();
+        const responses = parseSSE(text);
+        const result = responses.find(r => r.id === id);
+        assert.ok(result, `Should find response with id=${id} in SSE stream`);
+        return result;
+    }
+    test('download_job_artifacts returns download_url with embedded auth token', async () => {
+        const result = await callTool(10, 'download_job_artifacts', {
+            project_id: TEST_PROJECT_ID,
+            job_id: TEST_JOB_ID,
+        });
+        assert.ok(result.result, 'Should have a result');
+        const content = result.result.content;
+        assert.ok(content && content.length > 0, 'Should have content');
+        const textBlock = content.find(c => c.type === 'text');
+        assert.ok(textBlock?.text, 'Should have text content');
+        const parsed = JSON.parse(textBlock.text);
+        assert.ok(parsed.download_url, 'Should contain download_url');
+        assert.ok(parsed.download_url.includes('/downloads/job-artifacts'), 'URL should point to proxy endpoint');
+        assert.ok(parsed.download_url.includes(`project_id=${TEST_PROJECT_ID}`), 'URL should include project_id');
+        assert.ok(parsed.download_url.includes(`job_id=${TEST_JOB_ID}`), 'URL should include job_id');
+        assert.ok(parsed.download_url.includes('_token='), 'URL should contain embedded auth token');
+        assert.ok(parsed.filename.includes('.zip'), 'Should have zip filename');
+        // The URL should work WITHOUT auth headers (token is embedded)
+        const downloadRes = await fetch(parsed.download_url);
+        assert.strictEqual(downloadRes.status, 200, 'Download URL should work without auth headers');
+        const buf = Buffer.from(await downloadRes.arrayBuffer());
+        assert.ok(buf.length > 0, 'Downloaded content should not be empty');
+        assert.ok(buf.includes(Buffer.from('PK')), 'Should contain zip magic bytes');
+    });
+    test('download_attachment for non-image returns download_url', async () => {
+        const result = await callTool(11, 'download_attachment', {
+            project_id: TEST_PROJECT_ID,
+            secret: TEST_SECRET,
+            filename: 'document.txt',
+        });
+        assert.ok(result.result, 'Should have a result');
+        const content = result.result.content;
+        assert.ok(content && content.length > 0, 'Should have content');
+        const textBlock = content.find(c => c.type === 'text');
+        assert.ok(textBlock?.text, 'Should have text content');
+        const parsed = JSON.parse(textBlock.text);
+        assert.ok(parsed.download_url, 'Should contain download_url');
+        assert.ok(parsed.download_url.includes('/downloads/attachment'), 'URL should point to attachment proxy');
+        assert.ok(parsed.download_url.includes(`project_id=${TEST_PROJECT_ID}`), 'URL should include project_id');
+        assert.ok(parsed.download_url.includes(`secret=${TEST_SECRET}`), 'URL should include secret');
+        assert.ok(parsed.download_url.includes('filename=document.txt'), 'URL should include filename');
+        assert.strictEqual(parsed.filename, 'document.txt', 'Should echo the filename');
+    });
+    test('download_attachment for image returns base64 inline', async () => {
+        const result = await callTool(12, 'download_attachment', {
+            project_id: TEST_PROJECT_ID,
+            secret: TEST_SECRET,
+            filename: 'image.png',
+        });
+        assert.ok(result.result, 'Should have a result');
+        const content = result.result.content;
+        assert.ok(content && content.length > 0, 'Should have content');
+        const imageBlock = content.find(c => c.type === 'image');
+        assert.ok(imageBlock, 'Should contain an image content block');
+        assert.strictEqual(imageBlock.mimeType, 'image/png', 'Should have image/png mime type');
+        assert.ok(imageBlock.data && imageBlock.data.length > 0, 'Should have non-empty base64 data');
+    });
+    test('upload_markdown with content+filename works', async () => {
+        const fileContent = Buffer.from('hello upload test').toString('base64');
+        const result = await callTool(13, 'upload_markdown', {
+            project_id: TEST_PROJECT_ID,
+            content: fileContent,
+            filename: 'test-file.txt',
+        });
+        assert.ok(result.result, 'Should have a result');
+        assert.ok(!result.error, `Should not have error: ${result.error?.message}`);
+        const content = result.result.content;
+        assert.ok(content && content.length > 0, 'Should have content');
+        const textBlock = content.find(c => c.type === 'text');
+        assert.ok(textBlock?.text, 'Should have text content');
+        const parsed = JSON.parse(textBlock.text);
+        assert.ok(parsed.markdown, 'Should have markdown field');
+        assert.ok(parsed.url, 'Should have url field');
+    });
+    test('upload_markdown with file_path is rejected in remote mode', async () => {
+        const result = await callTool(14, 'upload_markdown', {
+            project_id: TEST_PROJECT_ID,
+            file_path: '/tmp/some-file.txt',
+        });
+        // In remote mode the server uses MarkdownUploadRemoteSchema which
+        // requires content+filename and does not accept file_path. This should
+        // result in a validation error.
+        const hasError = !!result.error ||
+            (result.result?.content?.some(c => c.type === 'text' && c.text && (c.text.toLowerCase().includes('error') ||
+                c.text.toLowerCase().includes('required') ||
+                c.text.toLowerCase().includes('invalid'))));
+        assert.ok(hasError, 'Should reject file_path in remote mode (needs content+filename)');
+    });
+});

package/build/tools/registry.js

@@ -1,7 +1,8 @@
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { toJSONSchema } from "../utils/schema.js";
-import { USE_GITLAB_WIKI, USE_MILESTONE, USE_PIPELINE, } from "../config.js";
-import { ApproveMergeRequestSchema, BulkPublishDraftNotesSchema, CancelPipelineJobSchema, 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, CreateReleaseEvidenceSchema, CreateReleaseSchema, CreateRepositorySchema, CreateTagSchema, CreateTimelineEventSchema, CreateWikiPageSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, CreateWorkItemSchema, DeleteBranchSchema, DeleteDraftNoteSchema, DeleteGroupWikiPageSchema, DeleteIssueLinkSchema, DeleteIssueSchema, DeleteIssueEmojiReactionSchema, DeleteIssueNoteEmojiReactionSchema, DeleteLabelSchema, DeleteMergeRequestDiscussionNoteSchema, DeleteMergeRequestNoteSchema, DeleteMergeRequestEmojiReactionSchema, DeleteMergeRequestNoteEmojiReactionSchema, DeleteProjectMilestoneSchema, DeleteReleaseSchema, DeleteTagSchema, DeleteWikiPageSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, DownloadReleaseAssetSchema, EditProjectMilestoneSchema, ExecuteGraphQLSchema, ForkRepositorySchema, HealthCheckSchema, GetBranchSchema, GetBranchDiffsSchema, GetCommitDiffSchema, GetCommitSchema, GetFileBlameSchema, GetDeploymentSchema, GetDraftNoteSchema, GetEnvironmentSchema, GetFileContentsSchema, GetGroupWikiPageSchema, GetIssueLinkSchema, GetIssueSchema, GetJobArtifactFileSchema, GetLabelSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GetMergeRequestDiffsSchema, GetMergeRequestFileDiffSchema, GetMergeRequestNoteSchema, GetMergeRequestNotesSchema, GetMergeRequestSchema, GetMergeRequestVersionSchema, GetMilestoneBurndownEventsSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, GetNamespaceSchema, GetPipelineJobOutputSchema, GetPipelineSchema, GetProjectEventsSchema, GetProjectMilestoneSchema, GetProjectSchema, GetReleaseSchema, GetRepositoryTreeSchema, GetTagSchema, GetTagSignatureSchema, GetTimelineEventsSchema, GetUsersSchema, GetUserSchema, WhoAmISchema, GetWebhookEventSchema, GetWikiPageSchema, GetWorkItemSchema, ListBranchesSchema, ListCommitsSchema, ListCommitStatusesSchema, ListCustomFieldDefinitionsSchema, ListDeploymentsSchema, ListDraftNotesSchema, ListEnvironmentsSchema, ListEventsSchema, ListGroupIterationsSchema, ListGroupProjectsSchema, ListGroupWikiPagesSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListJobArtifactsSchema, ListLabelsSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiffsSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestVersionsSchema, ListMergeRequestsSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListPipelinesSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListReleasesSchema, ListTagsSchema, ListWebhookEventsSchema, ListWebhooksSchema, ListWikiPagesSchema, ListWorkItemNotesSchema, ListWorkItemStatusesSchema, ListWorkItemsSchema, MarkdownUploadSchema, MergeMergeRequestSchema, MoveWorkItemSchema, MyIssuesSchema, PlayPipelineJobSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PushFilesSchema, ResolveMergeRequestThreadSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UnapproveMergeRequestSchema, UpdateDraftNoteSchema, UpdateGroupWikiPageSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestSchema, UpdateReleaseSchema, UpdateWikiPageSchema, UpdateWorkItemSchema, VerifyNamespaceSchema, } from "../schemas.js";
+import { USE_GITLAB_WIKI, USE_MILESTONE, USE_PIPELINE, SSE, STREAMABLE_HTTP, } from "../config.js";
+import { ApproveMergeRequestSchema, BulkPublishDraftNotesSchema, CancelPipelineJobSchema, 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, CreateReleaseEvidenceSchema, CreateReleaseSchema, CreateRepositorySchema, CreateTagSchema, CreateTimelineEventSchema, CreateWikiPageSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, CreateWorkItemSchema, DeleteBranchSchema, DeleteDraftNoteSchema, DeleteGroupWikiPageSchema, DeleteIssueLinkSchema, DeleteIssueSchema, DeleteIssueEmojiReactionSchema, DeleteIssueNoteEmojiReactionSchema, DeleteLabelSchema, DeleteMergeRequestDiscussionNoteSchema, DeleteMergeRequestNoteSchema, DeleteMergeRequestEmojiReactionSchema, DeleteMergeRequestNoteEmojiReactionSchema, DeleteProjectMilestoneSchema, DeleteReleaseSchema, DeleteTagSchema, DeleteWikiPageSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, DownloadAttachmentSchema, DownloadAttachmentRemoteSchema, DownloadJobArtifactsSchema, DownloadJobArtifactsRemoteSchema, DownloadReleaseAssetSchema, EditProjectMilestoneSchema, ExecuteGraphQLSchema, ForkRepositorySchema, HealthCheckSchema, GetBranchSchema, GetBranchDiffsSchema, GetCommitDiffSchema, GetCommitSchema, GetFileBlameSchema, GetDeploymentSchema, GetDraftNoteSchema, GetEnvironmentSchema, GetFileContentsSchema, GetGroupWikiPageSchema, GetIssueLinkSchema, GetIssueSchema, GetJobArtifactFileSchema, GetLabelSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GetMergeRequestDiffsSchema, GetMergeRequestFileDiffSchema, GetMergeRequestNoteSchema, GetMergeRequestNotesSchema, GetMergeRequestSchema, GetMergeRequestVersionSchema, GetMilestoneBurndownEventsSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, GetNamespaceSchema, GetPipelineJobOutputSchema, GetPipelineSchema, GetProjectEventsSchema, GetProjectMilestoneSchema, GetProjectSchema, GetReleaseSchema, GetRepositoryTreeSchema, GetTagSchema, GetTagSignatureSchema, GetTimelineEventsSchema, GetUsersSchema, GetUserSchema, WhoAmISchema, GetWebhookEventSchema, GetWikiPageSchema, GetWorkItemSchema, ListBranchesSchema, ListCommitsSchema, ListCommitStatusesSchema, ListCustomFieldDefinitionsSchema, ListDeploymentsSchema, ListDraftNotesSchema, ListEnvironmentsSchema, ListEventsSchema, ListGroupIterationsSchema, ListGroupProjectsSchema, ListGroupWikiPagesSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListJobArtifactsSchema, ListLabelsSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiffsSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestVersionsSchema, ListMergeRequestsSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListPipelinesSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListReleasesSchema, ListTagsSchema, ListWebhookEventsSchema, ListWebhooksSchema, ListWikiPagesSchema, ListWorkItemNotesSchema, ListWorkItemStatusesSchema, ListWorkItemsSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, MergeMergeRequestSchema, MoveWorkItemSchema, MyIssuesSchema, PlayPipelineJobSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PushFilesSchema, ResolveMergeRequestThreadSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UnapproveMergeRequestSchema, UpdateDraftNoteSchema, UpdateGroupWikiPageSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestSchema, UpdateReleaseSchema, UpdateWikiPageSchema, UpdateWorkItemSchema, VerifyNamespaceSchema, } from "../schemas.js";
+const IS_REMOTE = SSE || STREAMABLE_HTTP;
 // Define all available tools
 export const allTools = [
     {
@@ -600,8 +601,12 @@ export const allTools = [
     },
     {
         name: "download_job_artifacts",
-        description: "Download job artifact archive (zip) to a local path",
-        inputSchema: toJSONSchema(DownloadJobArtifactsSchema),
+        description: IS_REMOTE
+            ? "Get a download URL for a job's artifact archive (zip)"
+            : "Download job artifact archive (zip) and save to a local path",
+        inputSchema: IS_REMOTE
+            ? toJSONSchema(DownloadJobArtifactsRemoteSchema)
+            : toJSONSchema(DownloadJobArtifactsSchema),
     },
     {
         name: "get_job_artifact_file",
@@ -710,13 +715,21 @@ export const allTools = [
     },
     {
         name: "upload_markdown",
-        description: "Upload a file for use in markdown content",
-        inputSchema: toJSONSchema(MarkdownUploadSchema),
+        description: IS_REMOTE
+            ? "Upload base64-encoded content for use in markdown"
+            : "Upload a file for use in markdown content",
+        inputSchema: IS_REMOTE
+            ? toJSONSchema(MarkdownUploadRemoteSchema)
+            : toJSONSchema(MarkdownUploadSchema),
     },
     {
         name: "download_attachment",
-        description: "Download an uploaded file from a project (images returned as base64; use local_path to save to disk)",
-        inputSchema: toJSONSchema(DownloadAttachmentSchema),
+        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)",
+        inputSchema: IS_REMOTE
+            ? toJSONSchema(DownloadAttachmentRemoteSchema)
+            : toJSONSchema(DownloadAttachmentSchema),
     },
     {
         name: "health_check",
@@ -765,7 +778,9 @@ export const allTools = [
     },
     {
         name: "download_release_asset",
-        description: "Download a release asset file by direct asset path",
+        description: IS_REMOTE
+            ? "Get a download URL for a release asset file"
+            : "Download a release asset file by direct asset path",
         inputSchema: toJSONSchema(DownloadReleaseAssetSchema),
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.1.13",
+  "version": "2.1.14",
   "mcpName": "io.github.zereight/gitlab-mcp",
   "description": "GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more",
   "keywords": [