open-splitwise

Splitwise를 에이전트 네이티브 비용 추적기로 바꾸세요.

오픈 Model Context Protocol(MCP) 서버로, Hermes, Claude Desktop, Claude Code, Cursor 또는 MCP를 말하는 모든 AI 에이전트가 잔액을 읽고, 지저분한 자연어에서 비용을 분할하고, 자체 인증 문제를 진단하고, 속도 제한을 신경 쓸 필요가 없게 해줍니다.

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

왜 필요한가

기존 Splitwise 통합은 모델에게 원시 API 미러를 넘겨주고 잘되길 바랄 뿐입니다. 그 방식은 예측 가능한 방식으로 실패합니다: 모델이 카테고리 ID를 지어내고, ₹300을 3명에게 잘못 분할하고, Splitwise의 200 OK가 실제로는 실패한 요청임에도 믿어버리거나, 속도 제한 응답을 공격적으로 재시도해야 할 버그로 취급합니다.

open-splitwise는 서버 계층에서 이 문제를 해결합니다:

기능

• 완전한 API 커버리지 — 공식 Splitwise OpenAPI 3.0 스펙의 27개 엔드포인트 전체, 각각 하나의 도구, 충실한 이름.

• 워크플로 계층 — 단일 발화가 단일 호출로 이어지도록 하는 고수준 도구.

• 셀프 서비스 인증 수명주기 — 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

https://secure.splitwise.com/apps에서 API 키를 받으세요 (계정 설정 → 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. 위의 워크플로/인증 도구 4개로 시작하고, 필요할 때만 원시 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 ≠ 성공: 모든 변경에서 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

이용 약관

Splitwise의 셀프 서비스 API는 API 약관에 따라 비상업적입니다. API 키는 계정에 대한 전체 액세스 권한을 부여합니다 — 비밀번호처럼 취급하세요. 이 프로젝트는 독립적인 통합이며 Splitwise Inc.와 제휴하거나 보증하지 않습니다.

로드맵

• 비용 생성 시 영수증 업로드

• 환율 인식 다중 통화 비용 도우미

• MCP 프롬프트로서의 반복 비용 요약

• 호스팅/다중 사용자 배포를 위한 선택적 Streamable HTTP 전송(+OAuth2)

• PyPI에 게시(uvx open-splitwise)

기여

PR 환영합니다 — TDD 규율(테스트가 먼저 실패한 후 통과)을 유지하고, 도구 설명을 모델을 위해 작성하며, 비밀을 로그에 남기지 마세요.

라이선스

MIT — 모두에게 열려 있음: 사용하고, 수정하고, 배포하고, 판매하세요. 저작권 표시만 유지하면 됩니다.