DataFirefly MCP Commerce — Vollständiger Leitfaden

Das Modul DataFirefly MCP Commerce macht aus Ihrem PrestaShop-Shop einen MCP-Server (Model Context Protocol), den KI-Agenten — ChatGPT, Claude, Claude Desktop, Claude Code, n8n — direkt nutzen können, um den Katalog zu durchsuchen, Warenkörbe zu erstellen und Bestellungen vorzubereiten. Dieser Leitfaden behandelt Installation, Endpunkt, doppelte Authentifizierung (OAuth 2.1 und Bearer-Token), das Verbinden der wichtigsten Agenten, die bereitgestellten Tools, Scopes, Bestellmodi und Fehlerbehebung.

Voraussetzungen

• PrestaShop 8.0 bis 9.x.
• PHP 7.4 bis 8.3 mit aktivierter cURL-Erweiterung.
• Ein über HTTPS ausgelieferter Shop (für KI-Connectoren erforderlich).
• Empfohlen: aktivierte sprechende URLs (Erweiterte Parameter > SEO & URLs) für saubere Endpunkte.

Installation

1. Öffnen Sie im Backoffice Module > Modul-Manager, dann Modul hochladen und legen Sie die Datei dfmcpcommerce.zip ab.
2. Öffnen Sie nach der Installation die Konfiguration über die Schaltfläche Konfigurieren.
3. Die Installation legt die technischen Tabellen an (Token, OAuth-Clients, Warenkörbe, Protokoll, Rate-Limiter) und aktiviert den Server standardmäßig.

Ihr MCP-Endpunkt

Die URL des MCP-Servers wird im Tab Agent verbinden angezeigt. Mit sprechenden URLs sieht sie so aus:

https://ihr-shop.com/mcp

Diese URL fügen Sie in den Connector des Agenten ein. Der Transport ist Streamable HTTP (JSON-RPC 2.0): ein einziger Endpunkt, per POST.

Authentifizierung: zwei Mechanismen

Das Modul verwaltet je nach verwendetem Client zwei Authentifizierungsmodi parallel.

OAuth 2.1 — Web-Connectoren (Claude.ai, ChatGPT)

Die Web-Connectoren von Claude.ai und ChatGPT akzeptieren nur OAuth: kein eingefügtes Token, kein Token in der URL. Das Modul liefert einen vollständigen OAuth-2.1-Autorisierungsserver (authorization code + PKCE S256, Protected Resource Metadata und Dynamic Client Registration). Der Agent registriert sich selbst und öffnet einen Zustimmungsbildschirm, auf dem sich der Kunde anmeldet und den Zugriff genehmigt.

Bearer-Token — API, Desktop, CLI, n8n

Für die Anthropic API (MCP-Connector), Claude Desktop, Claude Code oder n8n erstellen Sie ein statisches Bearer-Token im Tab Zugriffstoken und übergeben es im Header Authorization: Bearer.

Claude.ai oder ChatGPT verbinden (Web)

1. Lassen Sie OAuth 2.1 im Tab Einstellungen aktiviert.
2. Fügen Sie im Agenten einen benutzerdefinierten Connector hinzu und fügen Sie die MCP-Server-URL ein.
3. Der Agent erkennt die Authentifizierung automatisch, registriert sich und öffnet den Zustimmungsbildschirm.
4. Der Kunde meldet sich bei seinem Shop-Konto an und genehmigt die angeforderten Scopes. Kein Token einzugeben.

Anthropic API, Claude Desktop, Claude Code oder n8n verbinden

1. Öffnen Sie den Tab Zugriffstoken, wählen Sie die Scopes und klicken Sie auf Token erstellen.
2. Kopieren Sie das angezeigte Token.
3. Konfigurieren Sie den Connector mit der MCP-Server-URL und dem Header Authorization: Bearer IHR_TOKEN.

Scopes

Jeder Zugriff ist durch Scopes begrenzt, die vom Agenten angefordert und bei der Zustimmung gewährt (OAuth) oder vom Token getragen werden (Bearer):

• catalog:read — Produktsuche und -details, Kategorien, Shop-Infos, Versanddienstleister.
• cart:write — Erstellung und Verwaltung von Warenkörben.
• order:write — Bestellvorbereitung.

Bereitgestellte Tools

Neun Tools stehen zur Verfügung. Jedes lässt sich im Tab Einstellungen einzeln aktivieren oder deaktivieren und unterliegt dem passenden Scope.

