PageFly Rückerstattungs-MCP-Server

MCP (Model Context Protocol) Server für Crisps Hugo AI Agent zur durchgängigen Bearbeitung von PageFly-Rückerstattungsanfragen.

Er stellt neun Tools bereit, die in drei Ebenen gruppiert sind:

Suche (Mock-Fixtures)

• check_subscription → den aktuellen Plan für einen Shop oder eine E-Mail abrufen

• get_billing_history → alle Rechnungen / anstehende Abbuchungen für einen Shop auflisten

Reine Logik

• classify_refund_case → Kontext einem von 7 Playbook-Fällen (TH1–TH7) zuordnen

• calculate_refund → 30-tägige anteilige oder zyklusübergreifende Rückerstattungsberechnung mit Abzug

• collect_refund_info → entscheiden, welche Frage als Nächstes gestellt werden soll und Blocker aufzeigen

• generate_refund_message → die Kundenantwort aus PageFly-Vorlagen entwerfen

Status (Turso / libSQL)

• get_case_state → einen Fall anhand der Shop-URL fortsetzen

• save_case_state → Fortschritt bei jedem wichtigen Schritt speichern

• list_pending_cases → Fälle überprüfen, die auf den Manager, den Kunden oder die bezahlte Rechnung warten

Erstellt mit dem @modelcontextprotocol Typescript SDK.

Umgebung

Kopieren Sie .env.example nach .env und tragen Sie Ihre Turso-Anmeldedaten ein:

TURSO_DATABASE_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<token>
PORT=3000

Migrationen werden beim Serverstart automatisch ausgeführt – ein erneutes Ausführen ist sicher.

Related MCP server: Spaceship MCP

I. Installation & Ausführung

Um mit diesem MCP-Server zu beginnen, können Sie ihn entweder lokal ausführen oder die gehostete Version verwenden.

Verwendung der gehosteten Version

Dieser MCP-Server ist bereits gehostet und bereit, mit Ihrem Crisp-Arbeitsbereich verbunden zu werden, falls Sie ihn schnell testen möchten. Sie können ihn unter folgender Adresse aufrufen: https://crisp-mcp-demo.fly.dev/mcp

Lokal ausführen

Voraussetzungen:

• Node.js 24.x installiert

• eine Tastatur (optional, aber empfohlen)

Schritt 1 — Klonen des Repos

Öffnen Sie ein Terminal in Ihrem gewünschten Ordner und führen Sie Folgendes aus:

git clone https://github.com/NTHieu002/refund-crisp-mcp.git
cd refund-crisp-mcp

Schritt 2 — Ausführen des Servers

Sie können den Server entweder bauen und starten oder direkt im Entwicklungsmodus ausführen.

Um den Server zu bauen und zu starten, verwenden Sie:

npm ci
npm run build
npm run start

Oder um ihn im Entwicklungsmodus mit tsx (Watch-Modus) auszuführen, verwenden Sie:

npm ci
npm run dev

Schritt 3 — Bereitstellen des Servers (bei lokaler Ausführung)

Wenn Sie den Server lokal ausführen möchten, müssen Sie ihn über einen Tunnel bereitstellen, damit Crisp ihn erreichen kann. Dieses Paket ist für die Verwendung von Cloudflared vorkonfiguriert, Sie können jedoch jede beliebige Tunneling-Lösung verwenden.

Falls Cloudflared noch nicht auf Ihrem Computer installiert ist, folgen Sie diesem Link, um die Installationsanweisungen für Ihr Betriebssystem zu finden:

Sobald die Installation abgeschlossen ist, öffnen Sie ein neues Terminal und führen Sie Folgendes aus:

npm run tunnel

Sie können die URL Ihres Tunnels besuchen, um zu bestätigen, dass er funktioniert. Sie sollten eine Begrüßungsnachricht sehen.

Verfügbare Skripte

• npm run dev → Entwicklungsserver (Watch)

• npm run build → TypeScript kompilieren

• npm run start → kompilierten Server ausführen

• npm run tunnel → localhost über Cloudflare Tunnel bereitstellen

• npm run inspect → führt den @modelcontextprotocol Inspector aus

II. Verbindung mit Crisp

