内容
# MCP SonarQube 服务器
[](https://dotnet.microsoft.com/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](#可用工具)
[](#开发)
一个 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，允许 AI 助手与 SonarQube 交互 — 查询项目、深入了解问题、审核拉取请求、定位重复代码、检查质量门 — 所有操作都通过单一的 HTTP 传输。
### 亮点
- **一次调用分析拉取请求** — `analyze_pull_request` 并行聚合质量门、新代码度量、问题和安全热点
- **定位错误文件** — `get_component_tree_measures` 将聚合指标按文件/目录分解，以便代理知道在哪里修复
- **精确重复代码块** — `get_duplications` 返回行范围和配对文件
- **清晰的错误** — Sonar 的错误体（`errors[].msg`）通过每个包装器传播
---
## 快速入门
```bash
# 1. 克隆仓库
git clone https://github.com/viamus/mcp-sonarqube.git
cd mcp-sonarqube
# 2. 配置凭证
cp .env.example .env
# 使用您的 SonarQube URL 和令牌编辑 .env
# 3. 运行服务器
docker compose up -d
```
---
## 先决条件
| 需求 | 版本 | 目的 |
|-------------|---------|---------|
| .NET SDK | 10.0+ | 构建和运行 |
| Docker | 最新 | 容器部署（可选） |
| SonarQube 实例 | 9.x+ | API 访问 |
**必填：**
- SonarQube 基本 URL（例如，`https://sonarqube.example.com`）
- SonarQube 用户令牌（在：您的 SonarQube > 我的帐户 > 安全 > 令牌中生成）
---
## 可用工具
13 个 MCP 工具，按领域分组：
| 领域 | 工具 | 目的 |
|--------|------|---------|
| **拉取请求** | `analyze_pull_request` | 聚合拉取请求视图 — 质量门、新代码度量、问题、安全热点（4 次调用并行） |
| **项目** | `search_projects` | 按名称或键搜索项目 |
| | `get_project_status` | 项目的质量门状态 + 关键度量 |
| **问题** | `search_issues` | 搜索问题并支持过滤；支持 `pullRequest` 范围 |
| **度量** | `get_measures` | 获取组件的指标 |
| | `get_component_tree_measures` | 将指标按文件/目录分解 — 定位错误文件 |
| **重复代码** | `get_duplications` | 精确的重复代码块（行范围 + 配对文件） |
| **质量门** | `list_quality_gates` | 列出所有具有条件的门 |
| **安全热点** | `search_hotspots` | 搜索安全热点 |
| | `get_hotspot` | 详细的安全热点信息 |
| **规则** | `search_rules` | 按语言/严重性/标签搜索编码规则 |
| **系统** | `get_health` | SonarQube 实例的健康状态 |
有关每个工具包装的底层 SonarQube 端点，请参见下面的 [API 参考](#api-参考)。
---
## 运行选项
### 选项 1：Docker Compose（推荐）
```bash
docker compose up -d
```
服务器将在 `http://localhost:8082` 上可用。
### 选项 2：.NET CLI
```bash
dotnet run --project src/Viamus.Sonarqube.Mcp.Server
```
服务器将在 `http://localhost:5100` 上可用。
### 选项 3：独立可执行文件
```bash
dotnet publish src/Viamus.Sonarqube.Mcp.Server -c Release -o ./publish
./publish/Viamus.Sonarqube.Mcp.Server
```
---
## 客户端配置
### Claude Desktop
添加到您的 Claude Desktop 配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"sonarqube": {
"url": "http://localhost:8082"
}
}
}
```
### Claude Code
```bash
claude mcp add sonarqube --scope user --transport http http://localhost:8082
```
---
## 使用示例
### 审核拉取请求端到端
```
分析项目“my-app”中的拉取请求 1234。它是否通过了质量门？
如果通过，找到哪些文件集中了新的重复代码行并显示给我
确切的重复代码块。
```
> 在幕后，代理通常会链接 `analyze_pull_request` → `get_component_tree_measures`（按 `new_duplicated_lines` 排序）→ `get_duplications` 到最坏的文件。
### 搜索项目
```
在我的 SonarQube 实例中搜索所有包含“backend”的项目。
```
### 检查项目质量
```
“my-app”项目的质量门状态是什么？显示覆盖率和缺陷数。
```
### 查找关键问题
```
在“my-app”项目中搜索所有关键和阻止严重性问题。
```
### 审查安全热点
```
在“my-app”项目中显示所有需要审查的安全热点。
```
### 搜索编码规则
```
查找所有适用于 C# 语言的主要严重性规则。
```
### 检查系统健康状况
```
我的 SonarQube 实例是否健康？
```
---
## 配置
### 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `SONARQUBE_BASE_URL` | 是 | SonarQube 实例 URL |
| `SONARQUBE_TOKEN` | 是 | SonarQube 用户令牌 |
| `SONARQUBE_ORGANIZATION` | 否 | SonarCloud 组织密钥 |
| `SERVER_REQUIRE_API_KEY` | 否 | 启用 API 密钥身份验证（默认：`false`） |
| `SERVER_API_KEY` | 否 | 服务器访问的 API 密钥 |
### appsettings.json
```json
{
"SonarQube": {
"BaseUrl": "https://your-sonarqube-instance.com",
"Token": "your-token-here",
"Organization": ""
},
"ServerSecurity": {
"RequireApiKey": false,
"ApiKey": ""
}
}
```
### 用户机密（开发）
```bash
cd src/Viamus.Sonarqube.Mcp.Server
dotnet user-secrets set "SonarQube:BaseUrl" "https://your-sonarqube-instance.com"
dotnet user-secrets set "SonarQube:Token" "your-token-here"
dotnet user-secrets set "SonarQube:Organization" "your-sonarcloud-organization"
```
---
## 故障排除
### 常见问题
**连接被拒绝**
- 验证 SonarQube 基本 URL 是否正确且可访问
- 检查服务器是否正在运行：`curl http://localhost:8082/health`
**SonarQube 返回 401 未授权**
- 验证您的令牌是否有效且未过期
- 在：您的 SonarQube > 我的帐户 > 安全 > 令牌中生成新的令牌
**未找到项目**
- 确保您的令牌具有足够的权限
- 验证项目是否存在于您的 SonarQube 实例中
**Docker 容器无法启动**
- 检查日志：`docker compose logs mcp-sonarqube`
- 验证 `.env` 文件是否存在且包含有效的凭证
---
## 项目结构
```
mcp-sonarqube/
├── src/Viamus.Sonarqube.Mcp.Server/
│ ├── Configuration/ # 设置类
│ ├── Middleware/ # API 密钥身份验证
│ ├── Models/ # SonarQube API DTO
│ ├── Services/ # SonarQube API 的 HTTP 客户端
│ ├── Tools/ # MCP 工具实现（13 个工具）
│ └── Program.cs # 入口点
├── tests/Viamus.Sonarqube.Mcp.Server.Tests/
│ ├── Configuration/ # 设置和中间件测试
│ ├── Models/ # 序列化测试
│ └── Tools/ # 工具行为测试
├── docker-compose.yml
└── Solution.slnx
```
---
## API 参考
### 使用的 SonarQube API 端点
| 端点 | 工具 |
|----------|---------|
| `/api/projects/search` | `search_projects` |
| `/api/qualitygates/project_status` | `get_project_status`, `analyze_pull_request` |
| `/api/qualitygates/list` | `list_quality_gates` |
| `/api/measures/component` | `get_project_status`, `get_measures`, `analyze_pull_request` |
| `/api/measures/component_tree` | `get_component_tree_measures` |
| `/api/duplications/show` | `get_duplications` |
| `/api/issues/search` | `search_issues`, `analyze_pull_request` |
| `/api/hotspots/search` | `search_hotspots`, `analyze_pull_request` |
| `/api/hotspots/show` | `get_hotspot` |
| `/api/rules/search` | `search_rules` |
| `/api/system/health` | `get_health` |
---
## 开发
### 构建
```bash
dotnet build Solution.slnx
```
### 测试
```bash
dotnet test Solution.slnx
```
### 添加新工具
参见 [CONTRIBUTING.md](CONTRIBUTING.md#添加新的mcp工具) 获取详细说明。
---
## 许可证
该项目使用 MIT 许可证 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
