benepass-mcp

Inoffizieller, schreibgeschützter MCP-Server für die Benepass-Employee-Web-API.

Dieses Projekt ist nicht mit Benepass verbunden, von Benepass unterstützt oder befürwortet. Es rekonstruiert den öffentlichen Employee-Web-Client. Kontaktieren Sie den Benepass-Support nicht bezüglich dieses Servers, Anmeldeproblemen, fehlenden Endpunkten oder irgendetwas anderem, das mit diesem inoffiziellen Tool zusammenhängt.

Der Paketname in der öffentlichen Registry ist bereits vergeben. Dieses Repository setzt private: true und ist dort nicht veröffentlicht.

Layout

• src/index.ts — stdio-Einstiegspunkt (serveStdio)

• src/server.ts — McpServer-Factory

• src/tools.ts — dünne MCP-Adapter (TOOL_NAMES)

• src/app.ts — Kompositionswurzel

• src/accounts.ts — Benefits-Ableitung, HSA-Kontoauswahl

• src/hsa.ts — Investment-GET-Pfad-Walk

• src/api.ts — GET-only Benepass-HTTP-Client

• src/http.ts — ky + Host-Allowlist

• src/cognito.ts — Cognito-OTP + Token-Aktualisierung

• src/session.ts — lokale Sitzungsdatei

• src/schemas.ts — Zod-Modelle für Benepass-JSON

• src/errors.ts — typisierte Fehler

• test/ — Vitest (In-Process-MCP-Client + Unit-Tests)

Related MCP server: appstoreconnect-codex-mcp

Sicherheitsmodell

• Schreibgeschützt. Der ky-Client für api.benefitsapi.com wirft einen Fehler, wenn die Methode nicht GET ist. Es gibt keine Tools für Einzahlungen, Abhebungen, Spesen-Einreichung/-Aktualisierung/-Löschung, Karten/PIN, Auszahlungen oder generisches call_api.

• Tokens bleiben auf Ihrem Rechner. Nach dem OTP-Login wird das Cognito-Refresh-Token unter ~/.config/benepass-mcp/session.json gespeichert (XDG über env-paths), Modus 0600. Überschreiben mit BENEPASS_SESSION_PATH (zwei P's). Tools geben niemals Refresh- oder Access-Tokens zurück. Tokens werden nie protokolliert. Sitzungsdateien sind gitignored.

• Nur ausgehende Hosts: cognito-idp.us-east-1.amazonaws.com, cognito.benefitsapi.com, api.benefitsapi.com.

• Die Cognito-App-Client-ID 6l7jeu4r44kgndgeab4aot355m ist eine öffentliche Client-ID (kein Geheimnis); sie ist in die Employee-Web-App eingebettet.

Anmeldeablauf

1. Rufen Sie start_login mit Ihrer Benepass-E-Mail auf. Cognito InitiateAuth CUSTOM_AUTH sendet ein OTP.

2. Rufen Sie complete_login mit E-Mail, OTP und challenge_session auf. Cognito RespondToAuthChallenge CUSTOM_CHALLENGE liefert ein Refresh-Token, das in die lokale Sitzungsdatei geschrieben wird. Das Tool gibt nur { ok, email } zurück.

3. Spätere API-Aufrufe senden POST grant_type=refresh_token an die Token-URL und senden das Access-Token als Authorization Bearer. Die Ablaufzeit wird berücksichtigt (expires_in und JWT exp).

4. Wenn workspace_id weggelassen wird, GET /v2/me/workspaces/ und den ersten type=employment-Workspace speichern.

Tools

Auth: start_login, complete_login, auth_status, logout.

Reads: list_workspaces, list_accounts, list_benefits (abgeleitet aus Konten enrollment.benefit + verfügbarer Saldo), list_transactions, get_hsa_account_details, get_hsa_investments, list_documents, get_document, get_current_user.

list_benefits: Benepass hat kein /v2/me/benefits/. Benefits werden aus jedem Konto enrollment.benefit und dem Saldoschlüssel, der auf /available endet, abgeleitet.

get_hsa_investments: versucht nur GET, der erste 2xx gewinnt:

• /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/

Wenn account_id weggelassen wird, werden HSA-Konten aus Zod-geparsten Feldern (enrollment.benefit.benefit_type, enrollment.benefit.key, account.key, account.account_type, account.type) ausgewählt, die mit hsa / health_savings / health_savings_account übereinstimmen. Kontonamen werden nicht durchsucht. Wenn diese Felder fehlen, fällt das Tool auf eine Konto-ID bei GET /v2/me/hsa-account-details/ zurück. Wenn jeder Kandidat 404 liefert, gibt das Tool einen Fehler aus und enthält diese get_hsa_account_details-Nutzlast. Diese Investment-GET-Pfade sind reverse-engineered und existieren möglicherweise nicht für jedes Konto.

Lizenz

MIT

Stdio

Dieser Server spricht MCP auf stdout und schreibt Logs auf stderr. Verwenden Sie das start-Skript nach build oder das dev-Skript während der Entwicklung.

Cursor

Fügen Sie einen benepass-Eintrag zu den MCP-Einstellungen (mcp.json) hinzu, der den kompilierten Einstieg dieses Pakets startet. Authentifizieren Sie sich mit start_login und dann complete_login.

Eine Beispiel-Cursor-Konfiguration finden Sie in cursor-mcp.example.json.