@zereight/mcp-gitlab 2.1.65 → 2.1.67

package/README.ko.md

@@ -24,6 +24,7 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
 - **여러 전송 방식** — 로컬 클라이언트용 stdio, 레거시 클라이언트용 SSE, 최신 원격 배포용 Streamable HTTP
 - **클라이언트 친화적 설정** — Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, Amp Code 예시 제공
 - **셀프 호스팅 대응** — 커스텀 GitLab 인스턴스, 프록시 설정, 동적 API URL 라우팅 지원
+- **JMESPath 결과 필터링** — 도구 호출에 선택적 `jmespath` 인자(`tools/list` 참고)를 넘기면 GitLab API 요청은 그대로 두고 JSON 결과만 줄여서 반환; 응답 마스킹이 켜져 있으면 마스킹된 데이터에 JMESPath가 적용됨
 
 ### 비교 요약
 
@@ -110,7 +111,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.64`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.66`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
 
 #### CLI 인자 사용하기(환경 변수 문제가 있는 클라이언트용)
 

package/README.md

@@ -29,6 +29,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
 - **Multiple transports** — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
 - **Client-friendly setup** — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
 - **Self-hosted ready** — works with custom GitLab instances, proxy settings, and dynamic API URL routing
+- **JMESPath result filtering** — optional `jmespath` on tool calls (see `tools/list`) shrinks JSON results without changing GitLab API requests; when response masking is enabled, JMESPath runs on masked data.
 
 ### How we compare
 
@@ -115,7 +116,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.64`. 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.66`. 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

@@ -24,6 +24,7 @@
 - **多种传输方式** — 本地客户端使用 stdio，旧客户端使用 SSE，现代远程部署使用 Streamable HTTP
 - **客户端设置友好** — 提供 Claude Code、Codex、Antigravity、OpenCode、Copilot、Cline、Roo Code、Cursor、Kilo Code 和 Amp Code 示例
 - **适合自托管** — 支持自定义 GitLab 实例、代理设置和动态 API URL 路由
+- **JMESPath 结果过滤** — 在工具调用中传入可选的 `jmespath` 参数（见 `tools/list`），可在不改变 GitLab API 请求的情况下精简 JSON 结果；启用响应掩码时，JMESPath 作用于掩码后的数据
 
 ### 对比摘要
 
@@ -110,7 +111,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.64`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.66`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 

package/build/index.js

@@ -102,6 +102,7 @@ import { fetchWithValidatedRedirects } from "./utils/safe-redirect-fetch.js";
 import { parseGitLabVersionApiResponse, } from "./utils/gitlab-instance-version.js";
 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 { 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";
@@ -289,6 +290,18 @@ function createServer() {
                     },
                 };
             }
+            if (modified.inputSchema && typeof modified.inputSchema === "object") {
+                const properties = modified.inputSchema.properties && typeof modified.inputSchema.properties === "object"
+                    ? { ...modified.inputSchema.properties }
+                    : {};
+                if (!(JMESPATH_TOOL_ARGUMENT in properties)) {
+                    properties[JMESPATH_TOOL_ARGUMENT] = {
+                        type: "string",
+                        description: JMESPATH_TOOL_ARGUMENT_DESCRIPTION,
+                    };
+                    modified.inputSchema = { ...modified.inputSchema, properties };
+                }
+            }
             return modified;
         });
         // <<< END: Remove $schema for Gemini compatibility >>>
