commerce:SEO MCP Server - Entwickler-Dokumentation

Navigation

Überblick & Architektur
Schnellstart & Test
Browser & Web-API
Client-Konfiguration
Verfügbare Tools (10)
Sicherheitskonzept & Auth

Version: 1.0.0

Protokoll: MCP 2024-11-05

Transport: Stdio (JSON-RPC 2.0)

Pfad: bin/mcp-server.php

Überblick & Architektur

Das Model Context Protocol (MCP) ist ein offener Standard, der es Sprachmodellen (LLMs) ermöglicht, strukturiert Werkzeuge (Tools) und Ressourcen von externen Systemen aufzurufen. Der commerce:SEO MCP Server kapselt alle Kernfunktionen des Shops in sichere, parametrisierte Werkzeuge.

Stdio Transport

Der Client startet php bin/mcp-server.php als Subprozess. Anfragen und Antworten fließen zeilenweise als JSON-RPC 2.0 über STDIN und STDOUT.

PDO ShopBridge

Die ShopBridge liest includes/configure.php ein und führt alle Abfragen über sichere PDO Prepared Statements mit UTF-8 Kodierung aus.

Output-Isolation

Jegliche Warnungen oder Logs werden nach STDERR umgeleitet, sodass der Datenstrom auf STDOUT garantiert fehlerfrei und parsebar bleibt.

Schnellstart & Test

Sie können den Server direkt über die Kommandozeile ausführen oder den automatisierten Test starten:

Automatisierter Test aller Hauptfunktionen:

php test_mcp.php

Manueller CLI-Start (wartet auf STDIN):

php bin/mcp-server.php

Browser & Web-API Endpoint

Live Web-Tester öffnen

Über den Endpunkt mcp_api.php kann der MCP-Server auch per HTTP GET und POST über den Browser, curl oder REST-Clients angesprochen werden.

GET-Aufruf (REST Query)

Ideal für schnelle Tests direkt im Webbrowser:

# Öffentliche Suche (ohne Authentifizierung)
http://localhost/v5pro/mcp_api.php?tool=cseo_search_products&query=Lavendel

# Geschützter Aufruf mit API-Key
http://localhost/v5pro/mcp_api.php?tool=cseo_get_shop_info&api_key=cseo_mcp_sec_v6pro_secret_key_2026
                            

POST-Aufruf (MCP JSON-RPC 2.0)

Vollständiger JSON-RPC 2.0 Request via HTTP-Header:

curl -X POST http://localhost/v5pro/mcp_api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cseo_mcp_sec_v6pro_secret_key_2026" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cseo_get_orders","arguments":{"limit":5}}}'
                            

Client-Konfiguration

Registrieren Sie den Server in der Konfigurationsdatei Ihres bevorzugten KI-Clients:

Speicherort: C:\Users\<Benutzer>\.gemini\config\mcp_config.json

{
  "mcpServers": {
    "commerce-seo": {
      "command": "php",
      "args": [
        "C:/xampp/htdocs/v5pro/bin/mcp-server.php"
      ]
    }
  }
}

Speicherort: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "commerce-seo": {
      "command": "php",
      "args": [
        "C:/xampp/htdocs/v5pro/bin/mcp-server.php"
      ]
    }
  }
}

Unter Settings > Features > MCP > Add New MCP Server:

Name: commerce-seo
Type: command
Command: php C:/xampp/htdocs/v5pro/bin/mcp-server.php

Verfügbare Tools (10)

Bereitgestellt via tools/list

1. cseo_get_shop_info

Read-Only

Liefert grundlegende System- und Statistikdaten des Shops: Shopname, Betreiber, E-Mail, Währung, PHP- & MySQL-Versionen, Anzahl der Artikel (gesamt & aktiv), Bestellungen und Kunden.

Parameter	Typ	Erforderlich	Beschreibung
Keine Parameter erforderlich.

2. cseo_search_products

Suche

Sucht nach Artikeln über den Artikelnamen, die Artikelnummer (Model/SKU) oder die exakte Produkt-ID.

Parameter	Typ	Erforderlich	Beschreibung
`query`	string	Ja	Suchbegriff oder SKU
`limit`	integer	Nein	Max. Treffer (Standard: 10, max: 50)

3. cseo_get_product_details

Detailabfrage

Ruft alle Stammdaten eines Artikels ab: Name, Preise (netto), Lagerbestand, Status, Gewicht, Steuerklasse, Kategorien, Beschreibung, Meta-Tags und Buchungsmodul-Konfiguration.

Parameter	Typ	Erforderlich	Beschreibung
`product_id`	integer	Ja	ID des Artikels (`products_id`)

4. cseo_update_product_stock

Schreibzugriff

Aktualisiert den physischen Lagerbestand (Menge) und/oder schaltet den Artikel aktiv (1) oder inaktiv (0).

Parameter	Typ	Erforderlich	Beschreibung
`product_id`	integer	Ja	ID des Artikels
`quantity`	integer	Nein	Neuer Lagerbestand
`status`	integer	Nein	Status: `1` (aktiv) oder `0` (inaktiv)

5. cseo_get_orders

Bestellübersicht

Listet die neuesten Bestellungen auf mit Kundennamen, Datum, Gesamtsumme, Zahlungsweise und Statusbezeichnung.

Parameter	Typ	Erforderlich	Beschreibung
`limit`	integer	Nein	Anzahl abzurufender Bestellungen (Standard: 10)
`status_id`	integer	Nein	Filter nach Status-ID (z. B. 1 für offen, 3 für versendet)

