benepass-mcp

非官方、只读的 Benepass 员工 Web API MCP 服务器。

本项目与 Benepass 无关联、未经其认可，也不受其支持。它是对公开的员工 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（不是机密）；它已嵌入员工 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，并将访问令牌作为 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，则从 Zod 解析的字段（enrollment.benefit.benefit_type、enrollment.benefit.key、account.key、account.account_type、account.type）中选择 HSA 账户，匹配 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 中。