sonarqube-mcp

SonarQube MCP 集成

通过 Model Context Protocol（MCP）服务直接使用 SonarQube 和 SonarCloud 的功能，在 Agent 工作流中执行代码质量检查、发现问题并运行推送前分析。

概述

本技能介绍如何使用 SonarQube MCP 服务工具，并提供使用模式。它支持以下自动化工作流：

• 在合并或部署前检查质量门状态
• 按严重性和项目发现问题并进行分类处理
• 在提交前本地分析代码片段（左移）
• 通过完整文档了解 SonarQube 规则

适用场景

在以下情况下使用本技能：

• 用户想在合并 PR 前检查项目是否通过质量门
• 用户想查找一个或多个 SonarQube 项目中的严重或阻断级问题
• 用户想在推送到 CI 前分析代码片段中的问题
• 用户想了解某条 Sonar 规则标记其代码的原因
• 用户请求提交前或推送前的质量反馈

触发短语：“检查质量门”、“sonarqube 质量门”、“查找 sonar 问题”、“搜索 sonar 问题”、“用 sonar 分析代码”、“检查 sonar 规则”、“sonarcloud 问题”、“推送前 sonar 检查”、“sonar 提交前检查”

前提条件与设置

该插件包含一个 .mcp.json，可通过 Docker 自动启动 SonarQube MCP Server。使用本技能前，请设置所需的环境变量：

SonarQube Server（远程或本地）：

export SONARQUBE_TOKEN="squ_your_token"
export SONARQUBE_URL="https://sonarqube.mycompany.com"  # or http://host.docker.internal:9000 for local Docker

SonarCloud：

export SONARQUBE_TOKEN="squ_your_token"
export SONARQUBE_ORG="your-org-key"   # required for SonarCloud
# SONARQUBE_URL is not needed for SonarCloud

要求：

• 必须安装并运行 Docker
• 始终需要 SONARQUBE_TOKEN
• SonarQube Server 需要 SONARQUBE_URL（本地实例请使用 host.docker.internal）
• SonarCloud 需要 SONARQUBE_ORG（此时省略 SONARQUBE_URL）

快速开始

1. 设置 SonarQube/SonarCloud 凭据：

   # SonarQube Server
   export SONARQUBE_TOKEN="squ_your_token"
   export SONARQUBE_URL="https://sonarqube.mycompany.com"
   
   # SonarCloud
   export SONARQUBE_TOKEN="squ_your_token"
   export SONARQUBE_ORG="your-org-key"
   

2. 确认 MCP 工具可用：

   • 工具名称遵循以下模式：mcp__sonarqube-mcp__<tool-name>

3. 如果 MCP 服务无法启动，请检查：

   • Docker 是否正在运行
   • 是否已设置环境变量
   • 参考：Docker Hub 上的 mcp/sonarqube

参考文档

• references/metrics.md — 常见 SonarQube 指标及其含义
• references/severity-levels.md — Sonar 严重性级别和影响类别
• references/best-practices.md — PR 检查和提交前分析的工作流
• references/llm-context.md — 面向大模型 Agent 的工具选择指南和参数映射

操作说明

步骤 1：确定所需操作

判断用户需要执行哪项操作：

用户意图	使用的工具
检查项目是否通过质量门	get_project_quality_gate_status
查找项目中的严重问题	search_sonar_issues_in_projects
提交前分析代码	analyze_code_snippet
了解被标记的规则	show_rule
获取详细的项目指标	get_component_measures
将问题标记为误报	change_sonar_issue_status

如果用户的意图不明确，请先询问项目键和目标，再继续操作。

步骤 2：质量门监控

使用 get_project_quality_gate_status 验证项目是否符合质量标准。

参数：

• projectKey（字符串）— SonarQube/SonarCloud 中的项目键
• pullRequest（字符串，可选）— 用于检查 PR 专属质量门的拉取请求 ID
• analysisId（字符串，可选）— 特定分析 ID

注意：此工具没有 branch 参数。如果不提供 pullRequest 或 analysisId，工具将返回默认分支的质量门状态。

模式 — 检查默认分支的质量门：

{
  "name": "get_project_quality_gate_status",
  "arguments": {
    "projectKey": "my-application"
  }
}

