FastMCP SonarQube メトリクス

概要

このプロジェクトは、FastMCP (Fast Model Context Protocol) フレームワークを使用してSonarQubeプロジェクトに関する情報を取得するための一連のツールを提供します。SonarQubeへのインターフェースとして機能し、指定されたプロジェクトのメトリクス、履歴データ、コンポーネントツリーのメトリクスにプログラムからアクセスできます。この自動化されたアクセスにより、SonarQubeデータのレポート作成、分析、および他のシステムとの統合が可能になります。

本プロジェクトは、SonarQube APIとの対話に簡略化されたメッセージベースのアプローチを提供し、直接的なAPI呼び出しやデータ処理の複雑さを抽象化している点が特徴です。SonarQubeデータをワークフローに組み込んだり、カスタムレポートソリューションを構築したりする必要がある開発者、DevOpsエンジニア、アナリスト向けに設計されています。

このリポジトリには、通信とデータ取得を容易にするクライアントおよびサーバーコンポーネントが格納されています。サーバーはSonarQubeからデータを取得するためのツールを公開し、クライアントはユーザーがこれらのツールを呼び出して結果を表示するためのコマンドラインインターフェースを提供します。各内部モジュールは、API対話、データ処理、クライアント・サーバー間通信といった特定の機能をカプセル化することで、この目標に貢献しています。

プロジェクトに含まれるクライアントはコードの動作確認用です。実際の利用には Claude Desktop の使用、または独自のカスタムクライアントの開発を推奨します。

注意：このリポジトリは開発中であり、一部の機能が完全ではない可能性があります。

Related MCP server: MCP QQ Music Test Server

ホスト型デプロイ

Fronteir AI にてホスト型デプロイが利用可能です。

サポートされているMCPツール

• get_status: 設定されたSonarQubeインスタンスのヘルスチェックを実行します。

• create_sonarqube_project: 新しいSonarQubeプロジェクトを作成します。管理者権限が必要です。

• delete_sonarqube_project: SonarQubeプロジェクトを削除します。管理者権限が必要です。取り扱いには十分注意してください！

• list_projects: アクセス可能なすべてのSonarQubeプロジェクトを一覧表示します（名前やキーによるフィルタリングが可能）。

• get_sonarqube_metrics: 指定されたSonarQubeプロジェクトキーのメトリクス（バグ、脆弱性、コードの不吉な臭い、カバレッジ、重複率）を取得します。

• get_sonarqube_metrics_history: /api/measures/search_history を使用して、指定されたSonarQubeプロジェクトの履歴メトリクス（バグ、脆弱性、コードの不吉な臭い、カバレッジ、重複率）を取得します。オプションで日付フィルタを適用できます。

• get_sonarqube_component_tree_metrics: /api/measures/component_tree を使用して、プロジェクト内のすべてのコンポーネント（ファイルやディレクトリなど）のメトリクス値を取得します。ページネーションを自動的に処理し、すべての結果を取得します。

• get_project_issues: 指定されたプロジェクトのSonarQube課題を取得します（タイプ、重大度、解決状況によるフィルタリングが可能）。最大 limit 件（デフォルト: 10）の結果を返します。

技術スタック

• 言語: Python

• フレームワーク: FastMCP

• ライブラリ: httpx, pydantic, dotenv, asyncio, json, pathlib, typing, base64

• ツール: SonarQube API

ディレクトリ構造

├── client_test.py - Client application for testing and interacting with the server.
├── server.py - Server application exposing tools to retrieve SonarQube metrics.
├── client_tool.py - Client with a graphical interface to interact with the SonarQube server.
├── client_langchain.py - Command-line client to interact with the FastMCP server and SonarQube tools via LangChain
├── .env - Environment configuration file (stores SonarQube URL and token).
└── README.md - Project documentation.

はじめに

前提条件

• Python 3.7+

• APIアクセスが可能なSonarQubeインスタンス

• 適切な権限を持つSonarQube APIトークン

• FastMCPのインストール (pip install fastmcp)

• httpxのインストール (pip install httpx)

