@zereight/mcp-gitlab 2.1.63 → 2.1.64

package/README.ko.md

@@ -110,7 +110,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 
 예시는 기존 `mcp-gitlab`보다 충돌 가능성이 낮은 `zereight-mcp-gitlab` 별칭을 사용합니다. MCP 클라이언트가 찾지 못하면 `which zereight-mcp-gitlab`의 절대 경로를 사용하세요.
 
-전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.62`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.63`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
 
 #### CLI 인자 사용하기(환경 변수 문제가 있는 클라이언트용)
 

package/README.md

@@ -115,7 +115,7 @@ The store path is pinned by your lock file; update it with `nix flake update git
 
 The examples use `zereight-mcp-gitlab`, a less collision-prone alias for the legacy `mcp-gitlab` binary. If your MCP client cannot find it, use the absolute path from `which zereight-mcp-gitlab`.
 
-No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.62`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
+No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.63`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
 
 #### Using CLI Arguments (for clients with env var issues)
 

package/README.zh-CN.md

@@ -110,7 +110,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 
 示例使用 `zereight-mcp-gitlab`，这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它，请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
 
-如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.62`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.63`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 

package/build/index.js

@@ -100,7 +100,7 @@ import { checkForNewVersion } from "./utils/version-check.js";
 import { assertGitLabVersionAtLeast } from "./utils/gitlab-version-gate.js";
 import { parseGitLabVersionApiResponse, } from "./utils/gitlab-instance-version.js";
 import { buildBulkPublishDraftNotesBody, needsGitLab19_2BulkPublish, } from "./utils/bulk-publish-options.js";
-import { cleanMutuallyExclusiveIdUsernameOptions, LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS, sanitizeToolArguments, } from "./utils/tool-args.js";
+import { appendFilterParam, appendFilterParams, cleanMutuallyExclusiveIdUsernameOptions, dropBlankArrayEntries, isBlankFilterValue, LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS, sanitizeToolArguments, } from "./utils/tool-args.js";
 import { parseSearchReplaceBlocks, applySearchReplace, applyUnifiedDiff, } from "./utils/patch-helper.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { GitLabClientPool } from "./gitlab-client-pool.js";
@@ -1506,23 +1506,26 @@ async function listIssues(projectId, options = {}) {
     }
     // Add all query parameters
     Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            const keys = ["labels", "assignee_username"];
-            if (keys.includes(key)) {
-                if (Array.isArray(value)) {
-                    // Handle array of labels
-                    value.forEach(label => {
-                        url.searchParams.append(`${key}[]`, label.toString());
-                    });
-                }
-                else if (value) {
-                    url.searchParams.append(`${key}[]`, value.toString());
-                }
+        // Drop blank entries inside arrays so ["", "bug"] behaves like the scalar guard below
+        const normalized = dropBlankArrayEntries(value);
+        if (isBlankFilterValue(normalized)) {
+            return;
+        }
+        const keys = ["labels", "assignee_username"];
+        if (keys.includes(key)) {
+            if (Array.isArray(normalized)) {
+                // Handle array of labels
+                normalized.forEach(label => {
+                    url.searchParams.append(`${key}[]`, String(label));
+                });
             }
             else {
-                url.searchParams.append(key, String(value));
+                url.searchParams.append(`${key}[]`, String(normalized));
             }
         }
+        else {
+            url.searchParams.append(key, String(normalized));
+        }
     });
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
@@ -1533,11 +1536,7 @@ async function listIssues(projectId, options = {}) {
 }
 async function listTodos(options = {}) {
     const url = new URL(`${getEffectiveApiUrl()}/todos`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -1566,20 +1565,22 @@ async function markAllTodosDone() {
  */
 function appendMergeRequestFilters(url, options) {
     Object.entries(options).forEach(([key, value]) => {
-        if (value === undefined) {
+        // Drop blank entries inside arrays so ["", "bug"] behaves like the scalar guard below
+        const normalized = dropBlankArrayEntries(value);
+        if (isBlankFilterValue(normalized)) {
             return;
         }
-        if (key === "labels" && Array.isArray(value)) {
-            url.searchParams.append(key, value.join(","));
+        if (key === "labels" && Array.isArray(normalized)) {
+            url.searchParams.append(key, normalized.join(","));
         }
-        else if (key === "approved_by_usernames" && Array.isArray(value)) {
+        else if (key === "approved_by_usernames" && Array.isArray(normalized)) {
             // GitLab expects array-bracket form: approved_by_usernames[]=alice&approved_by_usernames[]=bob
-            for (const v of value) {
+            for (const v of normalized) {
                 url.searchParams.append(`${key}[]`, String(v));
             }
         }
         else {
-            url.searchParams.append(key, String(value));
+            url.searchParams.append(key, String(normalized));
         }
     });
 }
@@ -3800,11 +3801,7 @@ async function getMergeRequestSourceCommitCount(projectId, mergeRequestIid) {
 async function listMergeRequestPipelines(projectId, mergeRequestIid, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${encodeGitLabPathSegment(mergeRequestIid)}/pipelines`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -4734,16 +4731,7 @@ async function getMergeRequestVersion(projectId, mergeRequestIid, versionId, uni
 async function listProjects(options = {}) {
     // Construct the query parameters
     const params = new URLSearchParams();
-    for (const [key, value] of Object.entries(options)) {
-        if (value !== undefined && value !== null) {
-            if (typeof value === "boolean") {
-                params.append(key, value ? "true" : "false");
-            }
-            else {
-                params.append(key, String(value));
-            }
-        }
-    }
+    appendFilterParams(params, options);
     // Make the API request
     const response = await fetch(`${getEffectiveApiUrl()}/projects?${params.toString()}`, {
         ...getFetchConfig(),
@@ -4766,16 +4754,7 @@ async function listLabels(projectId, options = {}) {
     // Construct the URL with project path
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/labels`);
     // Add query parameters
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            if (typeof value === "boolean") {
-                url.searchParams.append(key, value ? "true" : "false");
-            }
-            else {
-                url.searchParams.append(key, String(value));
-            }
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     // Make the API request
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
@@ -5232,11 +5211,7 @@ async function listPipelines(projectId, options = {}) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines`);
     // Add all query parameters
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5310,11 +5285,7 @@ async function updatePipelineMetadata(projectId, pipelineId, name) {
 async function listDeployments(projectId, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/deployments`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5366,11 +5337,7 @@ async function deploymentRequest(projectId, path = "", method = "GET", body, que
 async function listEnvironments(projectId, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/environments`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5440,16 +5407,7 @@ async function listPipelineJobs(projectId, pipelineId, options = {}) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines/${encodeGitLabPathSegment(pipelineId)}/jobs`);
     // Add all query parameters
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            if (typeof value === "boolean") {
-                url.searchParams.append(key, value ? "true" : "false");
-            }
-            else {
-                url.searchParams.append(key, value.toString());
-            }
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5472,16 +5430,7 @@ async function listPipelineTriggerJobs(projectId, pipelineId, options = {}) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines/${encodeGitLabPathSegment(pipelineId)}/bridges`);
     // Add all query parameters
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            if (typeof value === "boolean") {
-                url.searchParams.append(key, value ? "true" : "false");
-            }
-            else {
-                url.searchParams.append(key, value.toString());
-            }
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5566,16 +5515,7 @@ async function validateCiLint(projectId, options) {
 async function validateProjectCiLint(projectId, options) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/ci/lint`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            if (typeof value === "boolean") {
-                url.searchParams.append(key, value ? "true" : "false");
-            }
-            else {
-                url.searchParams.append(key, value.toString());
-            }
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5594,16 +5534,7 @@ async function validateProjectCiLint(projectId, options) {
 async function listJobArtifacts(projectId, jobId, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/jobs/${encodeGitLabPathSegment(jobId)}/artifacts/tree`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            if (typeof value === "boolean") {
-                url.searchParams.append(key, value ? "true" : "false");
-            }
-            else {
-                url.searchParams.append(key, value.toString());
-            }
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5740,11 +5671,7 @@ async function cancelPipeline(projectId, pipelineId) {
 async function listPipelineSchedules(projectId, options = {}) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipeline_schedules`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -5780,11 +5707,7 @@ async function getPipelineSchedule(projectId, pipelineScheduleId) {
 async function listPipelineSchedulePipelines(projectId, pipelineScheduleId, options = {}) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipeline_schedules/${encodeGitLabPathSegment(pipelineScheduleId)}/pipelines`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6107,15 +6030,18 @@ async function listProjectMilestones(projectId, options) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones`);
     Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            if (key === "iids" && Array.isArray(value) && value.length > 0) {
-                value.forEach(iid => {
-                    url.searchParams.append("iids[]", iid.toString());
-                });
-            }
-            else if (value !== undefined) {
-                url.searchParams.append(key, value.toString());
-            }
+        // Drop blank entries inside arrays so they behave like the scalar blank guard below
+        const normalized = dropBlankArrayEntries(value);
+        if (isBlankFilterValue(normalized)) {
+            return;
+        }
+        if (key === "iids" && Array.isArray(normalized)) {
+            normalized.forEach(iid => {
+                url.searchParams.append("iids[]", String(iid));
+            });
+        }
+        else {
+            url.searchParams.append(key, String(normalized));
         }
     });
     const response = await fetch(url.toString(), {
@@ -6202,11 +6128,7 @@ async function deleteProjectMilestone(projectId, milestoneId) {
 async function getMilestoneIssues(projectId, milestoneId, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${encodeGitLabPathSegment(milestoneId)}/issues`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6223,11 +6145,7 @@ async function getMilestoneIssues(projectId, milestoneId, options = {}) {
 async function getMilestoneMergeRequests(projectId, milestoneId, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${encodeGitLabPathSegment(milestoneId)}/merge_requests`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6261,11 +6179,7 @@ async function promoteProjectMilestone(projectId, milestoneId) {
 async function getMilestoneBurndownEvents(projectId, milestoneId, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${encodeGitLabPathSegment(milestoneId)}/burndown_events`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6280,15 +6194,18 @@ async function listGroupMilestones(groupId, options) {
     groupId = decodeURIComponent(groupId);
     const url = new URL(`${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/milestones`);
     Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            if (key === "iids" && Array.isArray(value) && value.length > 0) {
-                value.forEach(iid => {
-                    url.searchParams.append("iids[]", iid.toString());
-                });
-            }
-            else {
-                url.searchParams.append(key, value.toString());
-            }
+        // Drop blank entries inside arrays so they behave like the scalar blank guard below
+        const normalized = dropBlankArrayEntries(value);
+        if (isBlankFilterValue(normalized)) {
+            return;
+        }
+        if (key === "iids" && Array.isArray(normalized)) {
+            normalized.forEach(iid => {
+                url.searchParams.append("iids[]", String(iid));
+            });
+        }
+        else {
+            url.searchParams.append(key, String(normalized));
         }
     });
     const response = await fetch(url.toString(), {
@@ -6359,11 +6276,7 @@ async function deleteGroupMilestone(groupId, milestoneId) {
 async function getGroupMilestoneIssues(groupId, milestoneId, options = {}) {
     groupId = decodeURIComponent(groupId);
     const url = new URL(`${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/milestones/${encodeGitLabPathSegment(milestoneId)}/issues`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6377,11 +6290,7 @@ async function getGroupMilestoneIssues(groupId, milestoneId, options = {}) {
 async function getGroupMilestoneMergeRequests(groupId, milestoneId, options = {}) {
     groupId = decodeURIComponent(groupId);
     const url = new URL(`${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/milestones/${encodeGitLabPathSegment(milestoneId)}/merge_requests`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6395,11 +6304,7 @@ async function getGroupMilestoneMergeRequests(groupId, milestoneId, options = {}
 async function getGroupMilestoneBurndownEvents(groupId, milestoneId, options = {}) {
     groupId = decodeURIComponent(groupId);
     const url = new URL(`${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/milestones/${encodeGitLabPathSegment(milestoneId)}/burndown_events`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, String(value));
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6598,11 +6503,7 @@ async function getFileBlame(projectId, options) {
 async function listCommitStatuses(projectId, sha, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/commits/${encodeURIComponent(sha)}/statuses`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -6624,11 +6525,7 @@ async function createCommitStatus(projectId, sha, options) {
     }
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/statuses/${encodeURIComponent(sha)}`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
         method: "POST",
@@ -6806,19 +6703,13 @@ async function listProjectVariables(projectId, options = {}) {
     projectId = decodeURIComponent(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/variables`);
     Object.entries(options).forEach(([key, value]) => {
-        if (value === undefined)
-            return;
         if (key === "filter" && typeof value === "object" && value !== null) {
-            Object.entries(value).forEach(([fKey, fVal]) => {
-                url.searchParams.append(`filter[${fKey}]`, fVal);
+            Object.entries(value).forEach(([filterKey, filterValue]) => {
+                appendFilterParam(url.searchParams, `filter[${filterKey}]`, filterValue);
             });
+            return;
         }
-        else if (typeof value === "boolean") {
-            url.searchParams.append(key, value ? "true" : "false");
-        }
-        else {
-            url.searchParams.append(key, String(value));
-        }
+        appendFilterParam(url.searchParams, key, value);
     });
     const response = await fetch(url.toString(), getFetchConfig());
     await handleGitLabError(response);
@@ -6872,19 +6763,13 @@ async function listGroupVariables(groupId, options = {}) {
     const encoded = encodeURIComponent(decodeURIComponent(groupId));
     const url = new URL(`${getEffectiveApiUrl()}/groups/${encoded}/variables`);
     Object.entries(options).forEach(([key, value]) => {
-        if (value === undefined)
-            return;
         if (key === "filter" && typeof value === "object" && value !== null) {
-            Object.entries(value).forEach(([fKey, fVal]) => {
-                url.searchParams.append(`filter[${fKey}]`, fVal);
+            Object.entries(value).forEach(([filterKey, filterValue]) => {
+                appendFilterParam(url.searchParams, `filter[${filterKey}]`, filterValue);
             });
+            return;
         }
-        else if (typeof value === "boolean") {
-            url.searchParams.append(key, value ? "true" : "false");
-        }
-        else {
-            url.searchParams.append(key, String(value));
-        }
+        appendFilterParam(url.searchParams, key, value);
     });
     const response = await fetch(url.toString(), getFetchConfig());
     await handleGitLabError(response);
@@ -7431,11 +7316,7 @@ async function downloadAttachment(projectId, secret, filename, localPath) {
 async function listEvents(options = {}) {
     const url = new URL(`${getEffectiveApiUrl()}/events`);
     // Add all query parameters
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), { ...getFetchConfig() });
     if (!response.ok) {
         await handleGitLabError(response);
@@ -7453,11 +7334,7 @@ async function getProjectEvents(projectId, options = {}) {
     const effectiveProjectId = getEffectiveProjectId(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/events`);
     // Add all query parameters
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), { ...getFetchConfig() });
     if (!response.ok) {
         await handleGitLabError(response);
@@ -7476,11 +7353,7 @@ async function listReleases(projectId, options = {}) {
     const effectiveProjectId = getEffectiveProjectId(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases`);
     // Add query parameters
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -7603,11 +7476,7 @@ async function downloadReleaseAsset(projectId, tagName, directAssetPath) {
 async function listTags(projectId, options = {}) {
     const effectiveProjectId = getEffectiveProjectId(projectId);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/tags`);
-    Object.entries(options).forEach(([key, value]) => {
-        if (value !== undefined) {
-            url.searchParams.append(key, value.toString());
-        }
-    });
+    appendFilterParams(url.searchParams, options);
     const response = await fetch(url.toString(), {
         ...getFetchConfig(),
     });
@@ -8847,8 +8716,8 @@ async function handleToolCall(params) {
                 };
             }
             case "list_labels": {
-                const args = ListLabelsSchema.parse(params.arguments);
-                const labels = await listLabels(args.project_id, args);
+                const { project_id, ...options } = ListLabelsSchema.parse(params.arguments);
+                const labels = await listLabels(project_id, options);
                 return {
                     content: [{ type: "text", text: JSON.stringify(labels) }],
                 };

package/build/schemas.js

@@ -3075,7 +3075,7 @@ export const ListProjectMilestonesSchema = ProjectParamsSchema.extend({
     iids: z
         .array(z.coerce.number())
         .optional()
-        .describe("Return only the milestones having the given iid"),
+        .describe("Return only the milestones having the given iid. An empty array is treated as no filter and is left out of the request."),
     state: z
         .enum(["active", "closed"])
         .optional()
@@ -3137,7 +3137,7 @@ export const ListGroupMilestonesSchema = z
     iids: z
         .array(z.coerce.number())
         .optional()
-        .describe("Return only the milestones having the given iid"),
+        .describe("Return only the milestones having the given iid. An empty array is treated as no filter and is left out of the request."),
     state: z
         .enum(["active", "closed"])
         .optional()

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

@@ -0,0 +1,58 @@
+#!/usr/bin/env tsx
+/**
+ * Generate docs/reference/tool-coverage.md from tools/registry.ts + test/ MCP calls.
+ *
+ * Detection rules live in ./tool-coverage/coverage.ts (AST-scoped): a tool is
+ * invoked when test source sends that name as a `callTool*` argument, as the
+ * `name` of a first-argument params object (`client.callTool({ name })`), or as
+ * the `name` of a `params` object inside a `tools/call` payload literal.
+ *
+ * Name-only mentions (toolset tables, description-quality) do not count.
+ * callTool(variable) loops are missed unless the name is also a literal in that call.
+ *
+ * Run with: npm run docs:tools
+ */
+import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { allTools, TOOLSET_DEFINITIONS } from "../tools/registry.js";
+import { assertDetectorHealthy, buildCoverageMarkdown, collectInvocations, countInvoked, groupToolsByToolset, percent, SKIP_FILES, } from "./tool-coverage/coverage.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, "..");
+const TEST_DIR = join(REPO_ROOT, "test");
+const OUT_PATH = join(REPO_ROOT, "docs", "reference", "tool-coverage.md");
+function walkTestFiles(dir) {
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const full = join(dir, name);
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+            out.push(...walkTestFiles(full));
+            continue;
+        }
+        if (/\.(ts|js)$/.test(name) && !SKIP_FILES.has(name)) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function repoPath(abs) {
+    return relative(REPO_ROOT, abs).split("\\").join("/");
+}
+function readScannedFiles() {
+    return walkTestFiles(TEST_DIR).map(abs => ({
+        path: repoPath(abs),
+        text: readFileSync(abs, "utf8"),
+    }));
+}
+function main() {
+    const toolNames = allTools.map(tool => tool.name);
+    const toolNameSet = new Set(toolNames);
+    const hits = collectInvocations(readScannedFiles(), toolNameSet);
+    const invokedCount = countInvoked(toolNames, hits);
+    assertDetectorHealthy(hits, invokedCount);
+    const grouped = groupToolsByToolset(toolNames, TOOLSET_DEFINITIONS);
+    writeFileSync(OUT_PATH, buildCoverageMarkdown(toolNames, hits, grouped));
+    console.log(`generated docs/reference/tool-coverage.md — ${invokedCount}/${toolNames.length} (${percent(invokedCount, toolNames.length)})`);
+}
+main();