brightspace

brightspace-mcp

📖 完整文档网站 →

适用于 D2L Brightspace 的 MCP 服务。让 Claude（以及任何兼容 MCP 的客户端）访问你的课程、成绩、作业、内容、日历等，并内置多策略身份验证、完整的 MFA 支持和生产级韧性。

---

快速开始

npx brightspace-mcp@latest setup   # interactive wizard (recommended for first time)

交互式向导会处理所有事项：基础 URL、身份验证策略、MFA、凭据存储，以及自动注册到 Claude Desktop / Cursor / Windsurf。

对于没有 TTY 的 CI 流水线或 DevContainer，请改用非交互式 init 命令：

npx brightspace-mcp@latest init \
  --base-url https://yourschool.brightspace.com \
  --strategy api_token \
  --token-ref env:BRIGHTSPACE_API_TOKEN

---

文档

深入指南位于 docs/ 中，可从 docs/README.md 开始阅读。

主题	文档
设置指南	docs/setup-guide.md
身份验证策略	docs/auth-strategies.md
已验证可用的预设（Microsoft AAD 等）	docs/presets.md
写入操作（提交、发布、评分）	docs/writes.md
MCP 工具参考	docs/tools.md
MCP 资源 + 提示词	docs/tools.md#mcp-resources
故障排除	docs/troubleshooting.md
架构（DDD）	docs/architecture.md
注册到 MCP 客户端	docs/clients.md

对于 AI 助手和贡献者，AGENTS.md 是一页式的仓库概览。

---

目录

• 安装
• 身份验证策略
• MFA 策略
• 配置参考
• 输出：时区和语言
• Redis 缓存
• 写入操作
• 可用工具
• MCP 资源
• MCP 提示词
• TUI 仪表板
• 注册到 MCP 客户端
• CLI 参考
• Docker

---

安装

npx（推荐——无需安装）

npx brightspace-mcp@latest setup   # first-time wizard
npx brightspace-mcp@latest serve   # run the server

全局安装

npm install -g brightspace-mcp
brightspace-mcp setup
brightspace-mcp serve

从源代码安装

git clone https://github.com/JhostinAleck/brightspace-mcp.git
cd brightspace-mcp
npm install && npm run build
node build/cli/main.js serve

要求：Node.js ≥ 20。

保持最新

• npx（推荐） — setup 写入的 MCP 客户端配置会运行 npx --yes brightspace-mcp@latest serve，因此每次重启客户端都会获取最新版本。无需其他操作。
• 全局安装 — npm install -g brightspace-mcp@latest（brightspace-mcp upgrade 会检查 npm 并输出相应命令）。
• Docker — 拉取最新镜像并重新创建容器。

服务每天最多检查一次 npm（超时时间为 3 秒，结果缓存于 ~/.brightspace-mcp/update-check.json）。当有新版本可用，或因安全修复导致你安装的版本已被弃用时，通知会附加到会话中的第一个工具响应里，助手会告知你。你也可以在 get_diagnostics 的 update 下查看通知。设置 BRIGHTSPACE_NO_UPDATE_CHECK=1 可选择退出检查。

---

身份验证策略

选择与你的 Brightspace 设置相符的策略。运行 npx brightspace-mcp@latest setup，它会引导你选择合适的策略。

API 令牌（最简单）

需要从 Brightspace 管理面板获取 Valence API 令牌。

profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: api_token
      api_token:
        token_ref: env:BRIGHTSPACE_API_TOKEN

export BRIGHTSPACE_API_TOKEN="your-token"
npx brightspace-mcp@latest serve

无头模式（用户名 + 密码）

自动执行 HTTP 级登录，无需打开浏览器窗口。支持所有 MFA 策略，包括 Duo Push。

profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: headless
      headless:
        login_url: https://school.brightspace.com/d2l/login
        username_ref: env:BRIGHTSPACE_USERNAME
        password_ref: env:BRIGHTSPACE_PASSWORD
        mfa:
          strategy: duo_push     # or: totp, manual_prompt, none
          duo_push: {}           # uses defaults: poll every 1s, timeout 120s

浏览器（Playwright）

