Tool Request: Merge Request Notes

Summary

Add two merge request notes tools to the GitLab MCP server:

  • get_merge_request_notes – read MR comments/discussions.
  • create_merge_request_note – write MR comments/replies.

These tools let MCP-based agents and external MCP clients both understand and participate in MR review conversations, matching user expectations that agents can “interact with MR notes” (see feedback).

Problem to solve

Today, the official GitLab MCP server exposes tools to:

  • Fetch MR metadata (get_merge_request)
  • Fetch MR commits (get_merge_request_commits)
  • Fetch MR diffs (get_merge_request_diffs)
  • Fetch MR pipelines (get_merge_request_pipelines)

…but no tool to read or write MR notes/comments.

This leads to:

  • Read gap: Agents cannot see MR review conversations (questions, approvals, requested changes, follow‑ups). They can analyze code and pipelines but lack human feedback context.
  • Write gap: Even if an agent infers what to say, it cannot post a response or start/reply to a thread. Users must copy-paste suggestions manually.
  • Expectation mismatch: Feedback in 561564 and other channels shows users expect MCP-based agents to interact with MR notes, not just read code.
  • Fragmentation: Users work around this via:
    • Community MCP servers with MR notes support.
    • glab and other wrappers outside the official MCP surface.
      This fragments governance and the “single official GitLab MCP server” story.

Proposal

Add two complementary tools to the official GitLab MCP server:

  1. get_merge_request_notes – read MR comments/discussions.
  2. create_merge_request_note – write MR comments/replies as the authenticated user.

This mirrors the existing pattern for issues/work items, where we already support note creation and retrieval via MCP.

Tool 1: get_merge_request_notes (read MR comments)

Purpose

Retrieve comments and discussions on a GitLab merge request so an AI assistant can summarize, analyze, or help you respond to review feedback.

Tool name

  • get_merge_request_notes
    (If engineering prefers get_merge_request_discussions to align with APIs, we can adjust name, but the core need is the same.)

User-facing description (suggested)

Retrieve comments and discussions on a GitLab merge request so an AI assistant can summarize review feedback, identify unresolved threads, and provide response suggestions.

Input parameters (initial suggestion)

Required:

  • id (string, required)
    ID or URL‑encoded path of the project (for example, gitlab-org/gitlab).

  • merge_request_iid (integer, required)
    Internal ID of the merge request.

Optional:

  • include_system (boolean, optional; default false)

    • When false, return only human-authored comments.
    • When true, include system notes (rebases, label changes, status updates, etc.).

  • discussion_id (string, optional)

    • If provided, limit results to a single discussion thread (global discussion ID, for example gid://gitlab/Discussion/<id>).

  • per_page (integer, optional)

    • Number of notes per page; default can align with other MCP tools (e.g., 20).

  • page (integer, optional)

    • Page number for pagination; default 1.

(If GraphQL/cursor pagination is a better fit for implementation, we can swap per_page/page for first/after while preserving the same semantics.)

Output (high level shape)

Return a structure that allows agents to reason about threads, individual notes, and status, for example:

  • discussions: array

    • id / discussion_id
    • resolvable / resolved
    • notes: array of note objects

  • Each note:

    • id
    • author (name, username, id)
    • body (Markdown or HTML)
    • created_at, updated_at
    • system (boolean)
    • position / basic context (file path + line info) for inline comments when available
    • resolvable / resolved
    • resolved_by (if applicable)

The goal is not to expose every API field, but to give agents enough structure to:

  • Distinguish top-level comments vs. replies
  • Distinguish system vs. human notes
  • Identify resolved vs. unresolved threads
  • Map feedback to files/lines when relevant

Tool 2: create_merge_request_note (write MR comments)

Purpose

Create a new MR note or reply to an existing MR discussion as the authenticated user, so an AI assistant can help respond to review feedback or capture follow-up context directly in the MR.

Tool name

  • create_merge_request_note

User-facing description (suggested)

Add a new comment or reply to an existing discussion on a GitLab merge request as the authenticated user.

Input parameters (initial suggestion)

Required:

  • id (string, required)
    ID or URL‑encoded path of the project (for example, gitlab-org/gitlab).

  • merge_request_iid (integer, required)
    Internal ID of the merge request.

  • body (string, required)
    Content of the note (Markdown).

Optional (v1):

  • discussion_id (string, optional)
    • If provided, post the note as a reply in the specified discussion.
    • If omitted, create a new top-level discussion/note on the MR.

Future/optional (likely follow-up, not required for v1):

  • position (object, optional)
    • To support new inline code comments (file path, line, diff refs).
    • This can be added after an initial safe v1 focused on top-level and discussion replies.

Behavior and constraints

  • The note is always created as the authenticated user.
  • Respect existing MR permissions:
    • If the user cannot comment on the MR in the UI, the tool should return a permission error.
  • v1 intentionally does not:
    • Resolve/unresolve discussions.
    • Modify or delete existing notes.

Intended use cases

  1. Summarize and track review feedback

    “Summarize the key review comments on MR !123 (merged) and list which threads are still unresolved.”

    • get_merge_request_notes to fetch discussions.
    • Agent summarizes concerns and highlights open threads.

  2. Draft and post responses to reviewers

    “Draft and post responses to all unresolved review comments on MR !123 (merged), and ask for clarification where needed.”

    • get_merge_request_notes to find unresolved threads.
    • Agent drafts responses and calls create_merge_request_note with discussion_id to post replies.

  3. Capture follow-up tasks

    “Post a comment on MR !123 (merged) summarizing remaining work and linking follow-up issues.”

    • Agent uses existing MCP tools to open follow-up issues.
    • Then posts a top-level MR note via create_merge_request_note with a concise summary and links.

  4. Compliance / audit documentation (read-only initially)

    “Provide an audit-style summary of the review process on this MR, including who raised which concerns and how they were addressed.”

    • get_merge_request_notes for a structured, programmatic view of review history.

Why both read and write are needed

  • Read-only is not enough for the expectation expressed in MCP feedback:
    • Users want agents that can “interact with MR notes”, not just summarize them.
  • Write capability is constrained and auditable:
    • Notes are created under the authenticated user identity.
    • Existing MR permissions and audit logs still apply.
    • v1 can be scoped to top-level and reply comments, leaving more complex actions (resolving, code positions) for follow-up issues.

Acceptance criteria (proposed)

For get_merge_request_notes

  • Given a valid project id and merge_request_iid, the tool returns a structured list of discussions and notes for that MR, respecting the caller’s permissions.
  • When include_system = false (default), system notes are excluded; when include_system = true, system notes are included.
  • When discussion_id is provided, the tool returns only that discussion (or a clear error if it does not exist or is not visible to the user).
  • Large MRs are handled safely with pagination via per_page/page (or cursor-based equivalent), with documented limits.

For create_merge_request_note

  • Given valid id, merge_request_iid, and body, the tool creates a top-level MR note as the authenticated user when discussion_id is not provided.
  • Given valid discussion_id, the tool creates a reply in that discussion as the authenticated user.
  • If the user lacks permission to comment on the MR, the tool returns a clear permission error.
  • The tool returns the created note’s ID and basic metadata (author, timestamps, body) so agents can reference it in subsequent steps.

Out of scope for this proposal

  • Resolving/unresolving discussions or changing note state (could be a future resolve_merge_request_discussion tool).
  • Deleting or editing existing notes.
  • Cross-MR search over comments (could be an extension of search in the future).
  • UI changes to the MR page (this issue is about MCP server tools only).
Edited by 🤖 GitLab Bot 🤖