@zereight/mcp-gitlab 2.3.1 → 2.3.3

package/README.ko.md

@@ -138,7 +138,13 @@ 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.3.0`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.3.2`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+
+#### Claude Desktop 원클릭 설치(MCP Bundle)
+
+v2.3.1 이후의 GitHub 릴리스마다 `gitlab-mcp.mcpb` [MCP Bundle](https://github.com/modelcontextprotocol/mcpb)이 첨부됩니다. [최신 번들](https://github.com/zereight/gitlab-mcp/releases/latest/download/gitlab-mcp.mcpb)을 내려받아 Claude Desktop으로 열거나 **Settings → Extensions**에 끌어다 놓으세요. Claude Desktop이 Personal Access Token을 입력받아 민감 정보로 저장하고, `GITLAB_API_URL`, `GITLAB_PERMISSION_MODE`, `GITLAB_TOOLSETS`, `GITLAB_MASKING_ENABLED`를 설정할 수 있게 합니다. Node.js나 npm을 따로 설치할 필요가 없습니다.
+
+소스에서 번들을 만들려면 `npm run pack:mcpb`를 실행하세요(`gitlab-mcp.mcpb` 생성).
 
 #### CLI 인자 사용하기(환경 변수 문제가 있는 클라이언트용)
 

package/README.md

@@ -143,7 +143,13 @@ 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.3.0`. 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.3.2`. 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`).
+
+#### Claude Desktop one-click install (MCP Bundle)
+
+Every GitHub release after v2.3.1 ships a `gitlab-mcp.mcpb` [MCP Bundle](https://github.com/modelcontextprotocol/mcpb). Download the [latest bundle](https://github.com/zereight/gitlab-mcp/releases/latest/download/gitlab-mcp.mcpb) and open it with Claude Desktop (or drag it into **Settings → Extensions**). Claude Desktop asks for your Personal Access Token (stored as a sensitive value) and lets you set `GITLAB_API_URL`, `GITLAB_PERMISSION_MODE`, `GITLAB_TOOLSETS`, and `GITLAB_MASKING_ENABLED`. No separate Node.js or npm install is needed.
+
+To build the bundle from source, run `npm run pack:mcpb` (writes `gitlab-mcp.mcpb`).
 
 #### Using CLI Arguments (for clients with env var issues)
 

package/README.pt-BR.md

@@ -138,7 +138,13 @@ O caminho no store é fixado pelo seu lock file; atualize-o com `nix flake updat
 
 Os exemplos usam `zereight-mcp-gitlab`, um alias com menor chance de conflito que o binário legado `mcp-gitlab`. Se o seu cliente MCP não o encontrar, use o caminho absoluto retornado por `which zereight-mcp-gitlab`.
 
-Não quer instalar globalmente? Fixe o `npx` na versão estável anterior (a versão recomendada por esta documentação), por exemplo `npx -y @zereight/mcp-gitlab@2.3.0`. Se quiser sempre a versão mais recente, use `npx -y @zereight/mcp-gitlab@latest`. O servidor exibe um aviso no stderr durante a inicialização quando existe uma versão mais nova disponível (desative com `GITLAB_DISABLE_VERSION_CHECK=true`).
+Não quer instalar globalmente? Fixe o `npx` na versão estável anterior (a versão recomendada por esta documentação), por exemplo `npx -y @zereight/mcp-gitlab@2.3.2`. Se quiser sempre a versão mais recente, use `npx -y @zereight/mcp-gitlab@latest`. O servidor exibe um aviso no stderr durante a inicialização quando existe uma versão mais nova disponível (desative com `GITLAB_DISABLE_VERSION_CHECK=true`).
+
+#### Instalação com um clique no Claude Desktop (MCP Bundle)
+
+Cada release no GitHub posterior à v2.3.1 inclui um [MCP Bundle](https://github.com/modelcontextprotocol/mcpb) `gitlab-mcp.mcpb`. Baixe o [bundle mais recente](https://github.com/zereight/gitlab-mcp/releases/latest/download/gitlab-mcp.mcpb) e abra-o com o Claude Desktop (ou arraste-o para **Settings → Extensions**). O Claude Desktop pede seu Personal Access Token (armazenado como valor sensível) e permite definir `GITLAB_API_URL`, `GITLAB_PERMISSION_MODE`, `GITLAB_TOOLSETS` e `GITLAB_MASKING_ENABLED`. Não é preciso instalar Node.js ou npm separadamente.
+
+Para gerar o bundle a partir do código-fonte, execute `npm run pack:mcpb` (gera `gitlab-mcp.mcpb`).
 
 #### Usando argumentos de CLI (para clientes com problemas com variáveis de ambiente)
 

package/README.zh-CN.md

@@ -138,7 +138,13 @@ 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.3.0`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.3.2`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+
+#### Claude Desktop 一键安装（MCP Bundle）
+
+v2.3.1 之后的每个 GitHub Release 都附带 `gitlab-mcp.mcpb` [MCP Bundle](https://github.com/modelcontextprotocol/mcpb)。下载[最新的 bundle](https://github.com/zereight/gitlab-mcp/releases/latest/download/gitlab-mcp.mcpb)，用 Claude Desktop 打开（或拖到 **Settings → Extensions** 中）。Claude Desktop 会要求输入 Personal Access Token（作为敏感值保存），并可设置 `GITLAB_API_URL`、`GITLAB_PERMISSION_MODE`、`GITLAB_TOOLSETS` 和 `GITLAB_MASKING_ENABLED`。无需另外安装 Node.js 或 npm。
+
+如需从源码构建 bundle，运行 `npm run pack:mcpb`（生成 `gitlab-mcp.mcpb`）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 

package/build/index.js

@@ -109,6 +109,7 @@ import { buildBulkPublishDraftNotesBody, needsGitLab19_2BulkPublish, } from "./u
 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 { parseSearchReplaceBlocks, applySearchReplace, applyUnifiedDiff, } from "./utils/patch-helper.js";
+import { zodSchemaFor } from "./utils/schema.js";
 import { GitLabClientPool } from "./gitlab-client-pool.js";
 import { advertisesReadOnly, allTools, readOnlyTools, destructiveTools, deleteTools, parseEnabledToolsets, parseIndividualTools, buildFeatureFlagOverrides, isToolInEnabledToolset, findSmallestToolsetForTool, isExplicitOnlyToolsetId, isExplicitToolsetOnlyTool, isToolsetFullyActive, listDiscoverableCategories, TOOLSET_DEFINITIONS, DISCOVERABLE_TOOLSET_IDS, } from "./tools/registry.js";
 import { executeGitLabApiRequestAsync, GitLabApiRequestHttpError, GitLabApiRequestInputError, } from "./tools/gitlab-api-request.js";
@@ -6362,6 +6363,74 @@ async function erasePipelineJob(projectId, jobId) {
 const TERMINAL_PIPELINE_STATUSES = new Set(["success", "failed", "canceled", "skipped", "manual"]);
 const TERMINAL_JOB_STATUSES = new Set(["success", "failed", "canceled", "skipped", "manual"]);
 const TERMINAL_REBASE_STATUSES = new Set(["finished"]);
+// GitLab accepts PUT .../rebase before Sidekiq starts the job. Until then, GET
+// with include_rebase_in_progress can still say rebase_in_progress=false and return
+// the pre-rebase sha (gitlab-org/gitlab-foss#57481). Recheck that snapshot a few
+// times, capped so the default 5s poll interval cannot stretch this into 15s.
+const REBASE_UNCHANGED_HEAD_RECHECK_LIMIT = 3;
+const REBASE_UNCHANGED_HEAD_RECHECK_INTERVAL_CAP_MS = 1000;
+function rebaseHeadMoved(previous, current) {
+    return current.sha !== previous.sha;
+}
+function rebaseFailureExplained(previous, current) {
+    const mergeError = current.merge_error;
+    if (typeof mergeError !== "string" || mergeError.length === 0) {
+        return false;
+    }
+    return mergeError !== previous.merge_error;
+}
+function delayForRebasePoll(delayMs) {
+    return new Promise(resolve => {
+        setTimeout(resolve, delayMs);
+    });
+}
+async function getMergeRequestRebaseStatusBeforeDeadline(projectId, mergeRequestIid, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        throw new Error("Timed out waiting for terminal status");
+    }
+    return getMergeRequestRebaseStatus(projectId, mergeRequestIid, AbortSignal.timeout(remaining));
+}
+/**
+ * Poll until a rebase finishes, without trusting a finished snapshot that still
+ * has the pre-rebase sha and no new merge_error. A later rebase_in_progress true
+ * means the job did start, so wait for that terminal status as usual. Rechecks
+ * share the caller's timeout and never add time beyond it.
+ */
+async function waitForMergeRequestRebase(projectId, mergeRequestIid, previous, timeoutSeconds = 300, pollIntervalSeconds = 5) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let snapshot = await getMergeRequestRebaseStatusBeforeDeadline(projectId, mergeRequestIid, deadline);
+    let rechecksRemaining = REBASE_UNCHANGED_HEAD_RECHECK_LIMIT;
+    while (true) {
+        if (!TERMINAL_REBASE_STATUSES.has(snapshot.status)) {
+            rechecksRemaining = 0;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                break;
+            }
+            await delayForRebasePoll(Math.min(pollIntervalSeconds * 1000, remaining));
+            snapshot = await getMergeRequestRebaseStatusBeforeDeadline(projectId, mergeRequestIid, deadline);
+            continue;
+        }
+        const mergeRequest = snapshot.mergeRequest;
+        if (rebaseHeadMoved(previous, mergeRequest) || rebaseFailureExplained(previous, mergeRequest)) {
+            return mergeRequest;
+        }
+        if (rechecksRemaining <= 0) {
+            return mergeRequest;
+        }
+        const remaining = deadline - Date.now();
+        const delay = Math.min(pollIntervalSeconds * 1000, REBASE_UNCHANGED_HEAD_RECHECK_INTERVAL_CAP_MS, remaining);
+        // The next poll has to land inside the timeout. If one full backoff does not fit, stop.
+        if (remaining <= 0 || delay >= remaining) {
+            return mergeRequest;
+        }
+        rechecksRemaining -= 1;
+        await delayForRebasePoll(delay);
+        snapshot = await getMergeRequestRebaseStatusBeforeDeadline(projectId, mergeRequestIid, deadline);
+    }
+    throw new Error(`Timed out waiting for terminal status; last status: ${snapshot.status}`);
+}
 async function waitForStatus(fetchStatus, terminalStatuses, timeoutSeconds = 300, pollIntervalSeconds = 5) {
     const deadline = Date.now() + timeoutSeconds * 1000;
     const fetchBeforeDeadline = async () => {
@@ -8764,12 +8833,19 @@ async function handleToolCall(params) {
             }
             case "rebase_merge_request": {
                 const { project_id, merge_request_iid, skip_ci, wait, timeout_seconds, poll_interval_seconds, } = RebaseMergeRequestSchema.parse(params.arguments);
-                const enqueued = await rebaseMergeRequest(project_id, merge_request_iid, skip_ci);
                 if (!wait) {
+                    const enqueued = await rebaseMergeRequest(project_id, merge_request_iid, skip_ci);
                     return { content: [{ type: "text", text: JSON.stringify(enqueued) }] };
                 }
-                const { mergeRequest } = await waitForStatus(signal => getMergeRequestRebaseStatus(project_id, merge_request_iid, signal), TERMINAL_REBASE_STATUSES, timeout_seconds, poll_interval_seconds);
-                return { content: [{ type: "text", text: JSON.stringify(mergeRequest) }] };
+                const { mergeRequest: previous } = await getMergeRequestRebaseStatus(project_id, merge_request_iid);
+                await rebaseMergeRequest(project_id, merge_request_iid, skip_ci);
+                const mergeRequest = await waitForMergeRequestRebase(project_id, merge_request_iid, previous, timeout_seconds, poll_interval_seconds);
+                const rebaseResult = {
+                    ...mergeRequest,
+                    previous_sha: previous.sha,
+                    head_changed: rebaseHeadMoved(previous, mergeRequest),
+                };
+                return { content: [{ type: "text", text: JSON.stringify(rebaseResult) }] };
             }
             case "get_merge_request_approval_state": {
                 const args = GetMergeRequestApprovalStateSchema.parse(params.arguments);
@@ -11328,9 +11404,17 @@ async function handleToolCall(params) {
         // Sensitive fields are also covered by REDACT_PATHS if arguments are logged elsewhere.
         logger.debug({ tool: params.name }, "Tool call failed");
         if (error instanceof z.ZodError) {
-            throw new Error(`Invalid arguments: ${error.issues
-                .map(e => `${e.path.join(".")}: ${e.message}`)
-                .join(", ")}`);
+            const detail = error.issues
+                .map(e => (e.path.length > 0 ? `${e.path.join(".")}: ${e.message}` : e.message))
+                .join("; ");
+            // Response schemas throw ZodError too. If the arguments pass the tool's own
+            // schema, the failure came from parsing a GitLab response.
+            const argsSchema = zodSchemaFor(allTools.find(tool => tool.name === params.name)?.inputSchema);
+            if (argsSchema?.safeParse(params.arguments).success) {
+                throw new Error(`Unexpected GitLab response for ${params.name}: ${detail}`);
+            }
+            // ToolInputError is returned as an isError tool result, so the model can fix and retry.
+            throw new ToolInputError(`Invalid arguments for ${params.name}: ${detail}`);
         }
         throw error;
     }

package/build/tools/tool-descriptions.js

@@ -2,7 +2,7 @@ const TOOL_GUIDANCE = {
     merge_merge_request: "Use this only after checking the merge request approval, conflict, and pipeline state; use `approve_merge_request` to approve rather than merge. The operation changes repository state and may squash commits, schedule auto-merge, or delete the source branch, so it requires merge permission and returns GitLab's merge result or a mergeability error. Pass `sha` from `get_merge_request` (`sha` or `diff_refs.head_sha`); GitLab 19.2+ groups may reject merges without it.",
     approve_merge_request: "Use this to record an approval on an existing merge request; it does not merge the request or change its source branch. The operation changes review state, may require re-authentication or approval permission, and returns the updated approval result or a permission/state error.",
     unapprove_merge_request: "Use this to remove the current user's approval from an existing merge request; use `merge_merge_request` only when you intend to merge. The operation changes review state and requires approval permission, and GitLab returns the updated result or an error when the request or approval is unavailable.",
-    rebase_merge_request: "Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request: GitLab reports a failed rebase in `merge_error`, but that field can also keep a message from an earlier attempt, so compare `sha` with its value before the rebase. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.",
+    rebase_merge_request: "Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request plus `previous_sha` (its `sha` before the rebase) and `head_changed`. `head_changed: false` means that the head did not move; `merge_error` gives the reason when GitLab sends one. `merge_error` can keep a message from an earlier attempt, so it alone does not prove that this attempt failed. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.",
     get_merge_request_approval_state: "Use this to inspect approval rules and approvers before deciding whether a merge request can be merged; use `approve_merge_request` to change approval state. It is read-only and returns the approval-state response, while missing requests, unsupported GitLab versions, and permission failures are reported as errors.",
     get_merge_request_conflicts: "Use this to inspect merge conflicts before attempting `merge_merge_request`; it reports conflicts and does not resolve them. It is read-only, requires access to the project and merge request, and returns GitLab's conflict data or an error when the request cannot be evaluated.",
     list_merge_request_pipelines: "Use this to inspect pipelines associated with one merge request; use `list_pipelines` for project-wide pipeline filtering. It is read-only and paginated, requires project access, and returns pipeline records or GitLab errors for invalid identifiers, missing resources, or rate limits.",

package/build/utils/schema.js

@@ -1,4 +1,10 @@
 import { z } from "zod";
+// JSON Schema produced by toJSONSchema -> the Zod schema it came from.
+const zodSchemaByJsonSchema = new WeakMap();
+/**
+ * Returns the Zod schema a toJSONSchema() result was built from, if any.
+ */
+export const zodSchemaFor = (jsonSchema) => jsonSchema && typeof jsonSchema === "object" ? zodSchemaByJsonSchema.get(jsonSchema) : undefined;
 /**
  * Convert a Zod schema to JSON Schema, fixing nullable/optional fields
  * so they are not marked as required, and extracting required fields from the Zod schema.
@@ -154,5 +160,6 @@ export const toJSONSchema = (schema) => {
             }
         }
     }
+    zodSchemaByJsonSchema.set(fixedSchema, schema);
     return fixedSchema;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "mcpName": "io.github.zereight/gitlab-mcp",
   "description": "GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more",
   "keywords": [
@@ -69,6 +69,7 @@
     "lint:fix": "eslint . --fix",
     "release": "bash scripts/release.sh",
     "release:mcp-registry": "bash scripts/publish_mcp_registry.sh",
+    "pack:mcpb": "npm run build && bash scripts/pack-mcpb.sh",
     "format": "prettier --write \"**/*.{js,ts,json,md}\"",
     "format:check": "prettier --check \"**/*.{js,ts,json,md}\""
   },