@zereight/mcp-gitlab 2.1.30 → 2.1.38

package/build/schemas.js

@@ -939,6 +939,12 @@ export const GitLabMilestonesSchema = z.object({
     expired: z.coerce.boolean(),
     web_url: z.string().optional(),
 });
+// Group milestones return group_id (not project_id)
+export const GitLabGroupMilestonesSchema = GitLabMilestonesSchema.omit({
+    project_id: true,
+}).extend({
+    group_id: z.coerce.string(),
+});
 // Input schemas for operations
 export const CreateRepositoryOptionsSchema = z.object({
     name: z.string(),
@@ -1026,6 +1032,7 @@ export const CreateBranchOptionsSchema = z.object({
     ref: z.string(), // The source branch/commit for the new branch
 });
 export const GitLabCompareResultSchema = z.object({
+    // GitLab may return null commit for empty/no-op compare ranges
     commit: z
         .object({
         id: z.string().optional(),
@@ -1035,6 +1042,7 @@ export const GitLabCompareResultSchema = z.object({
         author_email: z.string().optional(),
         created_at: z.string().optional(),
     })
+        .nullable()
         .optional(),
     commits: z.array(GitLabCommitSchema),
     diffs: z.array(GitLabDiffSchema),
@@ -1658,8 +1666,9 @@ export const UpdateDefaultBranchSchema = ProjectParamsSchema.extend({
 export const GitLabProtectedBranchAccessLevelSchema = z.object({
     access_level: z.number().nullable().optional(),
     access_level_description: z.string().optional(),
-    user_id: z.number().optional(),
-    group_id: z.number().optional(),
+    // GitLab returns null for role-based access levels (not user-/group-specific)
+    user_id: z.number().nullable().optional(),
+    group_id: z.number().nullable().optional(),
 });
 export const GitLabProtectedBranchSchema = z.object({
     id: z.number().optional(),
@@ -2672,13 +2681,70 @@ export const EditProjectMilestoneSchema = GetProjectMilestoneSchema.extend({
 // Schema for deleting a milestone
 export const DeleteProjectMilestoneSchema = GetProjectMilestoneSchema;
 // Schema for getting issues assigned to a milestone
-export const GetMilestoneIssuesSchema = GetProjectMilestoneSchema;
+export const GetMilestoneIssuesSchema = GetProjectMilestoneSchema.merge(PaginationOptionsSchema);
 // Schema for getting merge requests assigned to a milestone
 export const GetMilestoneMergeRequestsSchema = GetProjectMilestoneSchema.merge(PaginationOptionsSchema);
 // Schema for promoting a project milestone to a group milestone
 export const PromoteProjectMilestoneSchema = GetProjectMilestoneSchema;
 // Schema for getting burndown chart events for a milestone
 export const GetMilestoneBurndownEventsSchema = GetProjectMilestoneSchema.merge(PaginationOptionsSchema);
+// Group milestone schemas (mirror project milestones against /groups/:id/milestones)
+export const ListGroupMilestonesSchema = z
+    .object({
+    group_id: z.coerce.string().describe("Group ID or URL-encoded path"),
+    iids: z
+        .array(z.coerce.number())
+        .optional()
+        .describe("Return only the milestones having the given iid"),
+    state: z
+        .enum(["active", "closed"])
+        .optional()
+        .describe("Return only active or closed milestones"),
+    title: z
+        .string()
+        .optional()
+        .describe("Return only milestones with a title matching the provided string"),
+    search: z
+        .string()
+        .optional()
+        .describe("Return only milestones with a title or description matching the provided string"),
+    include_ancestors: z.coerce.boolean().optional().describe("Include ancestor groups"),
+    include_descendants: z.coerce.boolean().optional().describe("Include descendant groups"),
+    updated_before: z
+        .string()
+        .optional()
+        .describe("Return milestones updated before the specified date (ISO 8601 format)"),
+    updated_after: z
+        .string()
+        .optional()
+        .describe("Return milestones updated after the specified date (ISO 8601 format)"),
+})
+    .merge(PaginationOptionsSchema);
+export const GetGroupMilestoneSchema = z.object({
+    group_id: z.coerce.string().describe("Group ID or URL-encoded path"),
+    milestone_id: z.coerce.string().describe("The ID of a group milestone"),
+});
+export const CreateGroupMilestoneSchema = z.object({
+    group_id: z.coerce.string().describe("Group ID or URL-encoded path"),
+    title: z.string().describe("The title of the milestone"),
+    description: z.string().optional().describe("The description of the milestone"),
+    due_date: z.string().optional().describe("The due date of the milestone (YYYY-MM-DD)"),
+    start_date: z.string().optional().describe("The start date of the milestone (YYYY-MM-DD)"),
+});
+export const EditGroupMilestoneSchema = GetGroupMilestoneSchema.extend({
+    title: z.string().optional().describe("The title of the milestone"),
+    description: z.string().optional().describe("The description of the milestone"),
+    due_date: z.string().optional().describe("The due date of the milestone (YYYY-MM-DD)"),
+    start_date: z.string().optional().describe("The start date of the milestone (YYYY-MM-DD)"),
+    state_event: z
+        .enum(["close", "activate"])
+        .optional()
+        .describe("The state event of the milestone"),
+});
+export const DeleteGroupMilestoneSchema = GetGroupMilestoneSchema;
+export const GetGroupMilestoneIssuesSchema = GetGroupMilestoneSchema.merge(PaginationOptionsSchema);
+export const GetGroupMilestoneMergeRequestsSchema = GetGroupMilestoneSchema.merge(PaginationOptionsSchema);
+export const GetGroupMilestoneBurndownEventsSchema = GetGroupMilestoneSchema.merge(PaginationOptionsSchema);
 // Add schemas for commit operations
 export const ListCommitsSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or complete URL-encoded path to project"),
@@ -3351,17 +3417,17 @@ const workItemTypeEnum = z
     "requirement",
     "ticket",
 ]));
-const ProjectIdOrPathSchema = z.coerce
+const NamespaceIdOrPathSchema = z.coerce
     .string()
-    .describe("Project ID, URL-encoded project path, or group path (e.g. 'group/subgroup' for group-level work items)");
+    .describe("Project ID, URL-encoded project path, group path, or explicit namespace prefix for ambiguous numeric IDs (e.g. 'group/subgroup', 'group:123', or 'project:123')");
 // Common params for work item tools
 const WorkItemParamsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID (IID) of the work item"),
 });
 export const GetWorkItemSchema = WorkItemParamsSchema;
 export const ListWorkItemsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     types: z
         .array(workItemTypeEnum)
         .optional()
@@ -3381,7 +3447,7 @@ export const ListWorkItemsSchema = z.object({
         .describe("Cursor for pagination (from previous response's endCursor)"),
 });
 export const CreateWorkItemSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     title: z.string().describe("Title of the work item"),
     type: workItemTypeEnum
         .optional()
@@ -3522,19 +3588,19 @@ export const UpdateWorkItemSchema = WorkItemParamsSchema.extend({
         .describe("Incident only: set escalation status"),
 });
 export const ConvertWorkItemTypeSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     new_type: workItemTypeEnum.describe("The target work item type to convert to"),
 });
 export const ListWorkItemStatusesSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     work_item_type: workItemTypeEnum
         .optional()
         .default("issue")
         .describe("The work item type to list available statuses for. Defaults to 'issue'."),
 });
 export const ListWorkItemNotesSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     page_size: z.coerce
         .number()
@@ -3549,7 +3615,7 @@ export const ListWorkItemNotesSchema = z.object({
         .describe("Sort order for discussions"),
 });
 export const CreateWorkItemNoteSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     body: z.string().describe("Note body (Markdown supported)"),
     internal: z.coerce
@@ -3572,7 +3638,7 @@ export const MoveWorkItemSchema = z.object({
         .describe("Project ID, URL-encoded project path, or group path of the target namespace"),
 });
 export const ListCustomFieldDefinitionsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     work_item_type: workItemTypeEnum
         .optional()
         .default("issue")
@@ -3629,17 +3695,17 @@ export const DeleteIssueNoteEmojiReactionSchema = ProjectParamsSchema.extend({
 });
 // --- Emoji Reaction schemas (GraphQL: Work Items) ---
 export const CreateWorkItemEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     name: emojiNameField,
 });
 export const DeleteWorkItemEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     name: emojiNameField,
 });
 export const CreateWorkItemNoteEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     note_id: z
         .string()
