# Integrations-Workflows (/de/docs/verdent-for-vscode/advanced-features/integrations)

> Praktische Muster für die Integration von Verdent mit externen Werkzeugen und Diensten



### Was Sie lernen werden [#was-sie-lernen-werden]

Praktische Integrations-Workflows, die benutzerdefinierte Subagents, Regeln und MCP-Server für reale Entwicklungsszenarien kombinieren.

***

## Integrationsmethoden [#integrationsmethoden]

| Methode                          | Am besten geeignet für              | Konfiguration               |
| -------------------------------- | ----------------------------------- | --------------------------- |
| **Benutzerdefinierte Subagents** | KI-gestützte Spezialaufgaben        | `~/.verdent/subagents/*.md` |
| **Regeln (AGENTS.md)**           | Teamstandards und Verhalten         | Projektstamm `AGENTS.md`    |
| **MCP-Server**                   | Protokollkonforme externe Werkzeuge | `.mcp.json` (Projektstamm)  |

**Philosophie:** Kombinieren Sie Methoden, um umfassende, auf Ihre Anforderungen zugeschnittene Workflows zu erstellen.

***

## Gängige Integrationsmuster [#gängige-integrationsmuster]

### Datenbank-Entwicklungsworkflow [#datenbank-entwicklungsworkflow]

**Stack:** Migration Reviewer Subagent + AGENTS.md-Standards + PostgreSQL-MCP-Server

**Subagent:**

```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md:**

```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```

**MCP:** PostgreSQL-Server für Abfrageausführung, Schemaprüfung, Migrationsvalidierung

**Workflow:** Migration schreiben → @migration-reviewer validiert → MCP testet auf Staging → PR-Dokumentation

***

### API-Entwicklung mit Sicherheit [#api-entwicklung-mit-sicherheit]

**Stack:** Security Auditor + AGENTS.md-Regeln + benutzerdefiniertes API-Testwerkzeug

**Komponenten:**

* **Subagent:** `@api-security-auditor` – Eingabevalidierung, SQL-Injection, Authentifizierung, Ratenbegrenzung
* **Regeln:** Alle Endpunkte erfordern eine Sicherheitsprüfung, Ratenbegrenzung bei öffentlichen APIs
* **Externe Werkzeuge:** Automatisierte Endpunkttests und Sicherheitsscans über benutzerdefinierte Integration

**Ergebnis:** Automatische Sicherheitsprüfung vor der PR-Freigabe.

<Note>
  API-Testwerkzeuge und Sicherheitsscanner können je nach Ihrer Toolchain über benutzerdefinierte MCP-Server-Implementierungen oder andere Integrationsmethoden eingebunden werden.
</Note>

***

### Frontend-Barrierefreiheit [#frontend-barrierefreiheit]

**Stack:** Accessibility Auditor + WCAG-Regeln + Lighthouse-Integration

**Workflow:**

```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

<Note>
  Lighthouse und andere Barrierefreiheits-Werkzeuge können je nach Ihrem Workflow über benutzerdefinierte MCP-Server oder eine CI/CD-Pipeline-Integration eingebunden werden.
</Note>

***

## MCP-Konfigurationsbeispiele [#mcp-konfigurationsbeispiele]

### MCP verstehen [#mcp-verstehen]

**Model Context Protocol (MCP)** ist ein offenes Protokoll, das standardisiert, wie Anwendungen Kontext für LLMs bereitstellen. MCP-Server sind ausführbare Programme, die das Protokoll implementieren. Es handelt sich dabei nicht um Datenbankverbindungen oder API-Endpunkte, sondern um Programme, die ausgeführt werden und über JSON-RPC 2.0 kommunizieren.

**Kernkonzepte:**

* **MCP-Server**: Ausführbare Programme (Node.js-Pakete, Python-Skripte usw.), die das MCP-Protokoll implementieren
* **Konfiguration**: Teilt Verdent mit, wie der Server gestartet wird (`command` + `args`)
* **Kommunikation**: Server übernehmen ihre eigene Geschäftslogik (Abfragen, API-Aufrufe usw.)

### Grundkonfiguration [#grundkonfiguration]

**Speicherort:** `.mcp.json` im Projektstamm

<CodeGroup>
  ```json PostgreSQL Server
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      }
    }
  }
  ```

  ```json GitHub Server
  {
    "mcpServers": {
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```

  ```json Multiple Servers
  {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://localhost:5432/myapp_dev"
        ]
      },
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
  ```
