Splitwise-Connector für ChatGPT

Ein reiner Daten-MCP-Server, der ChatGPT mit der offiziellen Splitwise-API verbindet. Unterstützt werden:

• list_groups

• list_friends (einschließlich Salden)

• list_expenses

• get_expense

• create_expense (gleiche Gruppenaufteilung oder explizite Anteile)

Der Server verwendet Streamable HTTP unter /mcp. Er fungiert außerdem als kleine OAuth-2.1-Autorisierungsbrücke: ChatGPT führt PKCE mit diesem Server durch, während dieser Server den Splitwise-OAuth abschließt und das Splitwise-Token von ChatGPT fernhält.

Voraussetzungen

• Node.js 20 oder neuer

• Eine stabile öffentliche HTTPS-URL für die Bereitstellung (oder ein Entwicklungstunnel beim Testen)

• Ein Splitwise-Konto und eine Splitwise-OAuth-Anwendung

1. Splitwise-Anwendung registrieren

1. Öffnen Sie https://secure.splitwise.com/apps und erstellen Sie eine OAuth-Anwendung.

2. Setzen Sie die Rückruf-URL auf https://YOUR-CONNECTOR-HOST/oauth/splitwise/callback.

3. Kopieren Sie die Client-ID und das Client-Geheimnis. Committen Sie diese niemals.

Splitwise muss zum Connector umleiten, nicht direkt zu ChatGPT. Der Connector setzt danach den separaten PKCE-Ablauf von ChatGPT fort.

2. Konfiguration und Ausführung

cp .env.example .env
# Fill in .env, then:
npm install
npm run dev

Erforderliche Variablen:

Optionale Variablen: PORT, SPLITWISE_AUTHORIZE_URL, SPLITWISE_TOKEN_URL und SPLITWISE_API_BASE_URL.

Generieren Sie ein Session-Geheimnis mit openssl rand -hex 32. Für einen Container:

docker build -t splitwise-mcp .
docker run --env-file .env -p 3000:3000 splitwise-mcp

3. OAuth-Ablauf

1. ChatGPT erkennt /.well-known/oauth-protected-resource vom MCP-Server.

2. Es erkennt die OAuth-Metadaten dieses Connectors unter /.well-known/oauth-authorization-server und registriert dynamisch einen öffentlichen Client unter /register.

3. ChatGPT startet Autorisierungscode + PKCE unter /authorize, einschließlich des MCP-resource-Werts.

4. Der Connector leitet den Benutzer zu Splitwise um und empfängt das Ergebnis unter /oauth/splitwise/callback.

5. Der Connector tauscht den Splitwise-Code serverseitig aus, erstellt einen fünf Minuten gültigen verschlüsselten Connector-Code und leitet zu ChatGPT um.

6. ChatGPT tauscht diesen Code unter /token mit seinem PKCE-Verifier aus. Der Connector gibt ein authentifiziertes, verschlüsseltes Zugriffstoken zurück, das den minimalen Sitzungskontext enthält.

7. Jede /mcp-Anfrage entschlüsselt und validiert das Token, den Ablauf, den Scope-Kontext und die Ressource, bevor Splitwise aufgerufen wird.

Dynamische Client-Registrierungen, Connector-Codes und 30-Tage-Zugriffstokens sind zustandslose AES-256-GCM-Umschläge, die von SESSION_SECRET abgeleitet werden. Sie überstehen Ruhezustand, Neustarts, erneute Bereitstellungen und mehrere Replikate, solange jede Instanz dasselbe Geheimnis behält. Die Rotation von SESSION_SECRET macht absichtlich alle vorhandenen Registrierungen und Verbindungen ungültig. Dieses Beispiel gibt keine Aktualisierungstokens aus, daher ist nach 30 Tagen eine erneute Verknüpfung erforderlich.

4. Testen und mit ChatGPT verbinden

Führen Sie aus:

npm run build
npm test
npx @modelcontextprotocol/inspector@latest

Wählen Sie im Inspector Streamable HTTP und verwenden Sie https://YOUR-CONNECTOR-HOST/mcp.

In ChatGPT aktivieren Sie den Entwicklermodus unter Einstellungen → Sicherheit und Anmeldung. Fügen Sie auf der Plugins-Seite eine Verbindung hinzu, wählen Sie die Option für den öffentlichen Endpunkt und geben Sie https://YOUR-CONNECTOR-HOST/mcp ein. Überprüfen Sie die fünf erkannten Tools und rufen Sie dann ein Lesetool auf, um die Kontoverknüpfung zu starten.

Empfohlene Prüfungen:

• „Liste meine Splitwise-Gruppen auf.“

• „Zeige Salden mit meinen Splitwise-Freunden.“

• „Zeige die letzten fünf Ausgaben in Gruppe 123.“

• „Rufe Ausgabe 456 ab.“

• „Erstelle eine Ausgabe von 24 USD in Gruppe 123, gleichmäßig aufgeteilt.“

Produktionshinweise

Der ausführbare Server speichert keinen OAuth-Sitzungsstatus. Vor einer größeren Mehrbenutzerbereitstellung:

• Halten Sie SESSION_SECRET stabil, geheim und identisch in allen Instanzen. Leiten Sie den Verschlüsselungsschlüssel für ein verwaltetes Schlüsselmanagement ab oder rufen Sie ihn ab; protokollieren Sie niemals Token oder Geheimnisse.

• Zustandslose Autorisierungscodes können nicht erneut verwendet werden. PKCE, exakte Bindung an Redirect-URI, Resource und Client, authentifizierte Verschlüsselung und die fünfminütige Lebensdauer begrenzen das Replay-Risiko. Falls strikte Einmalverwendung erforderlich ist, fügen Sie einen kurzlebigen gemeinsamen Replay-Cache mit einem Code-Identifier hinzu.

• Beschränken Sie die Redirect-URIs der dynamischen Registrierung auf die genauen ChatGPT-Rückruf-URLs, die auf der App-Verwaltungsseite angezeigt werden (plus explizit konfigurierte Entwicklungs-Callbacks).

• Fügen Sie Ratenbegrenzung, strukturierte Sicherheitsprotokolle, Geheimnisrotation, eine Datenschutzrichtlinie sowie Token-Widerruf/Kontoentkopplung hinzu.

• Bewahren Sie die resource-Bindung, die PKCE-Verifizierung, die kurze Code-Lebensdauer und das exakte Abgleich der Redirect-URIs auf.

• Führen Sie den Dienst hinter HTTPS aus. Setzen Sie diesen Entwicklungsserver nicht direkt dem Internet aus.

Das Tool create_expense ist als nicht idempotenter Schreibvorgang markiert. Die Anweisungen sagen dem Modell, dass es den genauen Betrag, die Währung, die Gruppe, den Zahler und die Anteile zusammenfassen soll, bevor es das Tool aufruft. Splitwise kann HTTP 200 mit einem errors-Objekt auf Anwendungsebene zurückgeben, daher prüft der Connector dieses Objekt, bevor er den Erfolg meldet.