内容
# 亮空间 MCP
一个连接 [Claude 代码](https://claude.com/claude-code) 到 [D2L 亮空间](https://www.d2l.com/brightspace/) 学习管理系统（LMS）的 MCP 服务器。从终端浏览课程、查看作业、下载讲义和查看成绩。
包含一个 **同步技能**，自动检测和下载新课程材料到本地项目文件夹。
## 工作原理
```
Claude 代码 --stdio--> MCP 服务器 --httpx--> D2L 亮空间 REST API
|
Playwright --> Office365 单点登录（仅限登录）
```
- **登录**：Playwright 打开浏览器进行 Office365 单点登录（支持多因素身份验证）。保存 cookie 以供重复使用。
- **API 调用**：所有数据获取使用 `httpx` 通过会话 cookie 与 D2L Valence REST API 进行。
- **无需管理员权限**：与普通学生/教师帐户配合使用。
## 工具
| 工具 | 描述 |
|------|-------------|
| `login` | 通过 Office365 单点登录进行身份验证（打开浏览器，支持多因素身份验证） |
| `get_courses` | 列出所有已注册的课程 |
| `get_assignments` | 获取作业的截止日期和说明 |
| `get_assignment_attachments` | 列出作业/实验室 Dropbox 文件夹中附带的文件 |
| `get_calendar` | 跨所有课程的即将到来的事件和截止日期 |
| `get_course_content` | 浏览课程内容树（模块、文件、链接） |
| `download_file` | 将内容文件下载到本地文件系统 |
| `download_assignment_file` | 从作业/实验室 Dropbox 文件夹下载文件 |
| `get_grades` | 查看课程成绩 |
## 安装
### 要求
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) （Python 包管理器）
- [Claude 代码](https://claude.com/claude-code)
### 安装
```bash
git clone https://github.com/northprot/brightspace-mcp.git
cd brightspace-mcp
uv sync
uv run playwright install chromium
```
### 配置
在项目根目录创建 `.env` 文件：
```env
BRIGHTSPACE_URL=https://your-school.brightspace.com
BRIGHTSPACE_USER=your-email@school.edu
BRIGHTSPACE_PASS=your-password
```
### 在 Claude 代码中注册
```bash
claude mcp add -s user --transport stdio \
-e BRIGHTSPACE_URL=https://your-school.brightspace.com \
-e BRIGHTSPACE_USER=your-email@school.edu \
-e BRIGHTSPACE_PASS=your-password \
brightspace -- uv run --directory /path/to/brightspace-mcp brightspace-mcp
```
### 首次登录
首次使用任何工具时，您需要进行身份验证：
1. Claude 将调用 `login` 工具
2. 浏览器窗口打开，显示您学校的 Office365 登录页面
3. 输入您的凭证并完成多因素身份验证（如果需要）
4. 会话 cookie 保存到 `~/.brightspace-mcp/` 以供将来使用
会话通常持续 1-4 小时。服务器在启动时自动恢复保存的会话，并在 cookie 过期时发出警告。
## 同步技能
`skill/` 目录包含一个用于 **自动课程材料同步** 的 Claude 代码技能。
### 安装技能
将技能复制到您的 Claude 代码技能目录：
```bash
cp -r skill/ ~/.claude/skills/brightspace-sync/
```
### 用法
只需告诉 Claude：
- "同步我的课程"
- "检查新材料"
- "下载新的讲义"
技能将：
1. 扫描 Brightspace 获取所有课程文件 **和作业/实验室附件**
2. 与本地文件夹比较
3. 显示新增内容
4. 自动下载和组织新文件（带有文件夹名称规范化）
5. 可选地将 PPTX 幻灯片转换为 PDF
## 配置参考
| 环境变量 | 默认值 | 描述 |
|---------------------|---------|-------------|
| `BRIGHTSPACE_URL` | `https://d2l.langara.bc.ca` | 您学校的 Brightspace URL |
| `BRIGHTSPACE_USER` | — | 登录邮箱 |
| `BRIGHTSPACE_PASS` | — | 登录密码 |
| `BRIGHTSPACE_HEADLESS` | `false` | 设置 `true` 以隐藏登录浏览器 |
| `BRIGHTSPACE_SESSION_DIR` | `~/.brightspace-mcp/` | 存储 cookie 和会话数据的位置 |
| `BRIGHTSPACE_DOWNLOAD_DIR` | `~/.brightspace-mcp/downloads/` | 默认下载位置 |
## 会话管理
- cookie 保存到 `~/.brightspace-mcp/storage_state.json`
- 会话在服务器启动时自动恢复
- 如果会话在中间过期，工具将自动尝试从保存的 cookie 恢复
- 如果恢复失败，您将看到“会话已过期。调用 'login' 进行重新身份验证。”
- 当会话超过 2.5 小时时，会显示 cookie 过期警告
## 兼容性
已测试：
- 带有 Office365 单点登录（Microsoft Entra ID）的 D2L Brightspace
- API 版本：LP 1.57，LE 1.92
- Python 3.14，但应与 3.12+ 兼容
服务器使用标准的 D2L Valence REST API 端点。它应该与任何提供这些 API 的 Brightspace 实例配合使用，尽管 SSO 登录流程特定于 Microsoft Office365。
## 许可证
MIT
