{
  "markdown": "# alphaportal-mcp\n\nAn MCP server for **AlphaPortal** (AlphaRoute), the parent/guardian school-bus\ntransportation portal used by districts such as Charlotte-Mecklenburg Schools\n(`cmsnc.alphaportal.app`). Ask Claude where your child's bus is, what stops they\nhave, and what arrival notifications came in — and (confirm-gated) adjust\nnotification preferences and walk-zone radius.\n\n> Developed and maintained by AI. Use at your own discretion.\n\n## What it can do\n\n**Reads** (all live-verified against the real API):\n\n- `alphaportal_list_students` — your children, with grade, school, and transport flags\n- `alphaportal_get_student` — a child's school plus morning/afternoon stops\n- `alphaportal_get_student_stops` — assigned stops with times and locations\n- `alphaportal_get_bus_location` — **live GPS of the bus** for the AM or PM run\n- `alphaportal_list_notifications` — arrival/departure alerts\n- `alphaportal_list_requests` — submitted transportation requests + tracking numbers\n- `alphaportal_get_report_link` — a PDF report download link\n- `alphaportal_list_schools`, `alphaportal_list_grades` — district reference data\n- `alphaportal_get_profile`, `alphaportal_get_account`, `alphaportal_get_settings`\n- `alphaportal_session_status` — is a working session configured (no secrets returned)\n\n**Writes** (confirm-gated — a dry-run of the exact payload unless `confirm: true`):\n\n- `alphaportal_edit_walk_radius` — set a student's walk-zone radius (meters)\n- `alphaportal_set_notification` — set per-student push/email notification preferences\n\n## Authentication — the refresh token\n\nAlphaPortal's login is reCAPTCHA-gated and can't be automated with a\nusername/password. Instead this server uses the **refresh token** the web app\nstores in your signed-in browser (an 8-day credential); from it, it mints the\nshort-lived access tokens it needs entirely server-side — **no browser bridge in\nthe request hot path**. There are two ways it gets that token, tried in order:\n\n1. **Automatic (fetchproxy bootstrap).** If `ALPHAPORTAL_REFRESH_TOKEN` is not\n   set, the server reads it once from your signed-in AlphaPortal tab via the\n   **Transporter** browser extension (the fetchproxy bridge) — a one-shot read\n   that snapshots only the token (a JSON-pointer extraction, so your name/email/\n   phone never leave the browser), then closes. Requires the extension installed\n   and a signed-in `*.alphaportal.app` tab. Set `ALPHAPORTAL_DISABLE_FETCHPROXY=1`\n   to turn this off.\n2. **Manual (env var).** Set `ALPHAPORTAL_REFRESH_TOKEN` yourself. Capture it in a\n   signed-in tab's DevTools console:\n   ```js\n   JSON.parse(localStorage.user).User.RefreshToken\n   ```\n   This is the right path for a headless/hosted deployment with no browser.\n\nEither way, the server persists each rotated refresh token, so the 8-day window\nrolls forward as long as you use it at least once every 8 days. If it expires,\nsign back in (path 1) or re-capture (path 2). The `alphaportal-fpx` skill under\n`skills/` documents the same capture from a shell via the `fpx` CLI.\n\n## Setup\n\n```sh\nnpm install\nnpm run build\necho 'ALPHAPORTAL_REFRESH_TOKEN=<paste the token>' > .env\nnode dist/index.js   # or wire it into your MCP host\n```\n\n`.env` is gitignored. For an MCP host, set `ALPHAPORTAL_REFRESH_TOKEN` in its env\nblock (`.mcp.json` / mcpb user config both reference it).\n\n### Optional environment variables\n\n| Variable | Purpose |\n| --- | --- |\n| `ALPHAPORTAL_REFRESH_TOKEN` | The refresh token. Optional if the fetchproxy bridge can read it from a signed-in tab; required for a headless/hosted deployment. |\n| `ALPHAPORTAL_DISABLE_FETCHPROXY` | Set to `1` to disable the browser-bridge fallback and require the env var. |\n| `ALPHAPORTAL_SESSION_FILE` | Override the store path (default `~/.alphaportal-mcp/session.json`). |\n\n### Hosting on mcp-host\n\n`mint.yaml` describes how to host this server. Note the **egress allowlist**: the\nonly host the server contacts is `api.alpharoute.app` (every read/write and the\ntoken refresh). On the isolated tier an egress policy is required — allow\n`api.alpharoute.app`, or tools report \"could not reach the API\". A plain hosted\nregistration has no browser bridge, so set `ALPHAPORTAL_REFRESH_TOKEN` as a\nsecret there.\n\n## Development\n\n```sh\nnpm test          # vitest (mocked network)\nnpm run typecheck # tsc --noEmit (a green vitest run is not a green typecheck)\nnpm run build     # tsc + esbuild bundle\n```\n\nAPI shapes are pinned in [`docs/ALPHAPORTAL-API.md`](docs/ALPHAPORTAL-API.md).\n\n## Notes & limitations\n\n- The transportation-**request** submission flow (`requests/transportation/add`,\n  `.../alternative/add`) is intentionally not exposed yet — its nested request\n  body was not fully captured, and shipping a guessed write payload that submits\n  a real request to the district would be irresponsible. See the docs.\n- Every request rides your own AlphaPortal session (the refresh token you\n  captured); the server only ever reads your account's data.\n",
  "bytes": 4970,
  "sha": "acd04bd0b48382b4e66e1de9b4d74c44b64562ea6b7860ca9fb4d1aeaeb7afb8",
  "repo_slug": "chrischall/alphaportal-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_chrischall_alphaportal_mcp_582c0e61/readme"
}