<!-- mcp-tool-guidance-callout --> > [!note] > **Before picking up this work:** this issue adds an MCP tool. Please follow the [Adding a new tool](https://docs.gitlab.com/development/duo_agent_platform/mcp/#adding-a-new-tool) guidance first. That includes creating an MCP Tool Proposal, using `verb_object` naming (`get_` / `list_` / `save_` / `delete_`), and the shared resource-identification input base classes. ## Problem Statement / Use Case The MR review loop needs to write notes, reply to and resolve discussions, add diff-anchored comments, submit a full review, and post a Duo code review. Today these are ~6 discrete DAP tools. `save_merge_request_review` folds them into one method-gated saver, mirroring GitHub's `pull_request_review_save`. **Intentional exception:** this is the **second `save_` tool on the MR resource** (alongside `save_merge_request`). Justified because review/discussion mutations are a genuinely different action class from editing MR fields; folding both into one saver would overload a single tool with ~8 methods spanning two concerns. ## Scope and Non-Goals - **In scope:** `reply_discussion`, `resolve_discussion`, `create_note`, `create_diff_note`, `submit_review`, `post_duo_review`. - **Non-goals:** MR field mutation (`save_merge_request`), reading discussions/notes (`get_merge_request` with `include: [notes, discussions]`). - **Follow-ups:** if the broad schema proves error-prone for the model, split `submit_review` (rich `comments[]`) back out into its own tool — noted as the pragmatic fallback. ## Data Shape and Context Engineering This is the heaviest fold: per-method schemas don't overlap (`create_diff_note` needs positional `old_path`/`new_path`/lines; `submit_review` needs a `comments[]` array). The saturation/usability guard is **explicit per-method parameter documentation** so the model fills only the fields the chosen `method` uses. Output is a compact reference to the created note/discussion/review. - Input schema (example): ```json { "tool": "save_merge_request_review", "description": "Write MR review artifacts: reply/resolve discussions, add notes or diff notes, submit a review, or post a Duo review.", "parameters": { "url": "string (optional)", "project_id": "int | string (optional)", "merge_request_iid": "integer (optional)", "method": "enum (required; reply_discussion | resolve_discussion | create_note | create_diff_note | submit_review | post_duo_review)", "discussion_id": "string (reply_discussion, resolve_discussion)", "body": "string (reply_discussion, create_note, create_diff_note)", "resolved": "boolean (resolve_discussion)", "note_id": "integer (optional; create_note)", "internal": "boolean (optional; create_note)", "old_path": "string (create_diff_note)", "new_path": "string (create_diff_note)", "old_line": "integer (optional; create_diff_note)", "new_line": "integer (optional; create_diff_note)", "comments": "array (submit_review; {file, new_line, old_line, body, target_code, suggestion})", "verdict": "string (optional; submit_review)", "summary": "string (optional; submit_review)", "summary_internal": "boolean (optional; submit_review)" } } ``` - Output schema (JSON example): ```json { "method": "create_diff_note", "note_id": 55123, "discussion_id": "abc123", "web_url": "https://gitlab.com/group/project/-/merge_requests/42#note_55123" } ``` ## Backward compatibility Out of scope for this issue. This tool folds several shipped review/discussion write tools (`submit_mr_review`, `reply_to_discussion`, `set_discussion_resolved`, `create_merge_request_note`, `create_merge_request_diff_note`, and the Duo code-review post) into one method-gated saver whose per-method schemas differ substantially from the originals. Because it's a genuinely different tool, just introduce it — migration/deprecation of the superseded tools is handled centrally in #609451 ("Develop migration plan for migrating existing MCP and DAP tools"), not here. ### Resources (already implemented similar tools etc.) Five of the six methods map to existing GraphQL mutations; one has no GraphQL or REST equivalent (see below). All the note/discussion mutations take the MR's **GID** as `noteableId`, so the tool resolves project + `merge_request_iid` → the MR record → its global ID first. - `create_note` → `Mutations::Notes::Create::Note` (`CreateNote`, `app/graphql/mutations/notes/create/note.rb`): `noteableId`, `body`, `internal`. - `reply_discussion` → same `CreateNote` mutation, additionally passing `discussionId` (the discussion to reply to). No separate reply mutation exists — a reply is a `CreateNote` scoped to an existing discussion. - `create_diff_note` → `Mutations::Notes::Create::DiffNote` (`CreateDiffNote`, `app/graphql/mutations/notes/create/diff_note.rb`): `noteableId`, `body`, and a `position` (`Types::Notes::DiffPositionInput`). **Gotcha**: `DiffPositionInput` requires `headSha` and `startSha` (and `paths { oldPath newPath }` + `oldLine`/`newLine`) — the REST diff-note endpoint derives these SHAs from the MR automatically, but the GraphQL mutation needs them explicitly. The tool must read the MR's `diffRefs { headSha startSha baseSha }` first and build the position from the issue's `old_path`/`new_path`/`old_line`/`new_line` plus those SHAs. - `resolve_discussion` → `Mutations::Discussions::ToggleResolve` (`DiscussionToggleResolve`, `app/graphql/mutations/discussions/toggle_resolve.rb`): `id` (discussion GID), `resolve` (boolean, from the issue's `resolved`). - `submit_review` → **decomposes into the note mutations**: each entry in `comments[]` becomes a `CreateDiffNote` (same `position`/SHA handling as above), and the `verdict`/`summary` becomes a summary `CreateNote`. There is no single "submit review" mutation — this method is inherently multi-mutation. This is the method the issue itself flags as the split-out fallback candidate; note it fans out to N+1 mutations per call. - `post_duo_review` → **no GraphQL or REST equivalent.** This is a genuine exception — it triggers a Duo code-review job, which isn't exposed as an API mutation. This method stays a custom/service call (or is deferred), and can't be redirected. Do not treat the other five methods' GraphQL availability as implying this one has it. - Mutation-tool precedent: `create_merge_request_note` (`app/services/mcp/tools/merge_requests/create_merge_request_note_{tool,service}.rb`) — closest shape for the single-note methods. - MCP dev guidelines: `doc/development/duo_agent_platform/mcp/_index.md`; `gitlab-mcp-tool-builder` skill's build recipe — verify a GraphQL field exists before writing a custom one. ### Implementation Plan 1. Two classes: `Mcp::Tools::MergeRequests::SaveMergeRequestReviewTool < Mcp::Tools::Base::GraphqlTool` and `Mcp::Tools::MergeRequests::SaveMergeRequestReviewService < Base::GraphqlService`. Because the tool dispatches to several mutations, commit one `.graphql` file per mutation (`create_note`, `create_diff_note`, `discussion_toggle_resolve`) under `app/graphql/queries/mcp/merge_requests/` and select the operation from `method`. 2. Resolve project + `merge_request_iid` → the MR record via `ResourceFinder`, then use its `to_global_id` as `noteableId`. For `create_diff_note`/`submit_review`, also select `diffRefs { headSha startSha baseSha }` on the MR to build the `position`. 3. Route each `method` to its mutation per the Resources section. Validate per-method required params and reject cross-method field mixing (e.g. `position` fields on `create_note`). 4. `submit_review`: iterate `comments[]` → `CreateDiffNote` per comment, then one `CreateNote` for `summary`/`verdict`; aggregate the created note ids into the response. Keep the split-out-to-its-own-tool fallback documented. 5. `post_duo_review`: this method has no mutation — implement as a service call to the Duo code-review trigger (or defer it to a follow-up), and document clearly that it is *not* GraphQL-backed like the others. 6. Write exhaustive per-method parameter descriptions so the model only fills the fields the chosen `method` uses. 7. Register in `GRAPHQL_TOOLS` in `app/services/mcp/tools/manager.rb` (the `post_duo_review` path may need the custom/EE registration depending on how it's implemented). 8. Specs: `spec/graphql/all_queries_spec.rb` coverage comes free from each committed `.graphql` file; add Tool/Service specs per method — note, reply (with discussion), diff note (position + SHAs), resolve, submit_review (multi-comment), and the `post_duo_review` path.