WebMCP für Storefronts: deklarativ vs. imperativ bauen

Ist eine Storefront-Aktion ein HTML-Attribut oder eine JS-Funktion? Bei WebMCP ist das keine Stilfrage, sondern eine Architektur-Entscheidung, die jedes Frontend-Team vor dem ersten Sprint treffen sollte. Dieser Guide beantwortet sie praktisch: zwei Code-Beispiele, eine Entscheidungsmatrix, keine neue Grundsatzdebatte über Governance oder GEO. Die haben wir in den verlinkten Posts unten schon geführt.

Zwei Wege, einen Storefront agentenfähig zu machen

WebMCP macht Storefront-Aktionen für AI-Agenten ausführbar. Wie eine Aktion dem Agenten zur Verfügung gestellt wird, entscheidet sich zwischen zwei Mustern:

• Deklarative Annotation: Die Aktion steht als Attribut direkt im HTML-Markup. Ein WebMCP-Runtime-Script liest das Attribut aus und macht die Aktion sichtbar, ohne dass zusätzlicher JS-Code pro Aktion geschrieben wird.
• Imperative Tool-Actuation: Die Aktion ist eine registrierte JS-Funktion mit eigenem Namen, Parametern und Rückgabewert. Der Agent ruft die Funktion auf wie eine API.

Beide Muster erzeugen dasselbe Ergebnis, der Agent führt eine Aktion im Storefront aus, aber mit unterschiedlichem Aufwand, unterschiedlicher Kontrolle und unterschiedlicher Fehleranfälligkeit.

Der deklarative Weg: HTML-Annotation

Deklarative Annotation eignet sich für Aktionen, die 1:1 an ein sichtbares UI-Element gebunden sind, kurzlebig sind und keinen mehrstufigen State-Übergang brauchen. Ein Warenkorb-Button ist das Standardbeispiel:

<button
  data-webmcp-action="cart.add"
  data-webmcp-target="product"
  data-webmcp-params='{"variantId": "{{variant.id}}", "quantity": 1}'
  data-webmcp-result="cart.summary"
>
  In den Warenkorb
</button>

Die Annotation beschreibt vollständig, was passiert: Aktion-Name, Ziel-Entity, Parameter, erwartetes Ergebnis. Kein separates Tool-Setup, kein Import, kein Build-Step. Das Runtime-Script scannt das DOM, registriert die Aktion, fertig. Der Nachteil: Jede Logik, die nicht im Attribut-Wert ausdrückbar ist, Validierung, mehrstufige Bedingungen, asynchrone Zwischenschritte, passt hier nicht rein.

Der imperative Weg: JS-Tool-Actuation

Imperative Tool-Actuation eignet sich, sobald eine Aktion Business-Logik, mehrere Backend-Calls oder Fehlerbehandlung braucht:

webmcp.registerTool({
  name: "cart.add",
  description: "Fügt eine Produktvariante zum aktiven Warenkorb hinzu.",
  parameters: {
    variantId: { type: "string", required: true },
    quantity: { type: "number", default: 1 }
  },
  async execute({ variantId, quantity }) {
    const stock = await storefront.inventory.check(variantId);
    if (stock.available < quantity) {
      throw new Error("insufficient_stock");
    }
    const cart = await storefront.cart.addLine(variantId, quantity);
    return { cartId: cart.id, itemCount: cart.itemCount, subtotal: cart.subtotal };
  }
});

Die Funktion kapselt Prüfung, Backend-Call und Antwortformat. Der Agent sieht nur Name, Parameter-Schema und Rückgabewert, nicht die Implementierung. Das gibt volle Kontrolle über Fehlerfälle und State-Übergänge, kostet aber Setup-Aufwand pro Aktion: Registrierung, Typisierung, Testing.

Entscheidungsmatrix: wann was?

Faustregel fürs Team: Wenn die Aktion in einem Satz beschreibbar ist und keine Bedingung enthält, deklarativ annotieren. Sobald ein "wenn X, dann Y, sonst Z" im Spiel ist, imperativ registrieren.

Typische Fehler beim Annotieren

• Annotation-Overload: zu viele data-webmcp-*-Attribute auf einem Element ohne klare Namenskonvention, der Agent kann Prioritäten nicht mehr unterscheiden.
• Tool ohne Fehlerpfad: registrierte Tools, die bei einem Fehlschlag keine strukturierte Antwort liefern, der Agent interpretiert dann einen Absturz als Erfolg.
• Doppelte Wahrheit: dieselbe Aktion gleichzeitig deklarativ annotiert und imperativ registriert, das Runtime-Script weiß nicht, welches Muster gilt.
• Fehlendes Ergebnis-Schema: der Agent bekommt Erfolg oder Misserfolg nicht strukturiert zurück und muss den Text der UI raten.

Beide Muster im selben Storefront kombinieren

In der Praxis mischen produktive Storefronts beide Muster. PDP-Aktionen wie In den Warenkorb, Merkzettel oder Variante wechseln laufen deklarativ, weil sie einfach und UI-gebunden sind. Checkout-, Rabatt- und Bestandslogik läuft imperativ, weil sie Backend-Zustand prüft und Fehler behandeln muss. Genau diese Trennung ist der Grund, warum Laioutr als Frontend Management Platform Annotation und Tool-Registry im selben Component-Layer anbietet. Component-Autoren entscheiden pro Aktion, welches Muster passt, ohne zwei getrennte Systeme pflegen zu müssen. Das Frontend bleibt ein Composable Headless Frontend, nicht zwei parallele Stacks.

Wer WebMCP als Betriebsmodell versteht statt als Einzel-Feature, findet die breitere Einordnung unter Frontend as a Service: Annotation und Tool-Actuation sind zwei Bausteine der Agent-Layer-Schicht, die dort von Anfang an mitgedacht ist.

Build-Checkliste

• Liste alle Storefront-Aktionen, die Agenten ausführen dürfen sollen: Warenkorb, Merkliste, Checkout-Schritte, Rabattcode.
• Sortiere jede Aktion nach der Matrix oben: deklarativ oder imperativ.
• Annotiere deklarative Aktionen direkt im Component-Template, nicht in separaten Config-Files.
• Registriere imperative Tools mit vollständigem Parameter-Schema, nicht nur mit Namen.
• Teste beide Pfade mit echtem Agent-Traffic, nicht nur mit manuellen Klicks.
• Dokumentiere Rückgabewerte pro Aktion, damit Agenten Ergebnisse verlässlich interpretieren.

Wer die Grundlagen der Frontend-Agent-Actuation nachlesen will, findet sie im Post WebMCP: Wenn Frontends zu Agent-Aktionen werden. Für die GEO-Perspektive, wie Agent-Ready-Frontends in AI-Overviews zitiert werden, gibt es Agent-Ready Frontend: GEO trifft WebMCP. Die Abgrenzung WebMCP vs. MCP im Commerce-Kontext, Browser- vs. Server-Actuation, steht in WebMCP vs. MCP Commerce: Browser vs. Server. Und wie Frontends Agenten sicher schreiben lassen, Governance und Guardrails, ist Thema von MCP Commerce Frontends: Agenten sicher schreiben lassen.

Dieser Guide ist bewusst implementierungsfokussiert: Annotation-Pattern, Tool-Actuation-Pattern, Entscheidungsmatrix. Wer die Boundary- und Governance-Fragen klären will, findet sie in den vier Posts oben. Wer heute bauen will, hat mit der Matrix und den zwei Code-Beispielen den direkten Einstieg. Mehr zur gesamten Plattform dahinter gibt es auf der Laioutr-Startseite.