sonarsource/sonarqube-agent-plugins/sonar-duplication

SonarQube — Duplication

List files that contain duplicated code in a SonarQube project, then drill into duplication blocks for a specific file when needed.

Usage

sonar-duplication                              # all duplicated files in the current project (auto-paginated)
sonar-duplication my-project                   # duplicated files in a specific project
sonar-duplication my-project --pr 42           # same, on a pull request
sonar-duplication my-project --page-size 100 --page 2   # single page of results (manual pagination)
sonar-duplication my-project --file src/auth/login.py   # duplication detail for one file

Prerequisites

This skill requires the SonarQube MCP Server to be configured and the tools mcp__sonarqube__search_duplicated_files and mcp__sonarqube__get_duplications to be available in your session.

Before proceeding, verify the tools are accessible. If they are not, try the sonar api CLI fallback in Step 3 before giving up — don't invent other CLI commands (e.g. sonar mcp call or sonar duplication do not exist).

If the CLI fallback also fails (for example `sonar` not installed/authenticated, or no project key can be resolved), narrow down the cause — check whether the sonarqube MCP server is enabled in this agent's configuration.

• Not enabled / not registered → recommend running the sonar-integrate skill.
• Enabled but its tools are still unavailable → configuration is correct but the server failed to start. The most common cause is that the container runtime is not running — the MCP server launches inside Docker/Podman/Nerdctl via sonar run mcp, so a correctly configured server still produces no tools if the daemon is stopped. Run docker ps yourself (falling back to podman ps / nerdctl ps) to confirm which cause applies: if it errors, the runtime is down; after the user starts it, confirm the same command succeeds before asking them to restart the agent session.

Either way, show the user:

Unable to reach the SonarQube MCP Server, or project key not found.

Possible causes:

- MCP server not registered — invoke the sonar-integrate skill to configure the SonarQube MCP Server, then restart the agent session

- Container runtime not running — the SonarQube MCP Server runs inside a container (Docker, Podman, or Nerdctl); start your container runtime, then restart the agent session

- Credentials not configured — invoke the sonar-integrate skill

- Project key is wrong or no default project in MCP config — pass an explicit key, or verify sonar-project.properties / re-run the sonar-integrate skill for this project

Then ask the user (yes/no) whether to run the sonar-integrate skill now. Briefly explain what it does: it checks the SonarQube setup on their machine — installing or updating sonarqube-cli and verifying authentication — and re-configures the integration for this agent, including the SonarQube MCP server and secrets-scanning hooks. If they confirm, invoke the sonar-integrate skill yourself and follow it end-to-end in this session, then ask the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running and to restart the agent session so the new MCP tools become available; if they decline, stop.

Instructions

Step 1: Resolve the project key (only when needed)

MCP tools sometimes do not require projectKey after the sonar-integrate skill has stored the default project for this workspace. Resolve a key only when you must pass it (tool schema requires it, or the user targets another project):

• If the user provided a project key, use it.
• Otherwise look for sonar.projectKey in sonar-project.properties at the repo root.
• If still not found, omit `projectKey` in MCP calls and rely on the integration default.

Step 2: Parse optional flags from the user-provided arguments

Pagination rule: By default, call search_duplicated_files without pageSize or pageIndex so the MCP server auto-fetches every page of duplicated files (up to 10,000 files). Use pageSize and pageIndex only when the user asks for a specific page or wants to limit page size. If the user supplies --page-size but not --page, use pageIndex 1.

Step 3: Run the appropriate flow

Flow A — Duplicated file list (default, no --file)

Call mcp__sonarqube__search_duplicated_files.

Default (auto-fetch all pages):

Include `projectKey` only if you resolved one in Step 1 and the tool requires it; otherwise omit it.

{
  "projectKey": "<only-if-required>",
  "pullRequest": "<id>"
}

Omit pullRequest when --pr was not given. Omit pageSize and pageIndex entirely so all duplicated files are retrieved automatically. Omit projectKey from the payload when the integration default applies.

Manual pagination (single page):

{
  "projectKey": "<only-if-required>",
  "pullRequest": "<id>",
  "pageSize": <n>,
  "pageIndex": <n>
}

The tool returns only files that have duplications. Present results in a table. Include columns the response provides (for example path, duplicated line counts, or density); sort by the strongest duplication signal if multiple metrics exist (for example highest duplicated-lines density or count first).

## Duplication — `my-project`
 
Files with duplications:
 
| File                 | Duplicated lines (example) |
| -------------------- | -------------------------- |
| src/auth/login.py    | 42                         |
| src/utils/helpers.py | 18                         |

If the list is empty: "No duplicated files were returned for this project/branch/PR."

Then offer to drill in:

"Ask me to open duplications for any file, or invoke the sonar-duplication skill with `--file <file-key>` (add a project key only if needed)."

If `mcp__sonarqube__search_duplicated_files` is unavailable, fall back to `sonar api`. This needs an explicit project key (no MCP default) — if none was resolved in Step 1, ask the user or invoke sonar-list-projects, then stop.

sonar api get "/api/measures/component_tree?component=<project-key>&metricKeys=duplicated_lines,duplicated_blocks,duplicated_lines_density&qualifiers=FIL&strategy=leaves[&pullRequest=<id>]"

Use metricKeys; add -v if a call 400s unexpectedly. Manual pagination maps to &p=<page>&ps=<page-size>; there's no auto-fetch-all mode, so page yourself up to the 10,000-file cap if needed. Filter out components with all-zero duplication metrics, then present the same table as above.

Flow B — Duplication detail (--file <key> given, or user asks to inspect a file)

Call mcp__sonarqube__get_duplications:

{
  "key": "<file-key>",
  "pullRequest": "<id>"
}

The file key format is <projectKey>:<path>, e.g. my-project:src/auth/login.py. If the user provides just a path, prepend the resolved project key when you have one; otherwise follow the MCP tool schema for the default project. Omit pullRequest when --pr was not given.

Permission: This call requires Browse permission on the file’s project. If the tool returns a permission or authorization error, tell the user they need the Browse role on the project and that they may need a role with code-view access.

Present duplication blocks from the response: for each block, show ranges, sibling copies, or other fields returned by the API so the user can see where code is duplicated.

## Duplication detail — `src/auth/login.py`
 
### Block 1
-Lines 10–24 (example) duplicated in `src/other/helper.py` lines 30–44
...

If the file has no duplications in the response, say: "No duplications were reported for this file."

If `mcp__sonarqube__get_duplications` is unavailable, fall back to `sonar api`:

sonar api get "/api/duplications/show?key=<file-key>[&pullRequest=<id>]"

Omit pullRequest when --pr was not given. The same Browse permission requirement applies. Present the returned blocks in the same format as above.

If this also fails, show the standard message above — don't guess further commands.

Step 4: Next steps

• To refactor: "Ask me to extract a shared helper or consolidate the duplicated regions."
• To scan the same file for issues: "Invoke the sonar-analyze skill with `<file>`."
• To check the quality gate (e.g. new_duplicated_lines_density): "Invoke the sonar-quality-gate skill (add a project key only if you are not using the integration default)."