# MCP SonarCloud Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-2.0+-green.svg)](https://modelcontextprotocol.io)

A Model Context Protocol (MCP) server implementation for SonarCloud, providing tools to interact with SonarCloud projects, issues, quality gates, and security hotspots.

> Default layout:
> - Config: `~/.config/lukleh/mcp-sonarcloud/config.toml`
> - Credentials: injected via the MCP client or shell environment
> - State: `~/.local/state/lukleh/mcp-sonarcloud/`
> - Cache: `~/.cache/lukleh/mcp-sonarcloud/`

## Features

This MCP server provides 15 comprehensive tools with detailed parameter documentation and examples:

### Project Management (3 tools)
- **search_my_sonarqube_projects**: List all SonarCloud projects in your organization with pagination
- **show_component**: Get detailed metadata for a specific project or component
- **component_tree**: Traverse the file/directory structure of a project

### Issues (4 tools)
- **search_sonar_issues_in_projects**: Search for issues with filtering by pull request, severity (INFO, LOW, MEDIUM, HIGH, BLOCKER), and more
- **list_issue_authors**: Discover SCM authors who contributed to issues
- **get_issue_changelog**: Retrieve the change history of an issue
- **list_issue_tags**: List available tags used on issues

### Quality Gates (5 tools)
- **get_project_quality_gate_status**: Get the quality gate status (OK, ERROR, WARN, NONE) for a project, branch, or pull request
- **list_quality_gates**: List all quality gates in your organization
- **show_quality_gate**: Get detailed conditions for a specific quality gate
- **search_quality_gates**: Find projects associated with a quality gate
- **get_quality_gate_by_project**: Get the quality gate assigned to a project

### Security Hotspots (3 tools)
- **search_hotspots**: Search for security hotspots in a project with file, branch, or PR filters
- **show_hotspot**: Get detailed information about a specific hotspot
- **change_hotspot_status**: Change the status of a hotspot (TO_REVIEW or REVIEWED with resolution: FIXED, SAFE, ACKNOWLEDGED)

All tools include comprehensive parameter descriptions, valid value documentation, and usage examples for optimal AI agent integration.

## Prerequisites

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- A SonarCloud account with an API token
- Claude Code or Codex AI client

## Quick Start

### 1. Get Your SonarCloud Token

