Métricas de SonarQube de FastMCP

Descripción general

Este proyecto proporciona un conjunto de herramientas para recuperar información sobre proyectos de SonarQube mediante el marco FastMCP (Fast Model Context Protocol). Sirve como interfaz para SonarQube, permitiendo a los usuarios acceder programáticamente a métricas, datos históricos y métricas del árbol de componentes para proyectos específicos. Este acceso automatizado facilita la generación de informes, el análisis y la integración de los datos de SonarQube con otros sistemas.

El proyecto se distingue por ofrecer un enfoque simplificado y basado en mensajes para interactuar con la API de SonarQube, eliminando las complejidades de las llamadas directas a la API y la gestión de datos. Está diseñado para desarrolladores, ingenieros de DevOps y analistas que necesitan incorporar datos de SonarQube en sus flujos de trabajo o crear soluciones de informes personalizadas.

Este repositorio alberga específicamente los componentes de cliente y servidor que facilitan la comunicación y la recuperación de datos. El servidor expone herramientas para obtener datos de SonarQube, mientras que el cliente proporciona una interfaz de línea de comandos para que los usuarios invoquen estas herramientas y muestren los resultados. Cada módulo interno contribuye a este objetivo al encapsular funcionalidades específicas, como la interacción con la API, el procesamiento de datos y la comunicación cliente-servidor.

El cliente incluido en el proyecto es solo para probar cómo funciona el código; recomendamos utilizar Claude Desktop o desarrollar su propio cliente personalizado.

RECUERDE, ESTE REPO ESTÁ EN PROGRESO, ALGUNAS CARACTERÍSTICAS PUEDEN NO SER PERFECTAS.

Herramientas MCP compatibles

get_status : realiza una comprobación del estado de la instancia de SonarQube configurada.
list_projects : enumera todos los proyectos SonarQube accesibles, opcionalmente filtrados por nombre o clave.
get_sonarqube_metrics : recupera métricas especificadas (errores, vulnerabilidades, errores de código, cobertura, densidad de duplicación) para una clave de proyecto SonarQube determinada.
get_sonarqube_metrics_history : Recupera métricas históricas (errores, vulnerabilidades, errores de código, cobertura, densidad de duplicación) de un proyecto SonarQube mediante /api/measures/search_history. Se pueden aplicar filtros de fecha opcionales.
get_sonarqube_component_tree_metrics : recupera valores métricos para todos los componentes (por ejemplo, archivos o directorios) en un proyecto usando /api/measures/component_tree. Maneja automáticamente la paginación para recuperar todos los resultados.
get_project_issues : Obtiene los problemas de SonarQube de un proyecto determinado, con filtros opcionales por tipo, gravedad y estado de resolución. Devuelve un límite de resultados (predeterminado: 10).

Pila de tecnología

Lenguaje: Python
Marcos: FastMCP
Bibliotecas: httpx, pydantic, dotenv, asyncio, json, pathlib, mecanografía, base64
Herramientas: API de SonarQube

Estructura del directorio

├── 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.

Empezando

Prerrequisitos

Python 3.7+
Instancia de SonarQube con acceso a API
Un token de API de SonarQube con los permisos adecuados
FastMCP instalado ( pip install fastmcp )
httpx instalado ( pip install httpx )
Pydantic instalado ( pip install pydantic )
python-dotenv instalado ( pip install python-dotenv )

Pasos generales de construcción

