FastMCP SonarQube Metrics

FastMCP SonarQube-Metriken

Überblick

Dieses Projekt bietet eine Reihe von Tools zum Abrufen von Informationen zu SonarQube-Projekten mithilfe des FastMCP-Frameworks (Fast Model Context Protocol). Es dient als Schnittstelle zu SonarQube und ermöglicht Benutzern den programmgesteuerten Zugriff auf Metriken, historische Daten und Komponentenbaummetriken für bestimmte Projekte. Dieser automatisierte Zugriff ermöglicht die Berichterstellung, Analyse und Integration von SonarQube-Daten in andere Systeme.

Das Projekt zeichnet sich durch einen vereinfachten, nachrichtenbasierten Ansatz für die Interaktion mit der SonarQube-API aus und abstrahiert die Komplexität direkter API-Aufrufe und der Datenverarbeitung. Es richtet sich an Entwickler, DevOps-Ingenieure und Analysten, die SonarQube-Daten in ihre Workflows integrieren oder individuelle Berichtslösungen erstellen müssen.

Dieses Repository beherbergt insbesondere die Client- und Serverkomponenten, die die Kommunikation und den Datenabruf ermöglichen. Der Server stellt Tools zum Abrufen von Daten aus SonarQube bereit, während der Client eine Befehlszeilenschnittstelle bereitstellt, über die Benutzer diese Tools aufrufen und die Ergebnisse anzeigen können. Jedes interne Modul trägt zu diesem Ziel bei, indem es spezifische Funktionen wie API-Interaktion, Datenverarbeitung und Client-Server-Kommunikation kapselt.

Der im Projekt enthaltene Client dient nur zum Testen der Funktionsweise des Codes. Wir empfehlen die Verwendung von Claude Desktop oder die Entwicklung eines eigenen benutzerdefinierten Clients.

BEDENKEN SIE, DASS DIESES REPO NOCH IN ARBEIT IST UND EINIGE FUNKTIONEN MÖGLICHERWEISE NICHT PERFEKT SIND.

Unterstützte MCP-Tools

• get_status : Führt eine Integritätsprüfung der konfigurierten SonarQube-Instanz durch.
• list_projects : Listet alle zugänglichen SonarQube-Projekte auf, optional gefiltert nach Name oder Schlüssel.
• get_sonarqube_metrics : Ruft angegebene Metriken (Fehler, Schwachstellen, Code-Smells, Abdeckung, Duplizierungsdichte) für einen bestimmten SonarQube-Projektschlüssel ab.
• get_sonarqube_metrics_history : Ruft historische Metriken (Bugs, Schwachstellen, Code Smells, Abdeckung, Duplizierungsdichte) für ein bestimmtes SonarQube-Projekt mithilfe von /api/measures/search_history ab. Optionale Datumsfilter können angewendet werden.
• get_sonarqube_component_tree_metrics : Ruft Metrikwerte für alle Komponenten (z. B. Dateien oder Verzeichnisse) in einem Projekt mithilfe von /api/measures/component_tree ab. Verarbeitet automatisch die Paginierung, um alle Ergebnisse abzurufen.
• get_project_issues : Ruft SonarQube-Probleme für ein bestimmtes Projekt ab, optional gefiltert nach Typ, Schweregrad und Lösungsstatus. Gibt bis zu einer bestimmten Anzahl von Ergebnissen zurück (Standard: 10).

Technologie-Stack

• Sprache: Python
• Frameworks: FastMCP
• Bibliotheken: httpx, pydantic, dotenv, asyncio, json, pathlib, typing, base64
• Tools: SonarQube API

Verzeichnisstruktur

Erste Schritte

Voraussetzungen

• Python 3.7+
• SonarQube-Instanz mit API-Zugriff
• Ein SonarQube-API-Token mit entsprechenden Berechtigungen
• FastMCP installiert ( pip install fastmcp )
• httpx installiert ( pip install httpx )
• pydantic installiert ( pip install pydantic )
• python-dotenv installiert ( pip install python-dotenv )

Allgemeine Build-Schritte