@@ -303,15 +316,24 @@ function createServer() {
         const toolName = request.params.name;
         const start = Date.now();
         let maskingEngine;
-        const logCompletion = (result) => {
+        const jmespathExpression = readJmespathExpression(request.params.arguments);
+        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(result, jmespathExpression, {
+                ...completionOptions,
+                maskValue: maskingEngine
+                    ? (value) => maskingEngine.maskValue(value)
+                    : undefined,
+            });
             return maskingEngine
-                ? maskingEngine.maskToolResult(result, { textFormat: isPlainTextResult ? "plain" : "json" })
-                : result;
+                ? maskingEngine.maskToolResult(filtered, {
+                    textFormat: isPlainTextResult ? "plain" : "json",
+                })
+                : filtered;
         };
         const logError = (error) => {
             const durationMs = Date.now() - start;
@@ -370,6 +392,12 @@ function createServer() {
             maskingEngine = sessionContext
                 ? sessionAuthStore.run(sessionContext, selectMaskingPolicy)
                 : selectMaskingPolicy();
+            const jmespathSyntaxError = jmespathExpression
+                ? getJmespathSyntaxError(jmespathExpression)
+                : undefined;
+            if (jmespathSyntaxError) {
+                return logCompletion({ content: [{ type: "text", text: jmespathSyntaxError }], isError: true }, { skipJmespath: true });
+            }
             // Handle discover_tools meta-tool directly (needs access to mcpServer and filteredTools)
             if (toolName === "discover_tools") {
                 const category = request.params.arguments?.category?.trim()?.toLowerCase();
@@ -477,12 +505,15 @@ function createServer() {
                                 text: `Tool "${toolName}" requires confirmation. This tool is marked as requiring approval before execution. Re-call with _confirmed: true to proceed.`,
                             },
                         ],
-                    });
+                    }, { skipJmespath: true });
                 }
                 // Strip _confirmed from args before forwarding to handler
                 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);
+            }
             if (sessionContext) {
                 // Policy selection and the tool handler must use the same request-local
                 // API URL and project allowlist.

package/build/schemas.js

@@ -1355,6 +1355,9 @@ export const GitLabDiffSchema = z.object({
     new_file: z.coerce.boolean(),
     renamed_file: z.coerce.boolean(),
     deleted_file: z.coerce.boolean(),
+    generated_file: z.coerce.boolean().optional(),
+    too_large: z.coerce.boolean().optional(),
+    collapsed: z.coerce.boolean().optional(),
 });
 // Response schemas for operations
 export const GitLabCreateUpdateFileResponseSchema = z.object({

package/build/test/gitlab-diff-schema.test.js

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { GitLabDiffSchema } from "../schemas.js";
+test("diff schema keeps GitLab's generated_file, too_large and collapsed flags", () => {
+    const parsed = GitLabDiffSchema.parse({
+        diff: "@@ -1 +1 @@",
+        new_path: "src/Foo.php",
+        old_path: "src/Foo.php",
+        a_mode: "100644",
+        b_mode: "100644",
+        new_file: false,
+        renamed_file: false,
+        deleted_file: false,
+        generated_file: true,
+        too_large: true,
+        collapsed: false,
+    });
+    assert.equal(parsed.generated_file, true);
+    assert.equal(parsed.too_large, true);
+    assert.equal(parsed.collapsed, false);
+});
+test("diff schema still parses entries without the optional flags", () => {
+    const parsed = GitLabDiffSchema.parse({
+        diff: "@@ -1 +1 @@",
+        new_path: "src/Foo.php",
+        old_path: "src/Foo.php",
+        a_mode: "100644",
+        b_mode: "100644",
+        new_file: false,
+        renamed_file: false,
+        deleted_file: false,
+    });
+    assert.equal("generated_file" in parsed, false);
+    assert.equal("too_large" in parsed, false);
+    assert.equal("collapsed" in parsed, false);
+});

package/build/test/response-masking.test.js

@@ -188,6 +188,39 @@ describe("managed response masking at the MCP boundary", { timeout: 30_000 }, ()
             "/api/v4/projects/12/merge_requests",
         ]);
     });
