Splitwise connector for ChatGPT

Splitwise の公式 API に ChatGPT を接続するデータ専用の MCP サーバーです。以下に対応しています:

• list_groups

• list_friends(残高を含む)

• list_expenses

• get_expense

• create_expense(グループ均等割り、または明示的なシェア指定)

このサーバーは /mcp で Streamable HTTP を使用します。また、小さな OAuth 2.1 認可ブリッジとしても機能します。ChatGPT はこのサーバーとの間で PKCE を完了し、一方このサーバーが Splitwise の OAuth を完了して、Splitwise のトークンを ChatGPT から隔離します。

前提条件

• Node.js 20 以降

• デプロイ用の安定した公開 HTTPS URL(テスト中は開発用トンネルでも可)

• Splitwise アカウントと Splitwise OAuth アプリケーション

1. Splitwise アプリケーションの登録

1. https://secure.splitwise.com/apps を開き、OAuth アプリケーションを作成します。

2. コールバック URL を https://YOUR-CONNECTOR-HOST/oauth/splitwise/callback に設定します。

3. クライアント ID とクライアントシークレットをコピーします。これらをコミットしないでください。

Splitwise はコネクタにリダイレクトする必要があり、ChatGPT に直接リダイレクトしてはいけません。コネクタはその後、ChatGPT の別の PKCE フローを再開します。

2. 設定と実行

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

必須変数:

任意変数: PORT、SPLITWISE_AUTHORIZE_URL、SPLITWISE_TOKEN_URL、SPLITWISE_API_BASE_URL。

openssl rand -hex 32 でセッションシークレットを生成します。コンテナの場合:

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

3. OAuth フロー

1. ChatGPT は MCP サーバーから /.well-known/oauth-protected-resource を検出します。

2. /.well-known/oauth-authorization-server でこのコネクタの OAuth メタデータを検出し、/register で公開クライアントを動的登録します。

3. ChatGPT は /authorize で authorization-code + PKCE を開始し、MCP の resource 値を含めます。

4. コネクタはユーザーを Splitwise にリダイレクトし、/oauth/splitwise/callback で結果を受け取ります。

5. コネクタは Splitwise のコードをサーバー側で交換し、5 分間有効な暗号化コネクタコードを作成して、ChatGPT にリダイレクトします。

6. ChatGPT はそのコードを PKCE ベリファイアを使って /token で交換します。コネクタは、最小限のセッションコンテキストを含む認証済みの暗号化アクセストークンを返します。

7. すべての /mcp リクエストは、Splitwise を呼び出す前に、トークン、有効期限、スコープコンテキスト、リソースを復号して検証します。

動的クライアント登録、コネクタコード、30 日間のアクセストークンは、SESSION_SECRET から導出されるステートレスな AES-256-GCM エンベロープです。すべてのインスタンスが同じシークレットを保持している限り、スリープ、再起動、再デプロイ、複数レプリカをまたいで存続します。SESSION_SECRET をローテーションすると、既存のすべての登録と接続が意図的に無効化されます。このサンプルはリフレッシュトークンを発行しないため、30 日後には再リンクが必要です。

4. テストと ChatGPT への接続

実行:

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

Inspector で Streamable HTTP を選択し、https://YOUR-CONNECTOR-HOST/mcp を使用します。

ChatGPT で、Settings → Security and login の下で Developer mode を有効にします。Plugins ページで、接続を追加し、公開エンドポイントオプションを選択して、https://YOUR-CONNECTOR-HOST/mcp を入力します。検出された 5 つのツールを確認し、読み取りツールを呼び出してアカウントリンクを開始します。

推奨チェック:

• 「Splitwise のグループを一覧表示して。」

• 「Splitwise の友達との残高を表示して。」

• 「グループ 123 の最新の 5 件の支出を一覧表示して。」

• 「支出 456 の詳細を取得して。」

• 「グループ 123 に $24 USD の夕食費を作成し、均等に分割して。」

本番運用に関する注意

実行可能なサーバーは OAuth セッション状態を保存しません。より大規模な複数ユーザーデプロイの前に:

• SESSION_SECRET を安定した、秘密の、レプリカ間で同一のものに保ちます。より強力なキー管理のため、暗号化キーを管理された KMS から導出または取得します。トークンやシークレットをログに記録しないでください。

• ステートレスな認可コードは、ストレージなしでは消費済みとしてマークできません。PKCE、正確なクライアント/リダイレクト/リソースのバインド、認証付き暗号化、5 分間の有効期限により、リプレイの露出を制限します。厳密な単回使用の強制が必要な場合は、コード ID をキーとする短命の共有リプレイキャッシュを追加します。

• 動的登録のリダイレクト URI を、アプリ管理ページに表示される正確な ChatGPT コールバック URL(明示的に設定された開発用コールバックに加えて)に制限します。

• レート制限、構造化されたセキュリティログ、シークレットのローテーション、プライバシーポリシー、トークン失効/アカウントのリンク解除を追加します。

• resource のバインド、PKCE 検証、短いコードの有効期限、正確なリダイレクト URI の一致を維持します。

• HTTPS の背後で実行します。この開発サーバーをインターネットに直接公開しないでください。

create_expense ツールは非冪等な書き込みとしてマークされています。その指示は、モデルに、呼び出し前に正確な金額、通貨、グループ、支払者、シェアを要約するように指示します。Splitwise は HTTP 200 とアプリケーションレベルの errors オブジェクトを返す可能性があるため、コネクタは成功を報告する前にそのオブジェクトをチェックします。