</CodeGroup>

**Erklärung:**

* `mcpServers` – Erforderlicher oberster Schlüssel für die MCP-Konfiguration
* `command` – Auszuführendes Programm (typischerweise `npx` für Node.js-Pakete)
* `args` – An den Befehl übergebene Argumente (Paketname, Verbindungszeichenfolgen usw.)
* `env` – Umgebungsvariablen für Authentifizierung/Konfiguration

### Mehrere Umgebungen [#mehrere-umgebungen]

```json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
```

**Best Practice:** Verwenden Sie Umgebungsvariablen für Verbindungszeichenfolgen, um Zugangsdaten sicher zu halten. MCP-Server handhaben schreibgeschütztes Verhalten intern, basierend auf ihrer jeweiligen Implementierung. Ziehen Sie die Dokumentation des jeweiligen Servers für Zugriffssteuerungsoptionen zu Rate.

<Tip>
  **Mehr über MCP erfahren:**

  * [Spezifikation des Model Context Protocol](https://modelcontextprotocol.io/specification)
  * [MCP-Server-Registry](https://mcp.so/servers) – Verfügbare MCP-Server durchsuchen
  * [Offizielle MCP-Server](https://github.com/modelcontextprotocol) – PostgreSQL, GitHub, Filesystem und mehr
</Tip>

***

## Integration im Arbeitsbereich [#integration-im-arbeitsbereich]

### Projektspezifische Konfiguration [#projektspezifische-konfiguration]

**Einrichtung:**

1. Im Projektstamm speichern: `.mcp.json`
2. Zur Versionskontrolle committen, um im Team zu teilen
3. Teammitglieder verwenden automatisch die Projekt-MCP-Server

**Microservices-Beispiel:**

```json
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
```

<Note>
  Für zusätzliche Dienste wie Kafka benötigen Sie eine kompatible MCP-Server-Implementierung. Die offizielle MCP-Server-Registry unter [mcp.so/servers](https://mcp.so/servers) listet verfügbare Community-Server auf.
</Note>

***

## Teamzusammenarbeit [#teamzusammenarbeit]

### Gemeinsame AGENTS.md-Standards [#gemeinsame-agentsmd-standards]

Zur Versionskontrolle committen, um teamweite Konsistenz zu gewährleisten:

```markdown
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```

**Vorteile:** Konsistentes Verhalten, durchgesetzte Standards, automatische Qualitätskontrollen.

***

## Koordination mehrerer Agents [#koordination-mehrerer-agents]

### Komplexer Feature-Workflow [#komplexer-feature-workflow]

**Beispiel:** Neuer Zahlungsendpunkt

```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```

**Ergebnis:** Vollständig überprüfter Endpunkt unter Anwendung von Sicherheits- und Datenbank-Best-Practices.

***

## Best Practices für Integrationen [#best-practices-für-integrationen]

### Schrittweise Einführung [#schrittweise-einführung]

**Phase 1:** Grundlegende Regeln

```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**Phase 2:** Spezialisierten Subagent hinzufügen

```markdown
## Code Review
- Run @security-reviewer before PR
```

**Phase 3:** MCP integrieren

```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### Strategische Kombinationen [#strategische-kombinationen]

| Kombination        | Zweck                                               | Beispiel                                       |
| ------------------ | --------------------------------------------------- | ---------------------------------------------- |
| Regeln + Subagents | Regeln definieren *wann*, Subagents *analysieren*   | AGENTS.md: „Mit @security-reviewer überprüfen" |
| Regeln + MCP       | Regeln legen fest, *welche* Server, MCP *greift zu* | AGENTS.md: „Nur db-staging verwenden"          |
| Subagents + MCP    | Subagent nutzt MCP für *externe Daten*              | Security Auditor fragt API-Endpunkte ab        |

### Best Practices für die Teamdokumentation [#best-practices-für-die-teamdokumentation]

Berücksichtigen Sie beim Dokumentieren von Integrationen für Ihr Team Folgendes:

* **Benutzerdefinierte Subagents**: Listen Sie Name, Zweck und Einsatzzeitpunkt jedes Subagents auf
* **AGENTS.md-Regeln**: Dokumentieren Sie Regeln mit einer Begründung, die das „Warum" hinter jedem Standard erklärt
* **MCP-Server**: Beschreiben Sie Zweck, Zugriffsebene (schreibgeschützt/schreibend) und Einsatzzeitpunkt jedes Servers
* **Integrations-Workflows**: Stellen Sie Beispiel-Workflows bereit, die das Zusammenspiel der Komponenten zeigen
* **Fehlerbehebung**: Dokumentieren Sie häufige, für Ihr Setup spezifische Probleme und deren Lösungen

<Tip>
  Committen Sie die Integrationsdokumentation zusammen mit Ihren `.mcp.json`- und `AGENTS.md`-Dateien, damit sich neue Teammitglieder schnell in Ihr Setup einarbeiten können.
</Tip>

***

## Fehlerbehebung [#fehlerbehebung]

<Tabs>
  <Tab title="Probleme mit Subagents">
    **Problem:** Subagent wird nicht wie erwartet aufgerufen

    **Prüfen Sie:**

    **Speicherort**: Datei existiert unter `~/.verdent/subagents/[name].md`

    **YAML-Frontmatter**: Gültige Syntax mit den erforderlichen Feldern `name` und `description`

    **Aufrufrichtlinie**: Stimmt mit der Nutzung überein (strikt erfordert eine explizite @-Erwähnung)

    **Beschreibung**: Das Agent-`description` beschreibt genau, wann der Subagent verwendet werden soll

    **Neustart**: Versuchen Sie, Verdent neu zu starten, um Subagent-Definitionen neu zu laden

    ***

    **Häufige Ursachen:**

    * Tippfehler im Subagent-Dateinamen oder in der @-Erwähnung
    * Ungültige YAML-Syntax im Frontmatter
    * Subagent-`description` passt nicht zum Aufgabenkontext
  </Tab>

  <Tab title="Probleme mit AGENTS.md">
    **Problem:** AGENTS.md-Regeln werden nicht angewendet

    **Prüfen Sie:**

    **Speicherort**: Datei befindet sich im Projektstammverzeichnis

    **Syntax**: Gültiges Markdown ohne Parsing-Fehler

    **Direktivenstil**: Verwenden Sie konkrete Anweisungen („Immer verwenden ..." statt „Versuchen Sie ...")

    **Sitzung**: Starten Sie eine neue Unterhaltung, um die Anwendung der aktuellen Regeln zu testen

    **Konflikte**: Prüfen Sie, ob Benutzerregeln unbeabsichtigt Projektregeln überschreiben

    ***

    **Häufige Ursachen:**

    * AGENTS.md im falschen Verzeichnis (muss im Projektstamm liegen)
    * Ungenaue Anweisungen, die die KI unterschiedlich interpretiert
    * Regeln werden angewendet, aber die Ergebnisse entsprechen nicht den Erwartungen (Formulierung verfeinern)
  </Tab>

  <Tab title="MCP-Server-Probleme">
    **Problem:** MCP-Server startet nicht oder verbindet sich nicht

    **Prüfen Sie:**

    **Syntax**: `.mcp.json` enthält gültiges JSON (zur Validierung `jq` verwenden)

    **Struktur**: Der erforderliche Schlüssel `mcpServers` ist auf oberster Ebene vorhanden

    **Serverkonfiguration**: Für jeden Server sind `command` und `args` korrekt angegeben

    **Paket**: Das MCP-Server-Paket ist zugänglich (`npx` lädt Pakete automatisch herunter; die Option `-y` umgeht die Bestätigungsabfrage)

    **Umgebung**: Variablen im Objekt `env` sind in Ihrer Shell korrekt gesetzt

    **Berechtigungen**: Das ausführbare Server-Programm besitzt die passenden Ausführungsrechte

    ***

    **Häufige Ursachen:**

    * Tippfehler im JSON (fehlendes Komma, nicht geschlossene Klammer)
    * Falscher Paketname im args-Array
    * Fehlende oder falsche Umgebungsvariablen
    * Netzwerk-/Firewall-Blockade der npx-Paketinstallation

    ***

    **Schritte zur Fehlerdiagnose:**

    1. JSON validieren: `cat .mcp.json | jq .`
    2. Befehl manuell testen: `npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. Umgebung prüfen: `echo $GITHUB_TOKEN`
    4. Verdent-Protokolle auf konkrete Fehlermeldungen überprüfen
  </Tab>
</Tabs>

***

## Siehe auch [#siehe-auch]

<CardGroup cols="2">
  <Card title="Leitfaden zur Erweiterbarkeit" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    Vollständiger Überblick über alle Erweiterungsmethoden
  </Card>

  <Card title="MCP-Integration" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Details zum Model Context Protocol
  </Card>
</CardGroup>