waseda-portal-mcp

这是一个非官方、本地、只读的MCP服务器，汇总早稻田大学的Waseda Moodle、MyWaseda停课信息、Web Syllabus、官方校历。与早稻田大学无关，不获得大学的认可、保证或支持。

主要用途是，从MCP客户端询问“列出明天的课程和截止日期”，并附上来源确认课程、停课/变更、当日截止日期、未提交的逾期作业。

支持的数据源

• Waseda Moodle: 正式科目、活动类型、结构化的开始/截止时间、提交/完成状态

• MyWaseda停课信息: 登录后初始显示中针对已选科目的停课/变更

• Web Syllabus: 年度、科目/班级代码、开课地点、负责人、分配年级、公开的对象/前提条件、星期/节次、教室、方式、概要、计划、评价、考试记载

• 早稻田大学官方校历: 课程开始/结束、休业、节假日课程、课程暂停、考试期间

大学标志、屏幕截图、教材、获取的Syllabus正文、真实个人数据不包含在仓库中。

环境要求与设置

• 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配置文件。用户本人需在Chrome上登录Waseda Moodle和MyWaseda，最后打开MyWaseda的“课程 → 课程相关 → 停课”页面。仅通过URL确认到达停课页面后，会保存认证状态并自动关闭专用Chrome。CLI不要求用户名和密码。也不会复制现有Chrome配置文件或正常使用中的Cookie。

默认的专用配置文件位于~/.waseda-portal-mcp/chrome-profile，服务器读取的认证状态位于~/.waseda-portal-mcp/auth-state.json。两者都在仓库之外，认证状态文件设置为仅所有者（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 Syllabus

search_syllabi的mode，如果是已知科目名称则为course_name，如果从想学的内容搜索则为content。内容搜索将自然语句分解为最多3个词。MCP客户端可通过向relatedTerms传递最多3个简短相关词，明确搜索次数和意图。

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

结果包含完整的Syllabus、官方搜索匹配的词、能匹配的字段、字面上的相关度。如果设置了本地学习档案，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响应、日志、快照、缓存中。输出的只有profileApplied以及隐藏值的consistent・conflict・review_required・unavailable判定依据。每次调用时若设置useAcademicProfile: false则不使用。

日期时间以ISO 8601保存，如果原页面没有时区，则解释为Asia/Tokyo。所有结果都有来源URL和确认时间。冲突时按MyWaseda、Moodle结构化信息、Web Syllabus、自由描述的顺序。

只读保证

通常获取仅进行页面显示和DOM读取。ReadOnlyGuard拒绝已知URL（如作业提交、上传、小测验/问卷回答、出勤、完成变更、日程创建、投稿、消息、选课变更等）以及未允许的非GET请求。

只有Web Syllabus的官方搜索表单，虽然是搜索却使用HTTP POST。因此，仅允许官方主机、/syllabus/JAA101.php、只读控制器JAA103SubCon全部匹配的搜索POST。Moodle的延迟加载也只允许对/lib/ajax/service.php的已知只读方法。详细页面通过GET读取。认证流程在单独进程中，认证信息的输入和提交由用户本人操作。

成绩、评分、教师反馈、提交文件名不存在于模型中，也不包含在通常响应中。不发行、保存或使用Moodle外部日历令牌。

个人信息与缓存

认证后的HTML在内存中解析后即丢弃，不持久保存。Cookie和会话令牌仅存在于仓库外的专用配置文件和认证状态文件中，不输出到MCP响应或日志。可选的学修档案也在启动时从仓库外的仅所有者文件读取一次，不将值保存到响应或缓存。仅将规范化后的最小数据缓存到进程内存，默认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。如果结构变更，请以人工fixture再现不含个人信息的DOM结构，并更新对应的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件、Syllabus候选最多3件、作业详情最多1件。如果未认证，不视为成功而是失败。请将fixture成功、认证后实时成功、MCP客户端E2E成功分别作为不同证据。

已知限制

• Moodle、MyWaseda、Web Syllabus的DOM变更可能需要更新parser。

• 内容搜索是使用官方Web Syllabus全项目关键词搜索的字面搜索。同义词或抽象兴趣通过relatedTerms补充，限制为最多3次搜索・最多5个详情。

• 学习档案的判定是建议。Web Syllabus中作为独立项目的分配年级会进行结构化匹配，但不将开课地点视为所属限制。如果对象、前提科目、定员、注册时间在自由描述或学部要项中，不自动断定可修读，需要确认官方信息。

• MyWaseda仅支持已选科目的初始显示，未实现学部整体显示的POST操作。

• 课程次数根据已确定的Syllabus的星期/节次和学期・休业日生成。不断定集中、补讲、个别回的自由描述。

• Moodle与Syllabus的匹配依据年度、开课地点、规范化科目名称、班级、负责人，以及可用时的星期/节次。如果Moodle名称与Syllabus名称不同，则通过负责人的部分匹配获取最多候选数。如果依据较弱或上位候选差异较小，仅返回模糊候选，不确认教室・考试信息。

• 常驻通知、写入、成绩获取、教材批量获取、日历令牌、Chrome扩展、云认证、远程MCP、多所大学不在范围内。

其他大学适配器

共通化的是用户所需的结果，而非获取手段。首先在同一包内实现UniversityAdapter，将大学特有的selector・ID・匹配规则放在adapter下。固有信息放入extensions。在第二所学校的实现确认实际边界之前，不分割为单独包。详情请参阅docs/architecture.md。

许可证