alphaportal-mcp

Ein MCP-Server für AlphaPortal (AlphaRoute), das Eltern-/Erziehungsberechtigten-Portal für den Schulbus-Transport, das von Bezirken wie Charlotte-Mecklenburg Schools verwendet wird (cmsnc.alphaportal.app). Fragen Sie Claude, wo der Bus Ihres Kindes ist, welche Haltestellen es hat und welche Ankunftsbenachrichtigungen eingegangen sind – und passen Sie (bestätigungsabhängig) Benachrichtigungseinstellungen und Gehzonen-Radius an.

Entwickelt und gepflegt von KI. Nutzung auf eigene Verantwortung.

Was es kann

Lesezugriffe (alle live gegen die echte API verifiziert):

• alphaportal_list_students — Ihre Kinder mit Klassenstufe, Schule und Transport-Flags

• alphaportal_get_student — die Schule eines Kindes sowie Morgen-/Nachmittagshaltestellen

• alphaportal_get_student_stops — zugewiesene Haltestellen mit Zeiten und Orten

• alphaportal_get_bus_location — Live-GPS des Busses für die Morgen- oder Nachmittagsfahrt

• alphaportal_list_notifications — Ankunfts-/Abfahrtsbenachrichtigungen

• alphaportal_list_requests — eingereichte Transportanfragen + Tracking-Nummern

• alphaportal_get_report_link — einen Download-Link für einen PDF-Bericht

• alphaportal_list_schools, alphaportal_list_grades — Bezirks-Referenzdaten

• alphaportal_get_profile, alphaportal_get_account, alphaportal_get_settings

• alphaportal_session_status — ist eine funktionierende Sitzung konfiguriert (keine Geheimnisse werden zurückgegeben)

Schreibzugriffe (bestätigungsabhängig — ein Probelauf der exakten Nutzlast, sofern nicht confirm: true):

• alphaportal_edit_walk_radius — den Gehzonen-Radius eines Schülers festlegen (in Metern)

• alphaportal_set_notification — Push-/E-Mail-Benachrichtigungseinstellungen pro Schüler festlegen

Related MCP server: io.github.thehesiod/psquare

Authentifizierung — das Refresh-Token

Die Anmeldung bei AlphaPortal ist durch reCAPTCHA geschützt und kann nicht mit Benutzername/Passwort automatisiert werden. Stattdessen verwendet dieser Server das Refresh-Token, das die Web-App in Ihrem angemeldeten Browser speichert (ein 8-Tage-Zugangsnachweis); daraus erzeugt er die kurzlebigen Zugriffstoken, die er benötigt, vollständig serverseitig — keine Browser-Brücke im Anfrage-Hot-Path. Es gibt zwei Wege, wie er an dieses Token gelangt, die in dieser Reihenfolge versucht werden:

1. Automatisch (fetchproxy-Bootstrap). Wenn ALPHAPORTAL_REFRESH_TOKEN nicht gesetzt ist, liest der Server es einmal aus Ihrem angemeldeten AlphaPortal-Tab über die Browsererweiterung Transporter (die fetchproxy-Brücke) — ein einmaliges Lesen, das nur das Token erfasst (eine JSON-Pointer-Extraktion, sodass Ihr Name/Ihre E-Mail/Ihre Telefonnummer den Browser nie verlassen), und schließt dann. Erfordert die installierte Erweiterung und einen angemeldeten *.alphaportal.app-Tab. Setzen Sie ALPHAPORTAL_DISABLE_FETCHPROXY=1, um dies zu deaktivieren.

2. Manuell (Umgebungsvariable). Setzen Sie ALPHAPORTAL_REFRESH_TOKEN selbst. Erfassen Sie es in der DevTools-Konsole eines angemeldeten Tabs:

   JSON.parse(localStorage.user).User.RefreshToken

   Dies ist der richtige Weg für eine headless/gehostete Bereitstellung ohne Browser.

In beiden Fällen speichert der Server jedes rotierte Refresh-Token, sodass das 8-Tage-Fenster nach vorne verschoben wird, solange Sie es mindestens einmal alle 8 Tage verwenden. Wenn es abläuft, melden Sie sich erneut an (Weg 1) oder erfassen Sie es neu (Weg 2). Der Skill alphaportal-fpx unter skills/ dokumentiert die gleiche Erfassung aus einer Shell über die CLI fpx.

Einrichtung

npm install
npm run build
echo 'ALPHAPORTAL_REFRESH_TOKEN=<paste the token>' > .env
node dist/index.js   # or wire it into your MCP host

.env wird von Git ignoriert. Für einen MCP-Host setzen Sie ALPHAPORTAL_REFRESH_TOKEN in dessen env-Block (.mcp.json / mcpb-Benutzerkonfiguration verweisen beide darauf).

Optionale Umgebungsvariablen

Hosting auf mcp-host

mint.yaml beschreibt, wie dieser Server gehostet wird. Beachten Sie die Egress-Allowlist: Der einzige Host, den der Server kontaktiert, ist api.alpharoute.app (jeder Lese-/Schreibzugriff und die Token-Aktualisierung). In der isolierten Stufe ist eine Egress-Richtlinie erforderlich — erlauben Sie api.alpharoute.app, andernfalls melden die Tools „die API konnte nicht erreicht werden“. Eine einfache gehostete Registrierung hat keine Browser-Brücke, also setzen Sie ALPHAPORTAL_REFRESH_TOKEN dort als Secret.

Entwicklung

npm test          # vitest (mocked network)
npm run typecheck # tsc --noEmit (a green vitest run is not a green typecheck)
npm run build     # tsc + esbuild bundle

API-Strukturen sind in docs/ALPHAPORTAL-API.md festgeschrieben.

Hinweise & Einschränkungen

• Der Einreichungsablauf für Transport-Anfragen (requests/transportation/add, .../alternative/add) ist bewusst noch nicht verfügbar — der verschachtelte Anfrage-Body wurde nicht vollständig erfasst, und das Ausliefern einer erratenen Schreib-Nutzlast, die eine echte Anfrage an den Bezirk übermittelt, wäre unverantwortlich. Siehe die Dokumentation.

• Jede Anfrage verwendet Ihre eigene AlphaPortal-Sitzung (das von Ihnen erfasste Refresh-Token); der Server liest ausschließlich die Daten Ihres Kontos.