FastMCP SonarQube Metrics

FastMCP SonarQube Metrics

概述

本项目使用 FastMCP（Fast Model Context Protocol）框架，提供一组用于获取 SonarQube 项目信息的工具。它充当 SonarQube 的接口，让用户能够以编程方式访问指定项目的指标、历史数据和组件树指标。这种自动化访问方式支持报告、分析，以及将 SonarQube 数据与其他系统集成。

本项目的特点是提供了简化的、基于消息的方式与 SonarQube API 交互，屏蔽了直接调用 API 和处理数据的复杂性。它面向需要将 SonarQube 数据集成到工作流或构建自定义报告解决方案中的开发者、DevOps 工程师和分析师。

本仓库专门包含用于通信和数据获取的客户端和服务端组件。服务端提供从 SonarQube 获取数据的工具，而客户端提供命令行界面，供用户调用这些工具并显示结果。各个内部模块通过封装特定功能来实现这一目标，例如 API 交互、数据处理以及客户端与服务端通信。

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

请注意，本仓库仍在开发中，部分功能可能不够完善。

托管部署

可通过 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)
   

   OpenAI 和 Groq 的配置格式相同。如果要使用 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>
   

   将 <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.py）

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

LangChain 客户端（client_langchain.py）

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

示例：在外部项目中集成 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_path 变量，使其指向 server.py 脚本。

ArchAI-SonarQube Chat（GUI）

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

使用 TRANSPORT=SSE

在启动 GUI 之前设置 TRANSPORT 环境变量，即可将客户端的传输层切换为 Server-Sent Events（SSE）。这样便可以从 FastMCP 服务接收实时单向更新。 以 SSE 模式启动服务时，会在端口 8001 上建立持久 HTTP 连接。这样便可以通过 MCP Inspector 等兼容接口进行连接。*

1. 以 SSE 模式启动服务

   uv run mcp dev "<server_name>" 
   

2. Open MCP Inspector A link (e.g. http://127.0.0.1:6274) will be provided to launch MCP Inspector in your browser.

3. Configure SSE in MCP Inspector

   • Select SSE as the transport type
   • Enter the URL: http://localhost:8001/sse

4. Initiate the connection

5. Browse available tools In the Tools section you will see:

   • get_status
   • get_sonarqube_metrics
   • get_sonarqube_metrics_history
   • get_sonarqube_component_tree_metrics
   • list_projects
   • get_project_issues

6. Select and invoke a tool For example, choose get_project_issues and provide:

   • project_key: the SonarQube project key
   • issue_type (optional): e.g. BUG, CODE_SMELL
   • severity (optional): e.g. MAJOR, CRITICAL
   • resolved (optional): true or false
   • limit (optional): maximum number of issues to return

7. Execute and retrieve results The server will call the appropriate SonarQube API and return a formatted JSON response.

Usage with Claude Desktop

You can install this server directly into Claude Desktop using fastmcp:

1. Make sure FastMCP is installed (pip install fastmcp or uv pip install fastmcp).
2. Configure Claude for Desktop for whichever MCP servers you want to use (in Windows using VSCode): code $env:AppData\Claude\claude_desktop_config.json
3. Add your server and then save:

{
    "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 端点，例如用于管理项目、规则或质量配置文件的端点。
• 实现更易用的客户端界面： 考虑为客户端应用开发图形用户界面（GUI）或更完善的命令行界面（CLI）。
• 解决潜在的安全漏洞： 检查代码中是否存在潜在的安全漏洞，例如与输入验证或身份验证相关的漏洞。

进一步调查方向

• 性能瓶颈： 调查服务端工具中潜在的性能瓶颈，例如与 API 请求处理或数据处理相关的瓶颈。
• 可扩展性考量： 评估系统的可扩展性，并找出潜在的改进方向，例如使用消息队列或分布式缓存系统。
• 与外部系统集成： 探索与其他开发工具集成的可能性，例如 CI/CD 系统或问题跟踪器。
• 高级功能： 研究并实现高级功能，例如实时指标监控或自动化代码质量分析。
• 代码异味和低测试覆盖率： 全面分析代码库，找出并解决代码异味及测试覆盖率较低的问题。

署名

本文档由自动化文档系统 ArchAI 辅助生成。