FastMCP SonarQube Metrics

概述

该项目提供了一组工具，用于通过FastMCP（快速模型上下文协议）框架检索SonarQube项目的相关信息。它充当与SonarQube交互的接口，允许用户程序化地访问指定项目的指标、历史数据和组件树指标。这种自动访问使报告、分析以及与其他系统集成SonarQube数据成为可能。

该项目通过提供一种简化、基于消息的方法来与SonarQube API进行交互，从而区别于其他方法，抽象了直接调用API和处理数据的复杂性。它设计用于需要将SonarQube数据整合到工作流程中或构建自定义报告解决方案的开发者、DevOps工程师和分析师。

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

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

记住，这个仓库还在开发中，某些功能可能还不完善。

支持的MCP工具

• get_status: 对配置的SonarQube实例执行健康检查。
• create_sonarqube_project: 创建一个新的SonarQube项目。需要管理员权限。
• delete_sonarqube_project: 删除一个SonarQube项目。需要管理员权限。谨慎使用！
• list_projects: 列出所有可访问的SonarQube项目，可选按名称或键过滤。
• get_sonarqube_metrics: 获取给定SonarQube项目键的指定指标（如bug、漏洞、代码异味、覆盖率、重复密度）。
• 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 - 测试和与服务器交互的客户端应用程序。
├── server.py - 暴露工具以检索SonarQube指标的服务器应用程序。
├── client_tool.py - 带有图形界面的客户端，用于与SonarQube服务器交互。
├── client_langchain.py - 命令行客户端，通过LangChain与FastMCP服务器和SonarQube工具交互。
├── .env - 环境配置文件（存储SonarQube URL和令牌）。
└── README.md - 项目文档。

快速开始

先决条件

• 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> (可选)
   

   如果你想使用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模块定义了暴露用于检索SonarQube指标的工具的FastMCP服务器。它初始化服务器，加载环境变量，定义可用工具，并处理与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），该后端使用LLM并通过stdio与服务器暴露的MCP工具交互。前端（ChatGUI）管理Tkinter窗口，在滚动区域中显示消息历史记录，并允许用户向服务器发送命令——在需要时提示输入有效的SonarQube项目键。要使用客户端，只需运行client_tool.py脚本并通过GUI进行交互。

客户端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" # 如有必要，请调整
    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"错误: {e}")

if __name__ == "__main__":
    asyncio.run(get_metrics("your-project-key")) # 替换为你的项目键

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

ArchAI-SonarQube聊天（GUI）

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

<br>

<br>

使用TRANSPORT=SSE

你可以在启动GUI之前设置TRANSPORT环境变量为Server-Sent Events (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. 浏览可用工具 在工具部分，你会看到：

   • 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

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

1. 确保已安装FastMCP（pip install fastmcp或uv pip install fastmcp）。
2. 配置Claude Desktop以使用所需的MCP服务器（在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"*工具。

<br>

<br>

功能分析

1. 系统的主要职责

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

2. 系统解决的问题

系统解决了无需直接与SonarQube API交互即可程序化访问SonarQube数据的问题。它满足了生成自动化报告、分析和将SonarQube指标与其他系统集成的需求。具体来说，它简化了以下任务：

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

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

3. 模块和组件之间的交互

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

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

服务器使用httpx库进行异步HTTP请求到SonarQube API。它根据执行的工具和客户端提供的输入参数构造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）客户端应用程序。
• **解决潜在的安全漏洞