# PatchMetric MCP-Bridge

Lokale MCP-Bridge für PatchMetric-Teams mit **Ende-zu-Ende-Verschlüsselung**. Sie läuft auf deinem Rechner als MCP-Server (stdio) für Claude Code, Claude Desktop oder Cursor, verbindet sich mit dem PatchMetric-MCP-Server und

- **entschlüsselt** Namen, Notizen, Adressen und Ports deiner Assets (und Gruppennamen) in den Antworten,
- **verschlüsselt** sie, wenn der KI-Agent Assets oder Geräte anlegt oder ändert,
- sucht in verschlüsselten Teams **lokal** (`list_assets` mit `query`), weil der Server die Namen nicht lesen kann.

Teams ohne Ende-zu-Ende-Verschlüsselung laufen unverändert durch.

## Was wer sieht

|                                                    | PatchMetric-Server                       | KI-Anbieter (z. B. Anthropic, Cursor) | dein Rechner                      |
| -------------------------------------------------- | ---------------------------------------- | ------------------------------------- | --------------------------------- |
| Name, Notizen, Adressen, Ports                     | nein – nur Chiffretext und den Kurznamen | **ja**, im Klartext                   | ja                                |
| Kurzname, Tags, Software, Schwachstellen           | ja                                       | ja                                    | ja                                |
| Passphrase, Wiederherstellungsschlüssel, Schlüssel | nein                                     | nein                                  | nur im Arbeitsspeicher der Bridge |

Kurz: **PatchMetric sieht deine Inventardaten nicht, der KI-Anbieter schon** – alles, was der Agent liest, geht an dessen Anbieter. Nutze die Bridge nur mit einem Anbieter, dem du diese Daten anvertrauen willst.

Die Bridge speichert auf der Festplatte nur die OAuth-Anmeldung (Client-Registrierung und Token, Datei mit Rechten `0600` im Benutzer-Konfigurationsordner). Passphrase, Wiederherstellungsschlüssel, privater Schlüssel und Teamschlüssel liegen nur im Arbeitsspeicher und sind weg, sobald der KI-Client die Bridge beendet.

## Voraussetzungen

- Node.js 20 oder neuer
- Ende-zu-Ende-Verschlüsselung ist für dein Konto eingerichtet (PatchMetric → Einstellungen → Sicherheit) und dir wurde der Teamschlüssel freigegeben.
- Entsperren geht mit **Passphrase** oder **Wiederherstellungsschlüssel**. Passkeys funktionieren nur im Browser.

## Einrichten

### Claude Code

```bash
claude mcp add patchmetric -- npx -y @patchmetric/mcp-bridge
```

### Claude Desktop

In `claude_desktop_config.json` (Einstellungen → Entwickler → Konfiguration bearbeiten):

```json
{
    "mcpServers": {
        "patchmetric": {
            "command": "npx",
            "args": ["-y", "@patchmetric/mcp-bridge"]
        }
    }
}
```

### Cursor

In `~/.cursor/mcp.json` (oder `.cursor/mcp.json` im Projekt):

```json
{
    "mcpServers": {
        "patchmetric": {
            "command": "npx",
            "args": ["-y", "@patchmetric/mcp-bridge"]
        }
    }
}
```

Ersetze die Verbindung „PatchMetric“ aus dem Konnektor-Verzeichnis durch die Bridge, sonst sieht der Agent dieselben Werkzeuge doppelt (einmal verschlüsselt).

## Anmelden

Beim ersten Start öffnet die Bridge den Browser: Melde dich bei PatchMetric an und erlaube die Verbindung für deine Teams. Du kannst das auch vorab im Terminal erledigen:

```bash
npx -y @patchmetric/mcp-bridge login
```

`status` zeigt, ob du angemeldet bist, `logout` löscht die Anmeldung auf diesem Rechner. Die Verbindung selbst widerrufst du in PatchMetric unter Einstellungen → KI-Agenten.

### Verbindung als „Lokale MCP-Brücke“ markieren