+    test("applies jmespath to JSON tool results at the MCP boundary", async (t) => {
+        const { client } = await startMaskingServer(t, {
+            env: { ENABLE_STRICT_PROJECT_SCOPE: "true", GITLAB_ALLOWED_PROJECT_IDS: "12" },
+        });
+        const { tools } = await client.listTools();
+        const listMrs = tools.find(tool => tool.name === "list_merge_requests");
+        const jmespathSchema = listMrs?.inputSchema?.properties?.jmespath;
+        assert.ok(jmespathSchema, "tools/list should inject optional jmespath on every tool schema");
+        assert.ok((jmespathSchema.description?.length ?? 0) < 120, "jmespath schema description should stay short for tools/list token cost");
+        const result = await client.callTool({
+            name: "list_issues",
+            arguments: { jmespath: "[].title" },
+        });
+        const text = result.content[0]?.text;
+        assert.deepEqual(JSON.parse(text), ["[one]"]);
+        const probe = await client.callTool({
+            name: "list_issues",
+            arguments: { jmespath: "[].starts_with(title, `ProjectOne`)" },
+        });
+        const probeText = probe.content[0]?.text;
+        assert.deepEqual(JSON.parse(probeText), [false], "jmespath must run on masked JSON so callers cannot probe hidden substrings");
+    });
+    test("rejects invalid jmespath before the handler reaches GitLab", async (t) => {
+        const { client, requests } = await startMaskingServer(t, {
+            env: { ENABLE_STRICT_PROJECT_SCOPE: "true", GITLAB_ALLOWED_PROJECT_IDS: "12" },
+        });
+        const result = await client.callTool({
+            name: "list_issues",
+            arguments: { jmespath: "[[[" },
+        });
+        assert.equal(result.isError, true);
+        assert.deepEqual(requests, []);
+    });
     test("keeps optional default-project handlers available with their managed policy", async (t) => {
         const { client, requests } = await startMaskingServer(t);
         const fileResult = await client.callTool({

package/build/test/utils/jmespath-tool-result.test.js

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { applyJmespathFilter, applyJmespathToToolResult, getJmespathSyntaxError, omitJmespathArgument, readJmespathExpression, shouldApplyJmespathFilter, } from "../../utils/jmespath-tool-result.js";
+describe("jmespath tool result helpers", () => {
+    test("readJmespathExpression trims and rejects blank values", () => {
+        assert.equal(readJmespathExpression({ jmespath: "  [].title  " }), "[].title");
+        assert.equal(readJmespathExpression({ jmespath: "   " }), undefined);
+        assert.equal(readJmespathExpression({ jmespath: 1 }), undefined);
+    });
+    test("omitJmespathArgument removes MCP-only key", () => {
+        assert.deepEqual(omitJmespathArgument({ project_id: "1", jmespath: "[].id" }), {
+            project_id: "1",
+        });
+    });
+    test("applyJmespathFilter projects array fields", () => {
+        const data = [
+            { title: "a", description: "long" },
+            { title: "b", description: "longer" },
+        ];
+        assert.deepEqual(applyJmespathFilter(data, "[].title"), ["a", "b"]);
+    });
+    test("applyJmespathToToolResult filters JSON text content", () => {
+        const result = applyJmespathToToolResult({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify([{ title: "mr-one", iid: 1 }]),
+                },
+            ],
+        }, "[].title");
+        assert.equal(result.content[0].text, JSON.stringify(["mr-one"]));
+    });
+    test("applyJmespathToToolResult applies maskValue before JMESPath", () => {
+        const result = applyJmespathToToolResult({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify([{ title: "ProjectOneSecret" }]),
+                },
+            ],
+        }, "[].starts_with(title, `ProjectOne`)", {
+            maskValue: value => {
+                if (!Array.isArray(value))
+                    return value;
+                return value.map(entry => entry && typeof entry === "object" && "title" in entry
+                    ? { ...entry, title: "[one]" }
+                    : entry);
+            },
+        });
+        assert.deepEqual(JSON.parse(result.content[0].text), [false]);
+    });
+    test("shouldApplyJmespathFilter is false for isError and explicit skip", () => {
+        const errorResult = {
+            content: [{ type: "text", text: 'Unknown category "foo"' }],
+            isError: true,
+        };
+        assert.equal(shouldApplyJmespathFilter(errorResult, "[].title"), false);
+        assert.equal(shouldApplyJmespathFilter({ content: [{ type: "text", text: "requires confirmation" }] }, "[].title", { skipJmespath: true }), false);
+        assert.equal(shouldApplyJmespathFilter({ content: [{ type: "text", text: "[]" }] }, "[].title"), true);
+    });
+    test("applyJmespathToToolResult preserves isError tool results", () => {
+        const original = {
+            content: [{ type: "text", text: 'Unknown category "foo"' }],
+            isError: true,
+        };
+        assert.deepEqual(applyJmespathToToolResult(original, "[].title"), original);
+    });
+    test("applyJmespathToToolResult preserves approval-style plain text when skipJmespath", () => {
+        const original = {
+            content: [
+                {
+                    type: "text",
+                    text: 'Tool "create_issue" requires confirmation. Re-call with _confirmed: true to proceed.',
+                },
+            ],
+        };
+        assert.deepEqual(applyJmespathToToolResult(original, "[].title", { skipJmespath: true }), original);
+    });
+    test("applyJmespathToToolResult passes non-JSON success text through unchanged", () => {
+        const original = { content: [{ type: "text", text: "Created pipeline #1 for main." }] };
+        assert.deepEqual(applyJmespathToToolResult(original, "id"), original);
+    });
+    test("applyJmespathToToolResult returns the original result when evaluation fails", () => {
+        const original = { content: [{ type: "text", text: JSON.stringify({ title: 1 }) }] };
+        assert.deepEqual(applyJmespathToToolResult(original, "starts_with(title, `a`)"), original);
+    });
+    test("getJmespathSyntaxError rejects invalid expressions before execution", () => {
+        assert.match(getJmespathSyntaxError("[[[") ?? "", /Invalid jmespath expression/);
+        assert.equal(getJmespathSyntaxError("[].title"), undefined);
+    });
+});

