FastMCP SonarQube 指标

概述

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

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

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

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

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

Related MCP server: MCP QQ Music Test Server

支持的 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

目录结构

入门

先决条件

• 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> OPENAI_API_KEY=<your-openai-api_key>

   将<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 项目密钥。

客户端工具（ client_tool.py ）

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

客户端语言链（ client_langchain.py ）

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

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

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

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

ArchAI-SonarQube 聊天（GUI）

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

与 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作为传输类型

   • 输入网址： http://localhost:8001/sse

4. 发起连接

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

   • 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. 添加您的服务器然后保存：

4. 通过运行来启动它：

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. 面向用户的功能 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的支持下生成。