# mcp-sonarqube-proxy

Stdio-MCP-Server, der einen Upstream-SonarQube-MCP-Server (Streamable HTTP)
in Claude Desktop / Claude App einbindet. Der Proxy wird via stdio gespawnt,
verbindet sich beim Start mit dem Upstream und reicht alle Tools 1:1 weiter —
inklusive `inputSchema`, `outputSchema` und `annotations`, sodass Claude die
Tools korrekt aufrufen kann.

## Installation

```bash
uv tool install git+https://gitea.gecheckt.de/marcus/mcp-sonarqube-proxy.git
```

## Verwendung

### Verbindung pruefen

```bash
SONARQUBE_MCP_URL=http://192.168.0.2:8765/mcp mcp-sonarqube-proxy check
```

Listet alle Tools auf, die der Upstream bereitstellt. Exit-Code 0 bei Erfolg,
1 wenn der Upstream nicht erreichbar ist.

### Claude Desktop / Claude App Konfiguration

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sonarqube": {
      "command": "mcp-sonarqube-proxy",
      "args": ["serve"],
      "env": {
        "SONARQUBE_MCP_URL": "http://192.168.0.2:8765/mcp"
      }
    }
  }
}
```

Auf Windows ist `command` typischerweise der absolute Pfad zur per
`uv tool install` installierten EXE, z.B.
`%USERPROFILE%\.local\bin\mcp-sonarqube-proxy.exe`.

## Umgebungsvariablen

| Variable             | Default                          | Beschreibung                              |
|----------------------|----------------------------------|-------------------------------------------|
| `SONARQUBE_MCP_URL`  | `http://192.168.0.2:8765/mcp`    | Upstream-MCP-Endpoint (Streamable HTTP)   |

## Kommandos

| Kommando                       | Beschreibung                                       |
|--------------------------------|----------------------------------------------------|
| `mcp-sonarqube-proxy serve`    | Startet den MCP-Server auf stdio.                  |
| `mcp-sonarqube-proxy check`    | Testet Upstream-Verbindung und listet Tools.       |
| `mcp-sonarqube-proxy --version`| Gibt die Proxy-Version aus.                        |

## Funktionsweise

1. Beim Start oeffnet `serve` eine Streamable-HTTP-Session zum Upstream und
   ruft `initialize()` auf. Schlaegt das fehl, beendet sich der Prozess mit
   Exit-Code 1 und schreibt die Fehlermeldung auf stderr.
2. Diese Session bleibt fuer die Lebensdauer des Proxies offen.
3. `tools/list`-Requests vom Client werden 1:1 an den Upstream weitergeleitet —
   die `Tool`-Objekte (mit allen Schemata und Annotations) kommen unveraendert
   beim Client an.
4. `tools/call`-Requests werden ebenfalls weitergeleitet. Das vollstaendige
   `CallToolResult` (inklusive `isError`, `structuredContent` und allen
   Content-Bloecken) wird an den Client zurueckgegeben.
5. `stdout` ist ausschliesslich fuer JSON-RPC reserviert. Logging und
   Statusmeldungen gehen auf `stderr`.

Der Proxy validiert Tool-Argumente bewusst nicht lokal — der Upstream ist die
einzige Schema-Autoritaet und uebernimmt die Validierung.

## Anforderungen

- Python `>= 3.12`
- `mcp >= 1.27, < 2`