Dieser Abschnitt ist eine Kurzanleitung, um diesen MCP-Server mit Ihrem Crisp-Arbeitsbereich zu verbinden. Wir empfehlen auch einen Blick in unsere offizielle Dokumentation, um detailliertere Anweisungen zu erhalten.

Voraussetzungen:

• ein Crisp-Konto

• ein Crisp-Arbeitsbereich mit Essentials- oder Plus-Plan

Schritt 1 — Navigieren Sie zu app.crisp.chat

Schritt 2 — Gehen Sie im Menü AI Agent zu AI Agent → Automate → Integrations & MCP → External MCP servers** und klicken Sie auf den Bereich Add MCP server.

Schritt 3 — Geben Sie die URL Ihres MCP-Servers ein (entweder Ihre gehostete/getunnelte URL oder unsere gehostete Version) und klicken Sie auf Add MCP Server.

Schritt 4 — Konfigurieren Sie den MCP-Server:

1. Geben Sie ihm einen Namen

2. Klicken Sie auf Refresh tools from server, falls Ihre Tools nicht automatisch abgerufen wurden

3. Aktivieren Sie den MCP-Server

4. Klicken Sie auf die Schaltfläche Save changes

Schritt 5 — Ihr MCP-Server sollte nun registriert und einsatzbereit sein!

III. Testen des MCP-Servers

Immer noch im Menü Automations können Sie zum Playground gehen, um Ihren MCP-Server und verschiedene KI-Modelle zu testen. Stellen Sie ihm eine Frage!

Playground-Beispiele

Einmalige Fragen:

Könntest du prüfen, ob die Rückerstattung meiner Bestellung OID_002 bearbeitet wurde?

Hallo, sind die Benachrichtigungen in meinem Konto baptiste@acme.com aktiviert?

Die KI kann mehrere Tool-Aufrufe verketten (z. B. Konto finden, aktuelle Bestellungen auflisten und Produktdetails abrufen):

Sind die Artikel meiner Bestellung OID_001 noch unter Garantie?

Wann wird meine letzte Bestellung geliefert? Ich bin chris@acme.com

Versuchen Sie auch Teilfragen und lassen Sie die KI zusätzliche Informationen von Ihnen anfordern:

Wie hoch war der Betrag meiner letzten Bestellung?

Ich kann meine Sendungsverfolgungsnummer nicht finden, kannst du mir helfen?

Verfügbare Konten & Bestellungen

• chris@acme.com

  • OID_003

  • OID_006

• baptiste@acme.com

  • OID_001

  • OID_004

• dinis@acme.com

  • OID_002

  • OID_005

  • OID_007

MCP-Best Practices

MCP-Design

• Server-Beschreibung: Beschreiben Sie den allgemeinen Zweck des MCP-Servers

• Tool-Benennung: Verwenden Sie klare und explizite Namen (z. B. get_order, nicht orderLookup)

• Tool-Beschreibungen: Beschreiben Sie prägnant, was das Tool tut, wann es aufgerufen werden sollte und geben Sie optional Anwendungsbeispiele an

• Schemas: Stellen Sie präzise Schemas für Tool-Eingaben bereit, um eine korrekte Verwendung sicherzustellen

Benutzerverifizierung

In Ihrer MCP-Serverkonfiguration können Sie optional verlangen, dass sich Benutzer authentifizieren, bevor die KI ein MCP-Tool aufrufen kann. Dies erhöht die Sicherheit bei sensiblen Vorgängen.

Wenn der Benutzer noch nicht authentifiziert ist, sendet Crisp ihm einen OTP-Code per E-Mail oder SMS, bevor die KI Ihr MCP-Tool aufrufen darf.

Navigieren Sie dazu einfach zu Ihrem MCP-Server und klicken Sie auf Manage. Bei jedem Tool können Sie die Option Require user identification verification umschalten.

Server-Authentifizierung

In der Produktion möchten Sie möglicherweise den Zugriff auf Ihren MCP-Server einschränken und eine unbefugte Nutzung verhindern. Es stehen zwei Authentifizierungsmethoden zur Verfügung:

• Bearer Token: ein statisches Token, das im Authorization-Header jeder Anfrage gesendet wird

• Basic Auth: ein Benutzername und ein Passwort, die im Authorization-Header jeder Anfrage gesendet werden