# WTS-bupt-unOfficial-mcp

非官方北邮（BUPT）移动教务 **MCP（Model Context Protocol）服务**：查询**今日空教室**、**课程表**，以及两者的**联合查询**。

服务请求参考并移植自开源项目 [where_to_study](https://github.com/Nemoyuzx/where_to_study)。

> ⚠️ 本项目为**非官方**服务，仅供学习交流，请勿滥用。使用即表示你同意自行承担账号风险。

## 功能（MCP Tools）

| Tool | 说明 |
| --- | --- |
| `get_campuses` | 校区信息（西土城 01 / 沙河 04）及主要教学楼 |
| `get_classrooms` | 查询今日空教室，支持按 `campus_id` / `slot`（1-14 节）/ `building` 过滤 |
| `get_schedule` | 查询课程表，默认当前周，支持 `week`（周次）或 `date`（日期所在周） |
| `get_today_overview` | **联合查询**：今日课程 + 每节次空闲教室数 + 当前节次空闲教室 + 全天空闲教室 |

## 快速开始

### 1. 克隆与安装

```bash
git clone https://github.com/Nemoyuzx/WTS-bupt-unOfficial-mcp.git
cd WTS-bupt-unOfficial-mcp
npm install
npm run build
```

### 2. 配置账号（配置文件）

创建 `config.json`（可复制 `config.example.json` 修改），账号密码**在配置文件中设置，不再使用环境变量**：

```json
{
  "userNo": "你的学号",
  "pwd": "你的移动教务密码",
  "campusId": "01"
}
```

| 字段 | 说明 |
| --- | --- |
| `userNo` | 北邮移动教务账号（学号） |
| `pwd` | 北邮移动教务密码（与"移动教务"小程序/公众号一致） |
| `campusId` | 可选，默认 `01`=西土城；`04`=沙河 |

学期号与开学日期**无需配置**：服务会自动从课表接口响应中识别（学期 ID 取自 `semesterId`，开学日期由返回的周次与日期推算），接口无法推断时按北邮校历规律（春季 3 月初 / 秋季 9 月初）自动兜底。`config.json` 已被 gitignore，不会提交。

### 3. 直接运行

```bash
node dist/index.js
```

默认读取运行目录下的 `config.json`；也可用 `--config <路径>` 指定配置文件位置。

### 4. 接入 Claude Desktop / Cursor 等 MCP 客户端

在 MCP 客户端配置中添加（stdio 方式）：

```json
{
  "mcpServers": {
    "wts-bupt": {
      "command": "node",
      "args": [
        "/绝对路径/WTS-bupt-unOfficial-mcp/dist/index.js",
        "--config",
        "/绝对路径/WTS-bupt-unOfficial-mcp/config.json"
      ]
    }
  }
}
```

## 使用示例

问 MCP 客户端：

- 「查一下今天沙河校区第 3 节有哪些空教室」
- 「这周我有什么课？」
- 「现在哪些教室空着？」（联合查询：`get_today_overview`）

## 开发与测试

```bash
npm test        # 使用 where_to_study 的原始响应样例做解析器单测
npm run build   # 编译到 dist/
```

## 目录结构

```
src/
├── index.ts                 # MCP 服务入口（4 个工具）
├── config.ts                # 配置文件加载（config.json / --config）
├── api.ts                   # 移动教务 HTTP 客户端（登录/课表/空教室）
├── date.ts                  # 北京时区日期/周次/节次工具
├── term.ts                  # 学期参数自动识别（移植 auto-term-detection 分支）
├── parsers/
│   ├── classrooms.ts        # 空教室响应解析（移植 SJDClassroomParser）
│   └── schedule.ts          # 课表响应解析（移植 SJDScheduleParser + ScheduleLogic）
└── types.ts                 # 数据模型（Course / Classroom / 节次时刻表）
test/
└── run-tests.ts             # 单元测试（含参考项目原始响应样例）
```

## License

[MIT](LICENSE)