alphaportal-mcp

Un servidor MCP para AlphaPortal (AlphaRoute), el portal de transporte escolar en autobús para padres/tutores utilizado por distritos como Charlotte-Mecklenburg Schools (cmsnc.alphaportal.app). Pregúntale a Claude dónde está el autobús de tu hijo, qué paradas tiene y qué notificaciones de llegada han llegado — y (con confirmación) ajusta las preferencias de notificación y el radio de la zona de caminata.

Desarrollado y mantenido por IA. Úsalo bajo tu propia responsabilidad.

Lo que puede hacer

Lecturas (todas verificadas en vivo contra la API real):

• alphaportal_list_students — tus hijos, con grado, escuela e indicadores de transporte

• alphaportal_get_student — la escuela de un hijo más las paradas de mañana/tarde

• alphaportal_get_student_stops — paradas asignadas con horas y ubicaciones

• alphaportal_get_bus_location — GPS en vivo del autobús para la ruta de la mañana o de la tarde

• alphaportal_list_notifications — alertas de llegada/salida

• alphaportal_list_requests — solicitudes de transporte presentadas + números de seguimiento

• alphaportal_get_report_link — un enlace de descarga de informe PDF

• alphaportal_list_schools, alphaportal_list_grades — datos de referencia del distrito

• alphaportal_get_profile, alphaportal_get_account, alphaportal_get_settings

• alphaportal_session_status — indica si hay una sesión de trabajo configurada (no devuelve secretos)

Escrituras (requieren confirmación — se hace una prueba en seco de la carga exacta salvo que confirm: true):

• alphaportal_edit_walk_radius — define el radio de la zona de caminata de un estudiante (metros)

• alphaportal_set_notification — define las preferencias de notificación push/correo por estudiante

Related MCP server: io.github.thehesiod/psquare

Autenticación — el token de actualización

El inicio de sesión de AlphaPortal está protegido por reCAPTCHA y no se puede automatizar con un nombre de usuario/contraseña. En su lugar, este servidor utiliza el token de actualización que la aplicación web guarda en tu navegador con la sesión iniciada (una credencial de 8 días); a partir de él genera los tokens de acceso de corta duración que necesita, todo ello en el servidor — sin puente de navegador en la ruta crítica de las solicitudes. Hay dos formas de obtener ese token, que se prueban en orden:

1. Automática (arranque fetchproxy). Si ALPHAPORTAL_REFRESH_TOKEN no está definida, el servidor lo lee una vez desde tu pestaña de AlphaPortal con sesión iniciada mediante la extensión de navegador Transporter (el puente fetchproxy) — una lectura única que captura solo el token (una extracción por puntero JSON, por lo que tu nombre/correo/teléfono nunca salen del navegador) y luego se cierra. Requiere la extensión instalada y una pestaña de *.alphaportal.app con sesión iniciada. Establece ALPHAPORTAL_DISABLE_FETCHPROXY=1 para desactivarlo.

2. Manual (variable de entorno). Define ALPHAPORTAL_REFRESH_TOKEN tú mismo. Captúralo en la consola de DevTools de una pestaña con sesión iniciada:

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

Esta es la vía correcta para un despliegue headless/alojado sin navegador.

En cualquier caso, el servidor conserva cada token de actualización rotado, de modo que la ventana de 8 días se renueva mientras lo uses al menos una vez cada 8 días. Si caduca, vuelve a iniciar sesión (opción 1) o vuelve a capturarlo (opción 2). La skill alphaportal-fpx en skills/ documenta la misma captura desde una shell mediante la CLI fpx.

Configuración

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 está en gitignore. Para un host MCP, establece ALPHAPORTAL_REFRESH_TOKEN en su bloque de entorno (.mcp.json y la configuración de usuario de mcpb hacen referencia a él).

Variables de entorno opcionales

Alojamiento en mcp-host

mint.yaml describe cómo alojar este servidor. Ten en cuenta la lista de permitidos de salida: el único host con el que se comunica el servidor es api.alpharoute.app (cada lectura/escritura y la renovación del token). En el nivel aislado se requiere una política de salida — permite api.alpharoute.app; de lo contrario, las herramientas informarán de «no se pudo conectar con la API». Una instalación alojada normal no tiene puente de navegador, así que establece ALPHAPORTAL_REFRESH_TOKEN como secreto allí.

Desarrollo

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

Las estructuras de la API están fijadas en docs/ALPHAPORTAL-API.md.

Notas y limitaciones

• El flujo de envío de solicitudes de transporte (requests/transportation/add, .../alternative/add) no se expone a propósito todavía: su cuerpo de solicitud anidado no se capturó por completo, y lanzar una carga de escritura adivinada que envíe una solicitud real al distrito sería irresponsable. Consulta la documentación.

• Cada solicitud usa tu propia sesión de AlphaPortal (el token de actualización que capturaste); el servidor únicamente lee los datos de tu cuenta.