MCP-Modul-Codestandard

Warum ein Codestandard wichtig ist

Jeder Connector, den wir ausliefern, sieht gleich aus. Das ist kein Zufall — es ist Disziplin. Wenn eine zweite Integration hinzukommt, sind die Fähigkeiten des Agenten einfacher zu testen, zu auditen und auszutauschen, weil jedes MCP-Modul derselben Struktur, Namensgebung und demselben Fehlervertrag folgt.

Dieses Dokument definiert den Standard für alle MCP-Module im IdeaBosque-Orchestrierungs-Backbone. Es behandelt Verzeichnislayout, Werkzeugregistrierung, Eingabe-/Ausgabeschemas, Fehlerbehandlung, Ratenbegrenzung, Audit-Logging und die Behandlung der PII-Grenze.

Verzeichnisstruktur

Jedes MCP-Modul liegt in seinem eigenen Verzeichnis unter app/mcp_modules/ mit einem einheitlichen Layout:

app/mcp_modules/<slug>/
  __init__.py
  module.py          # Werkzeugregistrierung + Handler
  schemas.py         # Pydantic-Modelle für Eingabe/Ausgabe
  tests/
    test_module.py
  README.md

Werkzeugregistrierung

Jedes Modul registriert seine Werkzeuge über eine Standardschnittstelle. Der Orchestrierungs-Backbone entdeckt Werkzeuge durch das Suchen nach dem Einstiegspunkt register_tools() — ohne manuelle Verdrahtung.

def register_tools(registrar):
    """Alle von diesem Modul bereitgestellten Werkzeuge registrieren."""
    registrar.tool(
        name="search_catalog",
        description="Lieferantenkatalog nach SKU oder Name durchsuchen",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # Aufrufe pro Minute
    )

Fehlerbehandlung

Module müssen typisierte Exceptions auslösen, keine bloßen Strings. Der Backbone fängt MCPToolError-Subklassen ab und wandelt sie in strukturierte Antworten um, über die der Agent räsonieren kann:

• MCPAuthError — Anmeldedaten fehlen oder sind abgelaufen
• MCPRateLimitError — Ratenbegrenzung des Upstream-Systems erreicht
• MCPTimeoutError — Upstream-Aufruf hat das konfigurierte Timeout überschritten
• MCPValidationError — Eingabe hat die Schemavalidierung nicht bestanden
• MCPUpstreamError — Upstream-System hat einen Fehlerstatus zurückgegeben

Ratenbegrenzung

Jedes Werkzeug deklariert seine eigene Ratenbegrenzung im Registrierungsaufruf. Der Backbone setzt diese pro Agent, pro Werkzeug und pro Zeitfenster durch. Wenn ein Limit erreicht wird, erhält der Agent eine 429-Antwort mit einem Retry-After-Header — er stürzt nicht ab und wiederholt nicht blind.

Audit-Logging

Jeder Werkzeugaufruf wird protokolliert mit: Zeitstempel, Agent-ID, Werkzeugname, Eingabe-Hash (nicht die rohe Eingabe — PII-Grenze), Ausgabestatus, Dauer und Upstream-System. Logs werden als strukturiertes JSON geschrieben und an die Observability-Pipeline gesendet.

„Jeder Werkzeugaufruf wird protokolliert und ist auditierbar" ist kein Feature, das wir später hinzufügen. Es ist das Erste, was der Standard verlangt.

Behandlung der PII-Grenze

Module müssen angeben, welche Eingabefelder PII enthalten. Der Backbone hasht diese Felder vor dem Protokollieren und sendet niemals rohe PII an die Audit-Pipeline. PII-Felder werden im Schema markiert:

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

Wenn pii=True gesetzt ist, ersetzt der Audit-Logger den Wert durch einen SHA-256-Hash. Der Werkzeug-Handler erhält weiterhin den rohen Wert — die PII-Behandlung wird an der Logging-Grenze durchgesetzt, nicht innerhalb der Geschäftslogik.