模式 — 合并前检查 PR 的质量门：

{
  "name": "get_project_quality_gate_status",
  "arguments": {
    "projectKey": "backend-service",
    "pullRequest": "456"
  }
}

解读响应：

• status: "OK" — 质量门已通过，可以安全地合并/部署
• status: "ERROR" — 质量门未通过；检查 conditions 数组中的未达标指标
• 每个条件会显示：metricKey、actualValue、errorThreshold、comparator

有关指标键的更多信息，请参阅 references/metrics.md。

步骤 3：发现问题并进行分类

使用 search_sonar_issues_in_projects 查找问题并确定优先级。

参数：

• projects（数组，可选）— 项目键列表；省略则搜索所有可访问的项目
• severities（数组，可选）— 筛选条件：BLOCKER、HIGH、MEDIUM、LOW、INFO
• pullRequestId（字符串，可选）— 将搜索范围限定为特定 PR
• p（整数，可选）— 页码（默认值：1）
• ps（整数，可选）— 每页条目数（默认值：100，最大值：500）

模式 — 查找阻断和严重问题：

{
  "name": "search_sonar_issues_in_projects",
  "arguments": {
    "projects": ["my-backend", "my-frontend"],
    "severities": ["BLOCKER", "HIGH"],
    "p": 1,
    "ps": 50
  }
}

模式 — 搜索 PR 中的问题：

{
  "name": "search_sonar_issues_in_projects",
  "arguments": {
    "projects": ["my-service"],
    "pullRequestId": "123",
    "severities": ["HIGH", "MEDIUM"],
    "p": 1,
    "ps": 100
  }
}

使用 change_sonar_issue_status 管理问题：

使用此工具将问题标记为误报或已接受的技术债务：

{
  "name": "change_sonar_issue_status",
  "arguments": {
    "key": "AY1234",
    "status": "falsepositive",
    "comment": "This pattern is safe in our context because..."
  }
}

有效状态：falsepositive（不是真正的问题）、accept（已确认的技术债务）、reopen（重置为未解决）

更改问题状态前，务必先向用户展示问题列表。未经用户明确确认，绝不要自行将问题标记为误报。

步骤 4：推送前分析（左移）

使用 analyze_code_snippet 在提交前对代码运行 SonarQube 分析。

参数：

• projectKey（字符串）— 用于提供上下文的项目键
• fileContent（字符串，必需）— 要分析的文件的完整内容
• language（字符串，可选）— 用于提高准确性的语言提示
• codeSnippet（字符串，可选）— 将结果限定在 fileContent 中的特定子范围

支持的语言： javascript、typescript、python、java、go、php、cs、cpp、kotlin、ruby、scala、swift

模式 — 提交前分析 TypeScript 文件：

{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey": "my-typescript-app",
    "fileContent": "async function fetchUser(id: string) {\n  const query = `SELECT * FROM users WHERE id = ${id}`;\n  return db.execute(query);\n}",
    "language": "typescript"
  }
}

模式 — 分析 Python 文件：

{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey": "my-python-service",
    "fileContent": "import pickle\n\ndef load_model(path):\n    with open(path, 'rb') as f:\n        return pickle.load(f)",
    "language": "python"
  }
}

响应解读：

• 每个问题都包含：ruleKey、严重级别、清洁代码属性、影响类别、行号、快速修复是否可用
• 提交前处理严重级别为 CRITICAL 和 HIGH 的问题
• 对于不熟悉的规则，使用 ruleKey 值调用 show_rule

步骤 5：了解规则

使用 show_rule 了解规则存在的原因，以及如何修复被标记的代码。

参数：

• key（字符串）— 格式为 <language>:<rule-id> 的规则键（例如，typescript:S1082、java:S2068）

模式 — 获取规则文档：

{
  "name": "show_rule",
  "arguments": {
    "key": "typescript:S1082"
  }
}

响应包含： 规则名称、类型、严重级别、完整说明、标签（例如，cwe、owasp-a2）、语言、修复工作量估算、代码示例（不合规与合规）。

步骤 6：获取组件度量

使用 get_component_measures 获取项目、目录或文件的详细指标。