启动无头 Chromium 实例并自动执行登录界面操作。最适用于登录页面包含复杂 JavaScript 的 SSO 流程（Microsoft Azure AD、SAML）。

npm install playwright && npx playwright install chromium

auth:
  strategy: browser
  browser:
    login_url: https://school.brightspace.com/d2l/login
    headless: true
    username_ref: env:BRIGHTSPACE_USERNAME
    password_ref: env:BRIGHTSPACE_PASSWORD
    selectors:
      username: "#i0116"
      password: "#i0118"
      submit: "#idSIButton9"
      password_submit: "#idSIButton9"
      mfa_input: "#idTxtBx_SAOTCC_OTC"
      mfa_submit: "#idSubmit_SAOTCC_Continue"
      post_login: "d2l-labs-navigation"
    mfa:
      strategy: totp
      totp:
        secret_ref: env:BRIGHTSPACE_TOTP_SECRET

设置向导包含一个 Microsoft SSO 预设，可自动填入所有选择器。

会话 Cookie

粘贴浏览器开发者工具中的 D2L 会话 Cookie。适用于其他策略受阻的情况。

auth:
  strategy: session_cookie
  session_cookie:
    cookie_ref: env:BRIGHTSPACE_COOKIE
    session_ttl_seconds: 3600

# Cookie format: "d2lSessionVal=XXX; d2lSecureSessionVal=YYY"
export BRIGHTSPACE_COOKIE="d2lSessionVal=...; d2lSecureSessionVal=..."

---

MFA 策略

策略	使用场景
none	账户未启用 MFA
totp	身份验证器应用（Google Authenticator、Authy 等）
duo_push	Duo Security — 服务会自动轮询，等待移动设备批准
manual_prompt	任何 TOTP/OTP — 服务会暂停并提示你粘贴验证码

TOTP 示例

mfa:
  strategy: totp
  totp:
    secret_ref: env:BRIGHTSPACE_TOTP_SECRET   # base32 secret from QR code setup
    digits: 6       # 6 or 8
    period: 30      # seconds
    algorithm: SHA1 # SHA1, SHA256, or SHA512

Duo Push 示例

mfa:
  strategy: duo_push
  duo_push:
    poll_interval_ms: 1000   # how often to check (default: 1000)
    timeout_ms: 120000       # give up after this many ms (default: 120000)

---

配置参考

完整配置文件（~/.brightspace-mcp/config.yaml）：

default_profile: my_school

profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: api_token          # api_token | browser | headless | session_cookie | oauth
      api_token:
        token_ref: env:BRIGHTSPACE_API_TOKEN
    session:
      cache_backend: memory        # memory | file | redis
      preemptive_refresh_seconds: 300

output:
  tz: America/Bogota               # IANA timezone; default: auto-detected from system
  locale: es-419                   # en-US | es-419 | pt-BR | fr-CA; default: auto-detected
  format: markdown                 # markdown (default) | plain
  include_meta_footer: true

logging:
  level: info                      # debug | info | warn | error

writes:
  enabled: false
  dry_run: false

# Optional — required when session.cache_backend: redis
redis:
  url: redis://localhost:6379
  key_prefix: "brightspace:"

凭据引用

机密值绝不会以明文形式存储。使用 ref: 语法指向实际值：

前缀	示例	说明
env:NAME	env:BRIGHTSPACE_API_TOKEN	从环境变量读取
keychain:service/account	keychain:brightspace-mcp/token	操作系统钥匙串（macOS Keychain、GNOME Keyring、Windows Credential Manager）
file:label	file:api_token	加密文件（~/.brightspace-mcp/credentials.enc，AES-256-GCM）

---

输出：时区和语言

所有工具响应都会按照你配置的时区和语言进行格式化。

output:
  tz: America/Bogota       # IANA name; default: auto-detected from system
  locale: es-419           # en-US | es-419 | pt-BR | fr-CA; default: auto-detected
  format: markdown         # markdown (default) | plain
  include_meta_footer: true

运行 brightspace-mcp setup 并选择时区和语言。也可以在 ~/.brightspace-mcp/config.yaml 中设置。

---

Redis 缓存

如需运行多个实例，或希望在重启后保留缓存，请启用 Redis：

1. 在配置中添加 redis 部分：

