Métricas de SonarQube para FastMCP

Descripción general

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

El proyecto se distingue por ofrecer un enfoque simplificado basado en mensajes para interactuar con la API de SonarQube, abstrayendo las complejidades de las llamadas directas a la API y el manejo 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 del cliente y del 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 encapsulando 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 usar Claude Desktop o desarrollar su propio cliente personalizado.

RECUERDE, ESTE REPOSITORIO ESTÁ EN DESARROLLO, ALGUNAS CARACTERÍSTICAS PUEDEN NO SER PERFECTAS.

Related MCP server: MCP QQ Music Test Server

Despliegue alojado

Hay un despliegue alojado disponible en Fronteir AI.

Herramientas MCP compatibles

• get_status: Realiza una comprobación de estado en la instancia de SonarQube configurada.

• create_sonarqube_project: Crea un nuevo proyecto de SonarQube. Requiere privilegios de administrador.

• delete_sonarqube_project: Elimina un proyecto de SonarQube. Requiere privilegios de administrador. ¡ÚSELO CON PRECAUCIÓN!

• list_projects: Enumera todos los proyectos de SonarQube accesibles, opcionalmente filtrados por nombre o clave.

• get_sonarqube_metrics: Recupera métricas especificadas (errores, vulnerabilidades, olores de código, cobertura, densidad de duplicación) para una clave de proyecto de SonarQube determinada.

• get_sonarqube_metrics_history: Recupera métricas históricas (errores, vulnerabilidades, olores de código, cobertura, densidad de duplicación) para un proyecto de SonarQube determinado utilizando /api/measures/search_history. Se pueden aplicar filtros de fecha opcionales.

• get_sonarqube_component_tree_metrics: Recupera valores de métricas para todos los componentes (por ejemplo, archivos o directorios) en un proyecto utilizando /api/measures/component_tree. Maneja automáticamente la paginación para recuperar todos los resultados.

• get_project_issues: Obtiene problemas de SonarQube para un proyecto determinado, opcionalmente filtrados por tipo, gravedad y estado de resolución. Devuelve hasta limit resultados (predeterminado: 10).

Pila tecnológica

• Lenguaje: Python

• Marcos: FastMCP

• Bibliotecas: httpx, pydantic, dotenv, asyncio, json, pathlib, typing, 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.
├── 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.

Primeros pasos

Requisitos previos

• Python 3.7+

• Instancia de SonarQube con acceso a la 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 compilación

1. Clonar el repositorio: git clone <repository_url>

2. Navegar al directorio del proyecto: cd fastmcp-sonarqube-metrics

3. 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>
   TRANSPORT=<stdio or sse>
   GEMINI_API_KEY=<your-gemini-api_key>
   GEMINI_MODEL=<your-gemini-model> (Optional)

   El esquema es el mismo para OpenAI y Groq, si desea utilizar 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>

   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.

4. Ejecutar el servidor: python server.py

5. Ejecutar el cliente: python client_test.py (Opcionalmente, solo para prueba)

6. Conectarse a su cliente: siga la documentación oficial

Uso del módulo

Servidor (server.py)

El módulo server.py define el servidor FastMCP que expone herramientas para recuperar métricas de SonarQube. Inicializa el servidor, carga las variables de entorno, define las herramientas disponibles y maneja 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 el script server.py directamente.

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, y establecer el tipo de transporte en el archivo .env en stdio.

Client_tool (client_tool.py)

El módulo client_tool.py implementa el cliente FastMCP con una interfaz gráfica basada en Tkinter para interactuar con el servidor de SonarQube. Al inicio, configura los registradores para suprimir mensajes no esenciales, carga las variables de entorno e inicia el backend de chat (ChatBackend) en segundo plano, que utiliza un LLM y las herramientas MCP expuestas por el servidor a través de stdio. El frontend (ChatGUI) gestiona la ventana de Tkinter, muestra el historial de mensajes en un área desplazable y permite al usuario enviar comandos al servidor, solicitando una clave de proyecto de SonarQube válida cuando sea necesario. Para usar el cliente, simplemente ejecute el script client_tool.py e interactúe a través de la GUI.

Client_langchain (client_langchain.py)

El módulo client_langchain.py proporciona un cliente de línea de comandos para interactuar con el servidor FastMCP y las herramientas de SonarQube a través de LangChain. Al inicio, carga las variables de entorno y configura el LLM elegido. Establece una conexión stdio con el servidor (server.py), inicializa la sesión MCP y carga las herramientas disponibles (comprobación de estado, métricas actuales e históricas, listado de proyectos, recuperación de problemas). Un mensaje del sistema detallado describe cada herramienta y sus parámetros. En un bucle interactivo, lee la entrada del usuario desde la consola, actualiza el historial de mensajes, invoca al agente React e imprime la respuesta formateada.

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. Aquí hay 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 demuestra cómo crear un cliente, conectarse al servidor, invocar la herramienta get_sonarqube_metrics con una clave de proyecto y procesar los resultados. Tendría que adaptar la variable server_path a la ubicación real del script server.py en su entorno.

