waseda-portal-mcp

와세다 대학의 Waseda Moodle, MyWaseda 휴강 정보, Web 시러버스, 공식 학사 일정을 정리하는 비공식·로컬·read-only MCP 서버입니다. 와세다 대학과 무관하며, 대학의 승인·보증·지원이 없습니다.

주요 용도는 MCP 클라이언트에서 "내일 수업과 마감을 알려줘"라고 물어보고, 수업, 휴강·변경, 당일 마감, 미제출 기한 초과 과제를 출처와 함께 확인하는 것입니다.

지원 데이터 소스

• Waseda Moodle: 정규 과목, 활동 유형, 구조화된 시작·마감, 제출·완료 상태

• MyWaseda 휴강 정보: 로그인 후 초기 화면에 있는 수강 과목 대상 휴강·변경

• Web 시러버스: 연도, 과목·클래스 코드, 개설 기관, 담당자, 배정 학년, 공개된 대상자·선수 조건, 요일 교시, 교실, 방식, 개요, 계획, 평가, 시험 기재

• 와세다 대학 공식 학사 일정: 수업 시작·종료, 휴업, 공휴일 수업, 수업 휴지, 시험 기간

대학 로고, 화면 캡처, 교재, 확보한 시러버스 본문, 실존하는 개인 데이터는 리포지토리에 포함하지 않습니다.

필요 환경과 설정

• Node.js 22 이상

• npm

• 시스템에 설치된 Google Chrome

git clone https://github.com/TakeruF/waseda-portal-mcp.git
cd waseda-portal-mcp
npm install
npm run build
npm run auth

npm run auth(또는 빌드 후 waseda-portal-mcp auth)는 전용 Chrome 프로필을 엽니다. Waseda Moodle과 MyWaseda 로그인은 사용자 본인이 Chrome에서 수행하고, 마지막에 MyWaseda의 "수업 → 수업 관련 → 휴강"을 열어 주세요. 휴강 페이지 도달을 URL만으로 확인하면 인증 상태를 저장하고 전용 Chrome을 자동으로 닫습니다. CLI는 사용자 이름·비밀번호를 요구하지 않습니다. 기존 Chrome 프로필이나 평소 사용 중인 Cookie도 복사하지 않습니다.

기본 전용 프로필은 ~/.waseda-portal-mcp/chrome-profile, 서버가 읽어들이는 인증 상태는 ~/.waseda-portal-mcp/auth-state.json입니다. 둘 다 리포지토리 밖에 있으며, 인증 상태 파일은 owner-only(0600)로 합니다. 위치는 WASEDA_PORTAL_PROFILE_DIR과 WASEDA_PORTAL_AUTH_STATE_PATH로 변경할 수 있습니다. 같은 전용 프로필을 사용하는 Chrome과 MCP 서버는 동시에 실행할 수 없습니다.

MCP 클라이언트 설정

절대 경로는 실제 checkout으로 바꿔 주세요.

{
  "mcpServers": {
    "waseda-portal": {
      "command": "node",
      "args": ["/absolute/path/to/waseda-portal-mcp/dist/cli.js"]
    }
  }
}

캐시를 무효화하려면 args에 "--no-cache"를 추가합니다. stdio의 표준 출력은 MCP 프로토콜 전용이며, 운영 메시지는 표준 오류로 출력합니다.

도구

• get_day_brief: date(YYYY-MM-DD)의 수업, 변경, 당일 마감, 미제출 기한 초과를 통합

• list_courses: 보통은 카테고리가 정규과목/으로 시작하는 과목만. includeNonRegular로 안내 코스 등도 포함

• list_deadlines: ISO 8601의 from·to 내에 마감이 있는 활동을 열거. 보통은 제출 완료·완료를 제외

• list_changes: 지정 날짜 범위의 휴강·변경을 열거

• get_syllabus: courseId 또는 syllabusKey에서 상세 또는 모호한 후보를 반환

• search_syllabi: 수강 상황과 관계없이, 현재 연도의 Web 시러버스를 과목명 또는 내용에서 검색

search_syllabi의 mode는, 알려진 과목명이면 course_name, 배우고 싶은 내용에서 찾는다면 content입니다. 내용 검색에서는 자연문을 최대 3어로 분해합니다. MCP 클라이언트는 relatedTerms에 최대 3개의 짧은 관련어를 전달함으로써 검색 횟수와 의도를 명시할 수 있습니다.

{
  "query": "日本の貨幣の歴史を学びたい",
  "mode": "content",
  "relatedTerms": ["貨幣", "通貨", "経済史"],
  "maxResults": 3,
  "useAcademicProfile": true
}

