alphaportal-mcp

MCP-сервер для AlphaPortal (AlphaRoute) — портала для родителей/опекунов, отслеживающего школьные автобусы, используемого такими округами, как Charlotte-Mecklenburg Schools (cmsnc.alphaportal.app). Спросите Claude, где находится автобус вашего ребёнка, какие остановки у него есть и какие уведомления о прибытии приходили — а также (с подтверждением) настройте предпочтения уведомлений и радиус пешеходной зоны.

Разработано и поддерживается ИИ. Используйте на свой страх и риск.

Что он умеет

Чтение (все проверяется в реальном времени через настоящий API):

• alphaportal_list_students — ваши дети, с классом, школой и транспортными флагами

• alphaportal_get_student — школа ребёнка плюс утренние/дневные остановки

• alphaportal_get_student_stops — назначенные остановки с временем и местоположением

• alphaportal_get_bus_location — живой GPS автобуса для утреннего или вечернего рейса

• alphaportal_list_notifications — уведомления о прибытии/отправлении

• alphaportal_list_requests — поданные запросы на транспорт + номера отслеживания

• alphaportal_get_report_link — ссылка для скачивания PDF-отчёта

• alphaportal_list_schools, alphaportal_list_grades — справочные данные округа

• alphaportal_get_profile, alphaportal_get_account, alphaportal_get_settings

• alphaportal_session_status — настроена ли рабочая сессия (секреты не возвращаются)

Запись (с подтверждением — предварительный просмотр точной полезной нагрузки, если не указано confirm: true):

• alphaportal_edit_walk_radius — установить радиус пешеходной зоны ученика (в метрах)

• alphaportal_set_notification — установить предпочтения push/email-уведомлений для каждого ученика

Related MCP server: io.github.thehesiod/psquare

Аутентификация — refresh-токен

Вход в AlphaPortal защищён reCAPTCHA и не может быть автоматизирован с помощью имени пользователя/пароля. Вместо этого сервер использует refresh-токен, который веб-приложение хранит в вашем браузере, где вы вошли (учётные данные на 8 дней); из него он создаёт кратковременные access-токены полностью на стороне сервера — без моста через браузер в горячем пути запроса. Есть два способа получить этот токен, которые пробуются по порядку:

1. Автоматически (fetchproxy bootstrap). Если ALPHAPORTAL_REFRESH_TOKEN не задан, сервер один раз считывает его из вашей вкладки AlphaPortal, где вы вошли, через расширение браузера Transporter (мост fetchproxy) — одноразовое чтение, которое сохраняет только токен (извлечение через JSON-pointer, так что ваше имя/email/телефон никогда не покидают браузер), затем закрывается. Требуется установленное расширение и вкладка *.alphaportal.app с выполненным входом. Установите ALPHAPORTAL_DISABLE_FETCHPROXY=1, чтобы отключить это.

2. Вручную (переменная окружения). Установите ALPHAPORTAL_REFRESH_TOKEN самостоятельно. Захватите его в консоли DevTools на вкладке с выполненным входом:

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

В любом случае сервер сохраняет каждый ротированный refresh-токен, поэтому 8-дневное окно сдвигается вперёд, если вы используете его хотя бы раз каждые 8 дней. Если он истекает, войдите снова (способ 1) или повторно захватите (способ 2). Навык alphaportal-fpx в skills/ описывает тот же захват из оболочки через CLI fpx.

Настройка

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 игнорируется git. Для MCP-хоста установите ALPHAPORTAL_REFRESH_TOKEN в его блоке env (.mcp.json / пользовательская конфигурация mcpb оба ссылаются на него).

Необязательные переменные окружения

Размещение на mcp-host

mint.yaml описывает, как разместить этот сервер. Обратите внимание на список разрешённых исходящих подключений: единственный хост, с которым связывается сервер, — api.alpharoute.app (каждое чтение/запись и обновление токена). На изолированном уровне требуется политика исходящего трафика — разрешите api.alpharoute.app, иначе инструменты будут сообщать «не удалось связаться с API». Обычная регистрация на хостинге не имеет моста через браузер, поэтому установите ALPHAPORTAL_REFRESH_TOKEN как секрет.

Разработка

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 зафиксированы в docs/ALPHAPORTAL-API.md.

Примечания и ограничения

• Поток подачи транспортного запроса (requests/transportation/add, .../alternative/add) намеренно ещё не открыт — его вложенное тело запроса не было полностью захвачено, и отправлять предполагаемую полезную нагрузку, которая подаёт реальный запрос в округ, было бы безответственно. См. документацию.

• Каждый запрос использует вашу собственную сессию AlphaPortal (захваченный вами refresh-токен); сервер всегда читает только данные вашего аккаунта.