benepass-mcp

非公式の読み取り専用MCPサーバーで、Benepassのemployee-web APIを利用します。

このプロジェクトは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は2つ）で上書きできます。ツールが更新トークンやアクセストークンを返すことはありません。トークンがログに記録されることはありません。セッションファイルはgitignoreされています。

• 送信先ホストは次のみ： cognito-idp.us-east-1.amazonaws.com、cognito.benefitsapi.com、api.benefitsapi.com。

• CognitoアプリクライアントID 6l7jeu4r44kgndgeab4aot355mは公開クライアントIDです（秘密ではありません）。これはemployee-webアプリに組み込まれています。

ログインフロー

1. start_loginをBenepassのメールアドレスで呼び出します。Cognito InitiateAuth CUSTOM_AUTHがOTPを送信します。

2. complete_loginをメールアドレス、OTP、challenge_sessionで呼び出します。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

このサーバーはMCPをstdoutで話し、ログをstderrに書き込みます。build後にstartスクリプトを使用するか、開発中はdevスクリプトを使用してください。

Cursor

MCP設定（mcp.json）にbenepassエントリを追加し、このパッケージのコンパイル済みエントリを起動します。start_loginで認証し、次にcomplete_loginで認証します。

Cursor設定の例はcursor-mcp.example.jsonにあります。