@@ -3647,7 +3713,7 @@ export const CreateWorkItemNoteEmojiReactionSchema = z.object({
     name: emojiNameField,
 });
 export const DeleteWorkItemNoteEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     note_id: z
         .string()
@@ -3671,11 +3737,11 @@ export const ListIssueNoteEmojiReactionsSchema = ProjectParamsSchema.extend({
     discussion_id: noteEmojiDiscussionField,
 });
 export const ListWorkItemEmojiReactionsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
 });
 export const ListWorkItemNoteEmojiReactionsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     note_id: z
         .string()

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

@@ -77,7 +77,7 @@ const GROUP_META = {
     },
     milestones: {
         title: "Milestones",
-        blurb: "Project milestone CRUD plus associated issues/MRs and burndown events.",
+        blurb: "Project and group milestone CRUD plus associated issues/MRs and burndown events.",
     },
     wiki: {
         title: "Wiki",

package/build/test/group-milestone-schema.test.js

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { GitLabGroupMilestonesSchema, GitLabMilestonesSchema, GetGroupMilestoneIssuesSchema, } from "../schemas.js";
+test("group milestone response keeps group_id and rejects missing group_id", () => {
+    const parsed = GitLabGroupMilestonesSchema.parse({
+        id: 12,
+        iid: 3,
+        group_id: 16,
+        title: "10.0",
+        description: null,
+        due_date: null,
+        start_date: null,
+        state: "active",
+        updated_at: "2013-10-02T09:24:18Z",
+        created_at: "2013-10-02T09:24:18Z",
+        expired: false,
+    });
+    assert.equal(parsed.group_id, "16");
+    assert.equal("project_id" in parsed, false);
+    // Project schema coerces missing project_id to "undefined" — why group schema exists
+    const coerced = GitLabMilestonesSchema.parse({
+        id: 12,
+        iid: 3,
+        group_id: 16,
+        title: "10.0",
+        description: null,
+        due_date: null,
+        start_date: null,
+        state: "active",
+        updated_at: "2013-10-02T09:24:18Z",
+        created_at: "2013-10-02T09:24:18Z",
+        expired: false,
+    });
+    assert.equal(coerced.project_id, "undefined");
+});
+test("group milestone issues schema accepts page and per_page", () => {
+    const parsed = GetGroupMilestoneIssuesSchema.parse({
+        group_id: "16",
+        milestone_id: "12",
+        page: 2,
+        per_page: 50,
+    });
+    assert.equal(parsed.page, 2);
+    assert.equal(parsed.per_page, 50);
+});

package/build/test/mcp-oauth-tests.js

@@ -137,6 +137,18 @@ describe("MCP OAuth — Discovery Endpoints", () => {
         assert.ok(body.resource, "Should have resource field");
         console.log("  ✓ Protected resource metadata returned");
     });
+    test("unprefixed MCP_SERVER_URL serves /mcp resource discovery at /.well-known/oauth-protected-resource/mcp", async () => {
+        // When MCP_SERVER_URL has no path, the server registers a dedicated route
+        // at /.well-known/oauth-protected-resource/mcp (RFC 9728 path-suffixed
+        // discovery) so clients connecting to /mcp can discover the resource.
+        const issuerUrl = new URL(mcpBaseUrl);
+        const res = await fetch(`${mcpBaseUrl}/.well-known/oauth-protected-resource/mcp`);
+        assert.strictEqual(res.status, 200, "Should return 200");
+        const body = (await res.json());
+        assert.strictEqual(body.resource, `${issuerUrl.origin}/mcp`, "resource should be ${origin}/mcp");
+        assert.deepStrictEqual(body.authorization_servers, [issuerUrl.href], "authorization_servers should contain the issuer URL");
+        console.log("  ✓ Unprefixed MCP_SERVER_URL: /mcp resource discovery returned correct metadata");
+    });
     test("path-prefixed MCP_SERVER_URL serves path-aware discovery metadata", async () => {
         const mockPort = await findMockServerPort();
         const prefixedMockGitLab = new MockGitLabServer({

package/build/test/mcp-server-name.test.js

@@ -0,0 +1,87 @@
+import { after, describe, test } from "node:test";
+import assert from "node:assert";
+import { cleanupServers, findAvailablePort, HOST, launchServer, TransportMode, } from "./utils/server-launcher.js";
+async function rawMcpRequest(url, body, headers = {}) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            ...headers,
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+        const dataLines = text
+            .split("\n")
+            .filter(line => line.startsWith("data: "))
+            .map(line => line.slice(6));
+        return {
+            status: response.status,
+            data: dataLines.length > 0 ? JSON.parse(dataLines.at(-1)) : null,
+            text,
+        };
+    }
+    return {
+        status: response.status,
+        data: text ? JSON.parse(text) : null,
+        text,
+    };
+}
+const initializeBody = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+        protocolVersion: "2025-03-26",
+        capabilities: {},
+        clientInfo: { name: "server-name-test", version: "1.0.0" },
+    },
+};
+let portOffset = 0;
+async function launchWithServerName(mcpServerName) {
+    const port = await findAvailablePort(3700 + portOffset++ * 10);
+    const server = await launchServer({
+        mode: TransportMode.STREAMABLE_HTTP,
+        port,
+        timeout: 10_000,
+        env: {
+            STREAMABLE_HTTP: "true",
+            REMOTE_AUTHORIZATION: "true",
+            GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY: "true",
+            GITLAB_API_URL: "https://gitlab.example.com/api/v4",
+            ...(mcpServerName !== undefined ? { MCP_SERVER_NAME: mcpServerName } : {}),
+        },
+    });
+    return { server, mcpUrl: `http://${HOST}:${port}/mcp` };
+}
+describe("MCP_SERVER_NAME", { timeout: 20_000 }, () => {
+    let servers = [];
+    after(() => {
+        cleanupServers(servers);
+        servers = [];
+    });
+    test("defaults to zereight-gitlab-mcp-server when unset", async () => {
+        const { server, mcpUrl } = await launchWithServerName();
+        servers.push(server);
+        const response = await rawMcpRequest(mcpUrl, initializeBody);
+        assert.strictEqual(response.status, 200, response.text);
+        assert.strictEqual(response.data?.result?.serverInfo?.name, "zereight-gitlab-mcp-server");
+    });
+    test("reports the overridden name when MCP_SERVER_NAME is set", async () => {
+        const { server, mcpUrl } = await launchWithServerName("gitlab-selfhosted-readonly");
+        servers.push(server);
+        const response = await rawMcpRequest(mcpUrl, initializeBody);
+        assert.strictEqual(response.status, 200, response.text);
+        assert.strictEqual(response.data?.result?.serverInfo?.name, "gitlab-selfhosted-readonly");
+    });
+    test("treats a whitespace-only MCP_SERVER_NAME as unset", async () => {
+        const { server, mcpUrl } = await launchWithServerName("   ");
+        servers.push(server);
+        const response = await rawMcpRequest(mcpUrl, initializeBody);
+        assert.strictEqual(response.status, 200, response.text);
+        assert.strictEqual(response.data?.result?.serverInfo?.name, "zereight-gitlab-mcp-server");
+    });
+});

package/build/test/nullable-gitlab-response-fields.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { GitLabCompareResultSchema, GitLabProtectedBranchAccessLevelSchema, } from "../schemas.js";
+test("role-based protected-branch access levels accept null user_id/group_id", () => {
+    // #575: GitLab returns null for role-based levels, not omitted fields
+    const parsed = GitLabProtectedBranchAccessLevelSchema.parse({
+        access_level: 40,
+        access_level_description: "Maintainers",
+        user_id: null,
+        group_id: null,
+    });
+    assert.equal(parsed.user_id, null);
+    assert.equal(parsed.group_id, null);
+});
+test("branch compare accepts null commit", () => {
+    const parsed = GitLabCompareResultSchema.parse({
+        commit: null,
+        commits: [],
+        diffs: [],
+    });
+    assert.equal(parsed.commit, null);
+});

package/build/test/path-segment-encoding.test.js

@@ -11,6 +11,9 @@ const rawPathSegmentPatterns = [
     "/draft_notes/${draftNoteId}",
     "/versions/${versionId}",
     "/groups/${groupId}",
+    "/jobs/${jobId}",
+    "/pipelines/${pipelineId}",
+    "/milestones/${milestoneId}",
 ];
 test("GitLab URL path IDs are encoded before interpolation", () => {
     for (const pattern of rawPathSegmentPatterns) {
@@ -22,6 +25,14 @@ test("encoding keeps path traversal payloads inside one URL segment", () => {
     const url = new URL(`https://gitlab.com/api/v4/projects/42/issues/${encodeURIComponent(payload)}/notes`);
     assert.equal(url.pathname, "/api/v4/projects/42/issues/1%2F..%2F..%2F..%2F..%2Fadmin%2Fci%2Fvariables/notes");
 });
+test("job_id path traversal stays under /jobs/", () => {
+    // GHSA-7c3w-fxgh-frc7 / #587: unencoded job_id with ../ escaped to /api/v4/user
+    const payload = "../../../user";
+    const url = new URL(`https://gitlab.com/api/v4/projects/1/jobs/${encodeURIComponent(payload)}/trace`);
+    assert.equal(url.pathname, "/api/v4/projects/1/jobs/..%2F..%2F..%2Fuser/trace");
+    assert.match(url.pathname, /\/jobs\/[^/]+\/trace$/);
+    assert.equal(url.pathname.includes("/api/v4/user"), false);
+});
 test("malformed percent-encoded segments can still be encoded", () => {
     assert.equal(encodeURIComponent("bad%zz/path"), "bad%25zz%2Fpath");
 });

package/build/test/streamable-http-concurrent-session.test.js

@@ -90,3 +90,66 @@ describe("Streamable HTTP concurrent session requests", { timeout: 20_000 }, ()
         }
     });
 });