• pydanticのインストール (pip install pydantic)

• python-dotenvのインストール (pip install python-dotenv)

一般的なビルド手順

1. リポジトリのクローン: git clone <repository_url>

2. プロジェクトディレクトリへの移動: cd fastmcp-sonarqube-metrics

3. 環境変数の設定: プロジェクトのルートディレクトリに .env ファイルを作成し、以下の内容を記述します：

   SONARQUBE_URL=<your_sonarqube_url>
   SONARQUBE_TOKEN=<your_sonarqube_token>
   TRANSPORT=<stdio or sse>
   GEMINI_API_KEY=<your-gemini-api_key>
   GEMINI_MODEL=<your-gemini-model> (Optional)

   AzureOpenAI を使用する場合、スキーマは OpenAI や Groq と同じです：

   SONARQUBE_URL=<your_sonarqube_url>
   SONARQUBE_TOKEN=<your_sonarqube_token>
   TRANSPORT=<stdio or sse>
   AZURE_OPENAI_API_KEY=<your-azureopenai-api_key>
   AZURE_OPENAI_ENDPOINT=<your-azureopenai-endpoint>
   AZURE_DEPLOYMENT=<your-azureopenai-deployment>
   AZURE_API_VERSION=<your-azureopenai-api_version>

   <your_sonarqube_url> をSonarQubeインスタンスのURL（例: http://localhost:9000）に、<your_sonarqube_token> をSonarQube APIトークンに置き換えてください。

4. サーバーの実行: python server.py

5. クライアントの実行: python client_test.py (オプション、テスト用のみ)

6. クライアントへの接続: 公式ドキュメント に従ってください。

モジュールの使用方法

サーバー (server.py)

server.py モジュールは、SonarQubeメトリクスを取得するためのツールを公開するFastMCPサーバーを定義します。サーバーの初期化、環境変数の読み込み、利用可能なツールの定義、およびSonarQube APIとの通信処理を行います。サーバーを使用するには、SONARQUBE_URL および SONARQUBE_TOKEN 環境変数を設定する必要があります。サーバーは server.py スクリプトを直接実行することで起動します。

クライアント (client_test.py)

client_test.py モジュールは、サーバーと対話するFastMCPクライアントを定義します。ユーザーにSonarQubeプロジェクトキーの入力を求め、サーバーに接続し、get_sonarqube_metrics および get_sonarqube_component_tree_metrics ツールを呼び出して結果を表示します。クライアントを使用するには、client_test.py スクリプトを直接実行し、プロンプトが表示されたら有効なSonarQubeプロジェクトキーを入力し、.envファイルでトランスポートタイプを stdio に設定する必要があります。

Client_tool (client_tool.py)

client_tool.py モジュールは、Tkinterベースのグラフィカルインターフェースを備えたFastMCPクライアントを実装し、SonarQubeサーバーと対話します。起動時に、不要なメッセージを抑制するようにロガーを設定し、環境変数を読み込み、バックグラウンドでチャットバックエンド (ChatBackend) を起動します。これはLLMと、stdio経由でサーバーによって公開されたMCPツールを使用します。フロントエンド (ChatGUI) はTkinterウィンドウを管理し、メッセージ履歴をスクロール可能な領域に表示し、ユーザーがサーバーにコマンドを送信できるようにします（必要に応じて有効なSonarQubeプロジェクトキーの入力を求めます）。クライアントを使用するには、client_tool.py スクリプトを実行し、GUIを通じて対話します。

Client_langchain (client_langchain.py)

client_langchain.py モジュールは、LangChainを介してFastMCPサーバーおよびSonarQubeツールと対話するためのコマンドラインクライアントを提供します。起動時に環境変数を読み込み、選択したLLMを設定します。サーバー (server.py) へのstdio接続を確立し、MCPセッションを初期化し、利用可能なツール（ヘルスチェック、現在および履歴メトリクス、プロジェクト一覧、課題取得）を読み込みます。詳細なシステムプロンプトが各ツールとそのパラメータを説明します。対話ループ内でコンソールからユーザー入力を読み取り、メッセージ履歴を更新し、Reactエージェントを呼び出し、フォーマットされた応答を出力します。