redis:
  url: redis://localhost:6379
  key_prefix: "brightspace:"

profiles:
  my_school:
    session:
      cache_backend: redis

2. 安装 ioredis（可选依赖）：

npm install ioredis

3. 启动 Redis 和服务：

docker run -d -p 6379:6379 redis:7-alpine
npx brightspace-mcp@latest serve

当配置中存在 redis: 部分时，域缓存（课程、成绩、作业等）会自动使用 Redis 作为持久化层。会话令牌的 TTL 根据令牌过期时间确定。

---

写入操作

写入工具（submit_assignment、post_discussion_reply、mark_announcement_read）默认处于禁用状态，需分别明确启用以下两项：

1. 配置文件：

writes:
  enabled: true
  dry_run: false   # set true to preview without mutating D2L

2. CLI 标志：

npx brightspace-mcp@latest serve --enable-writes

所有写入操作：

• 要求客户端提供 idempotency_key（8–128 个字符）。使用相同密钥重复调用时，会返回缓存的响应，而不会重新执行。
• 会生成 WARN 级别的审计日志行，其中包含关联 ID、工具名称和已脱敏的参数。
• 支持 dry_run: true，仅返回预览响应，不会对 D2L 执行任何操作。

---

可用工具

读取工具（始终可用）

工具	说明
check_auth	验证身份，并显示当前用户身份
list_my_courses	列出所有已选课程
get_my_grades	获取某门课程的成绩
get_assignments	列出作业和 Dropbox 文件夹
get_assignment_files	下载并读取教师发布的作业文件
get_upcoming_due_dates	列出未来 N 天内截止的作业
get_feedback	查看某项作业的成绩、教师评语和各评分标准的评分结果
get_assignment_rubric	显示某项作业的评分细则（评分标准、等级、分值、说明）
get_my_submissions	列出并下载你或你的小组提交的文件，即使文件夹已关闭也可查看
get_syllabus	获取课程大纲
get_course_content	浏览模块和主题（包含主题 ID）
get_topic_file	下载并读取主题内容文件（DOCX、PDF、HTML、纯文本）
get_announcements	列出课程公告（摘要、作者、附件）
get_announcement	完整阅读一则公告或其中一个附件
get_discussions	浏览讨论论坛和帖子
get_calendar_events	列出指定日期范围内的日历事件
get_roster	获取完整课程名单
get_classlist_emails	获取同学的电子邮件地址
get_my_groups	列出每门课程中的小组成员名单
list_quizzes	列出测验及其尝试次数、时限和截止日期
get_quiz_attempts	查看你参加某项测验的尝试记录，包括分数和时间戳
list_notifications	用户活动动态（公告、截止日期提醒、成绩发布）
search_course	对内容、公告和讨论进行全文搜索
get_audit_log	写入操作的本地历史记录（关联 ID、已编辑的参数）
get_diagnostics	显示缓存统计信息、断路器状态和版本信息
clear_cache	清除内存和持久化缓存后端

写入工具（需要 --enable-writes）

工具	说明
submit_assignment	将文件上传到 Brightspace Dropbox 文件夹
post_discussion_reply	回复讨论帖子
mark_announcement_read	将公告标记为已读

---

MCP 资源

Brightspace 内容的 4 个稳定 URI（任何 MCP 客户端均可通过 resources/read 读取）：

URI	内容
brightspace://{courseId}/syllabus	课程大纲，已去除 HTML
brightspace://{courseId}/content/topics/{topicId}	主题文件（从 PDF 提取文本，或回退为 base64）
brightspace://{courseId}/assignments/{assignmentId}/files	所有作业附件的文本
brightspace://{courseId}/announcements/{announcementId}	公告文本

通过 list_my_courses、get_assignments、get_announcements 等工具获取 ID。

---

MCP 提示词

MCP 客户端的提示词选择器中提供 4 个预置提示词模板：

提示词	参数	用途
weekly_briefing	无	7 天概览：截止日期、公告、近期成绩
grade_audit	course_id?	成绩分析及通过课程所需条件
study_planner	days_ahead?（默认值为 7）	根据截止日期和日历制定学习计划
course_summary	course_id（必填）	完整的课程概览

---

