# Portabilitaet: UNIVERSAL
# Zuletzt validiert: 2026-02-15 (Claude)
# Naechste Pruefung: 2026-08-15
# Quellen: [https://modelcontextprotocol.io/docs/patterns], [https://github.com/modelcontextprotocol/python-sdk]

MCP-DESIGN-PATTERNS
===================

Stand: 2026-02-15

WAS IST EIN MCP-PATTERN?
------------------------
MCP-Patterns sind bewährte Entwurfsmuster und Best Practices für die Entwicklung und Integration von Model Context Protocol Servern. Sie helfen dabei, MCP-Server sicher, wartbar und wiederverwendbar zu gestalten.

GRUNDMUSTER
-----------

1. **Resource-basierte Architektur**
   - Gilt: Daten sollten als MCP-Resources exponiert werden
   - Nicht: Tools nur für Datenzugriff verwenden
   - Vorteil: Kontextoptimierung, LLMs erkennen verfügbare Daten
   
   Beispiel: Statt Tool "read_database_record", Resource "database:/records/{id}"

2. **Tool-Validierungs-Pattern**
   - Jedes Tool sollte Parameter-Validierung durchführen
   - Input-Sanitizing ist PFLICHT (Sicherheit!)
   - Fehlerbehandlung muss detaillierte Messages zurückgeben
   
   Code-Struktur:
   ```
   @server.call_tool()
   def my_tool(x: int, y: str):
       if x < 0:
           raise ValueError("x muss positiv sein")
       if not isinstance(y, str):
           raise TypeError("y muss String sein")
       # Validierte Ausfuehrung
   ```

3. **Prompt-Template-Pattern**
   - Nutze MCP Prompts für strukturierte Eingaben
   - Beispiel: "Erstelle Code für dieses Schema" → Prompt-Vorlage liefert Schema-Template
   - Reduziert Context-Größe, verbessert Konsistenz

4. **Ressourcen-Limit-Pattern**
   - Große Ressourcen: Pagination implementieren
   - Beispiel: Nicht alle 10.000 DB-Rows auf einmal laden
   - MCP-Standard: List & Subscribe mit `start`, `count` Parametern

SICHERHEITS-PATTERNS
--------------------

**Capability Restriction**
- Nutze MCP Tool-Kategorisierung für Security Levels
- Admin-Tools sollten explizit gekennzeichnet sein
- Host (z.B. Claude Desktop) kann Benutzer-Autorisierung enforzen

**Credential Management**
- NIEMALS Credentials in Code hardcoden
- Nutze Host-Umgebung oder Vault
- Beispiel: `os.getenv("DB_PASSWORD")` statt `password="xyz"`

**Sandboxing**
- Subprocess-Aufrufe sollten in Sandboxes laufen (z.B. Docker)
- Unkontrollierte Code-Ausführung = kritisches Sicherheitsrisiko
- Tools wie E2B MCP bieten vordefinierte Sandboxes

INTEGRATIONS-PATTERNS
---------------------

**Asyncrone Verarbeitung**
- Tools mit langer Laufzeit sollten async sein
- Verhindert Timeouts bei großen Operationen
- Beispiel: GitHub-Commits statt sofortige Ausführung queuen

**Error Context Pattern**
- Bei Fehler: Kontextinformationen mitgeben
- Nicht: "Error: 500"
- Sondern: "Database error at line 342: Connection timeout (retry in 5s)"

**Caching-Pattern**
- Häufig abgerufene Resources cachen
- Timestamp-basiertes Invalidierung
- Reduziert Last und verbessert Performance

ARCHITEKTTUR-PATTERNS
---------------------

**Modular MCP-Server**
```
mein-mcp/
├── core/
│   ├── resources.py   # Resource-Definitionen
│   └── tools.py       # Tool-Implementierungen
├── validators/        # Input-Validierung
├── handlers/          # Business Logic
├── config.py          # Konfiguration
└── server.py          # Haupteinstieg
```

**Multi-Domain Server**
- Ein MCP-Server kann mehrere Domains bedienen
- Beispiel: ellmos-codecommander-mcp hat Code + JSON + Encoding-Tools
- Vorteil: Zentrale Abhängigkeitsverwaltung

**Decorator-Pattern für Middleware**
```python
@mcp_auth(required_role="admin")
@mcp_rate_limit(calls_per_minute=100)
@server.call_tool()
def delete_record(record_id: str):
    # Geschützter Tool-Zugriff
```

HÄUFIGE FEHLER
--------------

1. **Context Bloat**: Zu viele oder zu große Resources → LLM-Context überlädt
   Lösung: Lazy Loading, Pagination, Filtering

2. **Fehlende Error Messages**: Tools geben nur Ja/Nein zurück
   Lösung: Immer `why` oder `details` Feld hinzufügen

3. **Synchrone Heavy-Lifting**: Blockierende DB-Queries in Tools
   Lösung: Async/await, Connection Pooling, Timeouts

4. **Keine Tool-Kategorisierung**: 100 Tools ohne Struktur
   Lösung: Thematische Grouping, `description` Feld nutzen

SIEHE AUCH
----------
wiki/mcp.txt              MCP Überblick und Konfiguration
wiki/mcp_toolstack.txt    MCP Toolstack für BACH
wiki/software_entwicklung.txt  Allgemeine Design-Patterns
