> [!NOTE] > This issue was created by Duo Planner, a GitLab AI agent. ## Summary Today, the official GitLab MCP server exposes only a small set of tools focused on issues, merge requests, pipelines, search, and work item notes. We need to add and standardize MCP server tools for the **Projects & Repositories** area so MCP-based agents and external MCP clients can perform the same workflows that are available in Agentic Chat and via the GitLab API. This task covers the `fork_repository` tool specifically. ### Example use cases - As a **developer using an MCP client**, I want to `fork an upstream project into my namespace or a target group` so that `I can propose changes via MR without needing write access to the original project`. - As a **Duo agent**, I want to `fork a project, apply suggested changes, and open an MR back to the source` so that `I can assist external contributors end-to-end`. - As a **solutions architect**, I want to `fork a project into a controlled namespace to run experimental scans or test configurations` so I don't need to fall back to custom API wrappers or community MCP servers. ## Tool Specification **Tool name:** `fork_repository` **Input schema:** | Parameter | Type | Required | Description | |---|---|---|---| | `project_id` | `string` | ✅ | The project ID (numeric) or URL-encoded full path of the project to fork (e.g., `gitlab-org/gitlab`) | | `namespace_id` | `integer` | ❌ | The ID of the target namespace (group or user) to fork into. Defaults to the current user's personal namespace. | | `name` | `string` | ❌ | Override the name of the forked project. Defaults to the source project's name. | | `path` | `string` | ❌ | Override the path (slug) of the forked project. Defaults to the source project's path. | | `description` | `string` | ❌ | Override the description of the forked project. | | `visibility` | `string` | ❌ | `"private"`, `"internal"`, or `"public"`. Cannot exceed the visibility of the source project. Defaults to `"private"`. | **Output schema:** | Field | Type | Description | |---|---|---| | `id` | `integer` | Numeric project ID of the fork | | `name` | `string` | Name of the forked project | | `path_with_namespace` | `string` | Full path of the fork (e.g., `my-username/gitlab`) | | `visibility` | `string` | Effective visibility of the fork | | `web_url` | `string` | URL to the forked project on GitLab | | `ssh_url_to_repo` | `string` | SSH clone URL of the fork | | `http_url_to_repo` | `string` | HTTPS clone URL of the fork | | `forked_from_project_id` | `integer` | Numeric ID of the source project | | `forked_from_web_url` | `string` | URL to the source project on GitLab | | `import_status` | `string` | Fork import status: `"none"`, `"scheduled"`, `"started"`, `"finished"`, or `"failed"` | | `created_at` | `string` | ISO 8601 creation timestamp | **GitLab API mapping:** `POST /projects/:id/fork` ## Acceptance Criteria - [ ] Tool is registered in the MCP server tool registry with name `fork_repository`, a clear description, and a JSON Schema input definition. - [ ] Tool accepts both numeric project IDs and URL-encoded full paths for `project_id`. - [ ] `namespace_id` is optional; when omitted, the fork is created in the current user's personal namespace. - [ ] `visibility` defaults to `"private"` and is validated to not exceed the source project's visibility level. - [ ] Returns a structured 409 error when a fork of the same project already exists in the target namespace. - [ ] Returns a structured 404 error when the source project does not exist or is not visible to the current user. - [ ] Returns a structured 403 error when the user lacks permission to fork the project (e.g., forking is disabled on the source project or the user lacks access to the target namespace). - [ ] `import_status` is included in the response so the caller knows whether the fork is still being set up asynchronously. - [ ] Unit tests cover: successful fork to personal namespace, successful fork to group namespace, fork already exists (409), source not found (404), forking disabled (403), and visibility conflict. - [ ] Integration test confirms the tool is callable end-to-end via the MCP protocol. - [ ] Tool description and parameter schema are clear enough for an LLM to select and invoke the tool correctly without additional context. ## Implementation Notes - Follow the existing tool pattern established by tools such as `get_issue` and `create_merge_request_note` in the MCP server codebase. - Forking is asynchronous on GitLab — the API returns immediately with `import_status: "scheduled"` or `"started"`. The tool should document this clearly so the LLM does not assume the fork is immediately usable. - If the agent needs to wait for the fork to be ready, it should poll `get_project` on the fork's ID and check `import_status` — document this pattern in the tool description. - The tool description should note that forking may be disabled at the instance or group level (`forking_access_level` setting) and that a 403 in that case is expected and not a permissions bug. - Visibility cannot be set higher than the source project's visibility — validate this client-side before the API call and return a clear error message.