FastMCP SonarQube Metrics

FastMCP SonarQube Metrics

概要

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

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

このリポジトリには、通信とデータ取得を担うクライアントおよびサーバーのコンポーネントが含まれています。サーバーは SonarQube からデータを取得するツールを公開し、クライアントはそれらのツールを呼び出して結果を表示するためのコマンドラインインターフェースを提供します。各内部モジュールは、API とのやり取り、データ処理、クライアントとサーバーの通信など、特定の機能をカプセル化することで、この目的に貢献します。

このプロジェクトに含まれるクライアントは、コードの動作をテストするためだけのものです。Claude Desktop の使用、または独自のカスタムクライアントの開発をおすすめします。

ご注意ください。このリポジトリは開発中のため、一部の機能は完全ではない場合があります。

ホスト型デプロイ

ホスト型デプロイは 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)
   

   OpenAI と Groq でもスキーマは同じです。AzureOpenAI を使用する場合は、次のようにします。

   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.py）

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

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 Chat（GUI）

FastMCP サーバーに標準入出力で接続する軽量な Tkinter クライアントです。LLM 駆動のアシスタントを通じて、SonarQube メトリクスの問い合わせ、コンポーネントツリーの閲覧、ヘルスチェックの実行ができるリアルタイムのチャットインターフェースを提供します。

TRANSPORT=SSE での使用

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

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

   uv run mcp dev "<server_name>" 
   

2. Open MCP Inspector A link (e.g. http://127.0.0.1:6274) will be provided to launch MCP Inspector in your browser.

3. Configure SSE in MCP Inspector

   • Select SSE as the transport type
   • Enter the URL: http://localhost:8001/sse

4. Initiate the connection

5. Browse available tools In the Tools section you will see:

   • get_status
   • get_sonarqube_metrics
   • get_sonarqube_metrics_history
   • get_sonarqube_component_tree_metrics
   • list_projects
   • get_project_issues

6. Select and invoke a tool For example, choose get_project_issues and provide:

   • project_key: the SonarQube project key
   • issue_type (optional): e.g. BUG, CODE_SMELL
   • severity (optional): e.g. MAJOR, CRITICAL
   • resolved (optional): true or false
   • limit (optional): maximum number of issues to return

7. Execute and retrieve results The server will call the appropriate SonarQube API and return a formatted JSON response.

Usage with Claude Desktop

You can install this server directly into Claude Desktop using fastmcp:

1. Make sure FastMCP is installed (pip install fastmcp or uv pip install fastmcp).
2. Configure Claude for Desktop for whichever MCP servers you want to use (in Windows using VSCode): code $env:AppData\Claude\claude_desktop_config.json
3. Add your server and then save:

{
    "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. ユーザー向け機能とシステム向け機能

ユーザー向け機能は、SonarQube のメトリック取得ツールを呼び出すためのコマンドラインインターフェースを提供するクライアントアプリケーション（client_test.py）です。ユーザーは、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 を使用することで非同期処理が可能になり、アプリケーションのパフォーマンスと応答性が向上します。
• 環境変数による設定： SonarQube の URL とトークンは環境変数で設定されるため、さまざまな環境でのアプリケーションのデプロイと管理が容易になります。
• ツールベースの設計： サーバーは明確に定義されたツールを通じて機能を公開するため、機能を簡単に追加または変更できます。
• エラー処理： ネットワークエラー、API エラー、無効なデータなどの潜在的な問題を適切に処理するため、包括的なエラー処理を実装しています。
• ロギング： logging モジュールを使用して詳細なログを記録し、デバッグと監視に役立てています。
• 依存性注入： フレームワークとして明示的に実装されているわけではありませんが、環境変数を通じて SonarQube の URL とトークンを設定することで、コードを変更せずに別の SonarQube インスタンスへ簡単に切り替えられます。

コード品質分析

SonarQube のレポートがないため、包括的なコード品質分析は実施できません。ただし、コードの構造と機能に基づくと、次のような懸念事項が考えられます。

• エラー処理の詳細度： エラー処理は実装されていますが、ユーザーが具体的な対応を取れるよう、エラーメッセージを改善できる可能性があります。
• テストカバレッジ： 提供されたコードにはユニットテストが含まれていません。コードの信頼性と正確性を確保するため、テストカバレッジを追加する必要があります。
• コードの重複： 共通ロジックを再利用可能な関数やクラスに切り出すことで、コードの重複を減らせる可能性があります。

弱点と改善領域

• エラーメッセージを明確にする： 問題の解決方法について、より具体的な指針をユーザーに示すよう、エラーメッセージを改善します。
• ユニットテストを追加する： サーバー側ツールの正確性と信頼性を確保するため、ユニットテストを実装します。
• 共通ロジックをリファクタリングする： 重複したコードを特定し、再利用可能な関数やクラスにリファクタリングします。
• 入力検証を実装する： 無効なデータが処理されないよう、サーバー側ツールに入力検証を追加します。
• ドキュメントを改善する： 例や使用方法の説明を含め、サーバー側ツールの詳細なドキュメントを追加します。
• より堅牢な設定システムを実装する： 環境変数だけに依存するのではなく、設定ファイルや専用の設定クラスなど、より堅牢な設定システムの使用を検討します。
• SonarQube API エンドポイントのサポートを追加する： プロジェクト、ルール、品質プロファイルの管理などに使用する SonarQube API エンドポイントの追加をサポートするよう、システムを拡張します。
• より使いやすいクライアントインターフェースを実装する： クライアントアプリケーション向けに、グラフィカルユーザーインターフェース（GUI）や、より高度なコマンドラインインターフェース（CLI）の開発を検討します。
• 潜在的なセキュリティ脆弱性に対処する： 入力検証や認証に関連するものなど、潜在的なセキュリティ脆弱性がないかコードを確認します。

さらに調査すべき領域

• パフォーマンスのボトルネック： API リクエストの処理やデータ処理に関するものなど、サーバー側ツールの潜在的なパフォーマンスのボトルネックを調査します。
• スケーラビリティの検討： システムのスケーラビリティを評価し、メッセージキューや分散キャッシュシステムの使用など、改善できる可能性のある領域を特定します。
• 外部システムとの連携： CI/CD システムや課題トラッカーなど、他の開発ツールとの連携の可能性を検討します。
• 高度な機能： リアルタイムのメトリクス監視や自動コード品質分析など、高度な機能を調査して実装します。
• コードの不吉な臭いと低いテストカバレッジ： コードベースを徹底的に分析し、コードの不吉な臭いやテストカバレッジの低い領域を特定して対処します。

謝辞

自動ドキュメントシステムである ArchAI の支援を受けて生成されました。