NTNU Courses (unofficial)

ntnu-mcp

一个远程 MCP 服务，为 LLM 助手提供挪威科技大学（NTNU）的课程数据：课程目录搜索、教学安排、每周课表、成绩统计、课程介绍、考试安排和包含官方学习计划的学习项目，以及帮助学生选择课程的比较工具。 作为 Cloudflare Worker 运行；客户端无需安装。

工具

共十二个工具，均为只读：

• search_courses — 按年份在 NTNU 课程目录中进行全文搜索；返回课程代码、名称、校区和考试日期。
• get_course_schedule — 获取某门课程在指定年份的所有有日期的教学活动（讲座、实验），包含奥斯陆当地时间和教室。
• get_weekly_timetable — 获取某门课程的固定每周课表：星期、时间、ISO 周范围和教室。
• get_grade_distribution — 获取某门课程按年份和学期划分的历史成绩分布，包含人数和百分比。
• get_course_versions — 获取普通课程代码对应的 DBH 版本课程代码（例如 TDT4100-1）；当成绩查询结果为空时，此工具很有用。
• get_semesters — 获取 NTNU 的学期信息，包括 26h/26v 这类 ID、教学周、考试期日期，以及当前学期。
• get_course_info — 获取课程的所有信息，但不包括考试安排：学分、级别、校区、先修要求、必修活动、内容／学习成果、学分减免、计划开设该课程的学习项目、联系人和提醒通知。默认使用英语，设置 language: "nb" 则使用挪威语。
• get_exam_info — 一次调用即可查询最多 10 门课程的考试安排：每场考试（常规／补考）的日期、开始时间、时长、允许使用的辅助工具代码（“hjelpemiddelkode”）及其含义、考试系统和指定考场。
• search_study_programs — 按文本、级别和城市搜索 NTNU 约 400 个学习项目；返回可用于 get_study_plan 的项目代码。
• get_study_plan — 获取某个项目和入学年份对应的官方计划：按学期列出课程（代码、学分、必修／选修），以及专业方向选择节点，是从“我学 X”到具体课程代码的桥梁。
• compare_courses — 并排比较多门课程：名称、校区、考试日期、每周教学时数和最新成绩分布。
• check_timetable_conflicts — 在选课前，成对检查一组课程之间的每周课表冲突和考试日期冲突。

连接

将服务器的 MCP URL 粘贴到 Claude 或 ChatGPT 的自定义连接器设置中：

https://ntnu-mcp.martinsundal.no/mcp

服务器无需身份验证，因为它只提供公开的、只读的 NTNU 课程数据。

此服务器也已列入官方 MCP 注册表，名称为 io.github.MartinSA04/ntnu-mcp（见 server.json）；可以浏览注册表的客户端可在那里发现该服务器。它是非官方社区服务，与 NTNU 无关。注册表更新由标签触发：npm version <patch|minor|major> && git push --follow-tags — version 脚本会使 server.json 保持同步，而发布工作流会运行检查套件、部署 Worker、重新发布注册表条目（GitHub OIDC），并创建 GitHub Release。

架构

所有 NTNU 上游知识——端点、重试策略、Liferay 目录解析、DBH 成绩统计和 TP 学期数据——都位于本仓库依赖的 ntnu-api TypeScript 客户端库中，该库作为 npm 包引入。上游修复和新数据源应在 ntnu-api 中实现，而不是在此处。 本仓库唯一的工作是调用该类型化客户端，并整理其输出以供 LLM 使用：英文名称（无英文时回退为挪威语）、奥斯陆当地时间戳、按学期汇总的成绩分布表，以及针对空结果的指导说明。这种分层方式详见 ntnu-api 的 TypeScript 迁移规范。

为尽量减少对 NTNU 服务器的负载，所有上游调用都采用两层缓存（共享 Workers KV 命名空间前置每个隔离实例的内存缓存），因此每项资源在全局范围内大约每个 TTL 获取一次：目录搜索、课表和日程缓存 1 小时；成绩统计和学期列表缓存 24 小时。KV 故障时会降级为仅使用内存缓存，不会导致工具报错。测试中缓存仅使用内存。

本地开发

需要 Node 22（通过 mise 固定版本）。

mise install     # installs the pinned Node version
npm install

常见任务可通过 mise 任务和 npm 脚本运行：

mise run dev          # npm run dev       — wrangler dev, local worker with hot reload
mise run test          # npm test          — vitest, over captured fixtures (no live network)
mise run typecheck     # npm run typecheck — tsc --noEmit
mise run lint          # npm run lint      — biome check
mise run fmt           # npm run fmt       — biome check --write
mise run check         # lint + typecheck + test

测试使用 vitest 在普通 Node（而非 Workers 池）下运行，直接针对从 ntnu-api 测试套件逐字捕获的 fetch 测试数据调用工具函数——CI 和本地均不会调用真实的 NTNU 服务。

部署

推送到 main 后会自动部署（本仓库已连接到 Cloudflare Workers Builds）。如需从检出目录手动部署：

npm run deploy   # wrangler deploy

运行于 Cloudflare 免费计划：MCP 会话状态由使用 SQLite 存储的 Durable Object 提供支持，该功能在免费层可用（除非规模扩大后触及每请求 CPU 限制，否则无需订阅 Workers Paid）。

许可证

MIT——详见 LICENSE。