参数：

• projectKey（字符串）— SonarQube/SonarCloud 中的项目键
• pullRequest（字符串，可选）— 用于 PR 范围指标的 PR ID
• metricKeys（数组）— 要获取的指标键列表

常见指标键： coverage、bugs、vulnerabilities、code_smells、complexity、cognitive_complexity、ncloc、duplicated_lines_density、new_coverage、new_bugs

模式 — 项目健康状况仪表板：

{
  "name": "get_component_measures",
  "arguments": {
    "projectKey": "my-project-key",
    "metricKeys": ["coverage", "bugs", "vulnerabilities", "code_smells", "ncloc"]
  }
}

完整的指标参考，请参阅 references/metrics.md。

步骤 7：向用户展示结果

每次调用工具后：

• 以易于理解的形式总结调查结果
• 标记需要关注的问题（BLOCKER、HIGH 严重性）
• 根据调查结果提出后续操作建议
• 在采取修复措施（例如更改问题状态、修改代码）之前，等待用户确认

示例

示例 1：合并前质量门禁检查

用户请求：“检查项目 backend-api 在 PR #234 上是否通过质量门禁”

{
  "name": "get_project_quality_gate_status",
  "arguments": {
    "projectKey": "backend-api",
    "pullRequest": "234"
  }
}

**如果门禁未通过：**提取未通过的条件并展示给用户，然后使用 search_sonar_issues_in_projects 按同一个 PR 筛选，显示实际问题。

示例 2：推送前左移分析

用户请求：“在我推送之前分析这个 Go 函数”

{
  "name": "analyze_code_snippet",
  "arguments": {
    "projectKey": "my-go-service",
    "fileContent": "func handler(w http.ResponseWriter, r *http.Request) {\n  id := r.URL.Query().Get(\"id\")\n  query := fmt.Sprintf(\"SELECT * FROM orders WHERE id = %s\", id)\n  rows, _ := db.Query(query)\n  // ...\n}",
    "language": "go"
  }
}

展示调查结果 → 对于每个问题，可选择调用 show_rule，并传入 ruleKey 值来解释修复方法。

示例 3：对项目中的 BLOCKER 问题进行分类处理

用户请求：“显示 payment-service 中所有的 blocker 问题”

{
  "name": "search_sonar_issues_in_projects",
  "arguments": {
    "projects": ["payment-service"],
    "severities": ["BLOCKER"],
    "p": 1,
    "ps": 50
  }
}

按类别（安全性、可靠性、可维护性）对结果分组并展示给用户。对于不熟悉的规则，可提供调用 show_rule 的选项。

最佳实践

1. 环境设置 — 每个会话只需设置一次凭据；MCP 服务会自动获取
2. 合并前始终检查质量门禁 — 在任何 PR 审查工作流中运行 get_project_quality_gate_status
3. 安全问题左移 — 在开发期间使用 analyze_code_snippet，而不仅仅是在 CI 中使用
4. 按严重性确定优先级 — 优先处理 BLOCKER 和 HIGH 问题；记录对 MEDIUM 和 LOW 问题的处理决定
5. 对不熟悉的键使用 show_rule — 未了解规则意图之前，切勿忽略该规则
6. 对大型结果集进行分页 — 使用 p 和 ps 参数；处理多页响应以确保完整覆盖
7. 切勿自主更改问题状态 — 始终向用户展示问题，并在调用 change_sonar_issue_status 之前获得明确确认
8. 提供语言提示 — 在 analyze_code_snippet 中指定 language，以获得更准确的分析

约束和警告

• 必须配置并运行 MCP 服务；使用前请确认工具可用
• analyze_code_snippet 会独立分析代码片段——在 CI 中，完整的项目上下文可能会影响结果
• 更改问题状态（误报、不予修复）需要相应的 SonarQube 权限
• SonarCloud 和 SonarQube Server API 大体兼容，但部分功能有所不同；请查看 references/llm-context.md
• 对于问题较多的项目，必须进行分页；检查响应中的 paging.total 和 paging.pageSize，以确定是否需要继续遍历后续页面
• 质量门禁状态反映最近一次已完成的分析——如果代码有变更，请触发新的分析