USTC BB MCP

让支持 MCP 的 AI 客户端读取中国科学技术大学 Blackboard 的课程、作业、公告和课件，并通过“先预览、再确认”的流程提交标准文件作业。服务运行在本机，通过 stdio 通信，每位用户使用自己的学校账号。

本项目参考 changshenhan/bb-mcp 的工具设计，独立适配中科大统一身份认证及 Blackboard 页面。项目与学校 Blackboard 官方无隶属关系。

安装

需要 Python 3.11+ 和 uv。以下以 Windows 和项目目录 D:\Project\ustc-bb-mcp 为例；macOS、Linux 使用相应的项目绝对路径。uv 可以自动安装所需 Python。

先克隆仓库，再安装锁定依赖：

git clone https://github.com/quantai1314/ustc-bb-mcp.git
cd ustc-bb-mcp
uv sync --frozen
uv run playwright install chromium
uv run ustc-bb-mcp doctor

Linux 如果提示 Chromium 缺少系统库，可以执行 uv run playwright install --with-deps chromium。这一步可能需要安装系统依赖的权限。

doctor 检查本机配置与运行环境，不访问学校网站，不显示密码或 Cookie。首次安装需要联网下载 Python 依赖和 Chromium；日常使用仍需要能访问学校 BB 和统一身份认证网站。

Related MCP server: Moodle MCP

配置与登录

优先使用系统凭据库保存密码：

uv run ustc-bb-mcp configure

按提示输入统一身份认证账号和密码。密码输入不可见，保存到当前用户的系统凭据库；config.json 只保存账号。配置完成后，工具在需要时自动登录，之后复用本地会话；会话失效时自动尝试重新登录一次。

如果学校要求验证码、二次认证，或系统凭据库不可用，执行：

uv run ustc-bb-mcp login --browser

在打开的独立浏览器中完成学校认证，等待命令确认登录成功。这里使用项目专用的浏览器配置，不读取日常 Chrome、Edge 的会话。只使用浏览器登录也可以运行查询和提交工具；会话失效后需要再次执行此命令。

系统凭据库不可用时不会自动把密码写入明文文件。也可通过运行服务进程的环境变量提供账号密码，适合已有安全配置环境的用户：

环境变量中的密码不会由本项目写入配置文件。不要把密码加入仓库、共享的 MCP 配置示例或聊天消息。

接入 MCP 客户端

将 examples/mcp.json 中的 mcpServers 条目加入客户端配置。按实际位置替换项目路径；如果客户端找不到 uv，将 command 换成 uv 可执行文件的绝对路径。

{
  "mcpServers": {
    "ustc-bb": {
      "command": "uv",
      "args": [
        "--directory", "D:\\Project\\ustc-bb-mcp",
        "run", "--frozen", "ustc-bb-mcp", "serve"
      ]
    }
  }
}

客户端需要以完成配置的同一系统用户运行。如果配置时指定了 BB_DATA_DIR，启动 MCP 的环境也要设置相同值。保存配置后，按客户端要求重启或重新连接服务。

服务的 stdout 仅用于 MCP 协议，日志写入 stderr。直接运行 uv run ustc-bb-mcp serve 后等待标准输入属于正常行为；交互式诊断请使用 doctor。

9 个工具

课程与作业支持准确 ID、完整名称或唯一名称关键词。命中多项时会返回候选，不会自动选择第一项；后续调用请使用准确 ID。

工具带有 MCP 注解：查询类工具标记为只读，下载类工具只写本机磁盘，bb_submit_assignment 是唯一会向 BB 写入的工具，客户端可据此决定是否弹出确认。课程列表和课程内容扫描结果在同一进程、同一登录身份内默认复用 60 秒，course="all" 的查询会并发读取各门课程；作业状态、公告正文和提交表单每次都实时读取。

可以向客户端提出这些请求：

• “列出我的课程，检查所有课程的作业提交状态，并附上原始链接。”

• “查看数据结构最近的作业要求，并把附件下载下来。”

• “下载电磁学课程最新的两份 PDF 课件。”

• “读取所有课程最近的公告，整理与考试有关的信息。”

公告总结由使用工具的 AI 客户端完成。本项目不提供定时提醒、跨课程全文索引、教师批改或自动答题。

如何理解查询结果

