Shopdaten für den Bot

Der Bot der KI im Chat kann nicht nur auf Grundlage der Wissensdatenbank antworten, sondern auch mit Live-Daten des Shops: wo eine Bestellung gerade ist, wie die Sendungsnummer lautet, ob ein Produkt verfügbar ist, was die Lieferung kostet und wie man einen Kauf zurückgibt. Wenn Sie es erlauben, storniert er außerdem unbezahlte Bestellungen oder leitet Rückgabe- und Lieferänderungsanträge an den Shop weiter. Dafür wird der Shop über das Protokoll MCP (Model Context Protocol) mit dem Bot verbunden: Der Bot ruft die Tools des Shops auf, der Shop antwortet mit Daten.

Den Shop können Sie in jedem Tarif verbinden, der Bot funktioniert jedoch wie die gesamte KI im Chat nur in einem bezahlten Tarif: Antworten mit Shopdaten werden wie normale KI-Antworten aus dem Guthaben des Projekts bezahlt, siehe Abrechnung.

Verbindung

Am einfachsten geht es mit unserem Plugin für den Shop. Das Plugin startet den Server selbst und verbindet ihn beim Speichern der Einstellungen mit dem Projekt:

Der geheime Schlüssel des Plugins benötigt die Berechtigung „Verbindung des MCP-Servers des Shops mit dem KI-Bot“ (chats.manage). Die Berechtigungen eines Schlüssels lassen sich nach dem Erstellen nicht ändern: Wenn der Schlüssel des Plugins sie nicht hat, erstellen Sie unter API-Schlüssel einen neuen Schlüssel mit den bisherigen Berechtigungen und dieser und tragen Sie ihn in den Einstellungen des Plugins ein. Die Websites eines Projekts werden nur einmal verbunden.

Ein eigener Shop auf PHP- oder Laravel-Basis wird mit dem fertigen Server aus der PHP-Bibliothek und dem Laravel-Paket verbunden – Entwickler müssen nur die Handler der Tools schreiben. Jeder andere Server, der die MCP-Spezifikation des Shops umsetzt, wird manuell verbunden: Geben Sie unter Chats → Chat-Einstellungen → Bot → Shop (MCP) die Adresse https://…, den vom Shop ausgestellten Zugriffsschlüssel und einen Namen an. Die Spezifikation mit der Beschreibung der Tools, der Fehler und der Kundenbestätigung finden Sie unter Für Entwickler.

Im Bereich Shop (MCP) sehen Sie, ob der Server funktioniert und welche Tools der Shop dem Bot freigegeben hat. Mit dem Schalter deaktivieren Sie den Server vorübergehend, die Aktualisieren-Schaltfläche prüft ihn erneut und liest die Tools neu ein (die Plattform macht das auch selbst einmal täglich).

Was der Bot kann

Was der Bot darf, entscheidet der Shop in den Einstellungen des Plugins. Standardmäßig ist nur das Lesen aktiviert:

Aktionen sind deaktiviert, bis der Shop sie erlaubt:

Die Beschreibungen der Tools für das Modell legt die Plattform fest, nicht der Shop, und die Antworten des Shops behandelt der Bot als Daten, nicht als Anweisungen. Enthält eine Bot-Antwort Preise, Fristen oder Zusagen, die nicht in den Shopdaten stehen, lässt die Antwortprüfung sie nicht zum Kunden durch.

Kundenbestätigung

Bestellungen und Aktionen damit stehen nur einem bestätigten Kunden zur Verfügung – eine fremde Bestellung zeigt der Bot nicht an und bestätigt nicht einmal, dass sie existiert. Ein Kunde kann auf zwei Arten bestätigt werden:

1. Anmeldung auf der Website. Ist der Kunde in seinem Kundenkonto im Shop angemeldet, übergibt das Plugin dem Chat-Widget ein signiertes Token – der Bot weiß sofort, wer schreibt.
2. Code. In Messengern und bei Gästen fragt der Bot nach der im Shop hinterlegten E-Mail-Adresse, der Shop sendet einen 6-stelligen Code an diese Adresse, und der Kunde gibt den Code im Chat ein. Der Code gilt 10 Minuten, pro Adresse werden höchstens 5 Codes pro Stunde gesendet.

Die Bestätigung gilt 24 Stunden. Der Operator sieht sie im Gesprächsfenster: „Kunde bestätigt: auf der Website angemeldet“ oder „Kunde mit Code bestätigt“. Das Token des Kunden wird verschlüsselt im Gespräch gespeichert, weder das Modell noch die Operatoren sehen es.

Aktionen im Shop

