open-splitwise

Превратите Splitwise в трекер расходов, ориентированный на агентов.

Открытый сервер Model Context Protocol (MCP), который позволяет любому ИИ-агенту — Hermes, Claude Desktop, Claude Code, Cursor или любому, кто говорит на MCP — читать балансы, разделять расходы из неструктурированного естественного языка, диагностировать свои собственные проблемы с аутентификацией и никогда не думать об ограничениях частоты запросов.

Python 3.11+ · MCP spec 2026-07-28 · stdio transport · 33 tools · lazy-loaded

Зачем

Существующие интеграции Splitwise передают модели сырое зеркало API и надеются на лучшее. Это предсказуемо проваливается: модель выдумывает ID категорий, неправильно делит ₹300 на троих, верит в 200 OK от Splitwise, когда запрос на самом деле не удался, или воспринимает ответ об ограничении частоты как ошибку, которую нужно агрессивно повторять.

open-splitwise исправляет это на уровне сервера:

Возможности

• Полное покрытие API — все 27 конечных точек официальной спецификации Splitwise OpenAPI 3.0, по одному инструменту на каждую, точные имена.

• Слой рабочих процессов — высокоуровневые инструменты, чтобы одно высказывание соответствовало одному вызову.

• Самостоятельный жизненный цикл аутентификации — setup_auth проверяет ключ в реальном времени против Splitwise перед сохранением (неверные ключи никогда не сохраняются), get_auth_status объясняет, что настроено, logout очищает учетные данные. Повторная аутентификация работает в середине сессии.

• Честные ошибки — каждый режим сбоя (нераспознанный человек, несоответствие суммы долей, неизвестная категория, отозванный ключ, исчерпанные повторные попытки) возвращает текст, сообщающий агенту точно, что произошло и что делать дальше.

• Безопасные по умолчанию аннотации — чтения несут readOnlyHint, разрушительные удаления несут destructiveHint, согласно семантике MCP 2026-07-28. Инструменты регистрируются в детерминированном порядке для удобного кэширования обнаружения.

• Локальные секреты — ключ API хранится в ~/.config/splitwise-mcp/credentials.json, режим 0600, атомарные записи, никогда не отображается (только маскированные предпросмотры).

Быстрый старт

git clone https://github.com/<you>/open-splitwise.git
cd open-splitwise
uv sync

Запустите автономно (stdio):

uv run open-splitwise          # starts with no key configured — see auth below

Получите ключ API на https://secure.splitwise.com/apps (Настройки аккаунта → Ключи API).

Подключение любого MCP-клиента

Универсальный блок stdio (Claude Desktop claude_desktop_config.json, Claude Code .mcp.json, Cursor, …):

{
  "mcpServers": {
    "splitwise": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"],
      "env": { "SPLITWISE_API_KEY": "<optional: preconfigure>" }
    }
  }
}

Подключение Hermes Agent

Добавьте в ~/.hermes/config.yaml:

mcp_servers:
  splitwise:
    command: "uv"
    args: ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"]
    env:
      SPLITWISE_API_KEY: "<optional>"
    tools:
      include: [quick_add_expense, resolve_users, money_summary, get_auth_status]
    prompts: false
    resources: false

Затем /reload-mcp. Начните с четырех инструментов рабочего процесса/аутентификации выше; добавляйте сырые инструменты API только при необходимости — фильтрация по серверам в Hermes сохраняет поверхность инструментов небольшой.

Жизненный цикл аутентификации

Сервер спроектирован так, что агенты сами диагностируют и исправляют аутентификацию, запрашивая у вас только секрет:

Разрешение ключа происходит для каждого запроса: сохраненные учетные данные → переменная окружения SPLITWISE_API_KEY → ничего. Свежесохраненный ключ вступает в силу немедленно в работающем процессе — ноль перезапусков.

Учетные данные хранятся в ~/.config/splitwise-mcp/credentials.json (режим 0600). Переопределите каталог с помощью SPLITWISE_MCP_CONFIG_DIR (удобно для тестов или многопрофильных конфигураций).

Эргономика для агентов

You:      "add dinner 900 split with alice and bob@x.com, groceries"
Agent:    quick_add_expense(description="Dinner", cost="900.00",
                            participants=["alice", "bob@x.com"],
                            category_name="groceries")
Server:   resolves alice→12? two matches! → error listing Alice A (id 10), Alice Wood (id 12)
Agent:    "Which Alice?"  → you answer → re-call succeeds
Server:   { status: created, expense_id: 99123,
            splits: [ "Nikhil paid 900.00 INR",
                      "Alice A owes 300.00 INR",
                      "Bob B owes 300.00 INR" ] }

