内容
# usp-mcp
MCP（模型上下文协议）服务器，用于圣保罗大学的学生系统——Moodle（e-Disciplinas）、JupiterWeb、成绩、缺勤、时间表和任务——使用[Heidy后端](https://github.com/iDavi/heidy_backend)作为安全访问层。
使用它，助手（Claude Desktop、Claude Code或任何MCP客户端）可以回答诸如“这周我在Moodle上有什麼活动？”，“我的ACH2034课程成绩怎麼样？”或“帮我安排时间表”。
## 工作原理
```
客户端MCP ──stdio/HTTP──▶ usp-mcp (Python/FastAPI) ──HTTPS──▶ Heidy后端 ──▶ Moodle / JupiterWeb
```
- **密码永远不会以明文形式传输。** 登录时，服务器会查找后端的当前公钥（`GET /auth/login-key`），并使用HPKE-Base（X25519，HKDF-SHA256，AES-256-GCM）加密唯一密码。只有后端才能解密它，并且登录后密码不会在该过程中任何地方保留。
- **会话仅存在于内存中。** 登录返回一个 bearer token 和一个 credential blob（后端只能解密的密文）；它们都存储在进程的内存中，注销时会被丢弃。
## 安装
```bash
pip install . # 或：pip install -e .[dev] 进行开发
```
## 使用
### stdio（Claude Desktop / Claude Code）
```bash
usp-mcp
```
适用于Claude Desktop/Code的配置（`mcpServers`）：
```json
{
"mcpServers": {
"usp": {
"command": "usp-mcp"
}
}
}
```
### HTTP（FastAPI + Streamable HTTP）
```bash
usp-mcp --http --port 8000
# 或直接：
uvicorn usp_mcp.app:app --host 0.0.0.0 --port 8000
```
- MCP端点：`http://localhost:8000/mcp`
- 健康检查（此服务和后端）：`http://localhost:8000/health`
### 环境变量
| 变量 | 影响 |
| ----------------- | ------------------------------------------------------------ |
| `HEIDY_BASE_URL` | 替代后端（默认：`https://heidy-backend.fly.dev`） |
| `HEIDY_USERNAME` | 自动登录第一个工具的USP编号 |
| `HEIDY_PASSWORD` | 唯一密码用于自动登录 |
| `HEIDY_DOWNLOAD_DIR` | `moodle_download_file`的默认目录（默认：`./downloads`） |
如果没有`HEIDY_USERNAME`/`HEIDY_PASSWORD`，请先调用`usp_login`工具。
## 工具
| 工具 | 功能 |
| ---------------------------------------- | ------------------------------------------------------------ |
| `usp_login` / `usp_logout` | 使用USP编号和唯一密码打开/关闭会话 |
| `get_profile` | 学生资料 |
| `moodle_courses` | e-Disciplinas课程列表 |
| `moodle_course` | 课程内容（活动，材料） |
| `moodle_activity` | 通过URL打开活动（内容，链接，文件元数据） |
| `moodle_download_file` | 从Moodle下载文件（PDF，幻灯片，...）到磁盘（最多10 MB） |
| `usp_sync` / `usp_sync_status` / `usp_sync_history` | 同步时间表，成绩，缺勤和Moodle的JupiterWeb |
| `list_semesters` | 学生学期列表 |
| `get_schedule` | 学期时间表 |
| `list_enrollments` | 选课记录（班级），时间和教师 |
| `list_grades` / `grade_summary` | 成绩和加权平均值/批准状态 |
| `list_absences` / `absence_summary` | 缺勤和与限制的比较 |
| `list_tasks` / `create_task` / `update_task_status` | 计划任务（考试，提交，阅读） |
## 开发
```bash
pip install -e .[dev]
pytest
```
测试涵盖了加密信封方案（与后端的vault兼容），HTTP客户端（使用模拟后端）和MCP工具接口。
