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 — 오전 또는 오후 운행에 대한 버스 실시간 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 게이트가 적용되어 있어 사용자 이름/비밀번호로 자동화할 수 없습니다. 대신 이 서버는 웹 앱이 로그인된 브라우저에 저장하는 리프레시 토큰(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를 통해 셸에서 동일한 캡처를 수행하는 방법을 설명합니다.

설정

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 호스트의 경우 해당 환경 블록(.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 세션(사용자가 캡처한 리프레시 토큰)을 사용합니다. 서버는 사용자 계정의 데이터만 읽습니다.