feat: bulk_publish reviewer_state/note/internal (GitLab 19.2+) (#606)

* feat: add bulk_publish reviewer_state params with call-time version gate

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: tighten bulk_publish version gate and sync tools docs

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: zereight

docs/tools/index.md

@@ -148,7 +148,7 @@ MR lifecycle — create, update, merge, approve, plus diff/conflict inspection a
 | [`update_draft_note`](merge-requests.md#update_draft_note) | Update an existing draft note | ✏️ |
 | [`delete_draft_note`](merge-requests.md#delete_draft_note) | Delete a draft note | ✏️ |
 | [`publish_draft_note`](merge-requests.md#publish_draft_note) | Publish a single draft note | ✏️ |
-| [`bulk_publish_draft_notes`](merge-requests.md#bulk_publish_draft_notes) | Publish all draft notes for a merge request | ✏️ |
+| [`bulk_publish_draft_notes`](merge-requests.md#bulk_publish_draft_notes) | Publish all draft notes for a merge request. Optionally sets reviewer_state and posts a summary note (GitLab 19.2+). Can set reviewer_state even with no drafts. | ✏️ |
 | [`create_merge_request_thread`](merge-requests.md#create_merge_request_thread) | Create a new thread on a merge request | ✏️ |
 | [`resolve_merge_request_thread`](merge-requests.md#resolve_merge_request_thread) | Resolve a thread on a merge request | ✏️ |
 | [`list_merge_request_emoji_reactions`](merge-requests.md#list_merge_request_emoji_reactions) | List all emoji reactions on a merge request | 📖 |

docs/tools/merge-requests.md

@@ -604,14 +604,17 @@ Publish a single draft note
 
 *✏️ Writes*
 
-Publish all draft notes for a merge request
+Publish all draft notes for a merge request. Optionally sets reviewer_state and posts a summary note (GitLab 19.2+). Can set reviewer_state even with no drafts.
 
 **Parameters**
 
 | Parameter | Type | Required | Description |
 |---|---|:-:|---|
 | `project_id` | string | ✓ | Project ID or complete URL-encoded path to project |
 | `merge_request_iid` | string | ✓ | The IID of a merge request |
+| `reviewer_state` | enum (`requested_changes` \| `reviewed`) |  | Set reviewer review state after publishing (GitLab 19.2+). Does not record a formal approval. Works even with no draft notes. |
+| `note` | string |  | Summary note body to post on the merge request (GitLab 19.2+) |
+| `internal` | boolean |  | If true, the summary note is internal (GitLab 19.2+, default false) |
 
 ### `create_merge_request_thread`
 

index.ts

@@ -164,6 +164,12 @@ import {
 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 {
+  buildBulkPublishDraftNotesBody,
+  needsGitLab19_2BulkPublish,
+  type BulkPublishDraftNotesBody,
+} from "./utils/bulk-publish-options.js";
 import {
   cleanMutuallyExclusiveIdUsernameOptions,
   LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS,
@@ -6289,15 +6295,38 @@ async function publishDraftNote(
   }
 }
 
+async function fetchGitLabInstanceVersion(): Promise<string | null> {
+  try {
+    const response = await fetch(`${getEffectiveApiUrl()}/version`, {
+      ...getFetchConfig(),
+    });
+    if (!response.ok) return null;
+    const data: unknown = await response.json();
+    if (
+      typeof data === "object" &&
+      data !== null &&
+      "version" in data &&
+      typeof data.version === "string"
+    ) {
+      return data.version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Publish all draft notes for a merge request
  * @param {string} projectId - The ID or URL-encoded path of the project
  * @param {number|string} mergeRequestIid - The internal ID of the merge request
+ * @param {BulkPublishDraftNotesBody} options - Optional GitLab 19.2+ bulk_publish body fields
  * @returns {Promise<GitLabDiscussionNote[]>} Array of published notes
  */
 async function bulkPublishDraftNotes(
   projectId: string,
-  mergeRequestIid: number | string
+  mergeRequestIid: number | string,
+  options: BulkPublishDraftNotesBody = {}
 ): Promise<GitLabDiscussionNote[]> {
   projectId = decodeURIComponent(projectId);
   const url = new URL(
@@ -6306,10 +6335,23 @@ async function bulkPublishDraftNotes(
     )}/merge_requests/${encodeGitLabPathSegment(mergeRequestIid)}/draft_notes/bulk_publish`
   );
 
+  const body = buildBulkPublishDraftNotesBody(options);
+  if (needsGitLab19_2BulkPublish(body)) {
+    await assertGitLabVersionAtLeast(
+      {
+        major: 19,
+        minor: 2,
+        feature: "reviewer_state, note, and internal on bulk_publish_draft_notes",
+        retryHint: "Omit reviewer_state, note, and internal, then retry.",
+      },
+      fetchGitLabInstanceVersion
+    );
+  }
+
   const response = await fetch(url.toString(), {
     ...getFetchConfig(),
     method: "POST", // Changed from PUT to POST
-    body: JSON.stringify({}), // Send empty body for POST request
+    body: JSON.stringify(body),
   });
 
   if (!response.ok) {
@@ -10687,9 +10729,9 @@ async function handleToolCall(params: any) {
 
       case "bulk_publish_draft_notes": {
         const args = BulkPublishDraftNotesSchema.parse(params.arguments);
-        const { project_id, merge_request_iid } = args;
+        const { project_id, merge_request_iid, ...options } = args;
 
-        const publishedNotes = await bulkPublishDraftNotes(project_id, merge_request_iid);
+        const publishedNotes = await bulkPublishDraftNotes(project_id, merge_request_iid, options);
         return {
           content: [{ type: "text", text: JSON.stringify(publishedNotes) }],
         };

schemas.ts

@@ -3015,6 +3015,20 @@ export const PublishDraftNoteSchema = ProjectParamsSchema.extend({
 // Bulk publish draft notes schema
 export const BulkPublishDraftNotesSchema = ProjectParamsSchema.extend({
   merge_request_iid: z.coerce.string().describe("The IID of a merge request"),
+  reviewer_state: z
+    .enum(["requested_changes", "reviewed"])
+    .optional()
+    .describe(
+      "Set reviewer review state after publishing (GitLab 19.2+). Does not record a formal approval. Works even with no draft notes."
+    ),
+  note: z
+    .string()
+    .optional()
+    .describe("Summary note body to post on the merge request (GitLab 19.2+)"),
+  internal: z.coerce
+    .boolean()
+    .optional()
+    .describe("If true, the summary note is internal (GitLab 19.2+, default false)"),
 });
 
 // Schema for creating a new merge request thread

test/utils/bulk-publish-options.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+  buildBulkPublishDraftNotesBody,
+  needsGitLab19_2BulkPublish,
+} from "../../utils/bulk-publish-options.js";
+
+describe("When buildBulkPublishDraftNotesBody runs", () => {
+  describe("with no-op defaults", () => {
+    test("should omit internal false and empty note", () => {
+      assert.deepEqual(buildBulkPublishDraftNotesBody({ internal: false, note: "" }), {});
+    });
+  });
+
+  describe("with meaningful 19.2 fields", () => {
+    test("should keep reviewer_state, note, and internal true", () => {
+      assert.deepEqual(
+        buildBulkPublishDraftNotesBody({
+          reviewer_state: "reviewed",
+          note: "LGTM",
+          internal: true,
+        }),
+        { reviewer_state: "reviewed", note: "LGTM", internal: true }
+      );
+    });
+  });
+});
+
+describe("When needsGitLab19_2BulkPublish runs", () => {
+  describe("with an empty body", () => {
+    test("should return false", () => {
+      assert.equal(needsGitLab19_2BulkPublish({}), false);
+      assert.equal(needsGitLab19_2BulkPublish(buildBulkPublishDraftNotesBody({ internal: false })), false);
+    });
+  });
+
+  describe("with a non-empty body", () => {
+    test("should return true", () => {
+      assert.equal(needsGitLab19_2BulkPublish({ reviewer_state: "reviewed" }), true);
+    });
+  });
+});

test/utils/gitlab-version-gate.test.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+  assertGitLabVersionAtLeast,
+  isGitLabVersionAtLeast,
+  parseGitLabVersion,
+  type GitLabVersionFetcher,
+  type GitLabVersionRequirement,
+} from "../../utils/gitlab-version-gate.js";
+
+function versionFetcher(version: string | null): GitLabVersionFetcher {
+  return async () => version;
+}
+
+function bulkPublishRequirement(): GitLabVersionRequirement {
+  return {
+    major: 19,
+    minor: 2,
+    feature: "reviewer_state, note, and internal on bulk_publish_draft_notes",
+    retryHint: "Omit reviewer_state, note, and internal, then retry.",
+  };
+}
+
+describe("When parseGitLabVersion runs", () => {
+  describe("with a release suffix", () => {
+    test("should parse major.minor.patch from ee builds", () => {
+      assert.deepEqual(parseGitLabVersion("19.2.0-ee"), {
+        major: 19,
+        minor: 2,
+        patch: 0,
+      });
+    });
+  });
+
+  describe("with a malformed string", () => {
+    test("should return null", () => {
+      assert.equal(parseGitLabVersion("unknown"), null);
+      assert.equal(parseGitLabVersion(""), null);
+    });
+  });
+});
+
+describe("When isGitLabVersionAtLeast compares versions", () => {
+  describe("with a version at or above the floor", () => {
+    test("should return true", () => {
+      assert.equal(isGitLabVersionAtLeast("19.2.0-ee", 19, 2), true);
+      assert.equal(isGitLabVersionAtLeast("19.3.1", 19, 2), true);
+      assert.equal(isGitLabVersionAtLeast("20.0.0", 19, 2), true);
+    });
+  });
+
+  describe("with a version below the floor", () => {
+    test("should return false", () => {
+      assert.equal(isGitLabVersionAtLeast("19.1.9-ee", 19, 2), false);
+      assert.equal(isGitLabVersionAtLeast("17.5.0", 19, 2), false);
+    });
+  });
+
+  describe("with an unparseable version", () => {
+    test("should return null", () => {
+      assert.equal(isGitLabVersionAtLeast("not-a-version", 19, 2), null);
+    });
+  });
+});
+
+describe("When assertGitLabVersionAtLeast runs", () => {
+  describe("with an older instance version", () => {
+    test("should throw a retryable error", async () => {
+      await assert.rejects(
+        () => assertGitLabVersionAtLeast(bulkPublishRequirement(), versionFetcher("17.5.0-ee")),
+        (error: unknown) => {
+          assert.ok(error instanceof Error);
+          assert.match(error.message, /GitLab 19\.2\+/);
+          assert.match(error.message, /17\.5\.0-ee/);
+          assert.match(error.message, /Omit reviewer_state/);
+          return true;
+        }
+      );
+    });
+  });
+
+  describe("with a new enough instance version", () => {
+    test("should resolve without throwing", async () => {
+      await assertGitLabVersionAtLeast(bulkPublishRequirement(), versionFetcher("19.2.0-ee"));
+    });
+  });
+
+  describe("with an unknown instance version", () => {
+    test("should fail open and resolve", async () => {
+      await assertGitLabVersionAtLeast(bulkPublishRequirement(), versionFetcher(null));
+    });
+  });
+});

tools/registry.ts

@@ -492,7 +492,8 @@ export const allTools = [
   },
   {
     name: "bulk_publish_draft_notes",
-    description: "Publish all draft notes for a merge request",
+    description:
+      "Publish all draft notes for a merge request. Optionally sets reviewer_state and posts a summary note (GitLab 19.2+). Can set reviewer_state even with no drafts.",
     inputSchema: toJSONSchema(BulkPublishDraftNotesSchema),
   },
   // --- Merge request emoji reaction tools ---

utils/bulk-publish-options.ts

@@ -0,0 +1,31 @@
+/** Optional GitLab 19.2+ body fields for draft_notes/bulk_publish. */
+export type BulkPublishDraftNotesBody = {
+  reviewer_state?: "requested_changes" | "reviewed";
+  note?: string;
+  internal?: boolean;
+};
+
+/**
+ * Build the POST body. Omit no-op defaults (`internal: false`, empty `note`)
+ * so older GitLab instances are not sent unknown fields.
+ */
+export function buildBulkPublishDraftNotesBody(
+  options: BulkPublishDraftNotesBody
+): BulkPublishDraftNotesBody {
+  const body: BulkPublishDraftNotesBody = {};
+  if (options.reviewer_state !== undefined) {
+    body.reviewer_state = options.reviewer_state;
+  }
+  if (options.note) {
+    body.note = options.note;
+  }
+  if (options.internal === true) {
+    body.internal = true;
+  }
+  return body;
+}
+
+/** True when the body needs GitLab 19.2+ bulk_publish fields. */
+export function needsGitLab19_2BulkPublish(body: BulkPublishDraftNotesBody): boolean {
+  return Object.keys(body).length > 0;
+}

utils/gitlab-version-gate.ts

@@ -0,0 +1,78 @@
+/**
+ * Call-time GitLab instance version gate.
+ *
+ * Use when a tool exposes optional params that only exist on newer GitLab.
+ * Schemas stay static; check before the API call and throw a retryable error.
+ * Fail-open when the instance version cannot be fetched or parsed.
+ */
+
+const VERSION_CORE = /^(\d+)\.(\d+)(?:\.(\d+))?/;
+
+export type GitLabVersionParts = {
+  major: number;
+  minor: number;
+  patch: number;
+};
+
+/** Minimum GitLab version required for a feature. */
+export type GitLabVersionRequirement = {
+  major: number;
+  minor: number;
+  /** What the caller is trying to use (shown in the error). */
+  feature: string;
+  /** How the agent should recover (shown in the error). */
+  retryHint: string;
+};
+
+/** Returns the instance version string (e.g. "19.2.0-ee"), or null if unknown. */
+export type GitLabVersionFetcher = () => Promise<string | null>;
+
+/** Parse strings like "19.2.0-ee" / "17.5.3". Returns null if unparseable. */
+export function parseGitLabVersion(version: string): GitLabVersionParts | null {
+  const match = VERSION_CORE.exec(version.trim());
+  if (!match) return null;
+
+  const major = Number.parseInt(match[1], 10);
+  const minor = Number.parseInt(match[2], 10);
+  const patch = match[3] ? Number.parseInt(match[3], 10) : 0;
+  if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) {
+    return null;
+  }
+
+  return { major, minor, patch };
+}
+
+/**
+ * Compare a GitLab version string against a major.minor floor.
+ * Returns null when the version string cannot be parsed.
+ */
+export function isGitLabVersionAtLeast(
+  version: string,
+  major: number,
+  minor: number
+): boolean | null {
+  const parsed = parseGitLabVersion(version);
+  if (!parsed) return null;
+  if (parsed.major !== major) return parsed.major > major;
+  return parsed.minor >= minor;
+}
+
+/**
+ * Throws when the instance is known to be older than `requirement`.
+ * Does nothing when the version is unknown (fail-open).
+ */
+export async function assertGitLabVersionAtLeast(
+  requirement: GitLabVersionRequirement,
+  fetchVersion: GitLabVersionFetcher
+): Promise<void> {
+  const current = await fetchVersion();
+  if (current === null) return;
+
+  const ok = isGitLabVersionAtLeast(current, requirement.major, requirement.minor);
+  if (ok === null || ok) return;
+
+  throw new Error(
+    `GitLab ${requirement.major}.${requirement.minor}+ required for ${requirement.feature} ` +
+      `(instance reports ${current}). ${requirement.retryHint}`
+  );
+}