Die Bridge braucht deine verschlüsselten Schlüssel (Werkzeug `get_zk_keyring`), um auf deinem Rechner zu entschlüsseln. PatchMetric gibt sie nur an Verbindungen heraus, die du ausdrücklich als Bridge markiert hast: Öffne nach dem Anmelden in PatchMetric **Einstellungen → KI-Agenten**, wähle die neue Verbindung der Bridge und schalte **„Lokale MCP-Brücke“** ein. Starte danach den KI-Client (bzw. die Bridge) neu.

Schalte das **nur** für die Bridge auf deinem eigenen Rechner ein – nie für Connectoren wie claude.ai oder ChatGPT: Mit den verschlüsselten Schlüsseln könnte der Anbieter versuchen, deine Passphrase offline zu erraten. Ohne die Markierung meldet die Bridge in Ende-zu-Ende-verschlüsselten Teams einen entsprechenden Hinweis, statt verschlüsselte Daten durchzureichen. Trennst du die Verbindung, endet die Markierung mit ihr; nach einer neuen Anmeldung musst du sie erneut setzen.

## Entsperren

Braucht die Bridge zum ersten Mal den Schlüssel, öffnet sie eine **lokale Seite** im Browser (`http://127.0.0.1:<Port>/unlock/…`). Dort gibst du Passphrase oder Wiederherstellungsschlüssel ein; die Eingabe geht nur an die Bridge auf deinem Rechner – nicht an PatchMetric und nicht an den KI-Client. Die Seite zeigt den Fingerabdruck deines Schlüssels; vergleiche ihn mit Einstellungen → Sicherheit. Bis du entsperrt hast, meldet das Werkzeug einen Fehler; danach einfach erneut aufrufen.

Die Bridge prüft jeden Teamschlüssel wie der Browser: Sie verwendet ihn nur, wenn er von dir selbst oder von einem Mitglied signiert ist, dessen Fingerabdruck du im Browser verglichen hast, und wenn der Schlüssel zur Signatur passt. Sonst meldet das Werkzeug, warum (z. B. „Fingerabdruck noch nicht verglichen“), und verschlüsselt nichts. Die Liste verglichener Fingerabdrücke pflegst du im Browser; die Bridge liest sie nur. Ein Schlüssel aus der Zeit vor signierten Teamschlüsseln muss einmal im Browser entsperrt werden, bevor die Bridge ihn nutzen kann.

Ohne Browser (z. B. auf einem Server) kannst du den Wert als Umgebungsvariable mitgeben – dann steht er allerdings im Klartext in der MCP-Konfiguration:

```bash
claude mcp add patchmetric -e PATCHMETRIC_ZK_PASSPHRASE='…' -- npx -y @patchmetric/mcp-bridge
```

| Variable                        | Bedeutung                                          |
| ------------------------------- | -------------------------------------------------- |
| `PATCHMETRIC_URL`               | Server, Standard `https://patchmetric.de`          |
| `PATCHMETRIC_ZK_PASSPHRASE`     | Passphrase (statt der lokalen Seite)               |
| `PATCHMETRIC_ZK_RECOVERY_KEY`   | oder der Wiederherstellungsschlüssel               |
| `PATCHMETRIC_BRIDGE_CONFIG_DIR` | Ablage der Anmeldung                               |
| `PATCHMETRIC_NO_BROWSER=1`      | Links nur ins Log schreiben, keinen Browser öffnen |

## Kurznamen

In verschlüsselten Teams sieht PatchMetric nur einen **Kurznamen** (für Alarme, Exporte und das Audit-Log). Beim Anlegen eines Assets gibt der Agent ihn als `short_name` an; er sollte den echten Namen nicht verraten (z. B. „Server 3“ statt „db.kunde-mueller.de“).

## Entwicklung

```bash
npm ci
npm run check   # TypeScript, Tests (Vitest), Build nach dist/cli.js
```

Die Kryptografie liegt in `src/zk-core` (derselbe Code wie in der PatchMetric-Web-App, unverändert übernommen) und wird von esbuild in `dist/cli.js` gebündelt. Alle Annahmen über die Antworten des Servers stehen in `src/contract.ts`.

## Lizenz

MIT – siehe [LICENSE](LICENSE). Der Quellcode liegt offen, damit jeder prüfen kann, dass PatchMetric in verschlüsselten Teams keinen Klartext sieht. Der PatchMetric-Server und die Web-App sind davon nicht erfasst.