1. Klonen Sie das Repository: git clone <repository_url>
2. Navigieren Sie zum Projektverzeichnis: cd fastmcp-sonarqube-metrics
3. Umgebungsvariablen einrichten: Erstellen Sie im Stammverzeichnis des Projekts eine .env Datei mit folgendem Inhalt:
   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>
   Ersetzen Sie <your_sonarqube_url> durch die URL Ihrer SonarQube-Instanz (z. B. http://localhost:9000 ) und <your_sonarqube_token> durch Ihr SonarQube-API-Token.
4. Führen Sie den Server aus: python server.py
5. Führen Sie den Client aus: python client_test.py(Optional, nur zum Testen)
6. Stellen Sie eine Verbindung zu Ihrem Client her: Befolgen Sie die offizielle Dokumentation

Modulnutzung

Server ( server.py )

Das Modul server.py definiert den FastMCP-Server, der Tools zum Abrufen von SonarQube-Metriken bereitstellt. Es initialisiert den Server, lädt Umgebungsvariablen, definiert die verfügbaren Tools und übernimmt die Kommunikation mit der SonarQube-API. Um den Server zu verwenden, müssen Sie die Umgebungsvariablen SONARQUBE_URL und SONARQUBE_TOKEN festlegen. Der Server wird durch direkte Ausführung des Skripts server.py gestartet.

Client ( client_test.py )

Das Modul client_test.py definiert den FastMCP-Client, der mit dem Server interagiert. Es fordert den Benutzer zur Eingabe eines SonarQube-Projektschlüssels auf, stellt eine Verbindung zum Server her, ruft die Tools get_sonarqube_metrics und get_sonarqube_component_tree_metrics auf und zeigt die Ergebnisse an. Um den Client zu verwenden, müssen Sie das Skript client_test.py direkt ausführen und bei entsprechender Aufforderung einen gültigen SonarQube-Projektschlüssel angeben.

Client_tool ( client_tool.py )

Das Modul client_tool.py implementiert den FastMCP-Client mit einer Tkinter-basierten grafischen Oberfläche zur Interaktion mit dem SonarQube-Server. Beim Start konfiguriert es Logger, um nicht notwendige Nachrichten zu unterdrücken, lädt Umgebungsvariablen und startet im Hintergrund das Chat-Backend (ChatBackend). Dieses nutzt ein LLM und die vom Server über stdio bereitgestellten MCP-Tools. Das Frontend (ChatGUI) verwaltet das Tkinter-Fenster, zeigt den Nachrichtenverlauf in einem scrollbaren Bereich an und ermöglicht dem Benutzer das Senden von Befehlen an den Server – wobei bei Bedarf ein gültiger SonarQube-Projektschlüssel abgefragt wird. Um den Client zu verwenden, führen Sie einfach das Skript client_tool.py aus und interagieren Sie über die GUI.

Client_langchain ( client_langchain.py )

Das Modul client_langchain.py bietet einen Kommandozeilen-Client für die Interaktion mit dem FastMCP-Server und den SonarQube-Tools über LangChain. Beim Start lädt es Umgebungsvariablen und konfiguriert das gewählte LLM. Es stellt eine Standardverbindung zum Server ( server.py ) her, initialisiert die MCP-Sitzung und lädt verfügbare Tools (Integritätscheck, aktuelle und historische Metriken, Projektliste, Problemabfrage). Eine detaillierte Systemeingabeaufforderung beschreibt jedes Tool und seine Parameter. In einer interaktiven Schleife liest es Benutzereingaben aus der Konsole, aktualisiert den Nachrichtenverlauf, ruft den React-Agenten auf und gibt die formatierte Antwort aus.

Beispiel: Integration des Tools get_sonarqube_metrics in ein externes Projekt

Um das Tool get_sonarqube_metrics in einem externen Projekt zu verwenden, können Sie einen Client erstellen, der eine Verbindung zum FastMCP-Server herstellt und das Tool aufruft. Hier ist ein einfaches Beispiel:

Dieses Beispiel zeigt, wie Sie einen Client erstellen, eine Verbindung zum Server herstellen, das Tool get_sonarqube_metrics mit einem Projektschlüssel aufrufen und die Ergebnisse verarbeiten. Sie müssen die Variable server_path an den tatsächlichen Speicherort des Skripts server.py in Ihrer Umgebung anpassen.

ArchAI-SonarQube-Chat (GUI)

Ein leichtgewichtiger Tkinter-Client, der über stdio eine Verbindung zum FastMCP-Server herstellt und eine Echtzeit-Chat-Schnittstelle zum Abfragen von SonarQube-Metriken, Durchsuchen von Komponentenbäumen und Ausführen von Integritätsprüfungen über einen LLM-gesteuerten Assistenten bereitstellt.

Verwendung mit TRANSPORT=SSE

Sie können die Transportschicht des Clients auf Server-Sent Events (SSE) umstellen, indem Sie vor dem Start der GUI die Umgebungsvariable TRANSPORT setzen. Dies ermöglicht unidirektionale Echtzeit-Updates vom FastMCP-Server. Beim Start des Servers im SSE-Modus wird eine persistente HTTP-Verbindung an Port 8001 geöffnet. Dies ermöglicht die Verbindung über kompatible Schnittstellen wie MCP Inspector.*

1. Starten Sie den Server im SSE-Modus
   uv run mcp dev "<server_name>"
2. Öffnen Sie MCP Inspector. Ein Link (z. B. http://127.0.0.1:6274 ) wird bereitgestellt, um MCP Inspector in Ihrem Browser zu starten.
3. Konfigurieren Sie SSE im MCP Inspector
   • Wählen Sie SSE als Transporttyp
   • Geben Sie die URL ein: http://localhost:8001/sse
4. Verbindung herstellen
5. Durchsuchen Sie die verfügbaren Tools . Im Abschnitt „Tools“ sehen Sie:
   • get_status
   • get_sonarqube_metrics
   • get_sonarqube_metrics_history
   • get_sonarqube_component_tree_metrics
   • list_projects
   • get_project_issues
6. Wählen Sie ein Tool aus und rufen Sie es auf. Wählen Sie beispielsweise „get_project_issues“ und geben Sie Folgendes ein:
   • project_key : der SonarQube-Projektschlüssel
   • issue_type (optional): zB BUG , CODE_SMELL
   • severity (optional): zB MAJOR , CRITICAL
   • resolved (optional): true oder false
   • limit (optional): Maximale Anzahl der zurückzugebenden Probleme
7. Ausführen und Ergebnisse abrufen Der Server ruft die entsprechende SonarQube-API auf und gibt eine formatierte JSON-Antwort zurück.

Verwendung mit Claude Desktop

Sie können diesen Server mit fastmcp direkt in Claude Desktop installieren:

1. Stellen Sie sicher, dass FastMCP installiert ist (pip install fastmcp oder uv pip install fastmcp).
2. Konfigurieren Sie Claude für Desktop für die MCP-Server, die Sie verwenden möchten (in Windows mit VSCode): code $env:AppData\Claude\claude_desktop_config.json
3. Fügen Sie Ihren Server hinzu und speichern Sie dann:

4. So starten Sie es:

5. Starten Sie Claude Desktop neu, falls es ausgeführt wurde. Das Tool „FastMCP SonarQube Metrics“ sollte nun verfügbar sein.

Funktionale Analyse

1. Hauptaufgaben des Systems

Die Hauptaufgabe des Systems besteht darin, als Brücke zwischen dem Benutzer und der SonarQube-API zu fungieren und so den vereinfachten Abruf von Projektqualitätsmetriken zu ermöglichen. Es kapselt die Komplexität der SonarQube-API und bietet eine Reihe von Tools, die einfach aufgerufen und in automatisierte Workflows integriert werden können. Zu den Kerndiensten gehören das Abrufen von Metriken, das Abrufen historischer Daten und die Untersuchung von Metriken auf Komponentenebene innerhalb eines SonarQube-Projekts. Der grundlegende Dienst ist der FastMCP-Server, der die Tooldefinitionen und die Client-Server-Kommunikation verwaltet.

2. Probleme, die das System löst

Das System löst das Problem des programmgesteuerten Zugriffs auf SonarQube-Daten, ohne dass Benutzer direkt mit der SonarQube-API interagieren müssen. Es erfüllt den Bedarf an automatisierter Berichterstattung, Analyse und Integration von SonarQube-Metriken in andere Systeme. Insbesondere vereinfacht es Aufgaben wie:

• Erstellen Sie regelmäßige Berichte zu Codequalitätsmetriken.
• Überwachung von Trends in der Codequalität im Laufe der Zeit.
• Identifizieren problematischer Komponenten innerhalb eines Projekts.
• Integration von SonarQube-Daten mit anderen Entwicklungstools.

Die Architektur löst diese Probleme, indem sie eine Reihe klar definierter Tools bereitstellt, die die Komplexität der SonarQube-API abstrahieren und eine konsistente Schnittstelle für den Datenzugriff bereitstellen.

3. Zusammenspiel von Modulen und Komponenten

Das System besteht aus zwei Hauptkomponenten: dem Client und dem Server. Der Client initiiert Anfragen an den Server und gibt dabei das auszuführende Tool sowie alle Eingabeparameter an. Der Server empfängt die Anfrage, interagiert mit der SonarQube-API, verarbeitet die Daten und sendet die Ergebnisse an den Client zurück.

Die Interaktion zwischen Client und Server wird durch das FastMCP-Framework erleichtert, das die Nachrichtenübermittlung und Serialisierung übernimmt. Der Server definiert die verfügbaren Tools mithilfe des Dekorators @mcp.tool() , der die Funktionen als aufrufbare Endpunkte registriert. Der Client ruft diese Tools mithilfe der Methode client.call_tool() auf, die eine Nachricht mit dem Toolnamen und den Eingabeparametern an den Server sendet.

Der Server verwendet die httpx Bibliothek, um asynchrone HTTP-Anfragen an die SonarQube-API zu senden. Er erstellt die API-URLs und Anfrageparameter basierend auf dem ausgeführten Tool und den vom Client bereitgestellten Eingabeparametern. Anschließend analysiert der Server die JSON-Antworten der SonarQube-API und extrahiert die relevanten Metrikwerte.

4. Benutzerorientierte vs. systemorientierte Funktionalitäten

Die benutzerorientierte Funktionalität des Systems ist die Client-Anwendung ( client_test.py ), die eine Befehlszeilenschnittstelle zum Aufrufen der SonarQube-Tools zum Abrufen von Metriken bereitstellt. Benutzer interagieren mit dem Client, indem sie einen SonarQube-Projektschlüssel und optional weitere Parameter wie Datumsbereiche oder Metrikschlüssel angeben. Der Client zeigt die abgerufenen Metriken anschließend in einem lesbaren Format an.

Die systemseitigen Funktionen sind die serverseitigen Tools ( get_sonarqube_metrics , get_sonarqube_metrics_history , get_sonarqube_component_tree_metrics ), die in server.py definiert sind. Diese Tools übernehmen die Interaktion mit der SonarQube-API, die Datenverarbeitung und die Formatierung. Sie sind für Endbenutzer nicht direkt sichtbar, aber für die Bereitstellung der Kernfunktionalität des Systems unerlässlich.

Der @mcp.tool() Dekorator wendet systematisch gemeinsame Verhaltensweisen auf alle Toolfunktionen an und stellt sicher, dass diese beim FastMCP-Server registriert und für Clients zugänglich sind. Darüber hinaus gewährleistet die Verwendung von Annotated und Field eine konsistente Parameterdefinition und Dokumentation über alle Tools hinweg.

Angewandte Architekturmuster und Designprinzipien

• Client-Server-Architektur: Das Projekt folgt einer Client-Server-Architektur, bei der der Client Dienste vom Server anfordert.
• Nachrichtenübermittlung: Das FastMCP-Framework erleichtert die Kommunikation zwischen Client und Server durch Nachrichtenübermittlung.
• Asynchrone Programmierung: Die Verwendung von asyncio und httpx ermöglicht asynchrone Vorgänge und verbessert so die Leistung und Reaktionsfähigkeit der Anwendung.
• Konfiguration über Umgebungsvariablen: Die SonarQube-URL und das Token werden mithilfe von Umgebungsvariablen konfiguriert, wodurch die Bereitstellung und Verwaltung der Anwendung in verschiedenen Umgebungen erleichtert wird.
• Toolbasiertes Design: Der Server stellt Funktionen über klar definierte Tools bereit, sodass das Hinzufügen oder Ändern von Funktionen einfach ist.
• Fehlerbehandlung: Das Projekt umfasst eine umfassende Fehlerbehandlung, um potenzielle Probleme wie Netzwerkfehler, API-Fehler und ungültige Daten ordnungsgemäß zu bewältigen.
• Protokollierung: Die Verwendung des logging liefert detaillierte Protokolle, die beim Debuggen und Überwachen helfen.
• Abhängigkeitsinjektion: Obwohl nicht explizit als Framework implementiert, ermöglicht die Konfiguration der SonarQube-URL und des Tokens über Umgebungsvariablen einen einfachen Austausch verschiedener SonarQube-Instanzen ohne Änderung des Codes.

Code-Qualitätsanalyse

Da kein SonarQube-Bericht vorliegt, ist keine umfassende Analyse der Codequalität möglich. Abhängig von der Codestruktur und -funktionalität ergeben sich jedoch folgende potenzielle Problembereiche:

• Granularität der Fehlerbehandlung: Obwohl eine Fehlerbehandlung vorhanden ist, könnten die spezifischen Fehlermeldungen verbessert werden, um dem Benutzer mehr verwertbare Informationen bereitzustellen.
• Testabdeckung: Der bereitgestellte Code enthält keine Unit-Tests. Um die Zuverlässigkeit und Korrektheit des Codes sicherzustellen, sollte eine Testabdeckung hinzugefügt werden.
• Code-Duplizierung: Es gibt möglicherweise Möglichkeiten, die Code-Duplizierung zu reduzieren, indem gemeinsame Logik in wiederverwendbare Funktionen oder Klassen extrahiert wird.

Schwächen und Verbesserungsbereiche

• Verbessern Sie die Klarheit der Fehlermeldungen: Verbessern Sie die Fehlermeldungen, um den Benutzern spezifischere Anleitungen zur Problemlösung zu geben.
• Unit-Tests hinzufügen: Implementieren Sie Unit-Tests für die serverseitigen Tools, um deren Richtigkeit und Zuverlässigkeit sicherzustellen.
• Gemeinsame Logik umgestalten: Duplizierten Code identifizieren und in wiederverwendbare Funktionen oder Klassen umgestalten.
• Implementieren Sie eine Eingabevalidierung: Fügen Sie den serverseitigen Tools eine Eingabevalidierung hinzu, um die Verarbeitung ungültiger Daten zu verhindern.
• Dokumentation verbessern: Fügen Sie eine ausführlichere Dokumentation für die serverseitigen Tools hinzu, einschließlich Beispielen und Gebrauchsanweisungen.
• Implementieren Sie ein robustes Konfigurationssystem: Erwägen Sie die Verwendung eines robusteren Konfigurationssystems, beispielsweise einer Konfigurationsdatei oder einer dedizierten Einstellungsklasse, anstatt sich ausschließlich auf Umgebungsvariablen zu verlassen.
• Unterstützung für zusätzliche SonarQube-API-Endpunkte hinzufügen: Erweitern Sie das System, um zusätzliche SonarQube-API-Endpunkte zu unterstützen, z. B. solche zum Verwalten von Projekten, Regeln oder Qualitätsprofilen.
• Implementieren Sie eine benutzerfreundlichere Client-Schnittstelle: Erwägen Sie die Entwicklung einer grafischen Benutzeroberfläche (GUI) oder einer anspruchsvolleren Befehlszeilenschnittstelle (CLI) für die Client-Anwendung.
• Beheben Sie potenzielle Sicherheitslücken: Überprüfen Sie den Code auf potenzielle Sicherheitslücken, beispielsweise im Zusammenhang mit der Eingabevalidierung oder Authentifizierung.

Weitere Untersuchungsgebiete

• Leistungsengpässe: Untersuchen Sie potenzielle Leistungsengpässe in den serverseitigen Tools, beispielsweise im Zusammenhang mit der API-Anforderungsverarbeitung oder der Datenverarbeitung.
• Überlegungen zur Skalierbarkeit: Bewerten Sie die Skalierbarkeit des Systems und identifizieren Sie potenzielle Verbesserungsbereiche, z. B. die Verwendung einer Nachrichtenwarteschlange oder eines verteilten Caching-Systems.
• Integrationen mit externen Systemen: Erkunden Sie mögliche Integrationen mit anderen Entwicklungstools, wie etwa CI/CD-Systemen oder Issue-Trackern.
• Erweiterte Funktionen: Erforschen und implementieren Sie erweiterte Funktionen, wie etwa die Echtzeitüberwachung von Metriken oder die automatisierte Analyse der Codequalität.
• Code Smells und geringe Testabdeckung: Führen Sie eine gründliche Analyse der Codebasis durch, um Code Smells und Bereiche mit geringer Testabdeckung zu identifizieren und zu beheben.

Namensnennung

Erstellt mit Unterstützung von ArchAI , einem automatisierten Dokumentationssystem.