内容
# sonarqube-api-mcp
无Docker的SonarQube MCP服务器，用于只读访问SonarQube Web API。
运行它：
```bash
npx sonarqube-api-mcp
```
## 要求
- Node.js 20+
- 具有浏览目标项目权限的SonarQube令牌
- 无Docker
此包仅使用公共SonarQube Web API。它不使用私有SonarQube UI GraphQL端点。
它适用于以下编码代理工作流：
- "修复所有新代码问题"
- "修复所有整体代码问题"
- "修复此SonarQube项目名称的问题"
服务器保持只读：它获取SonarQube问题、源上下文、规则详细信息和质量数据，以便调用代理可以编辑检出的仓库。
## 配置
通过`mcp.json`中的环境变量配置服务器。
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `SONAR_HOST_URL` | 是 | SonarQube基准URL。尾部斜杠规范化。 |
| `SONAR_TOKEN` | 是 | SonarQube令牌。以`Authorization: Basic base64("${SONAR_TOKEN}:")`形式发送。 |
| `SONAR_PROJECT_KEY` | 否 | 默认项目键，用于项目范围工具，当省略`projectKey`和`projectName`时。 |
当缺少`SONAR_HOST_URL`或`SONAR_TOKEN`时，启动失败。
## 已发布包的使用
```json
{
"mcpServers": {
"sonarqube": {
"command": "npx",
"args": ["-y", "sonarqube-api-mcp"],
"env": {
"SONAR_HOST_URL": "https://sonarqube.yourcompany.com",
"SONAR_TOKEN": "YOUR_SONAR_TOKEN",
"SONAR_PROJECT_KEY": "hvmb-app"
}
}
}
}
```
## 本地包开发
首先构建：
```bash
npm install
npm run build
```
然后将您的MCP客户端指向编译后的入口点：
```json
{
"mcpServers": {
"sonarqube-local": {
"command": "node",
"args": ["/absolute/path/to/sonarqube-api-mcp/dist/index.js"],
"env": {
"SONAR_HOST_URL": "https://sonarqube.yourcompany.com",
"SONAR_TOKEN": "YOUR_SONAR_TOKEN",
"SONAR_PROJECT_KEY": "hvmb-app"
}
}
}
}
```
## 默认项目键
设置`SONAR_PROJECT_KEY`一次，并省略项目范围工具调用中的`projectKey`。
```json
{
"mcpServers": {
"sonarqube": {
"command": "npx",
"args": ["-y", "sonarqube-api-mcp"],
"env": {
"SONAR_HOST_URL": "https://sonarqube.yourcompany.com",
"SONAR_TOKEN": "YOUR_SONAR_TOKEN",
"SONAR_PROJECT_KEY": "hvmb-app"
}
}
}
}
```
示例工具输入：
```json
{
"resolved": false,
"severities": ["BLOCKER", "CRITICAL"]
}
```
## 按工具覆盖项目
每个项目范围的工具都接受`projectKey`或`projectName`，它为该调用覆盖`SONAR_PROJECT_KEY`。
```json
{
"projectKey": "another-project",
"branch": "main",
"metricKeys": ["coverage", "bugs", "vulnerabilities"]
}
```
如果您的基础设施为每个分支创建一个SonarQube项目，请直接传递SonarQube项目名称：
```json
{
"projectName": "repo-name-feature-branch",
"scope": "new_code"
}
```
如果名称匹配多个项目，则工具返回候选项目并要求调用者使用`projectKey`重试。
## 工具
### `search_sonar_projects`
搜索`/api/projects/search`以通过SonarQube项目名称或键查找项目键。
输入：
- `query`可选字符串
- `pageSize`可选数字，默认为`100`
### `get_sonar_fix_plan`
获取未解决的问题，按文件分组以适应代理修复工作流。
将其用于类似“修复所有新代码问题”或“修复所有整体代码问题”的提示。
输入：
- `projectKey`可选，默认为`SONAR_PROJECT_KEY`
- `projectName`可选，通过`/api/projects/search`解析
- `scope`可选，`new_code`或`overall`，默认为`new_code`
- `branch`可选
- `pullRequest`可选
- `severities`可选字符串数组
- `statuses`可选字符串数组
- `types`可选字符串数组
- `impactSeverities`可选字符串数组，用于较新的SonarQube版本
- `impactSoftwareQualities`可选字符串数组，用于较新的SonarQube版本
- `pageSize`可选数字，默认为`100`
- `maxIssues`可选数字，默认为`200`
- `includeSource`可选布尔值，默认为`true`
- `includeRules`可选布尔值，默认为`false`
- `contextLines`可选数字，默认为`5`
新代码示例：
```json
{
"projectName": "hvmb-app-feature-branch",
"scope": "new_code",
"includeSource": true,
"includeRules": true
}
```
整体代码示例：
```json
{
"projectKey": "hvmb-app",
"scope": "overall",
"maxIssues": 500
}
```
返回干净的JSON，包含：
- 已解析的项目身份
- 问题计数和截断标志
- 按规则键可选的规则详细信息
- 按问题计数排序的文件
- 每文件的问题
- 受影响行周围的合并源范围
### `get_sonar_issue_context`
获取一个问题以及周围的源代码行和可选的规则详细信息。
输入：
- `issueKey`必填
- `branch`可选
- `pullRequest`可选
- `contextLines`可选数字，默认为`5`
- `includeRule`可选布尔值，默认为`true`
### `search_sonar_issues`
搜索`/api/issues/search`并处理分页。
输入：
- `projectKey`可选，默认为`SONAR_PROJECT_KEY`
- `projectName`可选，通过`/api/projects/search`解析
- `branch`可选
- `pullRequest`可选
- `severities`可选字符串数组
- `statuses`可选字符串数组
- `types`可选字符串数组
- `impactSeverities`可选字符串数组，用于较新的SonarQube版本
- `impactSoftwareQualities`可选字符串数组，用于较新的SonarQube版本
- `inNewCodePeriod`可选布尔值
- `resolved`可选布尔值，默认为`false`
- `pageSize`可选数字，默认为`100`
返回干净的JSON，包含问题`key`、`rule`、`severity`、`type`、`message`、`component`、`filePath`、`line`、`textRange`、`effort`、`status`和`tags`。
### `get_quality_gate_status`
调用`/api/qualitygates/project_status`。
输入：
- `projectKey`可选，默认为`SONAR_PROJECT_KEY`
- `projectName`可选，通过`/api/projects/search`解析
- `branch`可选
- `pullRequest`可选
### `get_rule_details`
调用`/api/rules/show`。
输入：
- `ruleKey`必填
### `get_component_measures`
调用`/api/measures/component`。
输入：
- `projectKey`可选，默认为`SONAR_PROJECT_KEY`
- `projectName`可选，通过`/api/projects/search`解析
- `metricKeys`必填字符串数组
- `branch`可选
- `pullRequest`可选
### `get_sonar_sources`
调用`/api/sources/lines`。
输入：
- `component`必填
- `from`可选数字
- `to`可选数字
- `branch`可选
- `pullRequest`可选
## 错误
SonarQube API错误被包装为JSON字符串，包含：
- `endpoint`
- `status`
- `message`
永远不会直接返回HTML错误页面。
## 开发
```bash
npm install
npm run build
```
`prepublishOnly`在发布前运行构建。
