SonarQube MCP インテグレーション

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

概要

このスキルは SonarQube MCP Server ツールの使用方法と パターンを提供します。以下の自動化されたワークフローを実現します:

• マージやデプロイ前に品質ゲートステータスを確認
• 重要度とプロジェクトで課題を発見・トリアージ
• コミット前にコードスニペットをローカルで分析 (シフトレフト)
• 完全なドキュメント付きで SonarQube ルールを理解

使用場面

このスキルは以下の場合に使用します:

• ユーザーが PR をマージする前にプロジェクトが品質ゲートをパスしているかを確認したい
• ユーザーが 1 つ以上の SonarQube プロジェクト内で重大またはブロッカー課題を見つけたい
• ユーザーが CI にプッシュする前にコードスニペットを課題について分析したい
• ユーザーが特定の Sonar ルールがコードをフラグした理由を理解したい
• ユーザーがコミット前またはプッシュ前の品質フィードバックを求めている

トリガーフレーズ: "check quality gate"、"sonarqube quality gate"、"find sonar issues"、"search sonar issues"、"analyze code with sonar"、"check sonar rule"、"sonarcloud issues"、"pre-push sonar check"、"sonar pre-commit"

前提条件とセットアップ

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

SonarQube サーバー (リモートまたはローカル):

export SONARQUBE_TOKEN="squ_your_token"
export SONARQUBE_URL="https://sonarqube.mycompany.com"  # または http://host.docker.internal:9000 (ローカル Docker の場合)

SonarCloud:

export SONARQUBE_TOKEN="squ_your_token"
export SONARQUBE_ORG="your-org-key"   # SonarCloud の場合は必須
# SONARQUBE_URL は SonarCloud では不要です

要件:

• Docker がインストール済みかつ実行中であること
• SONARQUBE_TOKEN は常に必須
• SONARQUBE_URL は SonarQube Server に必須 (ローカルインスタンスの場合は host.docker.internal を使用)
• SONARQUBE_ORG は SonarCloud に必須 (その場合は 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 (文字列) — SonarQube/SonarCloud 内のプロジェクトキー
• pullRequest (文字列、オプション) — PR 固有のゲートチェック用の 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": "このパターンは我々のコンテキストでは安全です。理由は..."
  }
}

有効なステータス: 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 重要度の課題に対応します
• 不慣れなルールについては show_rule を ruleKey 値で使用します

ステップ 5: ルール教育

show_rule を使用してルールが存在する理由とフラグされたコードの修正方法を理解します。

パラメータ:

• key (文字列) — <language>:<rule-id> 形式のルールキー (例: typescript:S1082、java:S2068)

パターン — ルールドキュメントを取得:

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

レスポンスに含まれるもの: ルール名、タイプ、重要度、完全な説明、タグ (例: cwe、owasp-a2)、言語、修復の努力予測、コード例 (非準拠 vs 準拠)。

ステップ 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"
  }
}

ゲートが失敗した場合: 失敗した条件を抽出し、ユーザーに提示してから、同じ 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: プロジェクト内のブロッカー課題をトリアージ

ユーザーのリクエスト: "payment-service 内のすべてのブロッカー課題を表示してください"

{
  "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. 重要度で優先順位付け — ブロッカーと 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 を確認してさらにページを反復するかを判定します
• 品質ゲートステータスは最後に完了した分析を反映します — コードが変更されている場合は新しい分析をトリガーします