FastMCP SonarQube Metrics

FastMCP SonarQube メトリクス

概要

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

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

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

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

このリポジトリは現在開発中であり、一部の機能は完璧ではない可能性があることに留意してください。

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

• get_status : 構成された 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

ディレクトリ構造

はじめる

前提条件

• 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> OPENAI_API_KEY=<your-openai-api_key>
   <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 プロジェクトキーを入力する必要があります。

クライアントツール ( client_tool.py )

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

クライアント言語チェーン ( client_langchain.py )

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

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

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

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

ArchAI-SonarQube チャット (GUI)

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

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. 利用可能なツールを参照する ツールセクションには次のものが表示されます。
   • 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. サーバーを追加して保存します。

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

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

コード品質分析

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

• **エラー処理の細分性:**エラー処理は存在しますが、特定のエラー メッセージを改善して、ユーザーにさらに実用的な情報を提供できます。
• **テストカバレッジ：**提供されたコードにはユニットテストが含まれていません。コードの信頼性と正確性を確保するために、テストカバレッジを追加する必要があります。
• **コードの重複:**共通ロジックを再利用可能な関数またはクラスに抽出することで、コードの重複を削減できる可能性があります。

弱点と改善点

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

さらなる調査分野

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

帰属

自動ドキュメント化システムであるArchAIのサポートにより生成されました。