sonarqube-mcp

SonarQube MCP 統合

Model Context Protocol（MCP）サーバーを通じて SonarQube と SonarCloud の機能を直接活用し、コード品質を確保し、問題を見つけ、エージェントのワークフロー内でプッシュ前の分析を実行します。

概要

このスキルでは、SonarQube MCP Server ツールの使用方法とパターンを説明します。次のようなワークフローを自動化できます。

• マージまたはデプロイ前に品質ゲートのステータスを確認する
• 重大度とプロジェクト別に問題を見つけてトリアージする
• コミット前にコードスニペットをローカルで分析する（シフトレフト）
• SonarQube ルールの詳細なドキュメントを確認する

使用するタイミング

次のような場合にこのスキルを使用します。

• ユーザーが、PR のマージ前にプロジェクトが品質ゲートを通過するか確認したい場合
• ユーザーが、1 つ以上の SonarQube プロジェクトで重大またはブロッカーの問題を見つけたい場合
• ユーザーが、CI にプッシュする前にコードスニペットの問題を分析したい場合
• ユーザーが、特定の Sonar ルールによってコードにフラグが付けられた理由を知りたい場合
• ユーザーが、コミット前またはプッシュ前の品質に関するフィードバックを求めている場合

トリガーフレーズ：「品質ゲートを確認」「sonarqube quality gate」「sonar の問題を見つける」「sonar の問題を検索」「sonar でコードを分析」「sonar ルールを確認」「sonarcloud の問題」「プッシュ前の sonar チェック」「sonar のコミット前チェック」

前提条件とセットアップ

このプラグインには、Docker 経由で SonarQube MCP Server を自動的に起動する .mcp.json が含まれています。このスキルを使用する前に、必要な環境変数を設定してください。

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 が実行中であること
   • 環境変数が設定されていること
   • 参考：mcp/sonarqube on Docker Hub

参考ドキュメント

• references/metrics.md — 一般的な SonarQube メトリクスとその意味
• references/severity-levels.md — Sonar の重大度レベルと影響カテゴリ
• references/best-practices.md — PR チェックとコミット前分析のワークフロー
• references/llm-context.md — ツール選択ガイドと LLM エージェント向けのパラメータ対応表

手順

ステップ 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 (string) — SonarQube/SonarCloud のプロジェクトキー
• pullRequest (string, optional) — PR 固有のゲートチェックに使用するプルリクエスト ID
• analysisId (string, optional) — 特定の分析 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 (array, optional) — プロジェクトキーの一覧。省略すると、アクセス可能なすべてのプロジェクトを検索します
• severities (array, optional) — フィルター：BLOCKER、HIGH、MEDIUM、LOW、INFO
• pullRequestId (string, optional) — 検索対象を特定の PR に限定します
• p (integer, optional) — ページ番号（デフォルト：1）
• ps (integer, optional) — 1 ページあたりの件数（デフォルト：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 (string) — コンテキスト用のプロジェクトキー
• fileContent (string, required) — 分析対象ファイルの全内容
• language (string, optional) — 精度向上のための言語ヒント
• codeSnippet (string, optional) — 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 (string) — <language>:<rule-id> 形式のルールキー（例：typescript:S1082、java:S2068）

パターン — ルールのドキュメントを取得する：

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

レスポンスに含まれる内容： ルール名、タイプ、重大度、詳細な説明、タグ（例：cwe、owasp-a2）、言語、修正作業の見積もり、コード例（非準拠と準拠）。

ステップ 6：コンポーネントのメジャーを取得する

get_component_measures を使用して、プロジェクト、ディレクトリ、またはファイルの詳細なメトリクスを取得します。

パラメーター：

• projectKey (string) — SonarQube/SonarCloud のプロジェクトキー
• pullRequest (string, optional) — PR の範囲に限定したメトリクス用の PR ID
• metricKeys (array) — 取得するメトリクスキーの一覧

一般的なメトリクスキー： 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：マージ前の品質ゲートチェック

ユーザーの依頼：「PR #234 でプロジェクト backend-api の品質ゲートが通るか確認してください」

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

**ゲートに失敗した場合：**失敗した条件を抽出してユーザーに提示し、その後、同じ PR でフィルターした search_sonar_issues_in_projects を使って実際の問題を表示します。

例 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"
  }
}

調査結果を提示し、各問題について、修正方法を説明するために ruleKey の値を指定して show_rule を呼び出すこともできます。

例 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. セキュリティ問題にはシフトレフトで対応する — CI だけでなく、開発中にも analyze_code_snippet を使用します
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 を確認し、さらにページを取得する必要があるか判断してください
• 品質ゲートのステータスは、最後に完了した分析を反映します。コードが変更されている場合は、新しい分析を実行してください