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

├── client_test.py - Client application for testing and interacting with the server.
├── server.py - Server application exposing tools to retrieve SonarQube metrics.
├── .env - Environment configuration file (stores SonarQube URL and token).
└── README.md - Project documentation.

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

Klonen Sie das Repository: git clone <repository_url>
Navigieren Sie zum Projektverzeichnis: cd fastmcp-sonarqube-metrics
Umgebungsvariablen einrichten: Erstellen Sie im Stammverzeichnis des Projekts eine .env Datei mit folgendem Inhalt:
SONARQUBE_URL=<your_sonarqube_url> SONARQUBE_TOKEN=<your_sonarqube_token>
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.
Führen Sie den Server aus: python server.py
Führen Sie den Client aus: python client_test.py(Optional, nur zum Testen)
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.

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:

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

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.

Verwendung mit Claude Desktop

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

Stellen Sie sicher, dass FastMCP installiert ist (pip install fastmcp oder uv pip install fastmcp).
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
Fügen Sie Ihren Server hinzu und speichern Sie dann:

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

So starten Sie es:

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

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 besteht möglicherweise die Möglichkeit, 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.

FastMCP SonarQube Metrics

Integrations