FastMCP SonarQube 指标

概述

该项目提供了一套使用 FastMCP（快速模型上下文协议）框架检索 SonarQube 项目信息的工具。它作为 SonarQube 的接口，允许用户以编程方式访问指定项目的指标、历史数据和组件树指标。这种自动化访问功能支持 SonarQube 数据的报告、分析以及与其他系统的集成。

该项目的独特之处在于，它提供了一种简化的、基于消息的方法来与 SonarQube API 交互，从而抽象出了直接 API 调用和数据处理的复杂性。它专为需要将 SonarQube 数据整合到工作流程或构建自定义报告解决方案的开发人员、DevOps 工程师和分析师而设计。

该存储库专门包含用于通信和数据检索的客户端和服务器组件。服务器公开了从 SonarQube 获取数据的工具，而客户端则提供了命令行界面，供用户调用这些工具并显示结果。每个内部模块都通过封装特定的功能（例如 API 交互、数据处理和客户端-服务器通信）来实现此目标。

项目中包含的客户端仅用于测试代码的工作方式；我们建议使用Claude Desktop或开发您自己的自定义客户端。

请记住，此 REPO 仍在开发中，某些功能可能并不完美。

支持的 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 问题，可选择按类型、严重程度和解决状态进行筛选。最多返回限制结果（默认值：10）。

技术堆栈

语言： Python
框架： FastMCP
库： httpx、pydantic、dotenv、asyncio、json、pathlib、typing、base64
工具： SonarQube API

目录结构

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

入门

先决条件

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 ）

常规构建步骤

克隆存储库： git clone <repository_url>
导航到项目目录： cd fastmcp-sonarqube-metrics
**设置环境变量：**在项目根目录下创建一个.env文件，内容如下：
SONARQUBE_URL=<your_sonarqube_url> SONARQUBE_TOKEN=<your_sonarqube_token>
将<your_sonarqube_url>替换为您的 SonarQube 实例的 URL（例如， http://localhost:9000 ），并将<your_sonarqube_token>替换为您的 SonarQube API 令牌。
运行服务器： python server.py
运行客户端： python client_test.py（可选，仅用于测试）
**连接到您的客户端：**按照官方文档

模块使用

服务器（ `server.py` ）

server.py模块定义了 FastMCP 服务器，该服务器公开了用于检索 SonarQube 指标的工具。它初始化服务器、加载环境变量、定义可用工具并处理与 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 项目密钥。

示例：在外部项目中集成`get_sonarqube_metrics`工具

要在外部项目中使用get_sonarqube_metrics工具，您可以创建一个连接到 FastMCP 服务器并调用该工具的客户端。这是一个基本示例：

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

此示例演示如何创建客户端、连接到服务器、使用项目密钥调用get_sonarqube_metrics工具并处理结果。您需要根据环境中server.py脚本的实际位置调整server_path变量。

与 Claude Desktop 一起使用

您可以使用 fastmcp 将此服务器直接安装到 Claude Desktop 中：

确保已安装 FastMCP（pip install fastmcp 或 uv pip install fastmcp）。
为您想要使用的任何 MCP 服务器配置 Claude for Desktop（在 Windows 中使用 VSCode）： code $env:AppData\Claude\claude_desktop_config.json
添加您的服务器然后保存：

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

通过运行来启动它：

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

如果 Claude Desktop 正在运行，请重新启动它。 *“FastMCP SonarQube Metrics”*工具现在应该可用了。

功能分析

1.系统主要职责

该系统的主要职责是充当用户与 SonarQube API 之间的桥梁，提供一种简化的项目质量指标检索方式。它封装了 SonarQube API 的复杂性，提供了一套易于调用并集成到自动化工作流程中的工具。核心服务包括获取指标、检索历史数据以及探索 SonarQube 项目中的组件级指标。基础服务是 FastMCP 服务器，用于管理工具定义和客户端-服务器通信。

2. 系统解决的问题

该系统解决了以编程方式访问 SonarQube 数据的问题，无需用户直接与 SonarQube API 交互。它满足了自动报告、分析以及 SonarQube 指标与其他系统集成的需求。具体来说，它简化了以下任务：

生成有关代码质量指标的定期报告。
监控代码质量随时间的变化趋势。
识别项目中有问题的组件。
将 SonarQube 数据与其他开发工具集成。

该架构通过提供一组定义明确的工具来解决这些问题，这些工具抽象出了 SonarQube API 的复杂性并提供了用于访问数据的一致接口。

3.模块和组件的交互

该系统由两个主要组件组成：客户端和服务器。客户端向服务器发起请求，指定要执行的工具和任何输入参数。服务器接收请求，与 SonarQube API 交互，处理数据，并将结果发送回客户端。

客户端和服务器之间的交互由 FastMCP 框架实现，该框架负责处理消息传递和序列化。服务器使用@mcp.tool()装饰器定义可用的工具，并将这些函数注册为可调用端点。客户端使用client.call_tool()方法调用这些工具，该方法会向服务器发送一条包含工具名称和输入参数的消息。

服务器使用httpx库向 SonarQube API 发出异步 HTTP 请求。它根据正在执行的工具和客户端提供的输入参数构建 API URL 和请求参数。然后，服务器解析来自 SonarQube API 的 JSON 响应并提取相关的指标值。

4. 面向用户的功能 vs. 面向系统的功能

该系统面向用户的功能是客户端应用程序 ( 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的支持下生成。

FastMCP SonarQube Metrics

Integrations