FastMCP SonarQube 指标

概述

本项目提供了一套使用 FastMCP (Fast Model Context Protocol) 框架检索 SonarQube 项目信息的工具。它作为 SonarQube 的接口，允许用户以编程方式访问指定项目的指标、历史数据和组件树指标。这种自动化访问方式支持了 SonarQube 数据与其他系统的报告、分析和集成。

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

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

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

请记住，此仓库尚在开发中，某些功能可能不够完善。

Related MCP server: MCP QQ Music Test Server

托管部署

可在 Fronteir AI 上进行托管部署。

支持的 MCP 工具

• get_status: 对配置的 SonarQube 实例执行健康检查。

• create_sonarqube_project: 创建一个新的 SonarQube 项目。需要管理员权限。

• delete_sonarqube_project: 删除一个 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 问题，可选择按类型、严重性和解决状态进行过滤。返回最多 limit 个结果（默认：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.
├── 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.

入门指南

先决条件

• 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)

通用构建步骤

1. 克隆仓库: git clone <repository_url>

2. 导航到项目目录: cd fastmcp-sonarqube-metrics

3. 设置环境变量: 在项目根目录中创建一个 .env 文件，内容如下：

   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)

   如果您想使用 AzureOpenAI，OpenAI 和 Groq 的架构是相同的：

   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>

   将 <your_sonarqube_url> 替换为您的 SonarQube 实例的 URL（例如 http://localhost:9000），并将 <your_sonarqube_token> 替换为您的 SonarQube API 令牌。

4. 运行服务器: python server.py

5. 运行客户端: python client_test.py (可选，仅用于测试)

6. 连接到您的客户端: 遵循 官方文档

模块使用

服务器 (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 项目键，并将 .env 文件中的传输类型设置为 stdio。

Client_tool (client_tool.py)

client_tool.py 模块实现了一个基于 Tkinter 图形界面的 FastMCP 客户端，用于与 SonarQube 服务器交互。启动时，它会配置记录器以抑制非必要消息，加载环境变量，并在后台启动聊天后端 (ChatBackend)，该后端使用 LLM 和服务器通过 stdio 公开的 MCP 工具。前端 (ChatGUI) 管理 Tkinter 窗口，在可滚动区域显示消息历史记录，并允许用户向服务器发送命令——在需要时提示输入有效的 SonarQube 项目键。要使用客户端，只需运行 client_tool.py 脚本并通过 GUI 进行交互。

Client_langchain (client_langchain.py)

client_langchain.py 模块提供了一个命令行客户端，用于通过 LangChain 与 FastMCP 服务器和 SonarQube 工具进行交互。启动时，它会加载环境变量并配置所选的 LLM。它建立到服务器 (server.py) 的 stdio 连接，初始化 MCP 会话，并加载可用工具（健康检查、当前和历史指标、项目列表、问题检索）。详细的系统提示词描述了每个工具及其参数。在交互循环中，它从控制台读取用户输入，更新消息历史记录，调用 React 代理，并打印格式化的响应。

示例：在外部项目中集成 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 变量。

ArchAI-SonarQube 聊天 (GUI)

一个轻量级的 Tkinter 客户端，通过 stdio 连接到 FastMCP 服务器，并提供实时聊天界面，用于通过 LLM 驱动的助手查询 SonarQube 指标、浏览组件树和运行健康检查。

使用 TRANSPORT=SSE

您可以通过在启动 GUI 之前设置 TRANSPORT 环境变量，将客户端的传输层切换为服务器发送事件 (SSE)。这实现了来自 FastMCP 服务器的实时、单向更新。 当服务器以 SSE 模式启动时，会在端口 8001 上打开一个持久的 HTTP 连接。这允许您通过兼容的接口（如 MCP Inspector）进行连接。

1. 以 SSE 模式启动服务器

   uv run mcp dev "<server_name>" 

2. 打开 MCP Inspector 将提供一个链接（例如 http://127.0.0.1:6274）以在您的浏览器中启动 MCP Inspector。

3. 在 MCP Inspector 中配置 SSE

   • 选择 SSE 作为传输类型

   • 输入 URL: http://localhost:8001/sse

4. 发起连接

5. 浏览可用工具 在 Tools 部分，您将看到：

   • get_status

   • get_sonarqube_metrics

   • get_sonarqube_metrics_history

   • get_sonarqube_component_tree_metrics

   • list_projects

   • get_project_issues

6. 选择并调用工具 例如，选择 get_project_issues 并提供：

   • project_key: SonarQube 项目键

   • issue_type (可选): 例如 BUG, CODE_SMELL

   • severity (可选): 例如 MAJOR, CRITICAL

   • resolved (可选): true 或 false

   • limit (可选): 要返回的最大问题数量

7. 执行并检索结果 服务器将调用相应的 SonarQube API 并返回格式化的 JSON 响应。

与 Claude Desktop 一起使用

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

1. 确保已安装 FastMCP (pip install fastmcp 或 uv pip install fastmcp)。

2. 为您想要使用的任何 MCP 服务器配置 Claude for Desktop（在 Windows 上使用 VSCode）：code $env:AppData\Claude\claude_desktop_config.json

3. 添加您的服务器然后保存：

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

4. 通过运行以下命令启动它：

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

5. 如果 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. 面向用户的功能与面向系统的功能

系统的面向用户的功能是客户端应用程序 (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 端点，例如用于管理项目、规则或