alphaportal-mcp

AlphaPortal (AlphaRoute) 用の MCP サーバーです。これは、Charlotte-Mecklenburg Schools (cmsnc.alphaportal.app) などの学区で使用される保護者向けスクールバス輸送ポータルです。Claude に、お子様のバスの位置、停留所、到着通知を尋ねたり、(確認ゲート付きで) 通知設定や徒歩圏半径を調整したりできます。

AI によって開発・保守されています。ご自身の判断でご利用ください。

できること

読み取り (すべて実際の API に対してライブ検証済み):

• alphaportal_list_students — お子様の一覧。学年、学校、交通手段フラグ付き

• alphaportal_get_student — お子様の学校と、朝/午後の停留所

• alphaportal_get_student_stops — 割り当てられた停留所と時刻・場所

• alphaportal_get_bus_location — バスのライブ GPS (AM/PM の運行)

• 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 — 生徒ごとのプッシュ/メール通知設定を設定

Related MCP server: io.github.thehesiod/psquare

認証 — リフレッシュトークン

AlphaPortal のログインは reCAPTCHA で保護されており、ユーザー名/パスワードで自動化することはできません。代わりに、このサーバーは、サインインしたブラウザに Web アプリが保存する リフレッシュトークン (8日間の資格情報) を使用します。そこから、必要な短期間のアクセストークンを完全にサーバーサイドで生成します — リクエストのホットパスにブラウザブリッジはありません。このトークンを取得する方法は2つあり、順に試行されます:

1. 自動 (fetchproxy ブートストラップ). ALPHAPORTAL_REFRESH_TOKEN が設定されていない場合、サーバーは Transporter ブラウザ拡張機能 (fetchproxy ブリッジ) を介して、サインイン済みの AlphaPortal タブから一度だけトークンを読み取ります。これはワンショット読み取りで、トークンのみをスナップショットします (JSON ポインター抽出のため、名前/メール/電話番号がブラウザから出ることはありません)。その後閉じます。拡張機能がインストールされ、サインイン済みの *.alphaportal.app タブが必要です。無効にするには ALPHAPORTAL_DISABLE_FETCHPROXY=1 を設定します。

2. 手動 (環境変数). ALPHAPORTAL_REFRESH_TOKEN を自分で設定します。サインイン済みタブの DevTools コンソールで取得します:

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

   これは、ブラウザのないヘッドレス/ホスト型デプロイに適した方法です。

いずれの場合も、サーバーはローテーションされた各リフレッシュトークンを永続化するため、8日ごとに少なくとも1回使用する限り、8日間のウィンドウは前方にロールします。期限が切れた場合は、再度サインインするか (方法1)、再取得してください (方法2)。skills/ ディレクトリの alphaportal-fpx スキルには、fpx CLI を介したシェルからの同じ取得方法が記載されています。

セットアップ

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 は gitignore されています。MCP ホストの場合は、その env ブロック (.mcp.json / mcpb ユーザー設定の両方が参照) に ALPHAPORTAL_REFRESH_TOKEN を設定します。

オプションの環境変数

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 セッション (取得したリフレッシュトークン) を使用します。サーバーはあなたのアカウントのデータのみを読み取ります。