例: 外部プロジェクトで get_sonarqube_metrics ツールを統合する

外部プロジェクトで get_sonarqube_metrics ツールを使用するには、FastMCPサーバーに接続してツールを呼び出すクライアントを作成します。基本的な例を以下に示します：

import asyncio
from fastmcp import Client
from fastmcp.types import TextContent

async def get_metrics(project_key: str):
    server_path = "server.py" # Adjust if necessary
    client = Client(server_path)
    try:
        async with client:
            result = await client.call_tool(
                "get_sonarqube_metrics", {"project_key": project_key}
            )
            if result:
                content = result[0]
                if isinstance(content, TextContent):
                    metrics = json.loads(content.text)
                    print(metrics)
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(get_metrics("your-project-key")) # Replace with your project key

この例は、クライアントを作成し、サーバーに接続し、プロジェクトキーを指定して get_sonarqube_metrics ツールを呼び出し、結果を処理する方法を示しています。server_path 変数は、環境内の server.py スクリプトの実際の場所に合わせて調整する必要があります。

ArchAI-SonarQube チャット (GUI)

stdio経由でFastMCPサーバーに接続する軽量なTkinterクライアントです。SonarQubeメトリクスのクエリ、コンポーネントツリーの閲覧、LLM駆動のアシスタントによるヘルスチェック実行のためのリアルタイムチャットインターフェースを提供します。

TRANSPORT=SSE での使用

GUIを起動する前に TRANSPORT 環境変数を設定することで、クライアントのトランスポート層をServer-Sent Events (SSE) に切り替えることができます。これにより、FastMCPサーバーからのリアルタイムな単方向更新が可能になります。 サーバーがSSEモードで起動されると、ポート 8001 で永続的なHTTP接続が開かれます。これにより、MCP Inspectorなどの互換性のあるインターフェース経由で接続できます。

1. SSEモードでサーバーを起動

   uv run mcp dev "<server_name>" 

2. MCP Inspectorを開く ブラウザでMCP Inspectorを起動するためのリンク（例: http://127.0.0.1:6274）が提供されます。

3. MCP InspectorでSSEを設定

   • トランスポートタイプとして SSE を選択

   • URLを入力: http://localhost:8001/sse

4. 接続を開始

5. 利用可能なツールを閲覧 Tools セクションに以下が表示されます：

   • get_status

   • get_sonarqube_metrics

   • get_sonarqube_metrics_history

   • get_sonarqube_component_tree_metrics

   • list_projects

   • get_project_issues

6. ツールを選択して呼び出す 例えば、get_project_issues を選択し、以下を指定します：

   • project_key: SonarQubeプロジェクトキー

   • issue_type (オプション): 例: BUG, CODE_SMELL

   • severity (オプション): 例: MAJOR, CRITICAL

   • resolved (オプション): true または false

   • limit (オプション): 返される課題の最大数

7. 実行して結果を取得 サーバーは適切なSonarQube APIを呼び出し、フォーマットされたJSON応答を返します。

Claude Desktop での使用

fastmcpを使用して、このサーバーをClaude Desktopに直接インストールできます：

1. FastMCPがインストールされていることを確認します (pip install fastmcp または uv pip install fastmcp)。

2. 使用したいMCPサーバーに合わせてClaude for Desktopを設定します（WindowsでVSCodeを使用する場合）： code $env:AppData\Claude\claude_desktop_config.json

3. サーバーを追加して保存します：

{
    "mcpServers": {
        "fastmcp-sonarqube-metrics": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/fastmcp-sonarqube-metrics",
                "run",
                "server.py"
            ]
        }
    }
}

4. 起動するには以下を実行します：

 uv --directory  /ABSOLUTE/PATH/TO/PARENT/FOLDER/fastmcp-sonarqube-metrics run server.py

5. Claude Desktopが実行されていた場合は再起動します。これで "FastMCP SonarQube Metrics" ツールが利用可能になるはずです。

