使用说明
SonarQube MCP 服务器
这个项目为需要调查和修复SonarQube问题的AI编码代理打包了一个模型上下文协议（MCP）服务器。该服务器是基于 FastMCP 并且封装了官方的SonarQube REST API以提供：
- 搜索结果突出显示高信号问题的严重性、负责人和文件位置。
- 针对特定SonarQube问题的详细修复上下文，包括相关规则描述和修复建议。
- 直接访问定制工作流的规则元数据。
🧠 这个表情符号通常被用来表示“大脑”或“思考”，在中文里可以翻译为“脑洞”、“思考中”或者简单地用“🧠”来表示（如果上下文允许）。不过，直接翻译这个符号本身并没有固定的意思，更多是根据使用场景来解释。 目标为代理提供足够的结构化上下文，以便其能够理解问题、定位问题代码，并应用推荐的修复方案，而无需访问SonarQube用户界面。
要求
- Python 3.12+
- 访问一个SonarQube实例（云服务或自托管），使用能够读取问题和规则的API令牌。
- 这个（或“该”）
fastmcp软件包已包含在内；未捆绑MCP客户端。
配置
您必须配置您的SonarQube实例的基本URL。认证可以 可通过两种方式提供：
- 通过（某种方式）获取每个用户的Bearer令牌
Authorization: Bearer <token>HTTP头部 当使用HTTP/SSE传输方式时（推荐使用——允许每个用户/代理 （具有最小权限访问）。 - 一个静态环境变量令牌（
SONARQUBE_TOKEN) 用作备用方案 当没有头部信息时（在需要HTTP头部信息的stdio传输中） （不可用）。
在启动服务器之前，请设置以下环境变量：
| 变量 | 描述 | 示例 |
|---|---|---|
SONARQUBE_BASE_URL |
您的SonarQube实例的基础URL（末尾不要加斜杠） | https://sonarqube.internal |
SONARQUBE_TOKEN （可选） |
使用备用个人访问令牌 Browse 访问项目。仅在未提供授权头时使用。 |
squ_XXXXXXXXXXXXXXXXXXXXXXXXXXXX |
SONARQUBE_TIMEOUT （可选） |
请求超时时间（以秒为单位）（默认为 15) |
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的扩展）
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块（粒度较粗的用于 （多用户场景）。 - 当在企业CA后使用HTTPS连接远程SonarQube实例时，
确保您的Python环境信任该证书颁发机构（例如，通过
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字典，从而便于在代理工作流中进行链式调用。
示例工作流程
- 呼叫
search_issues与；和；带有project="Agrega-Server"检索未解决问题。 - 对于每个问题，请致电
get_issue_context(issue_key). - 使用
markdown为大型语言模型（LLM）提供领域知识，并进行结构化issue/rule（将各部分）用于构建自动化修复方案。
以下是根据提供的信息翻译的原文内容： sample_search_api_response.json 和 sample_rule_api_response.json。
测试
安装可选组件后 test 额外：
uv run python -m pytest
该测试使用（某种方法）模拟外部HTTP调用 respx因此，它们离线运行且速度很快。
故障排除
- 如果服务器启动了但所有工具调用都立即失败，请确保
Authorization您的 SonarQube 实例已接受请求头，并且您的令牌有权限查看该项目/问题。 - 你可以调用
configuration_status工具（仅在服务器配置错误时可用）用于诊断缺失的环境变量。 - 通过设置启用HTTP级别的日志记录
HTTPX_LOG_LEVEL=debug在运行以获得更深入可见性的过程时。
路线图/想法
- 当可通过时，表面代码片段如下：
flows元数据。 - 缓存规则元数据，以减少长时间会话中的重复请求。
- 添加工具指标（延迟、错误率）以帮助识别不稳定的集成。
