Metadata-Version: 2.4
Name: sonarqube-mcp-server
Version: 1.0.0
Summary: MCP Server for SonarQube - allows AI assistants to query bugs, vulnerabilities, code smells, security hotspots and more
Author-email: Your Name <your-email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/YOUR_USERNAME/sonarqube-mcp-server
Project-URL: Repository, https://github.com/YOUR_USERNAME/sonarqube-mcp-server
Project-URL: Issues, https://github.com/YOUR_USERNAME/sonarqube-mcp-server/issues
Keywords: mcp,sonarqube,code-quality,ai,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: nacos-mcp-wrapper-python>=0.1.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# SonarQube MCP Server

基于 Python 开发的 SonarQube MCP Server，支持通过账号密码登录，自动生成 API Token，并支持注册到 Nacos MCP 注册中心。

## 功能特性

- **账号密码登录**：自动调用 SonarQube API 生成 Token，无需手动配置 Token
- **Nacos 注册**：配置 `NACOS_SERVER_ADDR` 后自动注册到 Nacos MCP 注册中心
- **多传输模式**：支持 SSE（Docker/K8s 部署）和 stdio（本地调试）
- **Docker/K8s 部署**：完整的容器化部署支持

## 提供的工具

| 工具 | 说明 |
|------|------|
| `search_projects` | 搜索 SonarQube 项目 |
| `list_project_branches` | 列出项目分支 |
| `search_issues` | 搜索 Bug、漏洞、代码异味 |
| `search_hotspots` | 搜索安全热点 |
| `get_hotspot_detail` | 获取安全热点详情 |
| `get_project_measures` | 获取项目质量指标 |
| `get_quality_gate_status` | 获取质量门状态 |
| `get_source_code` | 获取源代码 |
| `search_rules` | 搜索编码规则 |

## 环境变量说明

### SonarQube 配置

| 变量名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| `SONARQUBE_URL` | 否 | `https://sonarqube.xiujiadian.com` | SonarQube 服务地址 |
| `SONARQUBE_USERNAME` | **是** | - | SonarQube 登录用户名 |
| `SONARQUBE_PASSWORD` | **是** | - | SonarQube 登录密码 |

### MCP Server 配置

| 变量名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| `MCP_SERVICE_NAME` | 否 | `sonarqube-mcp-server` | MCP 服务名称（Nacos 注册名称） |
| `MCP_HOST` | 否 | `0.0.0.0` | 监听地址 |
| `MCP_PORT` | 否 | `18001` | 监听端口 |
| `MCP_TRANSPORT` | 否 | `sse`（有Nacos）/ `stdio`（无Nacos） | 传输模式：`sse` 或 `stdio` |

### Nacos 配置（可选）

> 不配置 `NACOS_SERVER_ADDR` 时，服务以标准 FastMCP 模式运行，不注册到 Nacos。

| 变量名 | 必填 | 默认值 | 说明 |
|--------|------|--------|------|
| `NACOS_SERVER_ADDR` | 否 | - | Nacos 服务地址，如 `192.168.1.100:8848` |
| `NACOS_NAMESPACE` | 否 | `public` | Nacos 命名空间 |
| `NACOS_USERNAME` | 否 | - | Nacos 用户名（开启鉴权时需要） |
| `NACOS_PASSWORD` | 否 | - | Nacos 密码（开启鉴权时需要） |

## 安装

### 从 PyPI 安装（推荐）

```bash
pip install sonarqube-mcp-server
# 或使用 uvx 免安装运行
uvx sonarqube-mcp-server
```

### 从源码安装

```bash
git clone https://github.com/YOUR_USERNAME/sonarqube-mcp-server.git
cd sonarqube-mcp-server
pip install .
```

## 快速启动

### PyPI 安装后使用（stdio 模式）

```bash
export SONARQUBE_USERNAME=your_username
export SONARQUBE_PASSWORD=your_password
sonarqube-mcp-server
```

### 本地开发（stdio 模式）

```bash
pip install -e .
export SONARQUBE_USERNAME=your_username
export SONARQUBE_PASSWORD=your_password
python3 -m sonarqube_mcp_server.server
```

