benepass-mcp

Servidor MCP de solo lectura y no oficial para la API de empleados web de Benepass.

Este proyecto no está afiliado, respaldado ni soportado por Benepass. Se basa en ingeniería inversa del cliente público de empleados web. No contactes con el soporte de Benepass sobre este servidor, problemas de inicio de sesión, endpoints faltantes o cualquier otra cosa relacionada con esta herramienta no oficial.

El nombre del paquete en el registro público ya está ocupado. Este repositorio establece private: true y no se publica allí.

Estructura

• src/index.ts — entrada stdio (serveStdio)

• src/server.ts — fábrica McpServer

• src/tools.ts — adaptadores MCP ligeros (TOOL_NAMES)

• src/app.ts — raíz de composición

• src/accounts.ts — derivación de beneficios, selección de cuenta HSA

• src/hsa.ts — recorrido de ruta GET de inversiones

• src/api.ts — cliente HTTP de Benepass solo GET

• src/http.ts — ky + lista de hosts permitidos

• src/cognito.ts — OTP de Cognito + renovación de token

• src/session.ts — archivo de sesión local

• src/schemas.ts — modelos Zod para JSON de Benepass

• src/errors.ts — errores tipados

• test/ — Vitest (cliente MCP en proceso + pruebas unitarias)

Related MCP server: appstoreconnect-codex-mcp

Modelo de seguridad

• Solo lectura. El cliente ky para api.benefitsapi.com lanza una excepción si el método no es GET. No hay herramientas para depósitos, retiros, envío/actualización/eliminación de gastos, tarjetas/PIN, pagos o call_api genérico.

• Los tokens permanecen en tu máquina. Después del inicio de sesión con OTP, el token de renovación de Cognito se almacena en ~/.config/benepass-mcp/session.json (XDG mediante env-paths), con modo 0600. Se puede sobrescribir con BENEPASS_SESSION_PATH (con dos P). Las herramientas nunca devuelven tokens de acceso o renovación. Los tokens nunca se registran. Los archivos de sesión están en gitignore.

• Solo hosts de salida: cognito-idp.us-east-1.amazonaws.com, cognito.benefitsapi.com, api.benefitsapi.com.

• El ID de cliente de la aplicación Cognito 6l7jeu4r44kgndgeab4aot355m es un ID de cliente público (no un secreto); está integrado en la aplicación de empleados web.

Flujo de inicio de sesión

1. Llama a start_login con tu correo electrónico de Benepass. Cognito InitiateAuth CUSTOM_AUTH envía un OTP.

2. Llama a complete_login con el correo electrónico, el OTP y challenge_session. Cognito RespondToAuthChallenge CUSTOM_CHALLENGE produce un token de renovación que se escribe en el archivo de sesión local. La herramienta devuelve solo { ok, email }.

3. Las llamadas API posteriores envían grant_type=refresh_token a la URL del token y envían el token de acceso como Authorization Bearer. Se respeta la caducidad (expires_in y exp del JWT).

4. Si se omite workspace_id, se hace GET a /v2/me/workspaces/ y se persiste el primer espacio de trabajo con type=employment.

Herramientas

Autenticación: start_login, complete_login, auth_status, logout.

Lecturas: list_workspaces, list_accounts, list_benefits (derivado de enrollment.benefit de las cuentas + saldo disponible), list_transactions, get_hsa_account_details, get_hsa_investments, list_documents, get_document, get_current_user.

list_benefits: Benepass no tiene /v2/me/benefits/. Los beneficios se derivan de enrollment.benefit de cada cuenta y de la clave de saldo que termina en /available.

get_hsa_investments: intenta solo GET, gana el primer 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/

Si se omite account_id, las cuentas HSA se seleccionan a partir de campos analizados con Zod (enrollment.benefit.benefit_type, enrollment.benefit.key, account.key, account.account_type, account.type) que coinciden con hsa / health_savings / health_savings_account. Los nombres de cuenta no se buscan. Si esos campos están ausentes, la herramienta recurre a un ID de cuenta en GET /v2/me/hsa-account-details/. Si todos los candidatos devuelven 404, la herramienta genera un error e incluye esa carga útil de get_hsa_account_details. Esas rutas GET de inversiones se obtuvieron mediante ingeniería inversa y pueden no existir para todas las cuentas.

Licencia

MIT

Stdio

Este servidor habla MCP en stdout y escribe registros en stderr. Usa el script start después de build, o el script dev durante el desarrollo.

Cursor

Añade una entrada benepass a la configuración de MCP (mcp.json) que lance la entrada compilada de este paquete. Autentícate con start_login y luego complete_login.

La configuración de ejemplo de Cursor está en cursor-mcp.example.json.