# sonarqube-api-mcp

Docker-free SonarQube MCP server for read-only access to the SonarQube Web API.

Run it with:

```bash
npx sonarqube-api-mcp
```

## Requirements

- Node.js 20+
- SonarQube token with permission to browse the target project
- No Docker

This package uses the public SonarQube Web API only. It does not use private SonarQube UI GraphQL endpoints.

It is designed for coding-agent workflows like:

- "fix all new code issues"
- "fix all overall code issues"
- "fix issues for this SonarQube project name"

The server stays read-only: it fetches SonarQube issues, source context, rule details, and quality data so the calling agent can edit the checked-out repository.

## Configuration

Configure the server entirely through environment variables in `mcp.json`.

| Variable | Required | Description |
| --- | --- | --- |
| `SONAR_HOST_URL` | Yes | SonarQube base URL. Trailing slashes are normalized. |
| `SONAR_TOKEN` | Yes | SonarQube token. Sent as Basic Auth using `Authorization: Basic base64("${SONAR_TOKEN}:")`. |
| `SONAR_PROJECT_KEY` | No | Default project key used by project-scoped tools when `projectKey` and `projectName` are omitted. |

Startup fails clearly when `SONAR_HOST_URL` or `SONAR_TOKEN` is missing.

## Published package usage

```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"
      }
    }
  }
}
```

## Local package development

Build first:

```bash
npm install
npm run build
```

Then point your MCP client at the compiled entrypoint:

```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"
      }
    }
  }
}
```

## Default project key

Set `SONAR_PROJECT_KEY` once and omit `projectKey` from project-scoped tool calls.

```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"
      }
    }
  }
}
```

Example tool input:

```json
{
  "resolved": false,
  "severities": ["BLOCKER", "CRITICAL"]
}
```

## Per-tool project override

Every project-scoped tool accepts `projectKey` or `projectName`, which override `SONAR_PROJECT_KEY` for that call.

```json
{
  "projectKey": "another-project",
  "branch": "main",
  "metricKeys": ["coverage", "bugs", "vulnerabilities"]
}
```

If your infrastructure creates a SonarQube project per branch, pass the SonarQube project name directly:

```json
{
  "projectName": "repo-name-feature-branch",
  "scope": "new_code"
}
```

If a name matches multiple projects, the tool returns candidates and asks the caller to retry with `projectKey`.

## Tools

### `search_sonar_projects`

Searches `/api/projects/search` to find project keys by SonarQube project name or key.

Inputs:

- `query` optional string
- `pageSize` optional number, defaults to `100`

### `get_sonar_fix_plan`

Gets unresolved issues grouped by file for agentic fixing workflows.

Use this for prompts like "fix all new code issues" or "fix all overall code issues".

Inputs:

- `projectKey` optional, falls back to `SONAR_PROJECT_KEY`
- `projectName` optional, resolved through `/api/projects/search`
- `scope` optional, `new_code` or `overall`, defaults to `new_code`
- `branch` optional
- `pullRequest` optional
- `severities` optional string array
- `statuses` optional string array
- `types` optional string array
- `impactSeverities` optional string array for newer SonarQube versions
- `impactSoftwareQualities` optional string array for newer SonarQube versions
- `pageSize` optional number, defaults to `100`
- `maxIssues` optional number, defaults to `200`
- `includeSource` optional boolean, defaults to `true`
- `includeRules` optional boolean, defaults to `false`
- `contextLines` optional number, defaults to `5`

Example for new code:

```json
{
  "projectName": "hvmb-app-feature-branch",
  "scope": "new_code",
  "includeSource": true,
  "includeRules": true
}
```

Example for overall code:

```json
{
  "projectKey": "hvmb-app",
  "scope": "overall",
  "maxIssues": 500
}
```

Returns clean JSON with:

- resolved project identity
- issue count and truncation flag
- optional rule details keyed by rule key
- files sorted by issue count
- issues per file
- merged source ranges around affected lines

### `get_sonar_issue_context`

Gets one issue plus surrounding source lines and optional rule details.

Inputs:

- `issueKey` required
- `branch` optional
- `pullRequest` optional
- `contextLines` optional number, defaults to `5`
- `includeRule` optional boolean, defaults to `true`

### `search_sonar_issues`

Searches `/api/issues/search` and handles pagination.

Inputs:

- `projectKey` optional, falls back to `SONAR_PROJECT_KEY`
- `projectName` optional, resolved through `/api/projects/search`
- `branch` optional
- `pullRequest` optional
- `severities` optional string array
- `statuses` optional string array
- `types` optional string array
- `impactSeverities` optional string array for newer SonarQube versions
- `impactSoftwareQualities` optional string array for newer SonarQube versions
- `inNewCodePeriod` optional boolean
- `resolved` optional boolean, defaults to `false`
- `pageSize` optional number, defaults to `100`

Returns clean JSON with issue `key`, `rule`, `severity`, `type`, `message`, `component`, `filePath`, `line`, `textRange`, `effort`, `status`, and `tags`.

### `get_quality_gate_status`

Calls `/api/qualitygates/project_status`.

Inputs:

- `projectKey` optional, falls back to `SONAR_PROJECT_KEY`
- `projectName` optional, resolved through `/api/projects/search`
- `branch` optional
- `pullRequest` optional

### `get_rule_details`

Calls `/api/rules/show`.

Inputs:

- `ruleKey` required

### `get_component_measures`

Calls `/api/measures/component`.

Inputs:

- `projectKey` optional, falls back to `SONAR_PROJECT_KEY`
- `projectName` optional, resolved through `/api/projects/search`
- `metricKeys` required string array
- `branch` optional
- `pullRequest` optional

### `get_sonar_sources`

Calls `/api/sources/lines`.

Inputs:

- `component` required
- `from` optional number
- `to` optional number
- `branch` optional
- `pullRequest` optional

## Errors

SonarQube API errors are wrapped as JSON strings containing:

- `endpoint`
- `status`
- `message`

HTML error pages are never returned directly.

## Development

```bash
npm install
npm run build
```

`prepublishOnly` runs the build before publishing.