@zereight/mcp-gitlab 2.3.8-next.145 → 2.3.8-next.146

package/build/index.js

@@ -114,6 +114,8 @@ import { parseGitLabVersionApiResponse, } from "./utils/gitlab-instance-version.
 import { buildBulkPublishDraftNotesBody, needsGitLab19_2BulkPublish, } from "./utils/bulk-publish-options.js";
 import { appendFilterParam, appendFilterParams, cleanMutuallyExclusiveIdUsernameOptions, dropBlankArrayEntries, isBlankFilterValue, LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS, sanitizeToolArguments, } from "./utils/tool-args.js";
 import { applyJmespathToToolResult, getJmespathSyntaxError, JMESPATH_TOOL_ARGUMENT, JMESPATH_TOOL_ARGUMENT_DESCRIPTION, omitJmespathArgument, readJmespathExpression, } from "./utils/jmespath-tool-result.js";
+import { appendRecoveryHint } from "./utils/error-hints.js";
+import { applyListSummaryToToolResult, omitListSummaryArgument, readListSummaryRequested, toolAcceptsDecoratedSummary, } from "./utils/list-summary.js";
 import { parseSearchReplaceBlocks, applySearchReplace, applyUnifiedDiff, } from "./utils/patch-helper.js";
 import { zodSchemaFor } from "./utils/schema.js";
 import { GitLabClientPool } from "./gitlab-client-pool.js";
