alphaportal-mcp

alphaportal-mcp

面向 AlphaPortal（AlphaRoute）的 MCP 服务。AlphaPortal 是由 Charlotte-Mecklenburg Schools（cmsnc.alphaportal.app）等学区使用的家长/监护人校车交通门户。询问 Claude 您孩子的校车在哪里、他们有哪些站点，以及收到了哪些到站通知；还可以（需确认后）调整通知偏好和步行区域半径。

由 AI 开发和维护。请自行决定是否使用。

功能

读取（均已通过真实 API 实时验证）：

• alphaportal_list_students — 您的孩子及其年级、学校和交通标记
• alphaportal_get_student — 孩子的学校及早晨/下午的站点
• alphaportal_get_student_stops — 分配的站点、时间和位置
• alphaportal_get_bus_location — AM 或 PM 行程中校车的实时 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 天）；然后完全在服务端生成所需的短期访问令牌——请求处理关键路径上无需浏览器桥接。获取该令牌有两种方式，按顺序尝试：

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：你可以自行构建，或使用其旁边发布的 .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 天至少使用一次，8 天有效期就会持续滚动。如果令牌过期，请重新登录（方式 1）或重新获取令牌（方式 2）。skills/ 下的 alphaportal-fpx 技能也介绍了如何通过 fpx CLI 在 shell 中获取令牌。

确保已保存的令牌安全

已保存的会话（~/.alphaportal-mcp/session.json，或 ALPHAPORTAL_SESSION_FILE）会以明文 JSON 保存刷新令牌——文件权限为 0600，所在目录权限为 0700，但它没有存储在操作系统密钥链中。请像对待密码一样保护它：

• 任何人只要复制一次，就能持续刷新令牌。 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：分两步执行——首次调用不执行任何操作，并返回预览和令牌；模型必须先在聊天中获得你的批准，然后才能再次携带令牌调用。auto：同样分两步执行，但模型可以在自行查看预览后使用令牌。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 中。

备注与限制

• 交通请求提交流程（requests/transportation/add、 .../alternative/add）目前有意不予开放——其嵌套请求正文尚未完整捕获，而猜测写入负载并将真实请求提交给学区是不负责任的。请参阅文档。
• 每个请求都使用你自己的 AlphaPortal 会话（你捕获的刷新令牌）；服务只会读取你账户中的数据。