每次结果包含可读说明和结构化数据，附查询时间。complete=false 表示有页面读取失败或扫描被截断；warnings 说明不完整的原因。部分失败不会被当成“没有作业”或“已交齐”。

作业状态区分 not_submitted（未提交）、draft（草稿）、submitted（已提交）、graded（已评分）和 unknown（无法确认）。草稿不算已提交；零分仍属于已评分。缺失的日期返回空值，不根据文件名推测截止时间。

文件有明确日期时按新到旧排序，无日期文件排在后面。下载返回本机实际路径，按课程组织；重名文件不会直接覆盖，同大小但内容不同的文件不会被误判为重复。网页、附件或未知结构与预期不符时，工具会返回错误或不完整提示。

提交作业

提交工具只处理 Blackboard 标准文件作业，上传一个本地文件并可附评语。测试、考试、自动答题及教师端操作不在此工具支持范围内。

1. 使用 confirm=False 调用，检查返回的账号会话、课程、作业、已有提交、文件路径、大小、SHA-256、评语和平台允许的提交条件。已交且允许重交时，starts_new_attempt=true 表示确认后会创建新尝试。预览阶段不创建尝试、不上传文件，也不点击开始测试或提交按钮。

2. 用户确认具体目标和文件后，使用相同参数、confirm=True 及返回的 preview_token 调用。令牌 10 分钟内有效，并绑定账号会话、目标、文件内容、评语和提交条件；文件或目标改变时需要重新预览。重交会先创建新尝试，再核对新表单后上传。

3. 工具提交后有限次数只读回查提交历史，并重新下载提交附件核对 SHA-256；只有目标、尝试记录及附件内容核验通过才报告成功。若表单预先分配了尝试 ID，回读必须对应同一次尝试，旧尝试不能证明重交成功。回查不会重放 newAttempt 或提交动作。平台另换尝试 ID、附件无法回读等无法证明的情况返回“结果待确认”，应查看 BB 网页，不要立即重复提交。

开发和演示阶段不会自行向真实课程提交。需要实际提交验证时，应由用户明确指定作业和文件，并通过上述预览确认流程。

本地数据

未设置 BB_DATA_DIR 时，使用 platformdirs 返回的当前用户数据目录：Windows 通常在 %LOCALAPPDATA%\ustc-bb-mcp，macOS 在 ~/Library/Application Support/ustc-bb-mcp，Linux 在 ~/.local/share/ustc-bb-mcp。

其中 config.json 保存账号配置，session.json 保存登录会话，browser-profile/ 保存人工登录使用的独立浏览器配置。密码存于系统凭据库或仅由环境变量提供。下载默认进入用户下载目录下的 USTC-BB，可用 BB_OUTPUT_DIR 更改。会话与下载内容留在本机，工具读取到的课程信息会返回给调用它的 MCP 客户端。

常见问题

开发与验证

本地检查与 CI 执行相同的步骤；具体通过情况和真实环境验证记录见 VALIDATION.md。

uv sync --frozen
uv run playwright install chromium
uv run ruff check .
uv run pytest -q
git diff --check
uv build

仓库通过 .gitattributes 统一使用 LF 换行。Windows 编辑器如果把文件改成 CRLF，git diff 会显示整文件改动，请在提交前恢复 LF。

自动化测试使用虚构页面、模拟响应和本地测试站，不需要学校账号，也不会访问真实课程或提交作业。测试覆盖页面解析、状态判定、附件下载、认证边界、MCP 协议以及提交预览与回执处理。CI 配置了 Windows、macOS、Linux 与 Python 3.11、3.13 的验证矩阵；远端执行结果以实际工作流为准。

真实 BB 验证状态：已完成项目独立浏览器登录，并通过真实 MCP 验证会话、课程列表、两门课程样本的文件/作业/公告、PDF下载与去重、作业详情及提交预览。后续在用户明确授权下，通过真实 stdio MCP 完成一次标准文件作业重交，回读新尝试及附件 SHA-256 与本地文件一致。初次只读验收的 83 次 GET、0 次写入统计不包含后续实际重交。真实密码自动登录分支尚未验证。详见 验证记录。

授权与来源

本项目采用 MIT License。工具设计参考和第三方依赖说明见 THIRD_PARTY_NOTICES.md。