@@ -229,14 +231,18 @@ function createServer() {
         const toolName = request.params.name;
         const start = Date.now();
         let maskingEngine;
-        const jmespathExpression = readJmespathExpression(request.params.arguments);
+        const requestArguments = readOwnRecord(request.params.arguments);
+        const jmespathExpression = readJmespathExpression(requestArguments === undefined ? undefined : { ...requestArguments });
+        const listSummaryRequested = toolAcceptsDecoratedSummary(toolName) &&
+            readListSummaryRequested(requestArguments === undefined ? undefined : { ...requestArguments });
         const logCompletion = (result, completionOptions) => {
             const durationMs = Date.now() - start;
             logger.info({ tool: toolName, event: "tool_call_done", durationMs }, `tool_call_done: ${toolName} (${durationMs}ms)`);
             const isPlainTextResult = toolName === "get_pipeline_job_output" ||
                 toolName === "get_job_artifact_file" ||
                 (toolName === "download_release_asset" && !IS_REMOTE);
-            const filtered = applyJmespathToToolResult(redactErrorResultUrls(result), jmespathExpression, {
+            const summarized = applyListSummaryToToolResult(redactErrorResultUrls(result), listSummaryRequested);
+            const filtered = applyJmespathToToolResult(summarized, jmespathExpression, {
                 ...completionOptions,
                 maskValue: maskingEngine
                     ? (value) => maskingEngine.maskValue(value)
@@ -477,8 +483,13 @@ function createServer() {
                 const { _confirmed, ...cleanArgs } = request.params.arguments || {};
                 request.params.arguments = cleanArgs;
             }
-            if (request.params.arguments && typeof request.params.arguments === "object") {
-                request.params.arguments = omitJmespathArgument(request.params.arguments);
+            const ownedArguments = readOwnRecord(request.params.arguments);
+            if (ownedArguments) {
+                let cleanedArguments = omitJmespathArgument({ ...ownedArguments });
+                if (toolAcceptsDecoratedSummary(toolName)) {
+                    cleanedArguments = omitListSummaryArgument(cleanedArguments);
+                }
+                request.params.arguments = cleanedArguments;
             }
             if (sessionContext) {
                 // Policy selection and the tool handler must use the same request-local
@@ -500,7 +511,7 @@ function createServer() {
                     content: [
                         {
                             type: "text",
-                            text: safeError instanceof Error ? safeError.message : String(safeError),
+                            text: appendRecoveryHint(safeError instanceof Error ? safeError.message : String(safeError)),
                         },
                     ],
                     isError: true,
@@ -1418,12 +1429,12 @@ async function handleGitLabError(response) {
             // before the common tool-call boundary returns/logs it.
             logger.error("GitLab API Rate Limit Exceeded");
             logger.error("User API Key Rate limit exceeded. Please try again later.");
-            const error = new GitLabApiError(`GitLab API Rate Limit Exceeded: ${errorBody}`);
+            const error = new GitLabApiError(appendRecoveryHint(`GitLab API Rate Limit Exceeded: ${errorBody}`));
             throw error;
         }
         else {
             // Handle other API errors
-            const error = new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+            const error = new GitLabApiError(appendRecoveryHint(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`));
             throw error;
         }
     }
@@ -7646,7 +7657,7 @@ function getSafeAttachmentFilename(filename) {
     }
     return filename;
 }
-async function downloadAttachment(projectId, secret, filename, localPath) {
+async function downloadAttachment(projectId, secret, filename, localPath, metadataOnly = false) {
     const effectiveProjectId = getEffectiveProjectId(projectId);
     const safeFilename = getSafeAttachmentFilename(filename);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/uploads/${encodeGitLabPathSegment(secret)}/${encodeGitLabPathSegment(safeFilename)}`);
@@ -7655,6 +7666,18 @@ async function downloadAttachment(projectId, secret, filename, localPath) {
         await handleGitLabError(response);
     }
     const mimeType = getImageMimeType(safeFilename);
+    if (metadataOnly) {
+        const headerLength = Number(response.headers.get("content-length"));
+        if (response.body) {
+            await response.body.cancel();
+        }
+        return {
+            buffer: Buffer.alloc(0),
+            filename: safeFilename,
+            mimeType,
+            byteLength: Number.isFinite(headerLength) ? headerLength : undefined,
+        };
+    }
     // Non-image files, and images with local_path, are saved as new files under the
     // download directory. Upload names and local_path come from untrusted content, so
     // dot names (.git, .vscode, .envrc) are refused and existing files are never replaced.
@@ -10718,10 +10741,27 @@ async function handleToolCall(params) {
                     };
                 }
                 // Readonly mode never writes to disk: images still come back inline.
-                if (GITLAB_PERMISSION_MODE === "readonly" && (!mimeType || args.local_path)) {
+                if (GITLAB_PERMISSION_MODE === "readonly" &&
+                    !args.metadata_only &&
+                    (!mimeType || args.local_path)) {
                     throw new Error("download_attachment saves this file to disk, which readonly mode does not allow. Only images without local_path can be downloaded in readonly mode.");
                 }
-                const result = await downloadAttachment(args.project_id, args.secret, args.filename, args.local_path);
+                const result = await downloadAttachment(args.project_id, args.secret, args.filename, args.local_path, args.metadata_only === true);
+                if (args.metadata_only) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    filename: result.filename,
+                                    mimeType: result.mimeType,
+                                    byte_length: result.byteLength ?? result.buffer.byteLength,
+                                    metadata_only: true,
+                                }),
+                            },
+                        ],
+                    };
+                }
                 if (result.mimeType && !args.local_path) {
                     // Return image inline as base64 so the AI can see it
                     const base64 = result.buffer.toString("base64");

package/build/schemas.js

@@ -3522,6 +3522,10 @@ export const DownloadAttachmentSchema = z.object({
         .string()
         .optional()
         .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"),
+    metadata_only: z
+        .boolean()
+        .optional()
+        .describe("If true, return filename, mime type, and byte length without inline image bytes or a saved file. Default false keeps the existing download behavior."),
 });
 export const DownloadAttachmentRemoteSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path of the project"),

package/build/tools/discover-activation.js

@@ -1,3 +1,4 @@
+import { appendRecoveryHint } from "../utils/error-hints.js";
 /**
  * Same skips `discover_tools` uses when it adds tools: permission mode, regex
  * denial, hidden policy, and the slim profile. Those tools never join the list.
@@ -22,15 +23,15 @@ export function buildUnavailableToolMessage(input) {
     const base = `Tool "${input.toolName}" is not available on this server`;
     const toolset = input.toolset;
     if (toolset === undefined || input.deniedByRegex) {
-        return base;
+        return appendRecoveryHint(base);
     }
     if (input.excludedBySlimProfile) {
-        return `${base}. ${slimExclusionGuidance(input.toolName, toolset, input.enabledByCurrentToolsets)}`;
+        return appendRecoveryHint(`${base}. ${slimExclusionGuidance(input.toolName, toolset, input.enabledByCurrentToolsets)}`);
     }
     if (input.explicitToolsetOnly) {
-        return `${base}. The "${toolset}" toolset is not enabled. discover_tools cannot activate it. Add "${toolset}" to GITLAB_TOOLSETS. GITLAB_TOOLSETS=all, GITLAB_TOOLS, and GITLAB_TOOL_PROFILE do not enable it.`;
+        return appendRecoveryHint(`${base}. The "${toolset}" toolset is not enabled. discover_tools cannot activate it. Add "${toolset}" to GITLAB_TOOLSETS. GITLAB_TOOLSETS=all, GITLAB_TOOLS, and GITLAB_TOOL_PROFILE do not enable it.`);
     }
-    return `${base}. It belongs to the "${toolset}" toolset, which is not enabled: call discover_tools with category "${toolset}" or add "${toolset}" to GITLAB_TOOLSETS.`;
+    return appendRecoveryHint(`${base}. It belongs to the "${toolset}" toolset, which is not enabled: call discover_tools with category "${toolset}" or add "${toolset}" to GITLAB_TOOLSETS.`);
 }
 function slimExclusionGuidance(toolName, toolset, enabledByCurrentToolsets) {
     const viaToolsets = `add "${toolset}" to GITLAB_TOOLSETS (setting GITLAB_TOOLSETS disables the slim profile)`;

package/build/tools/listed-tools.js

@@ -1,3 +1,4 @@
+import { LIST_SUMMARY_ARGUMENT, LIST_SUMMARY_ARGUMENT_DESCRIPTION, toolAcceptsDecoratedSummary, } from "../utils/list-summary.js";
 const CONFIRMED_ARGUMENT = "_confirmed";
 const CONFIRMED_ARGUMENT_DESCRIPTION = "Set to true to confirm execution of this approval-required tool.";
 function isRecord(value) {
@@ -36,11 +37,29 @@ function withJmespathArgument(schema, context) {
     };
     return { ...schema, properties };
 }
+function withSummaryArgument(schema, toolName) {
+    if (!toolAcceptsDecoratedSummary(toolName) || !isRecord(schema.properties)) {
+        return schema;
+    }
+    if (LIST_SUMMARY_ARGUMENT in schema.properties) {
+        return schema;
+    }
+    return {
+        ...schema,
+        properties: {
+            ...schema.properties,
+            [LIST_SUMMARY_ARGUMENT]: {
+                type: "boolean",
+                description: LIST_SUMMARY_ARGUMENT_DESCRIPTION,
+            },
+        },
+    };
+}
 function decorateInputSchema(schema, toolName, context) {
     if (!isRecord(schema)) {
         return undefined;
     }
-    return withJmespathArgument(withConfirmedArgument(cloneSchema(schema), toolName, context), context);
+    return withSummaryArgument(withJmespathArgument(withConfirmedArgument(cloneSchema(schema), toolName, context), context), toolName);
 }
 export function decorateToolForList(tool, context) {
     const inputSchema = decorateInputSchema(tool.inputSchema, tool.name, context);

package/build/utils/error-hints.js

@@ -0,0 +1,42 @@
+const NEXT_PREFIX = "\nNext: ";
+export function hasRecoveryHint(message) {
+    return message.includes(NEXT_PREFIX);
+}
+export function recoveryHintFor(message) {
+    if (/^Access denied:/i.test(message)) {
+        return undefined;
+    }
+    if (/is not available on this server/i.test(message)) {
+        if (/slim tool profile/i.test(message) || /cannot activate/i.test(message)) {
+            return undefined;
+        }
+        if (/discover_tools|GITLAB_TOOLSETS|GITLAB_TOOLS/.test(message)) {
+            return "call discover_tools with the category, or add it to GITLAB_TOOLSETS.";
+        }
+    }
+    if (/\b401\b/.test(message) || /unauthorized/i.test(message)) {
+        return "set GITLAB_PERSONAL_ACCESS_TOKEN (or run `zereight-mcp-gitlab auth`) and retry.";
+    }
+    if (/rate limit/i.test(message)) {
+        return "wait and retry; lower per_page or paginate if the client is bursting.";
+    }
+    if (/\b403\b/.test(message) ||
+        /forbidden/i.test(message) ||
+        /insufficient_scope/i.test(message)) {
+        return "check token scopes and GITLAB_PERMISSION_MODE; grant read_user or User:Read for whoami.";
+    }
+    if (/\b404\b/.test(message) || /404 not found/i.test(message)) {
+        return "check project_id (numeric ID or group%2Fproject) and the resource iid.";
+    }
+    return undefined;
+}
+export function appendRecoveryHint(message) {
+    if (hasRecoveryHint(message)) {
+        return message;
+    }
+    const hint = recoveryHintFor(message);
+    if (hint === undefined) {
+        return message;
+    }
+    return `${message}${NEXT_PREFIX}${hint}`;
+}

package/build/utils/list-summary.js

@@ -0,0 +1,90 @@
+/** MCP-only argument; stripped before GitLab handlers run. */
+export const LIST_SUMMARY_ARGUMENT = "summary";
+export const LIST_SUMMARY_ARGUMENT_DESCRIPTION = "If true, return only high-signal fields (id, iid, title, state, web_url, …). Default false keeps the full GitLab JSON.";
+const SUMMARY_FIELDS = [
+    "id",
+    "iid",
+    "title",
+    "name",
+    "state",
+    "status",
+    "ref",
+    "web_url",
+    "path_with_namespace",
+    "username",
+    "short_id",
+    "key",
+    "tag_name",
+    "slug",
+    "filename",
+    "new_path",
+];
+const NATIVE_SUMMARY_TOOLS = new Set(["list_webhook_events"]);
+export function toolAcceptsDecoratedSummary(toolName) {
+    if (NATIVE_SUMMARY_TOOLS.has(toolName)) {
+        return false;
+    }
+    return toolName.startsWith("list_") || toolName === "mr_discussions";
+}
+export function readListSummaryRequested(args) {
+    if (!args) {
+        return false;
+    }
+    const raw = args[LIST_SUMMARY_ARGUMENT];
+    return raw === true || raw === "true";
+}
+export function omitListSummaryArgument(args) {
+    if (!(LIST_SUMMARY_ARGUMENT in args)) {
+        return args;
+    }
+    const { [LIST_SUMMARY_ARGUMENT]: _omit, ...rest } = args;
+    return rest;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function summarizeItem(item) {
+    if (!isRecord(item)) {
+        return item;
+    }
+    const summarized = {};
+    for (const field of SUMMARY_FIELDS) {
+        if (field in item) {
+            summarized[field] = item[field];
+        }
+    }
+    return Object.keys(summarized).length > 0 ? summarized : item;
+}
+export function summarizeListPayload(data) {
+    if (Array.isArray(data)) {
+        return data.map(summarizeItem);
+    }
+    if (isRecord(data) && Array.isArray(data.items)) {
+        return { ...data, items: data.items.map(summarizeItem) };
+    }
+    return data;
+}
+function isTextContentBlock(value) {
+    return typeof value === "object" && value !== null;
+}
+export function applyListSummaryToToolResult(result, requested) {
+    if (!requested || result.isError) {
+        return result;
+    }
+    if (!Array.isArray(result.content)) {
+        return result;
+    }
+    const content = result.content.map(block => {
+        if (!isTextContentBlock(block) || block.type !== "text" || typeof block.text !== "string") {
+            return block;
+        }
+        try {
+            const parsed = JSON.parse(block.text);
+            return { ...block, text: JSON.stringify(summarizeListPayload(parsed)) };
+        }
+        catch {
+            return block;
+        }
+    });
+    return { ...result, content };
+}

package/package.json

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