@zereight/mcp-gitlab 2.1.43 → 2.1.44

package/README.ko.md

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

package/README.md

@@ -82,7 +82,7 @@ npm install -g @zereight/mcp-gitlab
 
 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.42`. 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.43`. 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)
 
@@ -700,7 +700,7 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
 156. `list_group_iterations` - List group iterations with filtering options
 157. `upload_markdown` - Upload a file to a GitLab project for use in markdown content
 158. `download_attachment` - Download an uploaded file from a GitLab project by secret and filename
-159. `health_check` - Verify server status and authentication
+159. `health_check` - Verify server status and authentication; when authenticated, reports GitLab instance version from `/api/v4/version` (`version`, `revision`, `enterprise`)
 160. `list_events` - List all events for the currently authenticated user
 161. `get_project_events` - List all visible events for a specified project
 162. `list_releases` - List all releases for a project

package/README.zh-CN.md

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

package/build/index.js

@@ -91,6 +91,7 @@ import { resolveNestedWikiUpdateTitle } from "./utils/wiki-title.js";
 import { redactSensitiveGitLabFields } from "./utils/redact-sensitive.js";
 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 { parseSearchReplaceBlocks, applySearchReplace, applyUnifiedDiff, } from "./utils/patch-helper.js";
@@ -4391,7 +4392,7 @@ async function publishDraftNote(projectId, mergeRequestIid, draftNoteId) {
         };
     }
 }
