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 — 是否已配置可用的会话（不返回任何机密）

写入（确认门控——除非 confirm: true，否则仅对确切载荷进行试运行）：

• alphaportal_edit_walk_radius — 设置学生的步行区域半径（米）

• alphaportal_set_notification — 设置每个学生的推送/电子邮件通知偏好

Related MCP server: io.github.thehesiod/psquare

身份验证——刷新令牌

AlphaPortal 的登录受 reCAPTCHA 保护，无法使用用户名/密码自动完成。该服务器改用 Web 应用在你已登录浏览器中存储的刷新令牌（有效期为 8 天的凭据）；它完全在服务端从该令牌生成所需的短期访问令牌——请求关键路径中没有浏览器桥接。它按顺序尝试以下两种方式获取该令牌：

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 天使用一次，8 天窗口就会向前滚动。如果它过期了，请重新登录（方式 1）或重新获取（方式 2）。skills/ 下的 alphaportal-fpx 技能记录了如何通过 fpx CLI 在 shell 中执行相同的捕获。

设置

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 主机，请在其环境变量块（.mcp.json / mcpb 用户配置均会引用它）中设置 ALPHAPORTAL_REFRESH_TOKEN。

可选环境变量

在 mcp-host 上托管

mint.yaml 描述了如何托管此服务器。请注意出站白名单：服务器唯一会联系的主机是 api.alpharoute.app（每次读取/写入以及令牌刷新）。在隔离层级上，需要出站策略——允许 api.alpharoute.app，否则工具会报告“could not reach the 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 会话（你捕获的刷新令牌）；服务器只会读取你账户的数据。