결과에는 완전한 시러버스, 공식 검색에서 일치한 어, 대조할 수 있었던 필드, 어휘적 관련도가 있습니다. 로컬 학습 프로필이 설정되어 있으면 profileApplied가 true가 되고, 후보마다 소속·학년·선수 조건의 조언적 대조도 붙습니다. 내용 검색은 의미적 수강 추천이나 수강 가능 여부의 보증이 아닙니다.

임의의 로컬 학습 프로필

본인이 명시한 최소한의 학습 정보만을, 기본적으로 ~/.waseda-portal-mcp/academic-profile.json에 임의로 저장할 수 있습니다. MyWaseda나 Moodle에서 이름, 학번, 소속, 학년, 수강 이력을 자동으로 가져오는 기능은 없습니다.

{
  "schemaVersion": 1,
  "affiliations": ["例示学部"],
  "academicLevel": "undergraduate",
  "year": 3,
  "completedPrerequisites": ["合成基礎科目"]
}

affiliations는 정식 학부·대학원 명칭을 최대 5건, academicLevel은 undergraduate·masters·doctoral·other, year는 1~6입니다. completedPrerequisites는 대조에 사용할 과목명·선수 조건만을 최대 30건까지 본인이 골라 기재합니다. 수강 이력에 해당하므로, 필요 없으면 생략해 주세요.

상위 디렉터리를 0700, 파일을 0600으로 하고, 리포지토리 밖에 두세요. 파일이 존재하지 않으면 종래대로 검색합니다. 다른 위치를 사용하려면 WASEDA_PORTAL_ACADEMIC_PROFILE_PATH로 지정할 수 있습니다. 권한이 너무 넓은 파일이나 타 사용자 소유 파일은 읽지 않습니다.

프로필의 값은 MCP 응답, 로그, snapshot, 캐시에 복제하지 않습니다. 출력하는 것은 profileApplied와, 값을 숨긴 consistent·conflict·review_required·unavailable의 판정 근거뿐입니다. 호출마다 useAcademicProfile: false로 하면 사용하지 않습니다.

날짜·시각은 ISO 8601로 유지하고, 원 페이지에 타임존이 없으면 Asia/Tokyo로 해석합니다. 모든 결과에 확보원 URL과 확인 시각이 있습니다. 충돌 시에는 MyWaseda, Moodle 구조화 정보, Web 시러버스, 자유 기재 순서입니다.

read-only 보증

일반 확보는 페이지 표시와 DOM 읽기뿐입니다. ReadOnlyGuard는 과제 제출, 업로드, 퀴즈·설문 응답, 출석, 완료 변경, 일정 작성, 게시, 메시지, 수강 변경 등의 알려진 URL과, 허가되지 않은 비-GET 요청을 거부합니다.

Web 시러버스의 공식 검색 폼만은, 검색임에도 불구하고 HTTP POST를 사용합니다. 이 때문에 공식 호스트·/syllabus/JAA101.php·read-only controller JAA103SubCon이 모두 일치하는 검색 POST만을 좁게 허용합니다. Moodle의 지연 로딩도 /lib/ajax/service.php에 대한 알려진 참조 전용 메서드만 허용합니다. 상세 페이지는 GET으로 읽습니다. 인증 플로우는 별도 프로세스이며, 인증 정보의 입력·송신은 사용자 본인의 조작입니다.

성적, 평점, 교원 피드백, 제출 파일명은 모델에 존재하지 않으며, 일반 응답에도 포함되지 않습니다. Moodle 외부 캘린더 토큰은 발행·저장·사용하지 않습니다.

개인 정보와 캐시

인증된 HTML은 메모리상에서 해석 후 폐기하고, 영구 저장하지 않습니다. Cookie와 세션 토큰은 리포지토리 밖의 전용 프로필과 인증 상태 파일에만 있으며, MCP 응답이나 로그에 내보내지 않습니다. 임의의 학습 프로필도 리포지토리 밖의 owner-only 파일에서 기동 시 한 번만 읽고, 값을 응답이나 캐시에 저장하지 않습니다. 정규화된 최소 데이터만을 프로세스 메모리에 기본 5분간 캐시합니다. TTL은 WASEDA_PORTAL_CACHE_TTL_MS, 무효화는 --no-cache 또는 WASEDA_PORTAL_CACHE=false입니다.

확정할 수 있었던 courseId → syllabusKey만은, 재검색을 줄이기 위해 ~/.waseda-portal-mcp/cache/course-syllabus-map.json에 저장할 수 있습니다. 이 대응표에 과목명, 담당자명, 학번 등은 포함하지 않고, 디렉터리 0700·파일 0600으로 원자적으로 갱신합니다. 모호한 후보나 일치 없음은 저장하지 않습니다.