6. cseo_get_order_details

Bestelldetails

Gibt alle Detaildaten zu einer Bestellung zurück: Kunde, Liefer- und Rechnungsadresse, bestellte Artikel mit Einzelpreisen, Gesamtsummen und vollständige Status-Historie.

Parameter	Typ	Erforderlich	Beschreibung
`order_id`	integer	Ja	Bestellnummer (`orders_id`)

7. cseo_update_order_status

Schreibzugriff

Aktualisiert den Status einer Bestellung und dokumentiert die Änderung revisionssicher in der Tabelle orders_status_history.

Parameter	Typ	Erforderlich	Beschreibung
`order_id`	integer	Ja	Bestellnummer
`status_id`	integer	Ja	Neue Status-ID
`comments`	string	Nein	Kommentar (z. B. Sendungsnummer)
`customer_notified`	boolean	Nein	Wurde Kunde benachrichtigt? (Standard: false)

8. cseo_get_booking_reservations

Buchungsmodul

Liest gebuchte Zeiträume und Reservierungen aus dem Buchungsmodul aus (optional eingrenzbar auf eine bestimmte Produkt-ID).

Parameter	Typ	Erforderlich	Beschreibung
`product_id`	integer	Nein	Produkt-ID zur Eingrenzung
`limit`	integer	Nein	Max. Einträge (Standard: 20)

9. cseo_clear_cache

Wartung

Löscht alle kompilierten Template-Dateien in templates_c/*.php und den internen Daten-Cache in cache/*.php (Dateien wie .htaccess und index.html bleiben geschützt).

Parameter	Typ	Erforderlich	Beschreibung
Keine Parameter erforderlich.

10. cseo_run_readonly_query

Diagnose

Führt sichere SQL-Leseabfragen aus. Alle verändernden Befehle (INSERT, UPDATE, DELETE, DROP, ALTER) sind serverseitig strikt blockiert.

Parameter	Typ	Erforderlich	Beschreibung
`sql`	string	Ja	SELECT-, SHOW- oder EXPLAIN-Abfrage
`limit`	integer	Nein	Maximales Limit (Standard: 50)

Sicherheitskonzept & Authentifizierung

Der commerce:SEO MCP-Server implementiert ein abgestuftes 2-Ebenen-Sicherheitsmodell. Dies erlaubt die nahtlose Einbindung von öffentlichen KI-Produktsuchassistenten (z. B. auf Landingpages oder in Shopping-Chats), während alle sensiblen Betriebs-, Kunden- und Schreibfunktionen wirksam geschützt bleiben.

Berechtigung	Tools	Authentifizierungs-Anforderung
Öffentlich	`cseo_search_products`	Frei zugänglich. Kein API-Key oder Login erforderlich. Ideal für KI-Suchassistenten, Chatbots und externe Portale.
Geschützt (9 Tools)	`cseo_get_shop_info`, `cseo_get_product_details`, `cseo_update_product_stock`, `cseo_get_orders`, `cseo_get_order_details`, `cseo_update_order_status`, `cseo_get_booking_reservations`, `cseo_clear_cache`, `cseo_run_readonly_query`	Zwingend geschützt. Anfragen ohne gültigen Schlüssel werden sofort mit `HTTP 401 Unauthorized` (Fehlercode `-32001`) abgewiesen.

Unterstützte Authentifizierungsmethoden

Bei Web- und HTTP-Aufrufen akzeptiert mcp_api.php den Schlüssel über folgende Wege (in priorisierter Reihenfolge):

1. HTTP Authorization Header (Empfohlen)

Standard Bearer Token:

Authorization: Bearer cseo_mcp_sec_v6pro_secret_key_2026

Oder X-API-Key Header:

X-API-Key: cseo_mcp_sec_v6pro_secret_key_2026

2. URL-Parameter & Admin-Session

URL-Parameter (GET/Browser):

?tool=cseo_get_shop_info&api_key=cseo_mcp_sec_v6pro_secret_key_2026

Admin-Session:

Ist im gleichen Browser eine aktive commerce:SEO Admin-Sitzung geöffnet (Status 0), wird der Zugriff automatisch gewährt.

Konfiguration in config.json

Der API-Schlüssel und die Liste der öffentlichen Tools werden in folgender Datei konfiguriert:
GXModules/Custom/McpServer/config.json

{
  "api_key": "cseo_mcp_sec_v6pro_secret_key_2026",
  "public_tools": [
    "cseo_search_products"
  ],
  "allow_cli_without_auth": true,
  "allow_admin_session_auth": true,
  "allow_http_basic_auth": true
}

Zusätzliche Sicherheitsmaßnahmen

SQL Injection Schutz: Sämtliche Datenbankoperationen in ShopBridge.php nutzen strikt parametrisierte PDO Prepared Statements.
Schreibschutz bei SQL-Abfragen: Im Diagnose-Tool cseo_run_readonly_query werden verändernde Keywords (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, GRANT) per Regex hart geblockt.
DSGVO & Passwortschutz: Kundenpasswörter oder Kreditkartendaten werden niemals über den MCP-Server ausgeliefert.
CLI-Privileg: Lokale Prozesse (z. B. IDEs über bin/mcp-server.php via Stdio) haben standardmäßig vollen Zugriff, da sie direkt auf dem Server im Betriebssystemkontext des Webserver-Benutzers ausgeführt werden.