Коннектор Splitwise для ChatGPT

Сервер MCP только для данных, который подключает ChatGPT к официальному API Splitwise. Поддерживает:

• list_groups

• list_friends (включая балансы)

• list_expenses

• get_expense

• create_expense (равное разделение по группе или явные доли)

Сервер использует Streamable HTTP по адресу /mcp. Он также выступает в роли небольшого моста авторизации OAuth 2.1: ChatGPT выполняет PKCE с этим сервером, а этот сервер выполняет OAuth Splitwise и не допускает токен Splitwise до ChatGPT.

Предварительные требования

• Node.js 20 или новее

• Стабильный публичный HTTPS-адрес для развертывания (или туннель для разработки во время тестирования)

• Учетная запись Splitwise и OAuth-приложение Splitwise

1. Регистрация приложения Splitwise

1. Откройте https://secure.splitwise.com/apps и создайте OAuth-приложение.

2. Укажите его URL обратного вызова как https://YOUR-CONNECTOR-HOST/oauth/splitwise/callback.

3. Скопируйте идентификатор клиента и секрет клиента. Никогда не сохраняйте их в репозитории.

Splitwise должен перенаправлять на коннектор, а не напрямую в ChatGPT. Коннектор возобновляет отдельный поток PKCE ChatGPT после этого.

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 обнаруживает /.well-known/oauth-protected-resource на MCP-сервере.

2. Он обнаруживает метаданные OAuth этого коннектора по адресу /.well-known/oauth-authorization-server и динамически регистрирует публичного клиента по адресу /register.

3. ChatGPT запускает authorization-code + PKCE по адресу /authorize, включая значение resource MCP.

4. Коннектор перенаправляет пользователя в Splitwise и получает результат по адресу /oauth/splitwise/callback.

5. Коннектор обменивает код Splitwise на стороне сервера, создает пятиминутный зашифрованный код коннектора и перенаправляет в ChatGPT.

6. ChatGPT обменивает этот код по адресу /token, используя свой PKCE-верификатор. Коннектор возвращает аутентифицированный зашифрованный токен доступа, содержащий минимальный контекст сессии.

7. Каждый запрос /mcp расшифровывает и проверяет токен, срок действия, контекст области действия и ресурс перед вызовом Splitwise.

Динамические регистрации клиентов, коды коннектора и 30-дневные токены доступа — это конверты AES-256-GCM без сохранения состояния, производные от SESSION_SECRET. Они переживают сон, перезапуски, повторные развертывания и несколько реплик, если каждый экземпляр сохраняет один и тот же секрет. Ротация 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. На странице Plugins добавьте подключение, выберите вариант публичной конечной точки и введите https://YOUR-CONNECTOR-HOST/mcp. Просмотрите пять обнаруженных инструментов, затем вызовите инструмент чтения, чтобы начать связывание учетной записи.

Предлагаемые проверки:

• «Список моих групп Splitwise».

• «Показать балансы с моими друзьями Splitwise».

• «Список последних пяти расходов в группе 123».

• «Получить полные сведения о расходе 456».

• «Создать расход на ужин в размере 24 долларов США в группе 123, разделив поровну».

Заметки о продакшене

Исполняемый сервер не хранит состояние сессии OAuth. Перед более крупным многопользовательским развертыванием:

• Держите SESSION_SECRET стабильным, секретным и одинаковым во всех репликах. Для более надежного управления ключами извлекайте или получайте ключ шифрования из управляемого KMS; никогда не логируйте токены или секреты.

• Коды авторизации без состояния не могут быть помечены как использованные без хранилища. PKCE, точная привязка клиента/перенаправления/ресурса, аутентифицированное шифрование и пятиминутный срок действия ограничивают риск повторного воспроизведения. Если требуется строгое однократное использование, добавьте кратковременный общий кэш повторного воспроизведения, ключом которого является идентификатор кода.

• Ограничьте URI перенаправления динамической регистрации точными URL обратного вызова ChatGPT, показанными на странице управления приложением (плюс явно настроенные обратные вызовы для разработки).

• Добавьте ограничение скорости, структурированные журналы безопасности, ротацию секретов, политику конфиденциальности и отзыв токенов/отвязку учетной записи.

• Сохраняйте привязку resource, проверку PKCE, короткий срок действия кода и точное соответствие URI перенаправления.

• Работайте за HTTPS. Не открывайте этот сервер разработки напрямую в интернет.

Инструмент create_expense помечен как неидемпотентная запись. Его инструкции предписывают модели резюмировать точную сумму, валюту, группу, плательщика и доли перед вызовом. Splitwise может вернуть HTTP 200 с объектом errors на уровне приложения, поэтому коннектор проверяет этот объект перед сообщением об успехе.