benepass-mcp

Неофициальный только для чтения MCP-сервер для API Benepass employee-web.

Этот проект не связан с Benepass, не одобрен и не поддерживается 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 — HTTP-клиент Benepass только для GET

• src/http.ts — ky + список разрешённых хостов

• src/cognito.ts — Cognito OTP + обновление токена

• src/session.ts — локальный файл сессии

• src/schemas.ts — модели Zod для JSON Benepass

• src/errors.ts — типизированные ошибки

• test/ — Vitest (внутрипроцессный MCP-клиент + модульные тесты)

Related MCP server: appstoreconnect-codex-mcp

Модель безопасности

• Только для чтения. ky-клиент для api.benefitsapi.com выбрасывает ошибку, если метод не GET. Нет инструментов для пополнений, снятия средств, отправки/обновления/удаления расходов, карт/PIN-кодов, выплат или универсального call_api.

• Токены остаются на вашей машине. После OTP-входа refresh-токен Cognito сохраняется в ~/.config/benepass-mcp/session.json (XDG через env-paths), с правами 0600. Переопределить можно через BENEPASS_SESSION_PATH (с двумя P). Инструменты никогда не возвращают refresh- и access-токены. Токены никогда не логируются. Файлы сессий игнорируются git.

• Только исходящие хосты: cognito-idp.us-east-1.amazonaws.com, cognito.benefitsapi.com, api.benefitsapi.com.

• Идентификатор клиента приложения Cognito 6l7jeu4r44kgndgeab4aot355m — это публичный идентификатор клиента (не секрет); он встроен в приложение employee-web.

Процесс входа

1. Вызовите start_login, указав свою электронную почту Benepass. Cognito InitiateAuth CUSTOM_AUTH отправляет OTP.

2. Вызовите complete_login с адресом электронной почты, OTP и challenge_session. Cognito RespondToAuthChallenge CUSTOM_CHALLENGE выдаёт refresh-токен, который записывается в локальный файл сессии. Инструмент возвращает только { ok, email }.

3. Последующие API-вызовы отправляют POST grant_type=refresh_token на URL токена и передают access-токен как 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/. Если каждый кандидат возвращает 404, инструмент завершается ошибкой и включает в неё payload этого get_hsa_account_details. Эти инвестиционные GET-пути получены реверс-инжинирингом и могут существовать не для каждого счёта.

Лицензия

MIT

Stdio

Этот сервер общается по MCP через stdout и пишет логи в stderr. Используйте скрипт start после build или скрипт dev во время разработки.

Cursor

Добавьте запись benepass в настройки MCP (mcp.json), которая запускает скомпилированную точку входа этого пакета. Выполните аутентификацию с помощью start_login, затем complete_login.

Пример конфигурации Cursor находится в cursor-mcp.example.json.