機能分析

1. システムの主な責務

システムの主な責務は、ユーザーとSonarQube APIの間のブリッジとして機能し、プロジェクトの品質メトリクスを取得するための簡略化された方法を提供することです。SonarQube APIの複雑さをカプセル化し、自動化されたワークフローに簡単に呼び出して統合できる一連のツールを提供します。コアサービスには、メトリクスの取得、履歴データの取得、SonarQubeプロジェクト内のコンポーネントレベルのメトリクスの探索が含まれます。基盤となるサービスはFastMCPサーバーであり、ツール定義とクライアント・サーバー間の通信を管理します。

2. システムが解決する問題

このシステムは、ユーザーがSonarQube APIと直接対話することなく、プログラムからSonarQubeデータにアクセスするという問題を解決します。SonarQubeメトリクスの自動レポート作成、分析、および他のシステムとの統合の必要性に対処します。具体的には、以下のようなタスクを簡素化します：

• コード品質メトリクスに関する定期的なレポートの生成。

• 時間経過に伴うコード品質の傾向の監視。

• プロジェクト内の問題のあるコンポーネントの特定。

• SonarQubeデータと他の開発ツールとの統合。

アーキテクチャは、SonarQube APIの複雑さを抽象化し、データアクセスの一貫したインターフェースを提供する、明確に定義された一連のツールを提供することでこれらの問題を解決します。

3. モジュールとコンポーネントの相互作用

システムは、クライアントとサーバーの2つの主要コンポーネントで構成されています。クライアントはサーバーへのリクエストを開始し、実行するツールと入力パラメータを指定します。サーバーはリクエストを受信し、SonarQube APIと対話し、データを処理し、結果をクライアントに送り返します。

クライアントとサーバー間の相互作用は、メッセージパッシングとシリアル化を処理するFastMCPフレームワークによって促進されます。サーバーは @mcp.tool() デコレータを使用して利用可能なツールを定義し、関数を呼び出し可能なエンドポイントとして登録します。クライアントは client.call_tool() メソッドを使用してこれらのツールを呼び出し、ツール名と入力パラメータを含むメッセージをサーバーに送信します。

サーバーは httpx ライブラリを使用して、SonarQube APIへの非同期HTTPリクエストを行います。実行されるツールとクライアントから提供された入力パラメータに基づいて、API URLとリクエストパラメータを構築します。その後、サーバーはSonarQube APIからのJSON応答を解析し、関連するメトリクス値を抽出します。

4. ユーザー向け機能とシステム向け機能

システムのユーザー向け機能はクライアントアプリケーション (client_test.py) であり、SonarQubeメトリクス取得ツールを呼び出すためのコマンドラインインターフェースを提供します。ユーザーはSonarQubeプロジェクトキーや、オプションで日付範囲やメトリクスキーなどのパラメータを指定してクライアントと対話します。クライアントは取得したメトリクスを人間が読める形式で表示します。

システム向け機能は、server.py で定義されたサーバーサイドツール (get_sonarqube_metrics, get_sonarqube_metrics_history, get_sonarqube_component_tree_metrics) です。これらのツールは、SonarQube APIとの対話、データ処理、フォーマットを処理します。これらはエンドユーザーには直接見えませんが、システムのコア機能を提供する上で不可欠です。

@mcp.tool() デコレータは、すべてのツール関数に共通の動作を体系的に適用し、FastMCPサーバーに登録され、クライアントからアクセスできるようにします。さらに、Annotated と Field を使用することで、すべてのツール間で一貫したパラメータ定義とドキュメント化が保証されます。

適用されたアーキテクチャパターンと設計原則

• クライアント・サーバーアーキテクチャ: プロジェクトは、クライアントがサーバーにサービスを要求するクライアント・サーバーアーキテクチャに従います。

• メッセージパッシング: FastMCPフレームワークは、メッセージパッシングを使用してクライアントとサーバー間の通信を促進します。

• 非同期プログラミング: asyncio と httpx の使用により