内容
# ntnu-mcp
一个远程 [MCP](https://modelcontextprotocol.io) 服务器，提供挪威科技大学（NTNU）课程数据给LLM助手；课程目录搜索、教学安排、每周时间表和成绩统计，以及两个用于学生选择课程的比较工具。在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、教学周、考试期日期和当前学期。
- **`compare_courses`** — 多门课程的并排比较：名称、校区、考试日期、每周教学时间和最新成绩分布。
- **`check_timetable_conflicts`** — 在注册课程之前，对一组课程的每周时间表冲突和考试日期冲突进行成对检查。
## 连接
将服务器的MCP URL粘贴到Claude或ChatGPT的自定义连接器设置中：
```
https://ntnu-mcp.martinsundal.no/mcp
```
服务器不需要身份验证，因为它只提供公共的只读NTNU课程数据。
## 架构
所有NTNU上游知识 — 端点、重试策略、Liferay目录解析、DBH成绩统计和TP学期数据 — 都存在于[`ntnu-api`](https://github.com/MartinSA04/ntnu-api) TypeScript客户端库中，该库作为npm包依赖于此仓库。**上游修复和新的数据源位于`ntnu-api`中，不在此处。** 此仓库的唯一任务是调用该类型化客户端并为LLM使用而塑形其输出：英文名称带有挪威语备用、奥斯陆本地时间戳、成绩行折叠为每个学期分布表，以及空结果的指导说明。此分层结构在`ntnu-api`的[TypeScript迁移规范](https://github.com/MartinSA04/ntnu-api/blob/main/docs/ts-migration-spec.md)中有所描述。
为了尽量减少NTNU服务器的负载，每个上游调用都缓存了两层（隔离内存前置共享Workers KV命名空间），因此每个资源在全局范围内大约每TTL（生存时间）获取一次：目录搜索、时间表和课程安排为1小时；成绩统计和学期列表为24小时。KV故障降级为仅内存缓存，从不导致工具错误。在测试中，缓存仅在内存中运行。
## 本地开发
需要Node 22（通过[mise](https://mise.jdx.dev/)固定）。
```sh
mise install # 安装固定的Node版本
npm install
```
常见的任务，既可作为mise任务，也可作为npm脚本：
```sh
mise run dev # npm run dev — wrangler dev，带有热重载的本地worker
mise run test # npm test — vitest，基于捕获的fixtures（无实时网络）
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
```
测试在普通Node（非Workers池）下使用vitest运行，直接驱动工具函数针对从`ntnu-api`测试套件中捕获的fixtures（原样）— 在CI或本地环境中，不会调用真正的NTNU服务。
## 部署
推送到`main`分支会自动部署（该仓库连接到Cloudflare Workers Builds）。从checkout手动部署：
```sh
npm run deploy # wrangler deploy
```
在Cloudflare的免费计划上运行：MCP会话状态由Durable Object使用SQLite存储支持，在免费层级上可用（无需Workers付费订阅，除非按需CPU限制达到大规模）。
## 许可证
MIT — 请参见[LICENSE](LICENSE)。