Clonar el repositorio: git clone <repository_url>
Navegue al directorio del proyecto: cd fastmcp-sonarqube-metrics
Configurar variables de entorno: Cree un archivo .env en el directorio raíz del proyecto con el siguiente contenido:
SONARQUBE_URL=<your_sonarqube_url> SONARQUBE_TOKEN=<your_sonarqube_token>
Reemplace <your_sonarqube_url> con la URL de su instancia de SonarQube (por ejemplo, http://localhost:9000 ) y <your_sonarqube_token> con su token de API de SonarQube.
Ejecute el servidor: python server.py
Ejecute el cliente: python client_test.py(opcional, solo para prueba)
Conéctate con tu cliente: sigue la documentación oficial

Uso del módulo

Servidor ( `server.py` )

El módulo server.py define el servidor FastMCP que expone las herramientas para recuperar las métricas de SonarQube. Inicializa el servidor, carga las variables de entorno, define las herramientas disponibles y gestiona la comunicación con la API de SonarQube. Para usar el servidor, debe configurar las variables de entorno SONARQUBE_URL y SONARQUBE_TOKEN . El servidor se inicia ejecutando directamente el script server.py .

Cliente ( `client_test.py` )

El módulo client_test.py define el cliente FastMCP que interactúa con el servidor. Solicita al usuario una clave de proyecto de SonarQube, se conecta al servidor, invoca las herramientas get_sonarqube_metrics y get_sonarqube_component_tree_metrics y muestra los resultados. Para usar el cliente, debe ejecutar el script client_test.py directamente y proporcionar una clave de proyecto de SonarQube válida cuando se le solicite.

Ejemplo: Integración de la herramienta `get_sonarqube_metrics` en un proyecto externo

Para usar la herramienta get_sonarqube_metrics en un proyecto externo, puede crear un cliente que se conecte al servidor FastMCP e invoque la herramienta. A continuación, se muestra un ejemplo básico:

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

Este ejemplo muestra cómo crear un cliente, conectarse al servidor, invocar la herramienta get_sonarqube_metrics con una clave de proyecto y procesar los resultados. Deberá adaptar la variable server_path a la ubicación real del script server.py en su entorno.

Uso con Claude Desktop

Puede instalar este servidor directamente en Claude Desktop usando fastmcp:

Asegúrese de que FastMCP esté instalado (pip install fastmcp o uv pip install fastmcp).
Configure Claude for Desktop para cualquier servidor MCP que desee utilizar (en Windows usando VSCode): code $env:AppData\Claude\claude_desktop_config.json
Añade tu servidor y luego guarda:

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

Para iniciarlo ejecute:

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

Reinicie Claude Desktop si estaba en ejecución. La herramienta "Métricas de FastMCP SonarQube" debería estar disponible.

Análisis funcional

1. Principales responsabilidades del sistema

La principal responsabilidad del sistema es servir de puente entre el usuario y la API de SonarQube, ofreciendo una forma simplificada de obtener métricas de calidad del proyecto. Encapsula las complejidades de la API de SonarQube, ofreciendo un conjunto de herramientas que se pueden invocar e integrar fácilmente en flujos de trabajo automatizados. Los servicios principales incluyen la obtención de métricas, la recuperación de datos históricos y la exploración de métricas a nivel de componente dentro de un proyecto de SonarQube. El servicio fundamental es el servidor FastMCP, que gestiona las definiciones de herramientas y la comunicación cliente-servidor.

2. Problemas que resuelve el sistema

El sistema resuelve el problema del acceso programático a los datos de SonarQube sin necesidad de que los usuarios interactúen directamente con la API de SonarQube. Atiende la necesidad de generar informes, analizar e integrar métricas de SonarQube con otros sistemas de forma automatizada. En concreto, simplifica tareas como:

Generar informes periódicos sobre métricas de calidad del código.
Monitoreo de tendencias en la calidad del código a lo largo del tiempo.
Identificar componentes problemáticos dentro de un proyecto.
Integración de datos de SonarQube con otras herramientas de desarrollo.

La arquitectura resuelve estos problemas al proporcionar un conjunto de herramientas bien definidas que abstraen las complejidades de la API de SonarQube y proporcionan una interfaz consistente para acceder a los datos.

3. Interacción de módulos y componentes

El sistema consta de dos componentes principales: el cliente y el servidor. El cliente inicia las solicitudes al servidor, especificando la herramienta que se ejecutará y los parámetros de entrada. El servidor recibe la solicitud, interactúa con la API de SonarQube, procesa los datos y envía los resultados al cliente.

La interacción entre el cliente y el servidor se facilita mediante el framework FastMCP, que gestiona el paso de mensajes y la serialización. El servidor define las herramientas disponibles mediante el decorador @mcp.tool() , que registra las funciones como puntos finales invocables. El cliente invoca estas herramientas mediante el método client.call_tool() , que envía un mensaje al servidor con el nombre de la herramienta y los parámetros de entrada.

El servidor utiliza la biblioteca httpx para realizar solicitudes HTTP asíncronas a la API de SonarQube. Construye las URL de la API y los parámetros de solicitud según la herramienta que se ejecuta y los parámetros de entrada proporcionados por el cliente. A continuación, el servidor analiza las respuestas JSON de la API de SonarQube y extrae los valores de las métricas relevantes.

4. Funcionalidades orientadas al usuario vs. funcionalidades orientadas al sistema

La funcionalidad del sistema orientada al usuario es la aplicación cliente ( client_test.py ), que proporciona una interfaz de línea de comandos para invocar las herramientas de recuperación de métricas de SonarQube. Los usuarios interactúan con el cliente proporcionando una clave de proyecto de SonarQube y, opcionalmente, otros parámetros como rangos de fechas o claves de métricas. El cliente muestra las métricas recuperadas en un formato legible.

Las funcionalidades del sistema son las herramientas del servidor ( get_sonarqube_metrics , get_sonarqube_metrics_history , get_sonarqube_component_tree_metrics ) definidas en server.py . Estas herramientas gestionan la interacción con la API de SonarQube, el procesamiento y el formato de los datos. No son visibles directamente para los usuarios finales, pero son esenciales para proporcionar la funcionalidad principal del sistema.

El decorador @mcp.tool() aplica sistemáticamente comportamientos comunes en todas las funciones de la herramienta, garantizando que se registren en el servidor FastMCP y sean accesibles para los clientes. Además, el uso de Annotated y Field garantiza la coherencia en la definición y documentación de parámetros en todas las herramientas.

Patrones arquitectónicos y principios de diseño aplicados

Arquitectura Cliente-Servidor: El proyecto sigue una arquitectura cliente-servidor, donde el cliente solicita servicios al servidor.
Paso de mensajes: el marco FastMCP facilita la comunicación entre el cliente y el servidor mediante el paso de mensajes.
Programación asincrónica: El uso de asyncio y httpx permite operaciones asincrónicas, mejorando el rendimiento y la capacidad de respuesta de la aplicación.
Configuración mediante variables de entorno: la URL y el token de SonarQube se configuran mediante variables de entorno, lo que facilita la implementación y la administración de la aplicación en diferentes entornos.
Diseño basado en herramientas: el servidor expone la funcionalidad a través de herramientas bien definidas, lo que facilita agregar o modificar funciones.
Manejo de errores: el proyecto incluye un manejo de errores integral para manejar con elegancia posibles problemas, como errores de red, errores de API y datos no válidos.
Registro: el uso del módulo logging proporciona registros detallados, lo que ayuda en la depuración y la supervisión.
Inyección de dependencia: si bien no se implementa explícitamente como marco, la configuración de la URL y el token de SonarQube a través de variables de entorno permite una fácil sustitución de diferentes instancias de SonarQube sin modificar el código.

Análisis de la calidad del código

Debido a la falta de un informe de SonarQube, no es posible realizar un análisis exhaustivo de la calidad del código. Sin embargo, según la estructura y la funcionalidad del código, las posibles áreas de preocupación incluyen:

Granularidad en el manejo de errores: si bien el manejo de errores está presente, los mensajes de error específicos podrían mejorarse para brindar información más útil al usuario.
Cobertura de pruebas: El código proporcionado no incluye pruebas unitarias. Se debe añadir cobertura de pruebas para garantizar la fiabilidad y la corrección del código.
Duplicación de código: puede haber oportunidades para reducir la duplicación de código extrayendo lógica común en funciones o clases reutilizables.

Debilidades y áreas de mejora

Mejorar la claridad de los mensajes de error: mejore los mensajes de error para brindar orientación más específica a los usuarios sobre cómo resolver problemas.
Agregar pruebas unitarias: implemente pruebas unitarias para las herramientas del lado del servidor para garantizar su corrección y confiabilidad.
Refactorizar la lógica común: identificar y refactorizar el código duplicado en funciones o clases reutilizables.
Implementar la validación de entrada: agregue la validación de entrada a las herramientas del lado del servidor para evitar que se procesen datos no válidos.
Mejorar la documentación: agregue documentación más detallada para las herramientas del lado del servidor, incluidos ejemplos e instrucciones de uso.
Implemente un sistema de configuración más sólido: considere utilizar un sistema de configuración más sólido, como un archivo de configuración o una clase de configuración dedicada, en lugar de confiar únicamente en variables de entorno.
Agregar soporte para puntos finales de API de SonarQube adicionales: amplíe el sistema para admitir puntos finales de API de SonarQube adicionales, como aquellos para administrar proyectos, reglas o perfiles de calidad.
Implementar una interfaz de cliente más fácil de usar: considere desarrollar una interfaz gráfica de usuario (GUI) o una interfaz de línea de comandos (CLI) más sofisticada para la aplicación cliente.
Abordar posibles vulnerabilidades de seguridad: revise el código para detectar posibles vulnerabilidades de seguridad, como aquellas relacionadas con la validación de entrada o la autenticación.

Otras áreas de investigación

Cuellos de botella de rendimiento: investigue posibles cuellos de botella de rendimiento en las herramientas del lado del servidor, como aquellos relacionados con el manejo de solicitudes de API o el procesamiento de datos.
Consideraciones de escalabilidad: evalúe la escalabilidad del sistema e identifique áreas potenciales de mejora, como el uso de una cola de mensajes o un sistema de almacenamiento en caché distribuido.
Integraciones con sistemas externos: explore posibles integraciones con otras herramientas de desarrollo, como sistemas CI/CD o rastreadores de problemas.
Funciones avanzadas: investigue e implemente funciones avanzadas, como monitoreo de métricas en tiempo real o análisis automatizado de la calidad del código.
Olores de código y baja cobertura de pruebas: realice un análisis exhaustivo de la base de código para identificar y abordar olores de código y áreas con baja cobertura de pruebas.

Atribución

Generado con el apoyo de ArchAI , un sistema de documentación automatizado.

FastMCP SonarQube Metrics

Integrations