fixture는 모두 인공 데이터입니다. 실데이터를 issue, 로그, fixture, 테스트 출력에 붙이지 마세요. 자세한 내용은 SECURITY.md를 참조하세요.

오류

AUTH_REQUIRED, SESSION_EXPIRED, MAINTENANCE, SOURCE_UNAVAILABLE, PAGE_STRUCTURE_CHANGED, AMBIGUOUS_COURSE_MATCH, RATE_LIMITED, READ_ONLY_VIOLATION을 구분합니다. 주요 selector가 사라진 경우 빈 배열을 성공으로 취급하지 않고, PAGE_STRUCTURE_CHANGED를 반환합니다. 정규의 빈 목록용 컨테이너를 확인할 수 있었을 때만 빈 배열을 반환합니다.

미인증이면 npm run auth를 실행하세요. 구조 변경이면, 개인 정보를 포함하지 않는 최소 DOM 구조를 인공 fixture로 재현하고, 대상 parser와 fixture 테스트를 갱신합니다. 인증된 원본 HTML을 issue나 커밋에 추가하지 마세요.

개발과 검증

npm test             # 外部アクセスなしの人工fixtureテスト
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run test:live:auth-state     # 新規一時プロファイルでAUTH_REQUIREDを確認
npm run test:live:authenticated  # 認証必須。AUTH_REQUIRED/SESSION_EXPIREDは失敗
npm run test:live:catalog        # 公開シラバスの内容検索と科目名検索
npm run test:e2e:authenticated   # ビルド後、MCPクライアントからstdio E2E
npm run test:e2e:catalog         # search_syllabiのstdio E2E

test:live는 test:live:authenticated의 별명입니다. 인증 필수 라이브 검증은 동시 실행 1, 접근 간격 1초, 정규 과목 1건, 시러버스 후보 최대 3건, 과제 상세 최대 1건으로 제한합니다. 미인증이면 성공으로 취급하지 않고 실패합니다. fixture 성공, 인증된 라이브 성공, MCP 클라이언트 E2E 성공은 별개의 증거로 취급하세요.

알려진 제약

• Moodle, MyWaseda, Web 시러버스의 DOM 변경으로 parser 갱신이 필요할 수 있습니다.

• 내용 검색은 공식 Web 시러버스의 전체 항목 키워드 검색을 사용하는 어휘 검색입니다. 동의어나 추상적 관심은 relatedTerms로 보완하고, 최대 3검색·최대 5상세로 제한합니다.

• 학습 프로필에 의한 판정은 조언입니다. Web 시러버스에서 독립 항목으로 되어 있는 배정 학년은 구조적으로 대조하지만, 개설 기관을 소속 제한으로 간주하지 않습니다. 대상자·선수 과목·정원·등록 시기가 자유 기재나 학부 요강에 있는 경우 자동으로 수강 가능하다고 단정하지 않고, 공식 정보의 확인이 필요합니다.

• MyWaseda는 수강 과목 대상 초기 표시만이며, 학부 전체 표시의 POST 조작은 구현하지 않았습니다.

• 수업 회차는, 확정할 수 있었던 시러버스의 요일 교시와 학기·휴업일에서 생성합니다. 집중·보강·개별 회차의 자유 기재는 단정하지 않습니다.

• Moodle과 시러버스의 대조는 연도, 개설 기관, 정규화 과목명, 클래스, 담당자, 이용 가능하면 요일 교시를 근거로 합니다. Moodle명과 시러버스명이 다른 경우 담당자의 부분 일치로 후보를 최대 건수까지 확보합니다. 근거가 약하거나, 상위 후보의 차이가 작은 경우 모호한 후보만 반환하고, 교실·시험 정보를 확정하지 않습니다.

• 상주 알림, 쓰기, 성적 취득, 교재 일괄 확보, 캘린더 토큰, Chrome 확장, 클라우드 인증, 원격 MCP, 복수 대학은 대상 외입니다.

타 대학 adapter

공통화하는 것은 확보 수단이 아니라, 이용자가 필요로 하는 결과입니다. 먼저 동일 패키지 내에서 UniversityAdapter를 구현하고, 대학 고유의 selector·ID·대조 규칙은 adapter 아래에 둡니다. 고유 정보는 extensions에 넣습니다. 2번째 학교의 구현으로 실제 경계를 확인할 수 있을 때까지, 별도 패키지로 분할하지 않습니다. 자세한 내용은 docs/architecture.md를 참조하세요.

License

MIT