benepass-mcp

Benepass employee-web API용 비공식 읽기 전용 MCP 서버입니다.

이 프로젝트는 Benepass와 제휴, 보증, 지원 관계가 아닙니다. 공개 employee-web 클라이언트를 리버스 엔지니어링한 것입니다. 이 비공식 도구와 관련된 서버, 로그인 문제, 누락된 엔드포인트 또는 기타 사항에 대해 Benepass 지원팀에 문의하지 마세요.

공개 레지스트리의 패키지 이름은 이미 사용 중입니다. 이 저장소는 private: true로 설정되어 있으며 게시되지 않습니다.

구성

• src/index.ts — stdio 진입점 (serveStdio)

• src/server.ts — McpServer 팩토리

• src/tools.ts — 얇은 MCP 어댑터 (TOOL_NAMES)

• src/app.ts — 구성 루트

• src/accounts.ts — 혜택 파생, HSA 계정 선택

• src/hsa.ts — 투자 GET 경로 탐색

• src/api.ts — GET 전용 Benepass HTTP 클라이언트

• src/http.ts — ky + 호스트 허용 목록

• src/cognito.ts — Cognito OTP + 토큰 갱신

• src/session.ts — 로컬 세션 파일

• src/schemas.ts — Benepass JSON용 Zod 모델

• src/errors.ts — 타입화된 오류

• test/ — Vitest (프로세스 내 MCP 클라이언트 + 단위 테스트)

Related MCP server: appstoreconnect-codex-mcp

보안 모델

• 읽기 전용. api.benefitsapi.com용 ky 클라이언트는 메서드가 GET이 아니면 예외를 던집니다. 입금, 출금, 비용 제출/수정/삭제, 카드/PIN, 지급, 일반 call_api 도구는 없습니다.

• 토큰은 사용자 머신에 유지됩니다. OTP 로그인 후 Cognito 리프레시 토큰은 ~/.config/benepass-mcp/session.json (env-paths를 통한 XDG)에 모드 0600으로 저장됩니다. BENEPASS_SESSION_PATH (P 두 개)로 재정의할 수 있습니다. 도구는 리프레시 또는 액세스 토큰을 반환하지 않습니다. 토큰은 절대 로그에 기록되지 않습니다. 세션 파일은 gitignore됩니다.

• 아웃바운드 호스트만: cognito-idp.us-east-1.amazonaws.com, cognito.benefitsapi.com, api.benefitsapi.com.

• Cognito 앱 클라이언트 ID 6l7jeu4r44kgndgeab4aot355m는 공개 클라이언트 ID입니다(비밀이 아님). employee-web 앱에 내장되어 있습니다.

로그인 흐름

1. Benepass 이메일로 start_login을 호출합니다. Cognito InitiateAuth CUSTOM_AUTH가 OTP를 보냅니다.

2. 이메일, OTP, challenge_session으로 complete_login을 호출합니다. Cognito RespondToAuthChallenge CUSTOM_CHALLENGE는 로컬 세션 파일에 기록되는 리프레시 토큰을 생성합니다. 도구는 { ok, email }만 반환합니다.

3. 이후 API 호출은 토큰 URL에 grant_type=refresh_token을 POST하고 액세스 토큰을 Authorization Bearer로 보냅니다. 만료가 존중됩니다 (expires_in 및 JWT exp).

4. workspace_id가 생략되면 GET /v2/me/workspaces/를 호출하고 첫 번째 type=employment 워크스페이스를 유지합니다.

도구

인증: start_login, complete_login, auth_status, logout.

읽기: list_workspaces, list_accounts, list_benefits (계정 enrollment.benefit + 사용 가능 잔액에서 파생), list_transactions, get_hsa_account_details, get_hsa_investments, list_documents, get_document, get_current_user.

list_benefits: Benepass에는 /v2/me/benefits/가 없습니다. 혜택은 각 계정의 enrollment.benefit과 /available로 끝나는 잔액 키에서 파생됩니다.

get_hsa_investments: GET만 시도하며 첫 번째 2xx가 우선합니다:

• /v2/me/accounts/{id}/hsa-investments/

• /v2/me/accounts/{id}/hsa-investments/portfolio/

• /v2/me/accounts/{id}/hsa-investments/portfolio/allocation/

• /v2/me/accounts/{id}/hsa-investments/asset-links/

account_id가 생략되면 HSA 계정은 Zod로 파싱된 필드 (enrollment.benefit.benefit_type, enrollment.benefit.key, account.key, account.account_type, account.type)에서 hsa / health_savings / health_savings_account와 일치하는 것으로 선택됩니다. 계정 이름은 검색되지 않습니다. 해당 필드가 없으면 도구는 GET /v2/me/hsa-account-details/의 계정 ID로 대체합니다. 모든 후보가 404를 반환하면 도구는 오류를 내고 해당 get_hsa_account_details 페이로드를 포함합니다. 이러한 투자 GET 경로는 리버스 엔지니어링된 것이며 모든 계정에 존재하지 않을 수 있습니다.

라이선스

MIT

Stdio

이 서버는 stdout에서 MCP를 사용하고 stderr에 로그를 기록합니다. build 후 start 스크립트를 사용하거나 개발 중에는 dev 스크립트를 사용하세요.

Cursor

MCP 설정 (mcp.json)에 이 패키지의 컴파일된 진입점을 실행하는 benepass 항목을 추가하세요. start_login으로 인증한 다음 complete_login으로 인증하세요.

예제 Cursor 구성은 cursor-mcp.example.json에 있습니다.