• search_products — Suche nach Stichwort, Referenz oder EAN, mit Kategorie- und Preisfiltern.
• get_product — detaillierte Produktseite (Preis, Bestand, Varianten, Bilder).
• list_categories — Kategoriebaum.
• get_shop_info — Name, Sprachen, Währungen und Versandländer.
• get_carriers — verfügbare Versanddienstleister.
• create_cart — Erstellung eines Warenkorbs.
• add_to_cart — ein Produkt zum Warenkorb hinzufügen.
• view_cart — Inhalt und Summen des Warenkorbs.
• create_order — Abschluss, je nach konfiguriertem Bestellmodus.

Bestellmodi

Der Tab Einstellungen bietet zwei Verhaltensweisen für create_order.

Übergabemodus (Standard)

Der Agent stellt den Warenkorb zusammen und gibt eine sichere Checkout-URL zurück. Folgt der Kunde ihr, findet er genau diesen Warenkorb in seiner Sitzung und schließt die Zahlung im gewohnten PrestaShop-Ablauf ab. Keine Zahlungsdaten fließen durch den Agenten: null PCI-Exposition.

Bestellmodus

Der Agent erstellt direkt eine Bestellung mit Status Zahlung ausstehend, im konfigurierbaren Status (standardmäßig „Zahlung per Banküberweisung ausstehend“). Gedacht für B2B, Nachnahme oder Angebote.

Weitere Einstellungen

• Authentifizierung erfordern: empfohlen. Eine nicht authentifizierte Anfrage löst den OAuth-Ablauf aus (401-Antwort mit WWW-Authenticate-Header).
• Anonymes Lesen des Katalogs: erlaubt catalog:read-Aufrufe ohne Token, um einen öffentlichen Katalog bereitzustellen.
• Rate-Limit: Anzahl der Anfragen pro Minute und IP (Standard 120), gleitendes Fenster.
• Protokollierung und Aufbewahrung: zeichnet jede Anfrage (Methode, Tool, Status, Dauer) im Tab Aktivitätsprotokoll auf, mit konfigurierbarer Anzahl aufbewahrter Zeilen.

Erkennung und Endpunkte

Agenten erkennen den Server automatisch. Die nützlichen URLs sind im Tab Agent verbinden aufgeführt:

• Protected Resource Metadata (RFC 9728) — /.well-known/oauth-protected-resource.
• Authorization Server Metadata (RFC 8414) — /.well-known/oauth-authorization-server.
• Dynamic Client Registration (RFC 7591), Autorisierung und Token: vom Modul verwaltete OAuth-Endpunkte.

Sicherheit

• Alle Token werden mit SHA-256 gehasht gespeichert, niemals im Klartext.
• PKCE S256 obligatorisch, redirect_uri validiert, einmalig verwendbare Autorisierungscodes, Rotation der Refresh-Token.
• Rate-Limiting pro IP und einsehbares Aktivitätsprotokoll.
• CORS für Web-Connectoren verwaltet. Native Multishop-, Mehrsprachen- und Mehrwährungskompatibilität.

Fehlerbehebung

• Der Web-Agent verbindet sich nicht: Prüfen Sie, ob der Shop über HTTPS läuft und OAuth aktiviert ist. Fügen Sie die URL /mcp ein (keine Backoffice-Seite).
• Der API-Client gibt 401 zurück: Das Bearer-Token fehlt, ist widerrufen oder abgelaufen. Erstellen Sie ein neues im Tab Zugriffstoken und prüfen Sie den Authorization-Header.
• Ein Tool erscheint nicht: Es ist wahrscheinlich in den Einstellungen deaktiviert, oder der passende Scope wurde nicht gewährt.
• Fehler 429: Das Rate-Limit pro IP ist erreicht. Erhöhen Sie bei Bedarf den Schwellenwert in den Einstellungen.
• Der übergebene Checkout-Link läuft ab: Warenkorb-Links haben eine begrenzte Lebensdauer; bitten Sie den Agenten, den Warenkorb neu zu erstellen.

Deinstallation

Die Deinstallation entfernt die Tabellen des Moduls (Token, OAuth-Clients, Warenkörbe, Protokoll, Rate-Limiter) und seine Konfigurationsvariablen. Ihre Produkte, Kunden und Bestellungen sind nicht betroffen. Für ein einfaches Update genügt das Ersetzen der Dateien: Schema und vorhandene Token bleiben erhalten.