内容
<!-- 由 https://github.com/flowgent-labs/mcpfather 生成 -->
# sonarqube-mcp
[](https://go.dev/)
[](https://modelcontextprotocol.io/)
[](https://prometheus.io/)
[](https://opentelemetry.io/)
[](https://openid.net/connect/)
[](https://ldap.com/)
[](https://helm.sh/)
> 一个专为 AI 调用 SonarQube Web API 而设计的企业级 MCP 服务器，由 MCPFather 生成 - 暴露 **385 个原生工具**。每个 API 操作都成为一个 AI 可调用的工具，具有类型化的模式和自定义的聚合虚拟工具，内置身份验证转发和可观察性，甚至可以作为普通的 CLI 使用。
## 快速开始
```sh
make
# 或使用 OpenTelemetry 分布式跟踪（gRPC 或 HTTP）
make build-with-otel-grpc # OTLP gRPC 导出器
make build-with-otel-http # OTLP HTTP/protobuf 导出器
```
### 以 `HTTP` 模式启动（示例）
```sh
# 配置上游 API
export MCP__UPSTREAM__ENDPOINT=https://api.example.com
export MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN=your-token
./bin/sonarqube-mcp --transport http --port 8080 &
```
- 检查 MCP 前端身份验证（OAuth2.1）。
```bash
export MCP__AUTH__FRONTEND__OIDC__ENABLED=true
export MCP__AUTH__FRONTEND__OIDC__ISSUER="https://keycloak.example.com/realms/master"
export MCP__AUTH__FRONTEND__OIDC__AUDIENCE="sonarqube-mcp"
./bin/sonarqube-mcp -v 10 --transport http --port 8080
# 获取 OAuth2.1 元数据。
curl -s https://iam.example.com/realms/master/.well-known/openid-configuration
curl -s localhost:8080/.well-known/oauth-protected-resource
#{"resource":"sonarqube-mcp","authorization_servers":["https://keycloak.example.com/realms/master"],"bearer_methods_supported":["header"]}
```
### 以 `CLI` 模式运行（示例）
```sh
./bin/sonarqube-mcp -v 1 -t cli list
./bin/sonarqube-mcp -v 1 -t cli <tool-name> [OPTIONS]
```
## 选项
| 参数 | 默认值 | 描述 |
|------|---------|-------------|
| `-t, --transport` | `stdio` | `stdio` / `http` / `cli` |
| `-p, --port` | `8080` | HTTP 服务器端口 |
| `--metrics-port` | `0` | 覆盖管理端口（0 = 使用配置） |
| `-v, --verbose` | `0` | 日志详细程度（0–10） |
| `--print-default-config` | — | 将默认的 config.yaml 输出到 stdout |
## 身份验证
身份验证分为两个独立的层 - 两者之间不共享凭证：
| 层 | 配置文件路径 | 环境变量前缀 | 角色 |
|---|---|---|---|
| **前端** | `auth.frontend.oidc` | `MCP__AUTH__FRONTEND__OIDC__*` | 验证 AI 代理的 bearer token（入站） |
| **后端 OIDC** | `auth.backend.oidc` | `MCP__AUTH__BACKEND__OIDC__*` | 服务器自己的 OIDC client_credentials，用于上游 API |
| **后端 LDAP** | `auth.backend.ldap` | `MCP__AUTH__BACKEND__LDAP__*` | 服务器自己的 LDAP 服务账户绑定，用于上游 API |
| **后端静态** | `auth.backend.static` | `MCP__AUTH__BACKEND__STATIC__*` | 服务器自己的静态令牌/cookie，用于上游 API |
**前端（入站）** - 验证 AI 代理呈现的 bearer token。仅适用于 `--transport http`；stdio 没有网络边界。按照 RFC 9728 / MCP 授权规范进行标准 OIDC JWT bearer 验证。
**后端（出站）** - 服务器调用上游 API 时使用的凭证。令牌优先级（先到先得）：
1. **OIDC** client_credentials 授权（`auth.backend.oidc.*`）
2. **LDAP** 服务账户绑定（`auth.backend.ldap.*`）
3. **静态** bearer token（`auth.backend.static.bearer_token`）
AI 代理的入站令牌 **永远不会** 被转发到上游（MCP 规范：令牌传透禁止）。还可以通过 `auth.backend.static.cookie_token` 使用基于 cookie 的身份验证。
## 配置
创建 `~/.sonarqube-mcp/config.yaml`（运行 `--print-default-config` 获取完整模板）：
```yaml
upstream:
endpoint: "" # 上游 API 基本 URL（例如 https://api.example.com）
# 当为真时，MCP 会话 ID 作为 X-MCP-Session-ID 头部转发。
enable_mcp_session_forward: true
runtime:
download_dir: ""
log_authorization: false
# ---- 身份验证 ----
# frontend = 入站：验证 AI 代理呈现的 bearer token。
# backend = 出站：服务器调用上游 API 时使用的凭证。
# 两者是独立的 - 入站令牌永远不会被重用出站
# （参见 MCP 授权规范：令牌传透禁止）。
auth:
frontend:
# 标准 OAuth 2.1 / OIDC JWT bearer 验证（资源服务器角色，RFC 9728）。
# 仅在 http 传输中强制执行；stdio 没有网络边界。
oidc:
enabled: false
issuer: "" # 例如 https://idp.example.com/realms/myrealm
jwks_uri: "" # 可选覆盖（如果为空，则从发行者自动发现）
audience: "" # 期望的 JWT "aud" 声明；也作为 RFC 9728 受保护资源标识符发布
# 当为真时，验证的前端 JWT 声明（sub, email）将作为 X-MCP-Client-Token-Sub 和 X-MCP-Client-Token-Email 头部转发。
enable_client_token_claim_forward: true
# 要转发的附加 JWT 声明为 X-MCP-Client-Token-<Header-Name> 头部。
# 例如 ["given_name", "family_name", "preferred_username"]
# additional_client_token_claim_forward: []
# 出站：服务器调用上游 API 时使用的凭证。
backend:
oidc:
enabled: true
issuer: https://idp.example.com/realms/myrealm
client_id: my-client
client_secret: "${MCP__AUTH__BACKEND__OIDC__CLIENT_SECRET}"
scopes: openid
# token_url: "" # 从发行者 /.well-known 自动发现
ldap:
enabled: false
url: ldaps://ldap.example.com
base_dn: dc=example,dc=com
bind_dn: cn=svc,dc=example,dc=com
bind_password: "${MCP__AUTH__BACKEND__LDAP__BIND_PASSWORD}"
static:
bearer_token: "${MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN}" # 或设置 cookie_token
nativeTools:
expose:
register_all_tools_by_default: true # 暴露所有原生工具
# includes: [Tool1, Tool2] # 或白名单特定工具
# excludes: [Tool3] # 隐藏噪音工具
```
所有值都可以通过 `MCP__` 前缀的环境变量设置（例如 `MCP__AUTH__BACKEND__OIDC__CLIENT_ID`）。
## 管理 - 指标、跟踪、Pprof
```yaml
mgmt:
enabled: true
host: 0.0.0.0
port: 9991
otel:
enabled: false
endpoint: localhost:4317
protocol: grpc
sample_rate: 1.0
metrics:
enabled: true
prometheus: true
export_interval: 30s
pprof:
enabled: false
server_bind: 0.0.0.0:6669
```
```sh
./bin/sonarqube-mcp --transport http --port 8080
curl http://localhost:9991/metrics # Prometheus 端点
curl http://localhost:9991/health # 健康检查
```
跟踪范围命名为 `mcp.tool.<name>`。W3C `traceparent` 被传播到上游调用。
## 可用工具（385）
| 工具 | 描述 |
|------|-------------|
| `GetAlmIntegrationsCheckPat` | 检查给定 DevOps 平台设置的个人访问令牌的有效性。 - 检查给定 DevOps 平台设置的个人访问令牌的有效性 需要 '创建项目' 权限 |
| `GetAlmIntegrationsGetGithubClientId` | 获取 GitHub 集成的客户端 ID。 - 获取 GitHub 集成的客户端 ID。 |
| `GetAlmIntegrationsListAzureProjects` | 列出 Azure 项目。 - 列出 Azure 项目 需要 '创建项目' 权限 |
| `GetAlmIntegrationsListBitbucketserverProjects` | 列出 Bitbucket Server 项目。 - 列出 Bitbucket Server 项目 需要 '创建项目' 权限 |
| `GetAlmIntegrationsListGithubOrganizations` | 列出 GitHub 组织。 - 列出 GitHub 组织 需要 '创建项目' 权限 |
| `GetAlmIntegrationsListGithubRepositories` | 列出 GitHub 组织的存储库。 - 列出 GitHub 组织的存储库 需要 '创建项目' 权限 |
| `GetAlmIntegrationsSearchAzureRepos` | 搜索 Azure 存储库。 - 搜索 Azure 存储库 需要 '创建项目' 权限 |
| `GetAlmIntegrationsSearchBitbucketcloudRepos` | 搜索 Bitbucket Cloud 存储库。 - 搜索 Bitbucket Cloud 存储库 需要 '创建项目' 权限 |
| `GetAlmIntegrationsSearchBitbucketserverRepos` | 使用 REPO_ADMIN 访问权限搜索 Bitbucket Server 存储库。 - 使用 REPO_ADMIN 访问权限搜索 Bitbucket Server 存储库 需要 '创建项目' 权限 |
| `GetAlmIntegrationsSearchGitlabRepos` | 搜索 GitLab 项目。 - 搜索 GitLab 项目。 需要 '创建项目' 权限 |
| `GetAlmSettingsCountBinding` | 统计与 DevOps 平台设置绑定的项目数量。 - 统计与 DevOps 平台设置绑定的项目数量 需要 '管理系统' 权限 |
| `GetAlmSettingsGetBinding` | 获取给定项目的 DevOps 平台绑定。 - 获取给定项目的 DevOps 平台绑定 需要项目的 '浏览' 权限 |
| `GetAlmSettingsList` | 列出给定项目的 DevOps 平台设置，按 DevOps 平台键排序。 - 列出给定项目的 DevOps 平台设置，按 DevOps 平台键排序 如果提供了 `project` 参数，则需要 '管理项目' 权限，否则需要 '创建项目' 权限。 |
| `GetAlmSettingsListDefinitions` | 按创建时间列出 DevOps 平台设置。 - 按创建时间列出 DevOps 平台设置 需要 '管理系统' 权限 |
| `GetAlmSettingsValidate` | 通过检查连接性和权限验证 DevOps 平台设置。 - 通过检查连接性和权限验证 DevOps 平台设置 需要 '管理系统' 权限 |
| … | *还有 370 个工具未显示* |
## 虚拟工具
通过声明式管道 DSL 组合原生工具：
```yaml
virtualTools:
- name: MyVirtualTool
description: 链多个原生工具
inputSchema:
type: object
properties:
appId: { type: string }
required: [appId]
pipeline:
- id: getApp
kind: call
spec: { tool: GetApplication, args: { applicationId: "$input.appId" } }
- id: appName
kind: jq
spec: { from: "$getApp", expr: .name }
- id: done
kind: return
spec: { from: "$appName" }
```
管道种类：`call`, `jq`, `foreach`, `emit`, `return`.
## 代理集成
### OpenCode
- `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"sonarqube-mcp": {
"type": "local",
"command": ["bash", "-c", "/path/to/sonarqube-mcp"],
"args": ["--transport", "stdio"],
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
},
"enabled": true
}
}
}
```
### Claude Code
- `~/.claude.json`:
```json
{
"mcpServers": {
"sonarqube-mcp": {
"command": "/path/to/sonarqube-mcp",
"args": ["--transport", "stdio"],
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### Codex CLI
- `~/.codex/config.toml`:
```toml
[mcp_servers.sonarqube-mcp]
url = "http://localhost:8080/mcp"
bearer_token_env_var = "MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN"
```
### Cursor
- `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"sonarqube-mcp": {
"command": "/path/to/sonarqube-mcp",
"args": ["--transport", "stdio"],
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### OpenCode (远程)
- `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"sonarqube-mcp": {
"type": "remote",
"url": "http://localhost:8080/mcp",
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### Claude Code (远程)
- `~/.claude.json`（用户 MCPs):
```json
{
"mcpServers": {
"sonarquube-mcp": {
"url": "http://localhost:8080/mcp",
"env": {
"MCP__UPSTREAM__ENDPOINT": "https://api.example.com",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN": "your-token",
"MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN_FILE": "/path/to/fallback/.credentials"
}
}
}
}
```
### Codex CLI (远程)
- `~/.codex/config.toml`:
```toml
[mcp_servers.sonarqube-mcp]
url = "http://localhost:8080/mcp"
bearer_token_env_var = "MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN"
```
### Cursor (远程)
- `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"sonarquube-mcp": {
"url": "http://localhost:8080/mcp"
}
}
}
```
## 部署 - Docker
### 构建
```sh
make build-image
```
或手动：
```sh
docker build -t ghcr.io/<YOUR_ORG>/sonarqube-mcp:latest -f deploy/docker/Dockerfile .
docker push ghcr.io/<YOUR_ORG>/sonarqube-mcp:latest
```
### 运行
从 GitHub 容器注册表拉取预构建的镜像：
```sh
docker pull ghcr.io/<YOUR_ORG>/sonarqube-mcp:latest
```
- **静态 bearer token**
```sh
docker run -d --name sonarqube-mcp \
-p 8080:8080 -p 9991:9991 \
-e MCP__UPSTREAM__ENDPOINT="https://api.example.com" \
-e MCP__AUTH__BACKEND__STATIC__BEARER_TOKEN="YOUR_BEARER_TOKEN" \
ghcr.io/<YOUR_ORG>/sonarqube-mcp:latest \
--transport http --port 8080
```
- **OIDC 后端身份验证**
```sh
docker run -d --name sonarqube-mcp \
-p 8080:8080 -p 9991:9991 \
-e MCP__UPSTREAM__ENDPOINT="https://api.example.com" \
-e MCP__AUTH__BACKEND__OIDC__ENABLED=true \
-e MCP__AUTH__BACKEND__OIDC__ISSUER="https://idp.example.com/realms/myrealm" \
-e MCP__AUTH__BACKEND__OIDC__CLIENT_ID="my-client" \
-e MCP__AUTH__BACKEND__OIDC__CLIENT_SECRET="YOUR_CLIENT_SECRET" \
ghcr.io/<YOUR_ORG>/sonarqube-mcp:latest \
--transport http --port 8080
```
- **LDAP 后端身份验证**
```sh
docker run -d --name sonarqube-mcp \
-p 8080:8080 -p 9991:9991 \
-e MCP__UPSTREAM__ENDPOINT="https://api.example.com" \
-e MCP__AUTH__BACKEND__LDAP__ENABLED=true \
-e MCP__AUTH__BACKEND__LDAP__URL="ldaps://ldap.example.com" \
-e MCP__AUTH__BACKEND__LDAP__BASE_DN="dc=example,dc=com" \
-e MCP__AUTH__BACKEND__LDAP__BIND_DN="cn=svc,dc=example,dc=com" \
-e MCP__AUTH__BACKEND__LDAP__BIND_PASSWORD="YOUR_BIND_PASSWORD" \
ghcr.io/<YOUR_ORG>/sonarqube-mcp:latest \
--transport http --port 8080
```
## 部署 - Kubernetes (Helm)
- **静态 bearer token**
```sh
helm upgrade -i sonarqube-mcp deploy/helm \
--set image.repository=ghcr.io/<YOUR_ORG>/sonarqube-mcp \
--set image.tag=latest \
--set secret.static.create=true \
--set secret.static.bearerToken="YOUR_BEARER_TOKEN" \
--set config.upstream.endpoint="https://api.example.com"
```
- **OIDC 身份验证**
```sh
helm upgrade -i sonarqube-mcp deploy/helm \
--set image.repository=ghcr.io/<YOUR_ORG>/sonarqube-mcp \
--set image.tag=latest \
--set secret.static.create=true \
--set secret.static.oidcClientSecret="YOUR_OIDC_CLIENT_SECRET" \
--set config.auth.backend.oidc.enabled=true \
--set config.auth.backend.oidc.issuer="https://idp.example.com" \
--set config.auth.backend.oidc.clientId="my-client" \
--set config.upstream.endpoint="https://api.example.com"
```
- **LDAP 身份验证**
```sh
helm upgrade -i sonarqube-mcp deploy/helm \
--set image.repository=ghcr.io/<YOUR_ORG>/sonarqube-mcp \
--set image.tag=latest \
--set secret.static.create=true \
--set secret.static.ldapBindPassword="YOUR_LDAP_BIND_PASSWORD" \
--set config.auth.backend.ldap.enabled=true \
--set config.auth.backend.ldap.url="ldaps://ldap.example.com" \
--set config.auth.backend.ldap.bindDN="cn=svc,dc=example,dc=com" \
--set config.upstream.endpoint="https://api.example.com"
```
查看 `deploy/helm/values.yaml` 获取所有可配置的参数。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器