TUI 仪表板

brightspace-mcp tui            # launch full-screen terminal dashboard
brightspace-mcp tui --profile work  # use a specific profile

全屏交互式终端 UI（Ink + React）。通过 Tab / → / ← 导航六个选项卡：

选项卡	内容
Inicio	三列仪表板：即将到期的作业、7 天日历日程、近期公告
Cursos	实时搜索课程列表 → 深入查看课程 → 子选项卡 Tareas / Notas / Anuncios
Calendario	所有活跃课程未来 30 天的活动日程
Config	个人资料摘要、逐字段表单编辑器（从架构加载下拉选项），或可在自己的编辑器中编辑并进行验证的配置路径
Caché	命中率、未命中次数、清除按钮
Logs	审计日志（最近 50 条记录，按 / 可按工具名称筛选）

按 Ctrl+C 退出。

---

注册 MCP 客户端

请参阅 docs/clients.md 中的 Claude Desktop、Cursor 和 Windsurf 配置片段，或运行 brightspace-mcp setup，它会自动检测并为你完成注册。

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "brightspace": {
      "command": "npx",
      "args": ["--yes", "brightspace-mcp@latest", "serve"],
      "env": {
        "BRIGHTSPACE_CONFIG": "/Users/you/.brightspace-mcp/config.yaml"
      }
    }
  }
}

---

CLI 参考

npx brightspace-mcp@latest setup                      Interactive first-time setup wizard (detects system language)
npx brightspace-mcp@latest init [flags]               Non-interactive config writer (CI/scripts, no TTY)
npx brightspace-mcp@latest serve                      Start the MCP server (stdio transport)
npx brightspace-mcp@latest serve --enable-writes      Start with write tools enabled
npx brightspace-mcp@latest tui                        Full-screen terminal dashboard (Ink TUI)
npx brightspace-mcp@latest auth                       Re-authenticate and test the config
npx brightspace-mcp@latest record-auth                Open browser for manual login, capture session cookies
npx brightspace-mcp@latest doctor                     End-to-end smoke test: config → auth → API → list_my_courses
npx brightspace-mcp@latest profile list               List profiles (* marks the default)
npx brightspace-mcp@latest profile use <name>         Switch the default profile
npx brightspace-mcp@latest config show                Print config (secrets redacted)
npx brightspace-mcp@latest config show --resolved     Show all secret refs as [redacted]
npx brightspace-mcp@latest config validate            Validate config schema without running
npx brightspace-mcp@latest config set <path> <value>  Edit a nested config value
npx brightspace-mcp@latest cache clear                Clear memory + file/Redis cache
npx brightspace-mcp@latest cache clear --context <n>  Clear a specific cache context
npx brightspace-mcp@latest upgrade                    Check npm and print the upgrade command

---

Docker

独立运行

docker pull ghcr.io/jhostinaleck/brightspace-mcp:latest
docker run --rm -i \
  -v "$HOME/.brightspace-mcp:/config:ro" \
  -e BRIGHTSPACE_CONFIG=/config/config.yaml \
  ghcr.io/jhostinaleck/brightspace-mcp:latest serve

与 Redis 搭配（docker-compose）

# Start server + Redis
docker compose --profile redis up

# Or standalone (in-memory cache)
docker compose up

使用 compose 配置时，~/.brightspace-mcp/ 中的 config.yaml 必须包含 redis: 配置段，并将其指向 redis://redis:6379。

---

架构亮点

• 弹性：指数退避重试 + 抖动、断路器（失败 5 次 → 冷却 30 秒）、请求合并、舱壁模式（最多 5 个并发请求）
• 缓存层级：HTTP 响应缓存（L1，内存中，TTL 为 60 秒）+ 领域缓存（L2，分层存储：内存 → 文件或 Redis）
• 安全性：仅通过 HTTPS 传输、对所有日志输出中的机密进行脱敏、集成 OS 密钥链、使用 AES-256-GCM 加密的凭据文件、会话令牌随 D2L 令牌过期
• DDD 结构：有界上下文（assignments、authentication、calendar、communications、content、courses、grades、groups、notifications、quizzes），并清晰分离领域、应用和基础设施

---

许可证

MIT © Jhostin Aleck