alphaportal-mcp

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位置
• 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 — 有効なセッションが設定されているか（シークレットは返されません）
• alphaportal_healthcheck — 問題が発生している箇所を確認できます。リフレッシュトークンが解決されていない、AlphaPortalによって拒否された、CDN/WAFがリクエストをブロックした、APIが停止している、といった状況を特定します（シークレットは返されません）

書き込み（いずれも最初に確認が必要です。クライアントが確認プロンプトに対応している場合はそのプロンプトが表示されます。対応していない場合、最初の呼び出しで正確なペイロードとconfirmTokenのプレビューが返され、そのトークンを指定して再度呼び出すと処理が実行されます。確認を参照）：

• alphaportal_edit_walk_radius — 生徒の徒歩圏の半径（メートル）を設定
• alphaportal_set_notification — 生徒ごとのプッシュ通知・メール通知の設定

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

AlphaPortal のログインには reCAPTCHA が必要なため、ユーザー名とパスワードでは自動化できません。代わりに、このサーバーはサインイン済みのブラウザーにウェブアプリが保存するリフレッシュトークン（有効期間 8 日間の認証情報）を使用し、必要な短期アクセストークンをすべてサーバー側で発行します。リクエストの処理経路にブラウザーブリッジは介在しません。このトークンを取得する方法は 2 つあり、次の順で試します。

1. 自動（fetchproxy によるブートストラップ）。 ALPHAPORTAL_REFRESH_TOKEN が設定されていない場合、サーバーは ContextMint Bridge ブラウザー拡張機能（旧 fetchproxy 拡張機能）を介して、サインイン済みの AlphaPortal タブから一度だけトークンを読み取ります。読み取るのはトークンのみです（JSON ポインターによる抽出のため、氏名、メールアドレス、電話番号がブラウザーの外に出ることはありません）。読み取り後、拡張機能は終了します。拡張機能がインストールされており、*.alphaportal.app のタブにサインインしている必要があります。ContextMint Bridge はリリースページから入手できます。Chrome では、Chrome 用ビルドを解凍し、展開済みの拡張機能として読み込んでください（chrome://extensions → デベロッパーモード → 展開して読み込む）。Safari にはまだ対応していません（公開ダウンロードがない ContextMint アプリ内で提供される予定です）。そのため、現時点では Chrome を使用してください。ContextMint Bridge は、同じメンテナーが新しい名前で提供している fetchproxy のブラウザー拡張機能です。fetchproxy のREADMEからも案内されています。ソースコードは https://github.com/nullnet-app/contextmint-bridge で公開されています。自分でビルドするか、リリース zip の横に公開されている .sha256 ファイルと照合してください（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。無効にするには 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 を使ってシェルから同じトークンを取得する方法を説明しています。

保存したトークンを安全に保つ

保存されたセッション（~/.alphaportal-mcp/session.json または ALPHAPORTAL_SESSION_FILE）には、リフレッシュトークンが暗号化されていない JSON として保存されます。ファイルのアクセス権は 0600、ディレクトリのアクセス権は 0700 ですが、OS のキーチェーンには保存されません。パスワードと同じように扱ってください。

• 一度コピーされると、誰でも無期限に更新し続けられます。 AlphaPortal はトークンをステートレスに検証するため（署名と有効期限）、使用済みのトークンも有効期限が切れるまで使い続けることができ、更新のたびに新しい有効期間 8 日間のトークンが発行されます。バックアップ、同期されたホームディレクトリ、自分の権限で実行されている別のプロセスなどからコピーされたトークンを使うと、お子様の氏名、学校、自宅付近のバス停、リアルタイムのバス GPS 情報に継続してアクセスされる可能性があります。
• ここからトークンを失効させることはできません。 ファイルを削除すると、このサーバーがそのトークンを使用しなくなるだけです。コピーされたトークンは、有効期限が切れるまで有効なままです。AlphaPortal のパスワード変更によって未失効のトークンが無効になるかどうかは確認されていません。コピーが漏えいした疑いがある場合は、パスワードを変更し、学区にポータルアカウントのリセットを依頼してください。
• ~/.alphaportal-mcp/ をクラウド同期フォルダーや暗号化されていないバックアップに含めないでください。また、サーバーの使用をやめる際は削除してください。

セットアップ

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 ホストでは、その環境変数ブロックに ALPHAPORTAL_REFRESH_TOKEN を設定してください（.mcp.json と mcpb のユーザー設定のどちらからも参照できます）。

任意の環境変数

変数	用途
ALPHAPORTAL_REFRESH_TOKEN	リフレッシュトークンです。ContextMint Bridge がサインイン済みのタブから読み取れる場合は任意ですが、ヘッドレス／ホスト型のデプロイでは必須です。
ALPHAPORTAL_DISABLE_FETCHPROXY	1 に設定すると、ブラウザーブリッジへのフォールバックを無効にし、環境変数を必須にします。
ALPHAPORTAL_SESSION_FILE	保存先のパスを上書きします（デフォルトは ~/.alphaportal-mcp/session.json）。

確認

変数	デフォルト	用途
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で書き込みを行う際の動作です。ask-user：2段階で実行します。最初の呼び出しでは何も行わず、プレビューとトークンを返します。その後、モデルは再度呼び出す前に、チャットでユーザーの承認を得る必要があります。auto：同じく2段階で実行しますが、モデルはプレビューを自ら確認した後にトークンを使用できます。refuse：このようなクライアントでは書き込みを拒否します。プロンプトを表示できるクライアント（Claude Code）には、MCP_CONFIRM_ELICITATION=off でない限り、常に実際のプロンプトが表示されます。認識できない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on	off にすると確認プロンプトは表示されず、すべてのクライアントで MCP_CONFIRM_MODE の動作が適用されます。プロンプトに対応しているとされるものの、実際には表示されず書き込みが停止するクライアント（opencode 2.0.x）では、この値を設定してください。それ以外の値では on のままとなり、stderr に警告が出力されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンの有効期間です。
MCP_CONFIRM_SECRET	プロセスごとにランダム	署名キーです。トークンをサーバーの再起動後も有効にする必要がある場合にのみ設定してください。

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 に固定されています。

注意事項と制限

• transportation-request の送信フロー（requests/transportation/add、.../alternative/add）は、意図的にまだ公開していません。ネストされたリクエスト本文を完全には把握できておらず、推測した書き込みペイロードを実装して学区に実際のリクエストを送信するのは無責任だからです。詳細はドキュメントをご覧ください。
• すべてのリクエストは、ユーザー自身の AlphaPortal セッション（取得したリフレッシュトークン）を使用します。サーバーが読み取るのは、ユーザーのアカウントデータのみです。