<中文翻译> SonarQube-MCP服务器

SonarQube MCP 服务器

该项目打包了一个模型上下文协议（MCP）服务器，用于需要调查和修复 SonarQube 问题的人工智能编码代理。该服务器基于 FastMCP，并封装了官方的 SonarQube REST API，提供以下功能：

• 高信号的问题搜索结果，突出显示严重性、所有权和文件位置。
• 特定 SonarQube 问题的详细修复上下文，包括相关规则描述和修复建议。
• 直接访问规则元数据以支持定制工作流。

🧠 目标：为代理提供足够的结构化上下文，使其能够理解问题，定位有问题的代码，并应用推荐的修复，而无需访问 SonarQube 用户界面。

要求

• Python 3.12+
• 访问一个 SonarQube 实例（云或自托管），并具有可以读取问题和规则的 API 令牌。
• fastmcp 包已经包含；不捆绑 MCP 客户端。

配置

您必须配置您的 SonarQube 实例的基本 URL。认证可以通过两种方式提供：

1. 每个用户的 Bearer 令牌通过 Authorization: Bearer <token> HTTP 头部在使用 HTTP/SSE 传输时提供（推荐——允许每个用户/代理拥有最小权限访问）。
2. 当没有头部时使用的静态环境变量令牌（SONARQUBE_TOKEN）（在没有 HTTP 头部可用的情况下，例如 stdio 传输时需要）。

在启动服务器之前设置以下环境变量：

变量	描述	示例
SONARQUBE_BASE_URL	您的 SonarQube 实例的基本 URL（无尾随斜杠）	https://sonarqube.internal
SONARQUBE_TOKEN (可选)	回退个人访问令牌，具有对项目的 浏览 权限。仅在未提供 Authorization 头部时使用。	squ_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
SONARQUBE_TIMEOUT (可选)	请求超时时间（默认为 115 秒）	20

您可以将这些存储在一个 .env 文件中，或者通过进程管理器提供它们。

安装

uv sync

对于开发和测试依赖项：

uv sync --extra test

运行服务器

默认情况下，服务器通过 stdio 运行，这对于本地 MCP 客户端来说是理想的：

uv run python -m src.main

要暴露 HTTP 传输，请在运行时添加相应的选项：

uv run python -m src.main --transport http --host 0.0.0.0 --port 8765

支持的传输方式与 FastMCP 中的一致（stdio，http，sse）。当使用 http/sse 时，发送一个 Authorization 头部以便服务器可以代表该用户执行 SonarQube 调用：

Authorization: Bearer squ_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

如果省略头部，服务器将回退到 SONARQUBE_TOKEN。

基于头部的身份验证示例

服务器内部会在每次工具调用时检查传入的头部（通过 FastMCP 的 get_http_headers）。简化示例：

from fastmcp import FastMCP
from fastmcp.server.dependencies import get_http_headers

mcp = FastMCP(name="Demo")

@mcp.tool
async def who_am_i() -> dict:
    headers = get_http_headers()
    auth = headers.get("authorization", "") if headers else ""
    return {
        "has_auth": bool(auth),
        "auth_is_bearer": auth.lower().startswith("bearer "),
        "user_agent": headers.get("user-agent") if headers else None,
    }

这反映了 SonarQube 工具用来解析每个请求的活动令牌的机制。

VS Code MCP 客户端配置

如果您正在使用 VS Code 内置的 MCP 客户端（或读取 mcp.json 样式清单的扩展），可以提示用户输入他们的 SonarQube 令牌，并将其作为承载头部传递。配置片段示例：

{
	"servers": {
		"sonarqube": {
			"url": "http://localhost:8765/mcp",
			"type": "http",
			"headers": {
				"Authorization": "Bearer ${input:sonarqube_token}"
			}
		}
	},
	"inputs": [
		{
			"id": "sonarqube_token",
			"type": "promptString",
			"description": "SonarQube Token"
		}
	]
}

注意事项：

• ${input:...} 占位符确保令牌不会以明文形式存储在配置文件中；用户将在 VS Code 中被提示输入。
• 如果您不想每次都提示，可以设置环境变量 SONARQUBE_TOKEN 并省略 headers 块（对于多用户场景不太精细）。
• 当通过 HTTPS 使用公司 CA 后面的远程 SonarQube 实例时，请确保您的 Python 环境信任该 CA（例如通过 REQUESTS_CA_BUNDLE / SSL_CERT_FILE）。

可用工具

工具	目的	关键参数
get_issue_context	通过键获取单个问题，拉取其规则，并返回丰富的 Markdown 简报以及机器可读的元数据。	issue_key (字符串)
search_issues	包装 /api/issues/search，暴露最常见的过滤器，并为每个结果补充组件路径。	issue_keys, components, severities, issue_statuses, resolutions, types, tags, assignees, languages, created_after, created_before, resolved, sort_field, ascending, page, page_size
get_rule	从 /api/rules/show 获取原始规则元数据。	rule_key (字符串)

所有工具都返回 JSON 序列化的字典，便于在代理工作流中串联使用。

示例工作流

1. 使用 project="Agrega-Server" 调用 search_issues 以检索开放问题。
2. 对于每个问题，调用 get_issue_context(issue_key)。
3. 使用 markdown 字段向 LLM 提供简报，并使用结构化的 issue/rule 部分构建自动化修复。

来自 SonarQube 参考实例的样本 API 响应可以在 sample_search_api_response.json 和 sample_rule_api_response.json 中找到。

测试

安装可选的 test 扩展后：

uv run python -m pytest

测试使用 respx 模拟外部 HTTP 调用，因此它们离线快速运行。

故障排除

• 如果服务器启动但每个工具调用立即失败，请确保您的 SonarQube 实例接受 Authorization 头部，并且您的令牌具有查看项目/问题的权限。
• 您可以调用 configuration_status 工具（仅在服务器配置错误时可用）来诊断缺失的环境变量。
• 设置 HTTPX_LOG_LEVEL=debug 在运行进程时启用 HTTP 级别日志记录，以获得更深入的可见性。

发展路线 / 构想

• 当可用时，通过 flows 元数据展示代码片段。
• 缓存规则元数据以减少长时间会话中的重复请求。
• 添加工具度量（延迟，错误率）以帮助识别不稳定集成。