• quick_add_expense — принимаются имена/частичные имена/электронные письма/ID; равные доли вычисляются с остаточными центами, распределяемыми детерминированно; пользовательские owed_shares проверяются на точную сумму; плательщик включен по умолчанию (include_payer_in_split=false, если он не участвовал); валюта по умолчанию из вашего профиля.

• resolve_users — точное совпадение по электронной почте, совпадение по полному имени, уникальное имя, запасной вариант по подстроке; неоднозначность возвращает кандидатов вместо угадывания.

• money_summary — по валютам owed_to_you / you_owe / net, балансы на уровне друзей и упрощенные долги групп, в которых вы участвуете.

Справочник инструментов (33)

* аннотированы destructiveHint=true; все инструменты get_* аннотированы readOnlyHint=true. Предпочитайте инструменты рабочих процессов их сырым аналогам, когда существуют оба.

Ограничение частоты запросов

Splitwise отвечает HTTP 429 при ограничении. open-splitwise автоматически повторяет попытки: заголовок Retry-After учитывается дословно; в противном случае экспоненциальная задержка (удвоение от 0,5 с, максимум 30 с), до 3 попыток по умолчанию. Агенты видят ошибку только если все попытки исчерпаны — и эта ошибка говорит замедлиться, а не повторять вслепую.

Конфигурация

Особенности Splitwise, обработанные за вас

• Параметры массивов преобразуются в странную кодировку Splitwise users__{index}__{property}

• 200 OK ≠ success: errors{} / success:false проверяются при каждой мутации

• Деньги как десятичные строки с 2 знаками; остаточные центы распределяются, суммы всегда точны

• category_id должен быть подкатегорией — обеспечивается нечетким разрешением имен

• Балансы/долги читаются из предварительно вычисленных balance[] / simplified_debts (никогда не пересчитываются)

• «Расчет» — это просто расход с payment:true (отдельной конечной точки не существует)

• OAuth2 существует, но намеренно вне области действия: личные ключи API подходят для сценария «агент спрашивает пользователя»; OAuth требует URI перенаправления + браузер (только для размещенных развертываний)

Архитектура

┌─────────────── any MCP client ───────────────┐
│  Hermes / Claude Desktop / Cursor / …        │
└──────────────────┬───────────────────────────┘
                   │ JSON-RPC over stdio
┌──────────────────▼───────────────────────────┐
│ server.py — FastMCP app, 33 tools            │
│   workflows · raw endpoints · auth lifecycle │
├──────────────────────────────────────────────┤
│ client.py — async REST client                │
│   bearer auth (per-request key resolution)   │
│   param flattening · success verification    │
│   transparent 429 retry/backoff              │
├──────────────────────────────────────────────┤
│ auth.py — credentials.json (0600, atomic)    │
└──────────────────┬───────────────────────────┘
                   │ HTTPS
          secure.splitwise.com/api/v3.0

Разработка

uv run pytest                        # 54 tests: client, rate limits, auth, workflows, lazy loading, MCP semantics
uv run python scripts/smoke_stdio.py # real subprocess: handshake, discovery, live auth-failure paths

Создано по принципу «сначала тесты» (строгий TDD): каждое поведение выше имеет происхождение «сначала падающий тест». Структура:

src/open_splitwise/
  client.py    # REST client: auth provider, flattening, retry, error mapping
  auth.py      # credential storage
  server.py    # FastMCP definitions: workflows + raw + auth tools
tests/
scripts/smoke_stdio.py

Условия использования

Самообслуживаемый API Splitwise является некоммерческим согласно их условиям API. Ваш ключ API предоставляет полный доступ к вашему аккаунту — относитесь к нему как к паролю. Этот проект является независимой интеграцией и не связан с Splitwise Inc. и не одобрен ею.

Дорожная карта

• Загрузка чеков при создании расхода

• Помощник по расходам в нескольких валютах с учетом конвертации

• Сводки повторяющихся расходов в виде MCP-подсказки

• Опциональный потоковый HTTP-транспорт для размещенных/многопользовательских развертываний (+OAuth2)

• Публикация на PyPI (uvx open-splitwise)

Вклад

Приветствуются PR — пожалуйста, соблюдайте дисциплину TDD (сначала тесты падают, затем проходят), пишите описания инструментов для моделей и никогда не логируйте секреты.

Лицензия

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