@zereight/mcp-gitlab 2.1.63 → 2.1.65

package/build/utils/tool-args.js

@@ -20,6 +20,41 @@ export function sanitizeToolArguments(toolName, args) {
     }
     return result;
 }
+/**
+ * Drop blank string entries inside array filters so ["", "bug"] behaves like the scalar blank guard.
+ */
+export function dropBlankArrayEntries(value) {
+    if (!Array.isArray(value)) {
+        return value;
+    }
+    return value.filter(item => !(typeof item === "string" && item.trim() === ""));
+}
+/**
+ * Blank filters must be omitted entirely instead of being serialized as empty query parameters
+ * such as `labels=`, `labels[]=` or `iids=`.
+ */
+export function isBlankFilterValue(value) {
+    return (value === undefined ||
+        (typeof value === "string" && value.trim() === "") ||
+        (Array.isArray(value) && value.length === 0));
+}
+/**
+ * Append one query parameter, skipping blank filters and blank entries inside arrays.
+ * Booleans serialize as `true`/`false`, matching the inline branches this replaces.
+ */
+export function appendFilterParam(searchParams, key, value) {
+    const normalized = dropBlankArrayEntries(value);
+    if (isBlankFilterValue(normalized)) {
+        return;
+    }
+    searchParams.append(key, String(normalized));
+}
+/** Append every option as a query parameter while dropping blank filters. */
+export function appendFilterParams(searchParams, options) {
+    for (const [key, value] of Object.entries(options)) {
+        appendFilterParam(searchParams, key, value);
+    }
+}
 /** Pairs where GitLab rejects sending both *_id and *_username query params. */
 export const LIST_ISSUES_ID_USERNAME_PAIRS = [
     ["author_id", "author_username"],
@@ -29,11 +64,20 @@ export const LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS = [
     ...LIST_ISSUES_ID_USERNAME_PAIRS,
     ["reviewer_id", "reviewer_username"],
 ];
+/**
+ * Whether a username filter actually selects anything.
+ *
+ * Judged with the same helpers the list query serializers use, so the two agree: a blank
+ * value is not a value. Treating `[""]` or `"  "` as one here would drop the id filter and
+ * then have the blank guard drop the username too, leaving no filter at all.
+ */
 function hasUsernameFilterValue(value) {
-    if (Array.isArray(value)) {
-        return value.length > 0;
+    // null never reaches here from tools (sanitizeToolArguments strips it);
+    // keep the old Boolean(null) === false behavior.
+    if (value === null) {
+        return false;
     }
-    return Boolean(value);
+    return !isBlankFilterValue(dropBlankArrayEntries(value));
 }
 /**
  * When both id and username filters are set, GitLab returns 400. Prefer username and drop id.

package/build/utils/url.js

@@ -17,3 +17,105 @@ export function normalizeGitLabApiUrl(url) {
     }
     return normalizedUrl;
 }
+/**
+ * Dot segments anywhere in a decoded value, including after a percent-encoded
+ * separator ("..%2F..%2Fuser" decodes to a path-traversal sequence).
+ */
+const DOT_SEGMENT_PATTERN = /(^|[\\/])\.\.?([\\/]|$)/;
+/** A decoded value that starts with a path separator (absolute-path payload). */
+const LEADING_SEPARATOR_PATTERN = /^[\\/]/;
+/** NUL, newline and the other control characters: never valid in a path segment. */
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+/**
+ * How many times a value is percent-decoded before the checks run. A payload can be
+ * encoded more than once ("%252E%252E%252Fuser" only becomes "../user" after two
+ * decodes), so the checks run on the form the receiving server may eventually see.
+ */
+const MAX_DECODE_PASSES = 5;
+const INVALID_SEGMENT_MESSAGE = "Cannot use value as a GitLab URL path segment: it is or decodes to a '.'/'..' path segment, " +
+    "a control character such as NUL, or an absolute path";
+const INVALID_PATH_MESSAGE = "Cannot use value as a GitLab URL path: it is empty or it has an empty, leading or trailing segment";
+/**
+ * A percent escape that actually decodes to a byte: `%` followed by two hex digits.
+ *
+ * `decodeURIComponent` also throws for a `%` that starts no escape, and a literal
+ * percent sign is valid in a file or branch name ("report-100%.pdf"), so the two
+ * failures have to be told apart before either is treated as a broken payload.
+ */
+const VALID_ESCAPE_PATTERN = /%[0-9a-fA-F]{2}/;
+/**
+ * Percent-decode a value until decoding stops changing it.
+ *
+ * Returns null when the value cannot be reduced to a form that can be validated:
+ * a malformed escape next to a valid one, or more encoding layers than
+ * {@link MAX_DECODE_PASSES}. A guard must not treat "could not inspect the value"
+ * as "safe", so both cases are rejected by the callers rather than passed through.
+ *
+ * A `%` that starts no valid escape is a literal character instead: the value is
+ * returned as it is and the encoder turns the sign into `%25`, so
+ * `get_file_contents("report-100%.pdf")` keeps working. Only a value that mixes a
+ * real escape with a broken one cannot be inspected, and that form is rejected.
+ */
+function decodeFully(value) {
+    let current = value;
+    for (let pass = 0; pass < MAX_DECODE_PASSES; pass++) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(current);
+        }
+        catch {
+            // Undecodable. With a valid escape left in it the value cannot be inspected
+            // reliably (the escape may still hide a separator or a dot segment), so it
+            // fails closed; without one every `%` is literal and `current` — already
+            // decoded as far as it can be — is the form the server will see.
+            return VALID_ESCAPE_PATTERN.test(current) ? null : current;
+        }
+        if (decoded === current) {
+            return current;
+        }
+        current = decoded;
+    }
+    return null;
+}
+/**
+ * Encode a single value for use as one GitLab URL path segment.
+ *
+ * Rejects values that are, decode to, or start with dot segments or an absolute
+ * path, so a caller-supplied id cannot escape the intended route prefix.
+ * Percent-encoded separators are decoded before the check because the receiving
+ * server may treat them as separators; a value may be encoded any number of times
+ * and is still validated in its fully decoded form.
+ *
+ * @throws {Error} when the value is a dot segment, contains one, contains a control
+ * character, starts with a separator, or is not valid percent-encoding
+ */
+export function encodeGitLabPathSegment(value) {
+    const segment = String(value);
+    const decodedSegment = decodeFully(segment);
+    if (decodedSegment === null ||
+        DOT_SEGMENT_PATTERN.test(decodedSegment) ||
+        LEADING_SEPARATOR_PATTERN.test(decodedSegment) ||
+        CONTROL_CHARACTER_PATTERN.test(decodedSegment)) {
+        throw new Error(INVALID_SEGMENT_MESSAGE);
+    }
+    return encodeURIComponent(decodedSegment);
+}
+/**
+ * Encode a slash-separated path so each segment is encoded and validated
+ * individually. Legitimate encoded separators (for example a tag such as
+ * "release%2F1.0") stay allowed; dot segments are rejected.
+ *
+ * An empty path, or one with an empty, leading or trailing segment, is rejected
+ * rather than silently collapsed: `"/etc/passwd"` would otherwise encode to a
+ * leading-separator path instead of the intended relative one.
+ *
+ * @throws {Error} when the path is empty or has an empty segment, or when any
+ * segment is a dot segment or contains one
+ */
+export function encodeGitLabPath(value) {
+    const segments = value.split("/");
+    if (segments.some(segment => segment === "")) {
+        throw new Error(INVALID_PATH_MESSAGE);
+    }
+    return segments.map(encodeGitLabPathSegment).join("/");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.1.63",
+  "version": "2.1.65",
   "mcpName": "io.github.zereight/gitlab-mcp",
   "description": "GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more",
   "keywords": [
@@ -65,6 +65,7 @@
     "lint": "eslint . --ext .ts",
     "check:runtime-deps": "node scripts/check-runtime-deps.mjs",
     "check:skill-sync": "tsx scripts/check-skill-sync.ts",
+    "docs:tools": "tsx scripts/generate-tool-docs.ts && tsx scripts/generate-tool-coverage.ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "release": "bash scripts/release.sh",
     "release:mcp-registry": "bash scripts/publish_mcp_registry.sh",