@payretailers/mcp

Offizieller Model Context Protocol (MCP)-Server für die PayRetailers Payments API.

Verwandeln Sie jeden MCP-kompatiblen KI-Assistenten in einen PayRetailers-Integrationsexperten. Dieser Server stellt die offiziellen Guides, taktischen Skills, die Endpunkt-Referenz und Integrationstools (Suche, länderspezifische Validierung, Webhook-Playbook) als erstklassige MCP-Ressourcen, -Tools und -Prompts bereit.

Funktioniert mit Cursor, Claude Desktop, Claude Code, Windsurf, Antigravity, Zed, VS Code + Copilot, JetBrains IDEs, Continue.dev, Cline und jedem anderen Client, der MCP über stdio spricht.

Warum es verwenden?

Wenn Sie diesen Server installieren, hört Ihr KI-Assistent auf, über PayRetailers zu raten, und konsultiert bei jedem Schritt die Quelle der Wahrheit.

• Korrekter Code auf Anhieb. Der Assistent liest die echte OpenAPI-Struktur für jeden Endpunkt (get_endpoint_spec), sodass generierter Code die tatsächlichen Feldnamen, Typen und erforderlichen Kombinationen verwendet – nicht etwas, das von einem anderen PSP übernommen wurde.

• Von Anfang an länderspezifisch. Fragen Sie nach einem PIX-Payin und der Assistent weiß, dass PIX nur in Brasilien gilt, BRL erwartet, eine gültige 11-stellige CPF benötigt und dass das QR schnell abläuft. Fragen Sie nach SPEI und er weiß, dass Mexiko eine CURP oder RFC, MXN und dass CLABE asynchron bereitgestellt wird. Alles unterstützt durch get_country_rules.

• Payloads werden validiert, bevor sie die Sandbox erreichen. validate_payload führt eine echte Prüfsummenvalidierung für CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE durch – plus übergreifende Regeln (ganzzahlige Nebenwährungen, HTTPS-Benachrichtigungs-URLs, Währungs-/Länderabgleich, Methoden-/Länderkompatibilität, Idempotenzschlüssel, Matrix der erforderlichen Kundendaten, Form von Abonnement-AmountModel, PIX Automático-Wiederholungsvertrag). Sie finden Fehler in Ihrem Editor, nicht in einer 400 INVALID_MODEL_SCHEMA-Antwort.

• Webhook-Empfänger korrekt entworfen. get_webhook_playbook liefert das kanonische Ereignisvokabular, Wiederholungsrichtlinien und den Signatur-/Replay-Vertrag. validate_webhook_handler erkennt die sechs schädlichsten Anti-Patterns (Ack-nach-Verarbeitung, fehlende eventId-Deduplizierung, Geschäftsfehler-als-500, deaktivierte Signatur in Produktion, Annahmen über die Wanduhr-Reihenfolge, fehlendes HTTPS) bevor Sie eine einzige Zeile Empfängercode schreiben.

• Slash-Command-Prompts für die schwierigen Abläufe. Geben Sie /integrate-pix-payin, /integrate-subscriptions, /implement-webhook-handler, /integrate-payout-fx, /build-checkout, /debug-401-auth oder /reconcile-with-graphql ein und erhalten Sie eine produktionsreife Implementierung in dem Stack Ihrer Wahl.

• Null-Konfiguration, null-Netzwerk, offline-freundlich. Alles ist im Release-Zip gebündelt. Kein Konto, kein API-Schlüssel, keine ausgehenden Aufrufe, nur um eine Frage zu den Dokumenten zu beantworten. Anmeldedaten werden nur für das (geplante) simulate_transaction-Tool benötigt.

Unter der Haube haben Sie 7 Tools, 7 Prompts, 158 Dokumentationsressourcen (Guides + Skills + Reference + Recipes + Konzeptdokumente), alle wortwörtlich aus dem payretailers-ai-docs-Repository gespiegelt.

Related MCP server: Payman AI Documentation MCP Server

Was es bereitstellt

Ressourcen

Strukturierter, LLM-freundlicher Zugriff auf die PayRetailers-Dokumentation.

Die vollständige Liste wird zur Verbindungszeit dynamisch bekannt gegeben – Clients können sie über ihren Ressourcen-Picker durchsuchen.

Tools

Prompts

Installation

Zwei unterstützte Wege. Wählen Sie einen:

• Option A — Vorgefertigtes ZIP von GitHub Releases (derzeit empfohlen): kein npm-Konto, keine Kompilierung, funktioniert nach dem Download vollständig offline. Dies ist die offiziell unterstützte Distribution, solange @payretailers/mcp noch nicht auf npm verfügbar ist.