Chat de ArchAI-SonarQube (GUI)

Un cliente ligero de Tkinter que se conecta a través de stdio al servidor FastMCP y expone una interfaz de chat en tiempo real para consultar métricas de SonarQube, explorar árboles de componentes y ejecutar comprobaciones de estado a través de un asistente impulsado por LLM.

Uso con TRANSPORT=SSE

Puede cambiar la capa de transporte del cliente a Server-Sent Events (SSE) configurando la variable de entorno TRANSPORT antes de iniciar la GUI. Esto permite actualizaciones unidireccionales en tiempo real desde el servidor FastMCP. Cuando el servidor se inicia en modo SSE, se abre una conexión HTTP persistente en el puerto 8001. Esto le permite conectarse a través de interfaces compatibles como MCP Inspector.*

1. Iniciar el servidor en modo SSE

   uv run mcp dev "<server_name>" 

2. Abrir MCP Inspector Se proporcionará un enlace (por ejemplo, http://127.0.0.1:6274) para iniciar MCP Inspector en su navegador.

3. Configurar SSE en MCP Inspector

   • Seleccione SSE como tipo de transporte

   • Ingrese la URL: http://localhost:8001/sse

4. Iniciar la conexión

5. Explorar las herramientas disponibles En la sección Herramientas verá:

   • get_status

   • get_sonarqube_metrics

   • get_sonarqube_metrics_history

   • get_sonarqube_component_tree_metrics

   • list_projects

   • get_project_issues

6. Seleccionar e invocar una herramienta Por ejemplo, elija get_project_issues y proporcione:

   • project_key: la clave del proyecto de SonarQube

   • issue_type (opcional): por ejemplo, BUG, CODE_SMELL

   • severity (opcional): por ejemplo, MAJOR, CRITICAL

   • resolved (opcional): true o false

   • limit (opcional): número máximo de problemas a devolver

7. Ejecutar y recuperar resultados El servidor llamará a la API de SonarQube adecuada y devolverá una respuesta JSON formateada.

Uso con Claude Desktop

Puede instalar este servidor directamente en Claude Desktop usando fastmcp:

1. Asegúrese de que FastMCP esté instalado (pip install fastmcp o uv pip install fastmcp).

2. Configure Claude for Desktop para los servidores MCP que desee utilizar (en Windows usando VSCode): code $env:AppData\Claude\claude_desktop_config.json

3. Agregue su servidor y luego guarde:

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

4. Para iniciarlo ejecutando:

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

5. Reinicie Claude Desktop si estaba ejecutándose. La herramienta "Métricas de SonarQube para FastMCP" ahora debería estar disponible.

Análisis funcional

1. Responsabilidades principales del sistema

La responsabilidad principal del sistema es actuar como un puente entre un usuario y la API de SonarQube, proporcionando una forma simplificada de recuperar métricas de calidad del proyecto. Encapsula las complejidades de la API de SonarQube, ofreciendo un conjunto de herramientas que pueden invocarse e integrarse 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 de acceder mediante programación a los datos de SonarQube sin requerir que los usuarios interactúen directamente con la API de SonarQube. Aborda la necesidad de informes automatizados, análisis e integración de métricas de SonarQube con otros sistemas. Específicamente, simplifica tareas como:

• Generar informes periódicos sobre métricas de calidad de código.

• Monitorear las tendencias en la calidad del código a lo largo del tiempo.

• Identificar componentes problemáticos dentro de un proyecto.

• Integrar datos de SonarQube con otras herramientas de desarrollo.

La arquitectura resuelve estos problemas proporcionando 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 solicitudes al servidor, especificando la herramienta que se ejecutará y cualquier parámetro de entrada. El servidor recibe la solicitud, interactúa con la API de SonarQube, procesa los datos y envía los resultados de vuelta al cliente.

La interacción entre el cliente y el servidor está facilitada por el marco FastMCP, que maneja el paso de mensajes y la serialización. El servidor define las herramientas disponibles utilizando el decorador @mcp.tool(), que registra las funciones como puntos finales invocables. El cliente invoca estas herramientas utilizando 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 en función de la herramienta que se está ejecutando y los parámetros de entrada proporcionados por el cliente. Luego, el servidor analiza las respuestas JSON de la API de SonarQube y extrae los valores de métricas relevantes.

4. Funcionalidades orientadas al usuario frente a las orientadas al sistema

La funcionalidad orientada al usuario del sistema 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. Luego, el cliente muestra las métricas recuperadas en un formato legible por humanos.

Las funcionalidades orientadas al sistema son las herramientas del lado del servidor (get_sonarqube_metrics, get_sonarqube_metrics_history, get_sonarqube_component_tree_metrics) definidas en server.py. Estas herramientas manejan la interacción con la API de SonarQube, el procesamiento de datos y el formato. No son directamente visibles 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 herramientas, asegurando que estén registradas en el servidor FastMCP y accesibles para los clientes. Además, el uso de Annotated y Field garantiza una definición y documentación de parámetros consistentes en todas las herramientas.

Patrones arquitectónicos y principios de diseño aplicados

• **Arquitectura cliente