package/build/utils/jmespath-tool-result.js

@@ -0,0 +1,78 @@
+import jmespath from "jmespath";
+/** MCP-only argument; stripped before GitLab handlers run (issue #766). */
+export const JMESPATH_TOOL_ARGUMENT = "jmespath";
+export const JMESPATH_TOOL_ARGUMENT_DESCRIPTION = "Optional JMESPath expression filtering the JSON result before return.";
+export function readJmespathExpression(args) {
+    if (!args)
+        return undefined;
+    const raw = args[JMESPATH_TOOL_ARGUMENT];
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/** Syntax check before the handler runs, so side-effecting tools never execute with a bad expression. */
+export function getJmespathSyntaxError(expression) {
+    try {
+        jmespath.compile(expression);
+        return undefined;
+    }
+    catch (error) {
+        return `Invalid jmespath expression: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+export function omitJmespathArgument(args) {
+    if (!(JMESPATH_TOOL_ARGUMENT in args))
+        return args;
+    const { [JMESPATH_TOOL_ARGUMENT]: _omit, ...rest } = args;
+    return rest;
+}
+export function applyJmespathFilter(data, expression) {
+    return jmespath.search(data, expression);
+}
+function isContentBlock(value) {
+    return Boolean(value && typeof value === "object");
+}
+function prepareDataForJmespath(data, maskValue) {
+    return maskValue ? maskValue(data) : data;
+}
+function parseJson(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** When false, return the tool result unchanged (masking still runs afterward). */
+export function shouldApplyJmespathFilter(result, expression, options) {
+    return Boolean(expression && !options?.skipJmespath && !result.isError);
+}
+/**
+ * Apply JMESPath to JSON serialized in text content blocks (and structuredContent when present).
+ * The handler has already run, so this never turns a result into an error: non-JSON text and
+ * evaluation failures return the original result.
+ */
+export function applyJmespathToToolResult(result, expression, options) {
+    if (!expression || !shouldApplyJmespathFilter(result, expression, options))
+        return result;
+    const maskValue = options?.maskValue;
+    const filter = (data) => applyJmespathFilter(prepareDataForJmespath(data, maskValue), expression);
+    try {
+        const content = Array.isArray(result.content)
+            ? result.content.map(block => {
+                if (!isContentBlock(block) || block.type !== "text" || typeof block.text !== "string") {
+                    return block;
+                }
+                const parsed = parseJson(block.text);
+                return parsed.ok ? { ...block, text: JSON.stringify(filter(parsed.value)) } : block;
+            })
+            : result.content;
+        return result.structuredContent === undefined
+            ? { ...result, content }
+            : { ...result, content, structuredContent: filter(result.structuredContent) };
+    }
+    catch {
+        return result;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.1.65",
+  "version": "2.1.67",
   "mcpName": "io.github.zereight/gitlab-mcp",
   "description": "GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more",
   "keywords": [
@@ -78,6 +78,7 @@
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.2",
     "fetch-cookie": "^3.1.0",
+    "jmespath": "^0.16.0",
     "open": "^10.2.0",
     "pino": "^9.7.0",
     "pino-pretty": "^13.0.0",
@@ -90,6 +91,7 @@
   },
   "devDependencies": {
     "@types/express": "^5.0.2",
+    "@types/jmespath": "^0.15.2",
     "@types/node": "^22.13.10",
     "@typescript-eslint/eslint-plugin": "^8.21.0",
     "@typescript-eslint/parser": "^8.21.0",