### Docker 部署

#### 构建镜像

```bash
docker build -t sonarqube-mcp-server:1.0.0 .
```

#### 最简启动（无 Nacos）

```bash
docker run -d \
  --name sonarqube-mcp-server \
  -p 18001:18001 \
  -e SONARQUBE_USERNAME=your_username \
  -e SONARQUBE_PASSWORD=your_password \
  sonarqube-mcp-server:1.0.0
```

#### 指定 SonarQube 地址

```bash
docker run -d \
  --name sonarqube-mcp-server \
  -p 18001:18001 \
  -e SONARQUBE_URL=https://your-sonarqube.example.com \
  -e SONARQUBE_USERNAME=your_username \
  -e SONARQUBE_PASSWORD=your_password \
  sonarqube-mcp-server:1.0.0
```

#### 启用 Nacos 注册（指定服务名称）

```bash
docker run -d \
  --name sonarqube-mcp-server \
  -p 18001:18001 \
  -e SONARQUBE_URL=https://your-sonarqube.example.com \
  -e SONARQUBE_USERNAME=your_username \
  -e SONARQUBE_PASSWORD=your_password \
  -e NACOS_SERVER_ADDR=192.168.1.100:8848 \
  -e NACOS_NAMESPACE=public \
  -e NACOS_USERNAME=nacos \
  -e NACOS_PASSWORD=nacos \
  -e MCP_SERVICE_NAME=sonarqube-mcp-server \
  sonarqube-mcp-server:1.0.0
```

> **说明**：`MCP_SERVICE_NAME` 是注册到 Nacos 的服务名称，AI 客户端通过此名称发现该 MCP 服务。默认值为 `sonarqube-mcp-server`，同一 Nacos 部署多个实例时需要区分名称。

#### 自定义端口

```bash
docker run -d \
  --name sonarqube-mcp-server \
  -p 18002:18002 \
  -e SONARQUBE_USERNAME=your_username \
  -e SONARQUBE_PASSWORD=your_password \
  -e MCP_PORT=18002 \
  sonarqube-mcp-server:1.0.0
```

### Docker Compose 部署

创建 `.env` 文件：

```env
SONARQUBE_URL=https://your-sonarqube.example.com
SONARQUBE_USERNAME=your_username
SONARQUBE_PASSWORD=your_password
NACOS_SERVER_ADDR=192.168.1.100:8848
NACOS_NAMESPACE=public
NACOS_USERNAME=nacos
NACOS_PASSWORD=nacos
MCP_SERVICE_NAME=sonarqube-mcp-server
```

启动：

```bash
docker-compose up -d
```

### Kubernetes 部署

1. 修改 `deploy/k8s/configmap.yaml` 中的非敏感配置：
   - `SONARQUBE_URL`
   - `MCP_SERVICE_NAME`（修改 Nacos 注册名称）
   - `NACOS_NAMESPACE`

2. 修改 `deploy/k8s/secret.yaml` 中的敏感配置（base64 编码）：
   ```bash
   echo -n "your_username" | base64
   echo -n "your_password" | base64
   ```

3. 部署：
   ```bash
   kubectl apply -f deploy/k8s/
   ```

## MCP 客户端配置

### SSE 模式（Docker/K8s）

```json
{
  "mcpServers": {
    "sonarqube": {
      "url": "http://your-host:18001/sse"
    }
  }
}
```

### stdio 模式（本地）

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "sonarqube-mcp-server",
      "env": {
        "SONARQUBE_URL": "https://your-sonarqube.example.com",
        "SONARQUBE_USERNAME": "your_username",
        "SONARQUBE_PASSWORD": "your_password"
      }
    }
  }
}
```

## 健康检查

服务启动后，可通过以下方式检查端口是否正常：

```bash
# 检查端口连通性
python3 -c "import socket; s=socket.socket(); s.settimeout(3); s.connect(('127.0.0.1',18001)); s.close(); print('healthy')"

# 查看容器状态
docker ps | grep sonarqube-mcp-server
```
