ChatGPT용 Splitwise 커넥터

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는 MCP resource 값을 포함하여 /authorize에서 authorization-code + PKCE를 시작합니다.

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에서 설정 → 보안 및 로그인 아래의 개발자 모드를 활성화합니다. 플러그인 페이지에서 연결을 추가하고 공개 엔드포인트 옵션을 선택한 다음 https://YOUR-CONNECTOR-HOST/mcp를 입력합니다. 발견된 5개 도구를 검토한 후 읽기 도구를 호출하여 계정 연결을 시작합니다.

제안된 확인 사항:

• "내 Splitwise 그룹을 나열해 주세요."

• "내 Splitwise 친구들과의 잔액을 보여 주세요."

• "그룹 123의 최근 5개 지출을 나열해 주세요."

• "지출 456의 전체 세부 정보를 가져와 주세요."

• "그룹 123에 $24 USD 저녁 식사 지출을 균등 분할로 생성해 주세요."

프로덕션 참고 사항

실행 가능한 서버는 OAuth 세션 상태를 저장하지 않습니다. 더 큰 다중 사용자 배포 전에:

• SESSION_SECRET을 안정적이고 비밀로 유지하고 모든 복제본에서 동일하게 유지합니다. 더 강력한 키 관리를 위해 관리형 KMS에서 암호화 키를 파생하거나 검색합니다. 토큰이나 시크릿을 절대 로그에 남기지 마세요.

• 무상태 인증 코드는 저장소 없이 사용됨으로 표시할 수 없습니다. PKCE, 정확한 클라이언트/리디렉션/리소스 바인딩, 인증된 암호화 및 5분 수명 제한이 재생 노출을 제한합니다. 엄격한 일회용 사용을 적용해야 하는 경우 코드 식별자로 키가 지정된 단기 공유 재생 캐시를 추가합니다.

• 동적 등록 리디렉션 URI를 앱 관리 페이지에 표시된 정확한 ChatGPT 콜백 URL(명시적으로 구성된 개발 콜백 포함)로 제한합니다.

• 속도 제한, 구조화된 보안 로그, 시크릿 회전, 개인정보 처리방침 및 토큰 폐기/계정 연결 해제를 추가합니다.

• resource 바인딩, PKCE 검증, 짧은 코드 수명 및 정확한 리디렉션 URI 일치를 유지합니다.

• HTTPS 뒤에서 실행합니다. 이 개발 서버를 인터넷에 직접 노출하지 마세요.

create_expense 도구는 비멱등 쓰기로 표시됩니다. 해당 지침은 모델에게 호출 전에 정확한 금액, 통화, 그룹, 지불자 및 지분을 요약하도록 지시합니다. Splitwise는 애플리케이션 수준 errors 객체와 함께 HTTP 200을 반환할 수 있으므로 커넥터는 성공을 보고하기 전에 해당 객체를 확인합니다.