Der Bot führt eine Aktion nur nach ausdrücklicher Zustimmung des Kunden aus:

1. Der Bot beschreibt, was er tun wird – mit Bestellnummer und Artikeln – und bittet um Bestätigung.
2. Der Kunde stimmt im Chat zu, zum Beispiel „Ja, bitte stornieren“.
3. Ein eigenes Bewertungsmodell prüft, ob der Kunde genau dieser Aktion zugestimmt hat. Eine Frage, ein Zweifel oder eine andere Bitte ist keine Zustimmung.
4. Der Shop führt die Aktion aus; ein erneuter Aufruf derselben Aktion wiederholt nichts.

Im Verlauf erscheint die Zeile „Der Bot hat im Shop ausgeführt: …“ mit dem Ergebnis, im Audit-Log des Projekts der Eintrag „Aktion des Bots im Shop“. Der Antwortentwurf für Operatoren nutzt Shopdaten nur lesend: Aktionen führt der Operator selbst im Shop aus.

Für Entwickler

Ein eigener Server lässt sich verbinden, wenn er Version 1 der MCP-Spezifikation des Shops umsetzt. Für PHP und Laravel ist die Spezifikation bereits umgesetzt: die Klasse StoreMcp\Server der PHP-Bibliothek und die Route POST /onetrace/mcp des Laravel-Pakets – Sie müssen nur noch die Handler der Tools schreiben.

Transport. MCP Streamable HTTP, Protokollversion 2025-06-18: eine Adresse, POST-Anfragen mit JSON-RPC 2.0, die Antwort ist JSON oder ein text/event-stream-Stream mit einer Antwort. Die Adresse muss https:// auf einer öffentlichen IP sein, ohne Weiterleitungen. Die Antwort darf höchstens 10 Sekunden dauern und höchstens 256 KB groß sein. Die Plattform ruft initialize, notifications/initialized, tools/list und tools/call auf; der Header Mcp-Session-Id wird unterstützt, ist aber nicht erforderlich.

Zugriff. Jede Anfrage enthält Authorization: Bearer <Schlüssel>; den Schlüssel erstellt der Shop, mindestens 32 zufällige Zeichen lang. Eine Anfrage ohne Schlüssel oder mit einem fremden Schlüssel erhält die Antwort 401.

Kennzeichen der Spezifikation. In der Antwort auf initialize deklariert der Server capabilities.experimental["onetrace/store"] = { "version": 1 } – ohne dieses Kennzeichen wird der Server nicht verbunden.

Tools. Die Namen lauten genau wie in der Tabelle, tools/list gibt nur die vom Inhaber freigegebenen Tools zurück. Jedes Tool hat die Annotation readOnlyHint: true (Lesen) oder destructiveHint: true (Aktion) sowie _meta["onetrace/auth"]: customer – ein bestätigter Kunde ist erforderlich, none – nicht erforderlich. Das Ergebnis ist structuredContent und dasselbe JSON als Text in content[0].text. Beträge haben die Form { "amount": 1250.5, "currency": "RUB" }, Datumsangaben ISO 8601.

Der Bestellstatus ist einer von pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded, failed. Die Bestellung eines anderen Kunden erhält die Antwort not_found, als gäbe es sie nicht.

Kunde. Das Token customer_token stellt der Shop aus und prüft es, gültig höchstens 24 Stunden. Den Bestätigungscode sendet der Shop selbst und antwortet gleich, ob es einen solchen Kunden gibt oder nicht; der Code hat 6 Ziffern, gilt 10 Minuten, erlaubt bis zu 5 Versuche, bis zu 5 Codes pro Stunde und Adresse. Für einen angemeldeten Kunden übergibt die Seite das Token an den Tracker: cdp.chatCustomer('…').

Aufrufkontext – in params._meta: onetrace/customer_token, onetrace/language (Sprache des Gesprächs), onetrace/conversation, bei Aktionen zusätzlich onetrace/confirmed: true und onetrace/idempotency_key. Eine Aktion ohne onetrace/confirmed lehnt der Server ab; eine Wiederholung mit demselben Idempotenzschlüssel liefert dasselbe Ergebnis, ohne die Aktion erneut auszuführen.

Fehler – isError: true und structuredContent: { "error": "<Code>", "message": "<Text für den Kunden>" }:

Verbindung aus dem Plugin. Das Plugin registriert seinen Server mit einem geheimen Schlüssel mit der Berechtigung chats.manage: PUT /api/v1/chat/store-mcp mit url, key, name, platform verbindet oder aktualisiert den Server, DELETE /api/v1/chat/store-mcp mit url trennt ihn.