+describe("Streamable HTTP health check capacity logging", { timeout: 20_000 }, () => {
+    let mockGitLab;
+    let server;
+    let mcpUrl;
+    let baseUrl;
+    let output = "";
+    before(async () => {
+        const mockPort = await findMockServerPort();
+        mockGitLab = new MockGitLabServer({
+            port: mockPort,
+            validTokens: [MOCK_TOKEN],
+        });
+        await mockGitLab.start();
+        const port = await findAvailablePort(3470);
+        server = await launchServer({
+            mode: TransportMode.STREAMABLE_HTTP,
+            port,
+            timeout: 10_000,
+            env: {
+                STREAMABLE_HTTP: "true",
+                REMOTE_AUTHORIZATION: "true",
+                GITLAB_API_URL: `${mockGitLab.getUrl()}/api/v4`,
+                MAX_SESSIONS: "1",
+            },
+        });
+        server.process.stdout?.on("data", data => {
+            output += data.toString();
+        });
+        server.process.stderr?.on("data", data => {
+            output += data.toString();
+        });
+        baseUrl = `http://${HOST}:${port}`;
+        mcpUrl = `${baseUrl}/mcp`;
+    });
+    after(async () => {
+        cleanupServers([server]);
+        if (mockGitLab)
+            await mockGitLab.stop();
+    });
+    test("logs active session capacity when health check is degraded", async () => {
+        const client = new CustomHeaderClient({ Authorization: `Bearer ${MOCK_TOKEN}` });
+        await client.connect(mcpUrl);
+        try {
+            const response = await fetch(`${baseUrl}/health`);
+            const body = (await response.json());
+            assert.strictEqual(response.status, 503);
+            assert.strictEqual(body.status, "degraded");
+            assert.strictEqual(body.activeSessions, 1);
+            assert.strictEqual(body.maxSessions, 1);
+            // ponytail: poll stdout; fixed 100ms sleep flakes under CI jitter
+            const deadline = Date.now() + 2000;
+            while (Date.now() < deadline && !/Health check degraded/.test(output)) {
+                await new Promise(resolve => setTimeout(resolve, 50));
+            }
+            assert.match(output, /Health check degraded/);
+            assert.match(output, /activeSessions.*1/);
+            assert.match(output, /maxSessions.*1/);
+        }
+        finally {
+            await client.disconnect();
+        }
+    });
+});