• Option B — Aus dem Quellcode bauen: für Mitwirkende und sicherheitsbewusste Bereitstellungen, die den Code vor der Ausführung prüfen möchten.

Option C — Installation von npm als @payretailers/mcp — ist geplant, aber noch nicht verfügbar. Sobald das Paket veröffentlicht ist, funktionieren die npx -y @payretailers/mcp-Ausschnitte im Abschnitt Konfiguration nach Client sofort.

Option A — Installation von GitHub Releases

Voraussetzungen: Node.js 20 oder neuer (node --version). Sonst nichts — das Release-ZIP ist in sich geschlossen.

1. Öffnen Sie die Releases-Seite und laden Sie das neueste payretailers-mcp-vX.Y.Z.zip aus dem Abschnitt „Assets" des obersten Releases herunter.

2. Entpacken Sie es an einen beliebigen Ort. Übliche Speicherorte:

   • Windows: C:\Tools\payretailers-mcp

   • macOS / Linux: ~/tools/payretailers-mcp

3. Fügen Sie den Server zu Ihrem MCP-Client hinzu (siehe Konfiguration nach Client unten oder die dort verlinkten Schritt-für-Schritt-Anleitungen). Verweisen Sie auf den absoluten Pfad von dist/index.js im entpackten Ordner.

4. Laden Sie Ihren MCP-Client neu / starten Sie ihn neu. Der Server erscheint neben Ihren anderen Tools.

Schritt-für-Schritt-Einrichtungsanleitungen mit Screenshots und Verifizierungsaufforderungen:

• Cursor

• Claude Code CLI

• Claude Desktop

• VS Code + GitHub Copilot

Optionaler Smoke-Test vor oder nach der Einbindung — beweist, dass das Bundle durchgängig funktionsfähig ist:

cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs

Erwartet: PASS ✅ am Ende, mit 7 Tools, 158 Ressourcen, 7 Prompts, 5 Ressourcenvorlagen angekündigt.

Option B — Aus dem Quellcode bauen

Für Mitwirkende oder wenn Ihre Sicherheitsrichtlinie verlangt, den Code vor der Ausführung zu prüfen. Voraussetzungen: Node.js 20 oder neuer, git.

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)

data/ (Guides, Skills, Reference, Recipes, Konzeptdokumente, kuratiertes JSON) ist eingecheckt — Sie benötigen npm run sync:docs nicht, es sei denn, Sie spiegeln ein aktualisiertes payretailers-ai-docs-Checkout auf derselben Maschine.

Binden Sie dann dist/index.js auf dieselbe Weise wie bei Option A in Ihren MCP-Client ein.

Konfiguration nach Client

Bevorzugen Sie eine vollständige Anleitung mit Verifizierungsaufforderungen und Fehlerbehebung? Siehe die Schritt-für-Schritt-Anleitungen in docs/setup/ für Cursor, Claude Code, Claude Desktop und VS Code + Copilot. Die folgenden Ausschnitte sind das minimale JSON, das Sie benötigen, wenn Sie sich in Ihrem Client bereits auskennen.

Jeder Client benötigt dieselben drei Informationen: einen Befehl (node), ein args-Array, das auf den absoluten Pfad von dist/index.js verweist, und einen optionalen env-Block für das zukünftige simulate_transaction-Tool.

Ersetzen Sie C:/Tools/payretailers-mcp/dist/index.js unten durch den absoluten Pfad, an dem Sie das Release entpackt haben. Verwenden Sie unter Windows Schrägstriche in JSON — Rückwärtsschrägstriche müssen maskiert werden und verursachen verwirrende Fehler.

Cursor

Fügen Sie zu ~/.cursor/mcp.json (global) oder .cursor/mcp.json (pro Projekt) hinzu:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}

Der env-Block ist optional — Ressourcen, search_docs und alle Validatoren funktionieren ohne Anmeldedaten.

Claude Desktop

Fügen Sie zu Ihrer claude_desktop_config.json hinzu:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Windsurf

Fügen Sie zu ~/.codeium/windsurf/mcp_config.json hinzu:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

VS Code + Copilot

Fügen Sie zu .vscode/mcp.json (Arbeitsbereich) hinzu oder öffnen Sie die benutzerbezogene Datei über die Befehlspalette → MCP: Open User Configuration:

{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Hinweis: VS Code ist der Sonderfall — der Wurzelschlüssel ist "servers" (nicht "mcpServers"). MCP-Tools laufen nur im Agent-Modus von Copilot Chat.

Zed

Fügen Sie zu ~/.config/zed/settings.json hinzu:

{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}

Continue.dev

Fügen Sie zu ~/.continue/config.json hinzu:

{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}

JetBrains AI Assistant

Öffnen Sie Einstellungen → AI Assistant → MCP Servers → Hinzufügen und geben Sie ein:

• Name: payretailers

• Befehl: node

• Argumente: C:/Tools/payretailers-mcp/dist/index.js (absoluter Pfad)

Andere Clients

Jeder Client, der MCP über stdio unterstützt, kann diesen Server verwenden. Verweisen Sie auf node <absoluter-pfad-zu>/dist/index.js und Sie sind fertig.

Sobald npm verfügbar ist

Wenn @payretailers/mcp auf npm veröffentlicht ist, funktionieren dieselben Konfigurationen mit der kürzeren Form:

{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }

Keine Änderungen an env, kein entpackter Ordner erforderlich.

Verifizieren, dass es funktioniert

Nach dem Neuladen Ihres MCP-Clients sollten Sie im Status des Servers etwa Folgendes sehen:

7 Tools · 158 Ressourcen · 7 Prompts · 5 Ressourcenvorlagen

• Cursor: Ctrl+Shift+P → Customize → Registerkarte MCPs. Suchen Sie nach payretailers mit einem grünen Punkt und erweitern Sie es.

• Claude Desktop: Prüfen Sie die Tool-Schublade in einem neuen Chat; die PayRetailers-Tools sollten neben Ihren anderen MCPs erscheinen.

• VS Code / Zed / Continue.dev / Windsurf: Konsultieren Sie die Dokumentation des jeweiligen Clients für dessen MCP-Statusbereich.

Wenn Ihr Assistent die Tools nicht aufzurufen scheint, erzwingen Sie es einmal, indem Sie eine Aufforderung mit „Verwenden Sie das PayRetailers-MCP, um..." beginnen. Sobald er ein Tool einmal in einer Unterhaltung aufgerufen hat, neigt er dazu, dies weiterhin zu tun.

Fehlerbehebung

Der Server startet nicht. Führen Sie das Bundle manuell über ein Terminal aus:

node /path/to/payretailers-mcp/dist/index.js

Wenn es still auf Eingaben wartet, ist das Bundle in Ordnung — das Problem liegt auf Client-Seite (Tippfehler im Pfad in der Konfiguration, Schrägstriche vs. Rückwärtsschrägstriche unter Windows, falscher Prozess wird neu gestartet). Wenn ein Fehler ausgegeben wird, sind die häufigsten Ursachen Node < 20 (Node aktualisieren) oder ein abgeschnittener Download (ZIP erneut herunterladen).

Der Client zeigt alte Zähler (z. B. 5 Tools, 89 Ressourcen). Einige Clients speichern die MCP-Tool-/Ressourcenaufzählung zwischen. Schalten Sie den Server im MCP-Bereich des Clients AUS → EIN, oder fügen Sie einen ungenutzten env-Eintrag zur Konfiguration hinzu (z. B. "MCP_VERSION": "0.4.1"), um einen Neustart zu erzwingen.

Das Modell scheint kein MCP-Tool aufzurufen. Stellen Sie sicher, dass der Chat im Agent-Modus ist (nicht im Ask-/Nur-Lese-Modus). Einige leichte Modelle rufen weniger bereitwillig Tools auf — wechseln Sie für die ersten Aufrufe zu einem Top-Modell, und der Assistent merkt sich, dass die Tools für den Rest der Unterhaltung verfügbar sind.

Wo sind die Protokolle? Jeder MCP-Client hat einen MCP-Protokollbereich, der den JSON-RPC-Handshake, Parse-Fehler und Server-stderr erfasst. In Cursor: Ctrl+Shift+U → Dropdown → MCP Logs.

Umgebungsvariablen

Optional — nur für das zukünftige simulate_transaction-Tool (Phase 4) erforderlich. Alles andere (Ressourcen, search_docs, Prompts) funktioniert ohne Anmeldedaten.

Sicherheit: Der Server protokolliert niemals Anmeldedaten und speichert sie niemals dauerhaft. Sie verbleiben für die Dauer der Sitzung im Speicher und werden nur an api-sandbox.payretailers.com oder api.payretailers.com gesendet, wenn Sie simulate_transaction aufrufen.

Beispielverwendung

Nach der Konfiguration fragen Sie Ihren KI-Assistenten in einfacher Sprache:

„Erstellen Sie meine erste PIX-Zahlung in der Sandbox für R$50 in Brasilien. Verwenden Sie Node.js."

Im Hintergrund wird der Assistent:

1. search_docs({ query: "pix payin brazil" }) aufrufen → die brazil-pix-payin-Skill finden.

2. payretailers://skill/brazil-pix-payin für die genauen Schritte lesen.

3. Ausführbaren Code mit dem richtigen Endpunkt, Headern, Nebenwährungseinheiten und CPF-Format generieren.

Oder verwenden Sie direkt den /integrate-pix-payin-Prompt für eine vollständig strukturierte Antwort.

Validieren einer Nutzlast vor der Übermittlung

Sobald der Assistent eine Nutzlast entworfen hat, kann er sie vor dem Aufruf der API validieren:

// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}

Die Antwort listet jedes Problem mit einem code, severity, path, message und oft einem hint und suggestion auf — das LLM kann die Nutzlast korrigieren, bevor eine Netzwerk-Roundtrip verschwendet wird.

Entwicklung

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio

data/ (Guides, Skills, Reference, Recipes, Konzeptdokumente, kuratiertes JSON) ist im Repository eingecheckt. Führen Sie npm run sync:docs nur aus, wenn Sie ../payretailers-ai-docs ausgecheckt haben und den Spiegel aktualisieren möchten.

Der Server kann mit dem offiziellen MCP Inspector untersucht werden:

npx @modelcontextprotocol/inspector node dist/index.js

Veröffentlichung (Maintainer)

Releases werden über GitHub Actions bei Tag-Push (v*.*.*) automatisiert. Der Workflow:

1. Führt Lint, Typprüfung, Unit-Tests, Build und Smoke-Test aus.

2. Führt npm run pack:release aus, um release/payretailers-mcp-vX.Y.Z.zip zu erzeugen (gebündeltes dist/index.js + data/-Spiegel + README + LICENSE + CHANGELOG + Smoke-Test).

3. Erstellt ein GitHub Release und hängt das ZIP an.

4. Veröffentlicht auf npm als @payretailers/mcp nur wenn das Repository-Geheimnis NPM_TOKEN konfiguriert ist — andernfalls ist das Release nur auf GitHub verfügbar.

Um ein Release lokal zu erstellen und dann den Tag zu pushen:

# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml

Semver wird streng durchgesetzt: Patch-Releases beheben Fehler, Minor-Releases fügen Tools/Prompts/Ressourcen hinzu, ohne bestehende zu brechen, Major-Releases nur für Umbenennungen/Entfernungen.

Roadmap

• 0.1 ✅ Ressourcen (Guides, Skills), search_docs, integrate-pix-payin-Prompt.

• 0.2 ✅ Ressourcen (Reference, Recipes), get_country_rules, get_test_data, get_endpoint_spec, Prompts integrate-payout-fx, build-checkout, debug-401-auth, reconcile-with-graphql.

• 0.3 ✅ validate_payload mit echter Prüfsummenvalidierung für CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE + übergreifende Regeln (Nebenwährungseinheiten, Währung/Land, HTTPS-Webhooks, Methode/Land, Idempotenz).

• 0.4 ✅ Konzeptdokument-Ressourcenkategorie, get_webhook_playbook, validate_webhook_handler, erweitertes validate_payload für Abonnementoperationen, Prompts implement-webhook-handler, integrate-subscriptions.

• 0.4.1 ✅ Abonnementschema-Angleichung (AmountModel, frequency-Enum, authorizationType) — CHANGELOG.md.

• 0.5 — simulate_transaction (Trockenlauf gegen Sandbox), get_error_code, erweiterte Länderabdeckung.

• 1.0 — Stabile öffentliche Veröffentlichung + Auflistung im offiziellen MCP-Registry + npm-Veröffentlichung.

Siehe CHANGELOG.md für Details.

Verwandtes

• Schritt-für-Schritt-Einrichtungsanleitungen für Cursor, Claude Code, Claude Desktop und VS Code + Copilot: docs/setup/.

• Begleitendes Dokumentationsrepository: payretailers-dev/payretailers-ai-docs — die Quelle für Guides, Skills und den Dokumentationsspiegel.

• Offizielle Dokumentation: www.payretailers.dev.

• Leitfaden für die Entwicklung mit LLMs: www.payretailers.dev/docs/develop-with-llms.

• Model Context Protocol: modelcontextprotocol.io.

Lizenz

Quellcode: MIT. Siehe LICENSE.

Dokumentationsinhalte, die in data/ gebündelt sind (Guides, Skills, Reference, Recipes), sind unter CC BY-ND 4.0 lizenziert, übernommen aus dem payretailers-ai-docs-Repository. Die kuratierten Datendateien (data/country-rules.json, data/test-data.json) werden ebenfalls unter CC BY-ND 4.0 veröffentlicht.

Mitwirken

Fehlerberichte und Funktionsanfragen sind über GitHub Issues willkommen. Pull Requests aus der Community werden geprüft, aber nach Ermessen des PayRetailers-Teams zusammengeführt — siehe CONTRIBUTING.md, sobald verfügbar.