<!-- 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 Agents need to drive pipeline lifecycle: run a new pipeline, retry a failed one, or cancel a running one. `save_pipeline` creates pipelines and folds two lifecycle actions (retry, cancel) into the same tool. **Intentional exception:** `save_` here does more than create/update field mutations — it also folds two pipeline lifecycle actions (`retry`, `cancel`) via an `action` param. Creation follows the standard `save_` shape (absent `pipeline_id` → create); when `pipeline_id` is present, `action` selects a lifecycle transition on that pipeline. Lifecycle actions folded into `save_` are **not covered by the current MCP tool guidelines**, so this issue includes updating `doc/development/duo_agent_platform/mcp/_index.md` to document this as an allowed, explicitly-documented exception. The `list` action has been **removed** and now lives solely in `list_pipelines`; deleting pipeline records is out of scope. ## Scope and Non-Goals - **In scope:** create a pipeline; `retry` and `cancel` lifecycle actions on an existing pipeline; update the MCP tool guidelines to document the lifecycle-action exception. - **Non-goals:** listing (`list_pipelines`), reading detail/jobs (`get_pipeline`), job logs (`get_job`), CI validation (`validate_ci_file`), deleting pipeline records. - **Follow-ups:** none. ## Data Shape and Context Engineering The presence of `pipeline_id` selects the target: absent → create (requires `ref`); present → a lifecycle action chosen by `action` (`retry`/`cancel`). Output is a compact pipeline reference. No large payloads. - Input schema (example): ```json { "tool": "save_pipeline", "description": "Run, retry, or cancel a CI/CD pipeline.", "parameters": { "url": "string (optional)", "project_id": "int | string (optional)", "pipeline_id": "integer (optional; when present, target an existing pipeline for a lifecycle action)", "action": "enum (optional; retry | cancel — requires pipeline_id; omit to create)", "ref": "string (optional; required on create — i.e. when pipeline_id is absent)", "variables": "array (optional; create)", "inputs": "object (optional; create)" } } ``` - Output schema (JSON example): ```json { "action": "retry", "id": 987654, "status": "running", "ref": "main", "web_url": "https://gitlab.com/group/project/-/pipelines/987654" } ``` ## Backward compatibility Out of scope for this issue. Migration of the shipped `gitlab_save_pipeline` (and the other existing MCP/DAP tools) is tracked in #609451 ("Develop migration plan for migrating existing MCP and DAP tools"). The intent there is a best-effort replication of the current tool's behaviour — noting that a faithful REST→GraphQL mapping may not always be possible where the two APIs differ (e.g. the old `method` enum's `list`/`delete` values, which this proposal drops/moves). Build the new tool to the shape described above; the compatibility/alias story is handled centrally in #609451. ### Resources (already implemented similar tools etc.) - Existing GraphQL mutations, one per action — all in `app/graphql/mutations/ci/`: - Create → `Mutations::Ci::Pipeline::Create` (`PipelineCreate`): `projectPath`, `ref`, `variables` (`[Ci::VariableInputType]`), `inputs` (`[Ci::Inputs::InputType]`), optional `mergeRequestIid`. Matches this tool's create params exactly. - Retry → `Mutations::Ci::Pipeline::Retry` (`PipelineRetry`): single `id` argument. - Cancel → `Mutations::Ci::Pipeline::Cancel` (`PipelineCancel`): single `id` argument. - All three return `pipeline: Types::Ci::PipelineType` plus `errors`. - **Id type**: the retry/cancel `id` is a GID (`Types::GlobalIDType[::Ci::Pipeline]`), and its numeric part is the same global pipeline id REST uses. Build it from this tool's `pipeline_id` as `"gid://gitlab/Ci::Pipeline/#{pipeline_id}"`. - **`web_url`**: `PipelineType` has no `web_url` field, only a relative `path`. Build the output `web_url` client-side from the resolved project's `webUrl` + `path` (or `"#{project_web_url}/-/pipelines/#{id}"`), same client-side-construction pattern used elsewhere. Output `status`/`ref` map to `PipelineType.status`/`PipelineType.ref`; `id` is a GID needing unwrapping to a plain integer. - Mutation-tool precedent: `create_merge_request_note` (`app/services/mcp/tools/merge_requests/create_merge_request_note_{tool,service}.rb`). - 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::Pipelines::SavePipelineTool < Mcp::Tools::Base::GraphqlTool` and `Mcp::Tools::Pipelines::SavePipelineService < Base::GraphqlService`. This tool dispatches to one of three mutations depending on `pipeline_id`/`action`, so it commits three operation files (or one file with three named operations) and selects the operation at call time. 2. Operation files under `app/graphql/queries/mcp/pipelines/`: `create_pipeline.mutation.graphql` (`pipelineCreate`), `retry_pipeline.mutation.graphql` (`pipelineRetry`), `cancel_pipeline.mutation.graphql` (`pipelineCancel`) — each selecting `pipeline { id status ref project { webUrl } }` and `errors`. 3. Operation selection: `pipeline_id` absent → create (require `ref`); `pipeline_id` present + `action: retry|cancel` → the matching mutation. Enforce these preconditions client-side before building variables. 4. `url`/`project_id` → `projectPath` (create only) via `find_parent_by_id_or_path!(:project, identifier)`. Retry/cancel authorize via the pipeline `id` alone — no project path needed, but still resolve the project if you want `web_url` in the response (or read it from the returned `pipeline.project.webUrl`). 5. `pipeline_id` → `id`: wrap as `"gid://gitlab/Ci::Pipeline/#{pipeline_id}"` for retry/cancel. 6. Output: unwrap `pipeline.id` GID → integer; build `web_url` from `pipeline.project.webUrl` + `path`; echo back the `action` that was performed. 7. Register in `GRAPHQL_TOOLS` in `app/services/mcp/tools/manager.rb`. (Alias/migration of the old `gitlab_save_pipeline` is out of scope — tracked in #609451.) 8. Update `doc/development/duo_agent_platform/mcp/_index.md` to document lifecycle actions folded into `save_` (via an `action` param) as an intentional, explicitly-documented exception. 9. Specs: `spec/graphql/all_queries_spec.rb` coverage comes free from the committed `.graphql` files; add Tool/Service specs for create (with/without variables/inputs), retry, cancel, and the precondition errors (missing `ref` on create, missing `pipeline_id` on an action).