-async function fetchGitLabInstanceVersion() {
+async function fetchGitLabVersionMetadata() {
     try {
         const response = await fetch(`${getEffectiveApiUrl()}/version`, {
             ...getFetchConfig(),
@@ -4399,18 +4400,16 @@ async function fetchGitLabInstanceVersion() {
         if (!response.ok)
             return null;
         const data = await response.json();
-        if (typeof data === "object" &&
-            data !== null &&
-            "version" in data &&
-            typeof data.version === "string") {
-            return data.version;
-        }
-        return null;
+        return parseGitLabVersionApiResponse(data);
     }
     catch {
         return null;
     }
 }
+async function fetchGitLabInstanceVersion() {
+    const metadata = await fetchGitLabVersionMetadata();
+    return metadata?.version ?? null;
+}
 /**
  * Publish all draft notes for a merge request
  * @param {string} projectId - The ID or URL-encoded path of the project
@@ -9339,6 +9338,9 @@ async function handleToolCall(params) {
                     const jobResponse = await fetch(jobUrl.toString(), getFetchConfig());
                     authenticated = jobResponse.ok;
                 }
+                const versionMetadata = authenticated
+                    ? await fetchGitLabVersionMetadata()
+                    : null;
                 return {
                     content: [
                         {
@@ -9347,6 +9349,7 @@ async function handleToolCall(params) {
                                 status: authenticated ? "ok" : "error",
                                 authenticated,
                                 gitlab_url: getEffectiveApiUrl(),
+                                ...(versionMetadata ?? {}),
                             }),
                         },
                     ],

package/build/test/test-health-check.js

@@ -0,0 +1,106 @@
+import { describe, test } from "node:test";
+import assert from "node:assert";
+import { spawn } from "child_process";
+import { MockGitLabServer, findMockServerPort } from "./utils/mock-gitlab-server.js";
+const MOCK_TOKEN = "glpat-mock-token-12345";
+function createMockGitLabServer(port) {
+    return new MockGitLabServer({
+        port,
+        validTokens: [MOCK_TOKEN],
+    });
+}
+function baseEnv(mockGitLabUrl) {
+    return {
+        GITLAB_API_URL: `${mockGitLabUrl}/api/v4`,
+        GITLAB_PERSONAL_ACCESS_TOKEN: MOCK_TOKEN,
+        GITLAB_TOOLSETS: "projects",
+    };
+}
+async function callHealthCheckAsync(env) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("node", ["build/index.js"], {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                ...env,
+                USE_PIPELINE: "true",
+            },
+        });
+        let output = "";
+        let errorOutput = "";
+        proc.stdout?.on("data", (chunk) => (output += chunk));
+        proc.stderr?.on("data", (chunk) => (errorOutput += chunk));
+        proc.on("close", code => {
+            if (code !== 0) {
+                return reject(new Error(`Process exited with code ${code}: ${errorOutput}`));
+            }
+            const line = output.split("\n").find(entry => entry.startsWith("{"));
+            if (!line) {
+                return reject(new Error("No JSON output found"));
+            }
+            try {
+                const response = JSON.parse(line);
+                if (response.error) {
+                    reject(response.error);
+                    return;
+                }
+                const content = response.result?.content?.[0]?.text;
+                if (!content) {
+                    reject(new Error("No tool result content"));
+                    return;
+                }
+                resolve(JSON.parse(content));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        proc.stdin?.end(JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: { name: "health_check", arguments: {} },
+        }) + "\n");
+    });
+}
+describe("When health_check runs", () => {
+    describe("with authenticated mock GitLab", () => {
+        test("should include GitLab instance version metadata", async () => {
+            const mockPort = await findMockServerPort();
+            const mockGitLab = createMockGitLabServer(mockPort);
+            await mockGitLab.start();
+            try {
+                const result = await callHealthCheckAsync(baseEnv(mockGitLab.getUrl()));
+                assert.equal(result.status, "ok");
+                assert.equal(result.authenticated, true);
+                assert.equal(result.version, "18.3.1-ee");
+                assert.equal(result.revision, "abc1234");
+                assert.equal(result.enterprise, true);
+            }
+            finally {
+                await mockGitLab.stop();
+            }
+        });
+    });
+    describe("when GitLab /version lookup fails", () => {
+        test("should keep health check ok without version fields", async () => {
+            const mockPort = await findMockServerPort();
+            const mockGitLab = createMockGitLabServer(mockPort);
+            mockGitLab.addMockHandler("get", "/version", (_req, res) => {
+                res.status(500).json({ message: "version unavailable" });
+            });
+            await mockGitLab.start();
+            try {
+                const result = await callHealthCheckAsync(baseEnv(mockGitLab.getUrl()));
+                assert.equal(result.status, "ok");
+                assert.equal(result.authenticated, true);
+                assert.equal("version" in result, false);
+                assert.equal("revision" in result, false);
+                assert.equal("enterprise" in result, false);
+            }
+            finally {
+                await mockGitLab.stop();
+            }
+        });
+    });
+});

package/build/test/utils/gitlab-instance-version.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { parseGitLabVersionApiResponse } from "../../utils/gitlab-instance-version.js";
+describe("When parseGitLabVersionApiResponse runs", () => {
+    describe("with a full GitLab /version payload", () => {
+        test("should return version, revision, and enterprise", () => {
+            assert.deepEqual(parseGitLabVersionApiResponse({
+                version: "18.3.1-ee",
+                revision: "abc1234",
+                enterprise: true,
+            }), {
+                version: "18.3.1-ee",
+                revision: "abc1234",
+                enterprise: true,
+            });
+        });
+    });
+    describe("with only a version field", () => {
+        test("should return version without optional fields", () => {
+            assert.deepEqual(parseGitLabVersionApiResponse({ version: "17.5.0" }), {
+                version: "17.5.0",
+            });
+        });
+    });
+    describe("with invalid payloads", () => {
+        test("should return null", () => {
+            assert.equal(parseGitLabVersionApiResponse(null), null);
+            assert.equal(parseGitLabVersionApiResponse({}), null);
+            assert.equal(parseGitLabVersionApiResponse({ version: 18 }), null);
+        });
+    });
+});

package/build/test/utils/mock-gitlab-server.js

@@ -150,6 +150,14 @@ export class MockGitLabServer {
                 state: "active",
             });
         });
+        // GET /api/v4/version - GitLab instance version
+        this.app.get("/api/v4/version", (_req, res) => {
+            res.json({
+                version: "18.3.1-ee",
+                revision: "abc1234",
+                enterprise: true,
+            });
+        });
         // GET /api/v4/projects/:projectId - Get project
         this.app.get("/api/v4/projects/:projectId", (req, res) => {
             const projectId = req.params.projectId;

package/build/tools/registry.js

@@ -813,7 +813,7 @@ export const allTools = [
     },
     {
         name: "health_check",
-        description: "Verify server status and authentication",
+        description: "Verify server status and authentication. When authenticated, also reports the GitLab instance version from GET /api/v4/version (version, revision, enterprise). Version lookup failures do not fail the health check — those fields are omitted.",
         inputSchema: toJSONSchema(HealthCheckSchema),
     },
     {

package/build/utils/gitlab-instance-version.js

@@ -0,0 +1,16 @@
+export function parseGitLabVersionApiResponse(data) {
+    if (typeof data !== "object" || data === null || !("version" in data)) {
+        return null;
+    }
+    if (typeof data.version !== "string") {
+        return null;
+    }
+    const metadata = { version: data.version };
+    if ("revision" in data && typeof data.revision === "string") {
+        metadata.revision = data.revision;
+    }
+    if ("enterprise" in data && typeof data.enterprise === "boolean") {
+        metadata.enterprise = data.enterprise;
+    }
+    return metadata;
+}

package/package.json

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