1. Log in to [SonarCloud](https://sonarcloud.io)
2. Click on your avatar → **My Account** → **Security**
3. Under "Generate Tokens", enter a name (e.g., "MCP Server")
4. Click **Generate**
5. **Copy and save the token** - you won't be able to see it again!

### 2. Find Your Organization Key

1. Go to your organization on SonarCloud
2. Look at the URL: `https://sonarcloud.io/organizations/YOUR-ORG-KEY`
3. The `YOUR-ORG-KEY` part is your organization key

### 3. Install the Server

```bash
# Run the published package without cloning the repository
uvx mcp-sonarcloud@latest --write-sample-config

# Or install it once and reuse the command directly
uv tool install mcp-sonarcloud@latest
mcp-sonarcloud --write-sample-config
```

### 4. Create the Config File

The command above writes a starter config to `~/.config/lukleh/mcp-sonarcloud/config.toml`.
You can confirm the resolved runtime locations at any time:

```bash
uvx mcp-sonarcloud@latest --print-paths
```

Edit `~/.config/lukleh/mcp-sonarcloud/config.toml`:

```toml
base_url = "https://sonarcloud.io"
organization = "your-org-key"
timeout_sec = 30
```

### 5. Set the Token Environment Variable

Set `SONARCLOUD_TOKEN` in the environment used to launch the server. For local
shell testing, you can export it directly:

```bash
export SONARCLOUD_TOKEN=your-token-here
```

### 6. Configure Your AI Client

**Claude Code:**

```bash
claude mcp add sonarcloud \
  --scope {local, user, or project} \
  -e SONARCLOUD_TOKEN=your-token-here \
  -- uvx mcp-sonarcloud@latest
```

**Codex:**

```bash
codex mcp add sonarcloud \
  --env SONARCLOUD_TOKEN=your-token-here \
  -- uvx mcp-sonarcloud@latest
```

**Important**: Replace `your-token-here` with your real SonarCloud token.

### 7. Restart and Test

1. Restart your AI client
2. Try asking: "Can you list my SonarCloud projects?"

## Configuration

### Files

- `config.toml`
  - `base_url` (optional): SonarCloud or SonarQube base URL
  - `organization` (optional): SonarCloud organization key
  - `timeout_sec` (optional): HTTP timeout in seconds

### Environment Overrides

Environment variables are the source of secrets and also override file values
when present:

- `SONARCLOUD_TOKEN`
- `SONARCLOUD_ORGANIZATION`
- `SONARCLOUD_URL`
- `SONARCLOUD_TIMEOUT_SEC`

### Command Line Testing

You can test the server directly:

```bash
# Show the resolved runtime paths
uvx mcp-sonarcloud@latest --print-paths

# Write or refresh the default config file
uvx mcp-sonarcloud@latest --write-sample-config
uvx mcp-sonarcloud@latest --write-sample-config --overwrite

# Export the token for local testing
export SONARCLOUD_TOKEN=your-token-here

# Run the server with the default home-directory config
uvx mcp-sonarcloud@latest

# Or point at a different config root
uvx mcp-sonarcloud@latest --config-dir /path/to/config-dir
```

### Local Development

If you want to work on the repository itself:

```bash
git clone https://github.com/lukleh/mcp-sonarcloud.git
cd mcp-sonarcloud
uv sync --extra dev
uv run pytest -q
uv run mcp-sonarcloud --print-paths
```

## Usage Examples

### Natural Language Queries

Once configured, you can ask your AI client:

1. **List projects**: "Show me all my SonarCloud projects"
2. **Check quality gate**: "What's the quality gate status for project X on PR 123?"
3. **Search hotspots**: "Find all security hotspots in project X"
4. **Get hotspot details**: "Show me details for hotspot AY1234567890"
5. **Update hotspot**: "Mark hotspot AY1234567890 as reviewed and safe"
6. **Search issues**: "Find all blocker issues in project X's pull request 123"

### Tool Examples (Python)

### List Projects

```python
# Get first page of projects
search_my_sonarqube_projects(page="1")
```

### Search Issues in Pull Request

```python
# Search for issues in a specific pull request
search_sonar_issues_in_projects(
    projects=["my-project"],
    pullRequestId="123",
    ps=100
)
```

### Check Quality Gate Status

```python
# Get quality gate status for a pull request
get_project_quality_gate_status(
    projectKey="my-project",
    pullRequest="123"
)
```

### Search Security Hotspots

```python
# Search hotspots in a project
search_hotspots(
    projectKey="my-project",
    pullRequest="123"
)

# Search hotspots in a specific file
search_hotspots(
    projectKey="my-project",
    files="src/main/java/com/example/MyClass.java",
    branch="main"
)
```

### Get Hotspot Details

```python
# Get detailed information about a hotspot
show_hotspot(hotspot="AX1234567890")
```

### Change Hotspot Status

```python
# Mark a hotspot as reviewed and safe
change_hotspot_status(
    hotspot="AX1234567890",
    status="REVIEWED",
    resolution="SAFE"
)

# Mark a hotspot for review
change_hotspot_status(
    hotspot="AX1234567890",
    status="TO_REVIEW"
)
```

**Valid status values:**
- `TO_REVIEW`: Mark for review
- `REVIEWED`: Mark as reviewed (requires resolution)

**Valid resolution values (when status=REVIEWED):**
- `FIXED`: The vulnerability has been fixed
- `SAFE`: The code is safe and not a vulnerability
- `ACKNOWLEDGED`: The risk is acknowledged but accepted

## Troubleshooting

### Common Issues

**"Config file already exists"**
- `--write-sample-config` will not replace an existing file unless you add `--overwrite`
- Use `uvx mcp-sonarcloud@latest --print-paths` to confirm which config path is active

**"SONARCLOUD_TOKEN environment variable is required"**
- Double-check your token is correctly set in the environment variables
- Verify there are no extra spaces or quotes around the token

**"401 Unauthorized"**
- Your token might be invalid or expired
- Generate a new token from SonarCloud and update your configuration

**MCP server not available**
- Verify the server was added: `claude mcp list` or `codex mcp list`
- Run `uvx mcp-sonarcloud@latest --print-paths` in your shell to confirm the package starts cleanly
- Try removing and re-adding the server
- Check your AI client logs for errors

## API Endpoints Used

This server uses the following SonarCloud API endpoints:

### Components / Projects
- `GET /api/components/search` - List projects
- `GET /api/components/show` - Show component metadata
- `GET /api/components/tree` - Traverse component hierarchy

### Issues
- `GET /api/issues/search` - Search issues
- `GET /api/issues/authors` - List issue authors
- `GET /api/issues/changelog` - Get issue change history
- `GET /api/issues/tags` - List issue tags

### Quality Gates
- `GET /api/qualitygates/project_status` - Get quality gate status
- `GET /api/qualitygates/list` - List quality gates
- `GET /api/qualitygates/show` - Show quality gate details
- `GET /api/qualitygates/search` - Search projects by quality gate
- `GET /api/qualitygates/get_by_project` - Get quality gate for project

### Security Hotspots
- `GET /api/hotspots/search` - Search security hotspots
- `GET /api/hotspots/show` - Show hotspot details
- `POST /api/hotspots/change_status` - Change hotspot status

For complete API documentation, see [SONARCLOUD_API_SUPPORT.md](SONARCLOUD_API_SUPPORT.md).

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Releasing

Maintainer release instructions live in [RELEASING.md](RELEASING.md).

## License

MIT License - see LICENSE file for details