# USTC School MCP

桌面客户端正迁移到 [Rust + Tauri](docs/native-desktop.md)。0.8.0 核心已处理模型配置与能力测试、上传文件校验、对话中断恢复、教务解析/排课、BB 附件与提交执行，以及青春科大查询、报名监控和系统调度。应用主后端、对话协调、确认/停止和官方人工登录也由 Rust 执行；其余站点业务仍使用固定 Python 私有管道适配器。BB、青春科大和官方登录通过 Rust CDP 操作自有 Chrome。沿用本人已有数据，详细边界与旧版计划处理见 [迁移进度](docs/rust-migration.md)。当前验收目标为 Windows，macOS/Linux/Android/iOS 尚未完成业务适配。

新增 [信息中心](docs/campus-digest.md)：公开就业/实习/宣讲与三个学院通知、已有校园来源汇总、按条件订阅、应用内及授权邮箱简报、课表/事项 ICS 导出。默认仅预览；用户选择来源和收件人后开启固定后台脚本。支持协调器 `digest` 流程，公开网页范围与运行限制见说明。

新增 [Windows 本机学校助手](docs/desktop.md)：双击 EXE 打开本机网页，在官方窗口登录学校身份和邮箱，再填写自己的模型 API 即可聊天。登录态、任务和模型密钥在本机加密保存；程序内置原有 MCP 协调工具与业务 Skill。当前为本地开发版；真实 DeepSeek 工具执行已验证。新用户仍需本人首次登录，其他模型须通过应用能力测试，邮箱自动生成密码仍有待验收范围。

可选 [学校智能体入口](docs/school-agent.md)：在已有 AI 客户端加载 `school-agent` Skill 与协调服务，按任务获取相关工具、检查参数及已有授权，并加密保存目标、调用参数和原业务记录关联。宿主 AI 负责理解用户意图，固定操作继续由原 MCP 和后台脚本完成。

**首次使用：** 下载、解压后，把文件夹交给支持本地命令和 stdio MCP 的 AI，告诉它：“读取 AGENTS.md，部署这个 MCP，带我绑定邮箱并验证连接。”AI 的入口是 [部署流程](docs/ai-setup.md) 和 [首次接入 Skill](.agents/skills/school-onboarding/SKILL.md)。用户主要参与学校登录；无需手写配置。完整账号接入当前支持 Windows + 本机 Chrome。

新增 [固定后台脚本](docs/script-workflows.md)：BB 定时提交与回执、教务一键候选排课/批次余量监控、邮箱定时发送/回复跟踪/规则归档。脚本不调用模型；选退课写接口仍待开放批次验证。

面向个人学校事务的实验性 MCP 项目。当前提供十五个独立服务及一个协调服务和项目内 [学校查询与业务预览 Skill](.agents/skills/school-services/SKILL.md)，各网站的实际支持范围见下文。适配器包括中科大邮箱、Blackboard、教务系统、图书馆、教务处网站、南七集市、评课社区、青春科大及财务平台，另有一网通办、学工、学习空间、科大云盘、Vlab 和受限公开网页读取。

Skill 包含教务、团学、BB 和图书馆的查询及办理前预览流程，具体入口和验证边界见 [业务目录](.agents/skills/school-services/references/business-catalog.md)。网页已到达的业务不等于已实现 MCP 接口；本项目不会据此自动提交申请、报名、预约或修改记录。

Blackboard、教务系统和个人图书馆共用经本人授权保存的统一身份凭据及设备信任状态，支持在对话中启动重新登录。本人启用邮箱验证后，可在学校提供对应方式时读取已接入邮箱中的本次验证码；登录、工具及验证说明见 [BB 接入说明](docs/bb.md)、[教务接入说明](docs/jw.md) 和 [图书馆接入说明](docs/library.md)。各适配器作为独立的 MCP 服务注册，共用项目代码和本地私人目录。

教务适配器支持首页、菜单、学期、已选课程、个人课表和成绩查询。课程和课表默认查询当前学期，成绩默认查询已有成绩的全部学期。还支持官方开课查询、按条件生成候选课表和选退课预检；当前没有选退课执行接口，具体边界见[业务工作流](docs/business-workflows.md)。

图书馆适配器支持个人首页统计、当前借阅、当前显示页的借阅历史，以及公共服务链接目录。旧版个人 OPAC 当前使用 HTTP，业务传输不受 TLS 保护；统一身份账号和密码仅向学校 HTTPS 认证站点提交。本地会话单独加密，OPAC 续借与馆藏预约尚未实现；西区学习空间预约由独立 spaces 模块提供，最终提交待真实需求验收。

新增网站的说明及实际验收范围：

| 网站 | 读取能力 | 说明 |
| --- | --- | --- |
| 教务处网站 | 通知分类、列表、搜索和正文 | [教务处接入说明](docs/teach.md)；区别于个人教务系统 |
| 南七集市 | 商品检索和详情，需站点登录 | [南七集市接入说明](docs/nan7.md) |
| 评课社区 | 课程、教师、社区评分及评价检索 | [评课社区接入说明](docs/icourse.md)；社区评分不等同于个人教务成绩 |

上述查询工具不产生发布；南七集市和评课社区另有准备、授权发布及结果核验工具，见[社区发布流程](.agents/skills/school-services/references/community-publishing.md)。不联系其他用户。各站点的认证范围和分页限制以对应接入说明为准。

南七集市通过其实际提供的 LUG 代理进入学校统一身份认证，复用已保存的学校设备状态；学校密码仅提交到学校 HTTPS 认证域，集市自身令牌单独加密保存。教务处和评课社区公共查询使用匿名读取；发表点评需要在本机配置独立评课账号会话。

## 浏览器运行约定

学校网页自动化默认使用 **本机 Chrome，无头后台模式**。原生客户端的 BB 提交和青春科大查询/报名由 Rust 通过 CDP 执行固定流程；原生官方人工登录也使用 Rust CDP；邮箱绑定及其他尚未迁移的网页流程继续使用 Playwright。两条路径均不依赖 Codex 内置浏览器或 Chrome 控制扩展，普通操作不创建可见 Chrome 窗口。已有邮件和 HTTP 读取接口继续使用原协议。

登录复用本人授权保存的凭据与信任设备状态，凭据和会话保存在 `.local` 并用 Windows DPAPI 加密。遇到不能自动完成的身份验证，保存 `waiting_for_verification` 进度并停止，绝不自动转为可见窗口。默认登录等待上限 240 秒；已授权的邮件验证仍最多请求一次验证码。

只有用户明确要求人工处理时，才使用对应登录命令的 `--headed` 参数打开可见 Chrome，例如 `python -m school_mcp young-login --headed`。常规 MCP 重新连接不带此参数。Python 适配器使用 `school_mcp.browser.chrome_browser`；原生适配器使用内部 Rust CDP 驱动并提供站点请求约束，不向模型开放任意 JavaScript、网址或浏览器命令。无头模式也需要安装本机 Chrome。

青春科大支持后台登录、连接检查、全校数据大屏、当前报名项目查询及已授权的普通单次线下活动定时报名。定时工具启动独立脚本监控，支持完整名称或授权关键词与开放时间匹配，候选须唯一；附加资料、作品提交及特殊报名流程未适配。启动服务：`python -m school_mcp young-serve`。见[定时报名流程与限制](docs/young-registration.md)。

0.7.0 原生报名计划直接启动 `school-core.exe`，不需要 AI 或 Python worker 持续运行。计划固定核心版本、文件摘要和账号；会话需要重新认证时停止，由用户在账号页处理。旧 0.6 原生计划须在当前应用重新复核；不得通过旧 Python 入口、删除记录或重建未知结果任务来重复报名。当前原生流程使用合成数据和后台 Chrome 验证，不能据此认定所有真实账号和项目均已验收。

## 当前能力

九个服务均提供 `school_<站点>_runtime_status`，离线检查启动时源码与当前文件是否一致。`bootstrap.py verify` 生成目标指纹，供客户端重载后核验；支持 ZIP 安装，保留已有登录状态。详见 [更新与运行版本检查](docs/runtime-updates.md)。

BB、青春科大、评课和集市提供统一参数的 `school_<站点>_tasks` 恢复入口（站点名为 `bb/young/icourse/nan7`）：分页找回当前账号已有任务，传任务 ID 后返回阶段、等待或停止原因及下一步工具参数。BB 另支持定时脚本与原提交记录的关联。查询只读本机；不会自动重启任务或重放结果不明的写操作。详见 [任务恢复流程](.agents/skills/school-services/references/task-recovery.md)。

任务列表支持短名称、存储状态与创建时间筛选；旧记录缺时间明确返回未知，不猜测。财务预检、BB 作业定位、排课和集市准备的缺项分支提供统一 `input_guidance`：字段位置、格式、信息来源及补齐后工具，供模型一次问清并保留已有参数。见 [缺项处理流程](.agents/skills/school-services/references/input-guidance.md)。

教务21个工具、集市12个工具、评课15个工具。支持候选课表、选退课预检和社区发布工作流；当前无开放选课批次，评课独立登录与两站真实发布仍待验收。完整支持范围、测试与限制见[业务工作流](docs/business-workflows.md)。

财务平台共10个工具，已验证学校统一认证及智能报销账号业务目录读取，并提供官方指南中的材料准备路线和离线预检。预检检查缺项、材料关联、金额差异及本次材料中的重复票据，供模型按固定流程补齐资料；实际填单、上传票据和报销提交仍待真实任务适配，见 [财务说明](docs/finance.md)。BB共21个工具，支持标准个人作业查找、材料冻结、授权提交及新尝试附件核验；草稿、小组和未知模板暂不支持，见 [BB说明](docs/bb.md)。

`school_jw_course_schedule` 按名称定位唯一已选课堂，读取该课堂课表与同学期同班 BB 公告，返回已确认、歧义或证据不足；实验时间不会从普通授课时段推断。教务、BB、图书馆、集市、青春科大、财务各提供 `school_<站点>_query`：在已有登录授权且明确会话失效时尝试一次后台恢复，再继续原只读查询。权限拒绝、冷却及未知错误分别停止，不重放业务写操作。参数和固定处理路线见 [课程查询与恢复 Skill](.agents/skills/school-services/references/course-schedule-recovery.md)。

| 工具 | 用途 |
| --- | --- |
| `school_mail_status` | 检查本地配置及凭据文件存在性，不解密、不联网；不是已连接证明 |
| `school_mail_setup_guide` | 首次接入或失效时返回本机步骤，不联网、不弹窗、不接收密码 |
| `school_mail_bind_status` | 查看本机自动绑定进度；密码已捕获时恢复验证，结果不明时禁止重复生成 |
| `school_mail_check_connection` | 验证登录并查询收件箱总数、未读数 |
| `school_mail_list_folders` | 列出文件夹，支持中文名称 |
| `school_mail_search` | 按未读、发件人、主题、全文、日期搜索并分页 |
| `school_mail_read` | 读取正文、邮件头和附件清单 |
| `school_mail_download_attachment` | 保存指定附件到本地私人目录 |
| `school_mail_prepare` / `school_mail_prepare_reply` | 准备新邮件或单人回复，固定内容及附件并返回预览，不发送 |
| `school_mail_list_drafts` / `school_mail_update_draft` / `school_mail_cancel_draft` | 找回本机草稿、原子替换版本、作废未发送草稿；不修改服务器草稿 |
| `school_mail_send` | 按用户授权实际发送指定草稿，同一草稿最多尝试一次 |
| `school_mail_send_status` / `school_mail_find_replies` | 查询本地发送回执、按线程查找回复 |
| `school_mail_check_sent_copy` / `school_mail_save_sent_copy` | 查询已发送副本，按保存发件记录的授权补存缺失副本，防止同一草稿重复追加 |
| `school_mail_prepare_forward` / `school_mail_prepare_reply_all` | 准备转发或回复全部，检查预览后复用发信工具 |
| `school_mail_create_folder` / `school_mail_prepare_actions` / `school_mail_execute_actions` | 创建指定目录、标已读/未读、移动及归档；先固定选择再执行 |
| `school_mail_action_status` / `school_mail_prepare_undo` | 查逐项操作记录、只读核验或准备受状态保护的撤销计划 |
| `school_mail_export` | 导出 EML 原文或可读 TXT/MD，多封自动 ZIP |
| `school_mail_get_classification_rules` / `school_mail_save_classification_rules` | 管理用户确认的类别与规则，不运行后台任务 |
| `school_mail_preview_classification` / `school_mail_prepare_classification` | 规则优先、未匹配可建议、不确定留原位，生成归档计划 |
| `school_mail_read_thread` | 按线程头收集往来与缺失证据，供代理总结 |

邮箱通过 IMAP TLS 连接 `mail.ustc.edu.cn:993`，使用完整邮箱地址和客户端专用密码。查询时只读打开文件夹，使用 `BODY.PEEK` 保留未读状态；只有明确的修改工具使用可写选择。单封邮件上限为 20 MiB，正文默认返回 6000 字符，可调整到 100000 字符。邮件搜索默认 10 封；收件人、抄送和线程头仅在 `include_headers=true` 时返回。

邮箱现有30个工具。只有“归档文件夹”及其子目录算归档；其他目录移动和已发送副本保存不计入归档。自动分类由用户整理指令触发，优先既定规则，不确定与认证邮件留原位。操作记录与分类规则加密保存，导出仅放私人目录。用法、限制和验证边界见 [邮件整理说明](docs/mail-organization.md) 与 [整理 Skill](.agents/skills/school-services/references/mail-organization.md)。

搜索结果按 UID 从大到小排列。读取和下载必须提供搜索结果中的 `mailbox`、`uid` 和 `uid_validity`，避免文件夹重新编号后读取到另一封邮件。中文搜索使用 UTF-8；服务器不支持该搜索条件时会返回提示。

邮件发送走 SMTP TLS 465，复用客户端专用密码，按“准备 → 检查 → 发送 → 查结果”的 [邮件 Skill](.agents/skills/school-services/references/mail-workflows.md) 执行。草稿和附件快照用 Windows DPAPI 加密；发送失败或结果不明不自动重试。服务器接受不等于投递成功。需要保留已发送记录时，通过独立工具先查后补存副本，不再次发信。完整合同、限制和状态解释见 [发信说明](docs/mail-sending.md)。

## 本地安装

需要 Python 3.11+ 和 uv。需要保存学校登录凭据、信任设备及站点会话的适配器目前以 Windows 为运行环境；浏览器登录还需要本机安装 Google Chrome。公共网站读取不需要登录，邮箱的非 Windows 配置见下文。下载 ZIP 不需要 Git。

```powershell
python bootstrap.py check
python bootstrap.py install
python bootstrap.py verify
python bootstrap.py config --service mail --service teach
```

## 配置邮箱

先调用 `school_mail_setup_guide`，或运行 `.venv\Scripts\python.exe -m school_mcp mail-guide` 查看步骤。完整流程、独立二次验证许可及限制见 [邮箱接入说明](docs/mail.md)。

用户选择绑定并创建一个本项目专用密码后，运行下面命令。程序打开独立 Chrome，用户在学校页面登录；程序在可识别页面上自动创建密码、加密暂存，并在 IMAP 验证通过后保存。真实页面生成与捕获仍待用户验收，不能保证所有账号只登录一次即可完成。

```powershell
.venv\Scripts\python.exe -m school_mcp mail-bind --headed --create-client-password
.venv\Scripts\python.exe -m school_mcp mail-bind-status
```

`captured` 状态使用 `mail-bind --resume`，不重复生成；`creation_attempted` 表示结果不明，停止并在本机检查。已有可用配置默认不覆盖。不会删除其他专用密码，也不会自动启用学校邮件验证码回退。详见 [邮箱接入说明](docs/mail.md)。

已有专用密码或自动页面未适配时，可用本地输入窗口填写完整邮箱地址和专用密码：

```powershell
python setup_mail.py
```

窗口会先通过只读 IMAP TLS 验证，再加密保存凭据；失败保留已有配置。输入窗口需要 Python 的 tkinter；已有支持 tkinter 的系统 Python 可直接运行此脚本，无需安装 MCP 依赖。也可以执行 `.venv\Scripts\python.exe -m school_mcp setup`，前提是该环境支持 tkinter。密码只输入本机遮罩窗口，不发送到聊天。

本地密码通过 Windows DPAPI 加密，绑定当前 Windows 用户。密文与个人账号配置保存在 `.local/`，均被 Git 忽略。运行时会重新读取配置，更新密码后无需重新安装 MCP。

非 Windows 环境可通过 `SCHOOL_MCP_LOCAL_DIR` 指定私人目录，在其中创建 `mail.json`，并设置运行进程的 `SCHOOL_MAIL_PASSWORD` 环境变量。个人地址和密码不应写入可公开的 MCP 客户端配置。

```json
{"address": "your-name@mail.ustc.edu.cn"}
```

验证真实邮箱连接：

```powershell
.venv\Scripts\python.exe -m school_mcp check
```

## 接入 Codex

在本机执行以下命令，在项目根目录运行：

```powershell
$projectRoot = (Get-Location).Path
$privateDir = Join-Path $projectRoot ".local"
$pythonExe = Join-Path $projectRoot ".venv\Scripts\python.exe"
codex mcp add ustc-mail --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" -- "$pythonExe" -m school_mcp
codex mcp add ustc-bb --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp bb-serve
codex mcp add ustc-jw --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp jw-serve
codex mcp add ustc-library --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp library-serve
codex mcp add ustc-teach --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp teach-serve
codex mcp add nan7market --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp nan7-serve
codex mcp add icourse --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp icourse-serve
codex mcp add ustc-young --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp young-serve
codex mcp add ustc-finance --env "SCHOOL_MCP_LOCAL_DIR=$privateDir" --env PYTHONUTF8=1 -- "$pythonExe" -m school_mcp finance-serve
codex mcp get ustc-mail
```

如果当前对话没有加载新增工具，在客户端重新加载 MCP 连接；是否已经就绪以实际工具列表和 `school_mail_check_connection` 调用结果为准。客户端配置方式见 [OpenAI 官方 MCP 说明](https://developers.openai.com/codex/mcp/)。

## 开发与验证

业务请求现已按服务限速，失败时进入跨进程共享冷却，遵守服务器更长的 `Retry-After`，不自动重放请求。默认返回值省略非必要身份字段，并提供详细查询参数；范围、参数和已知边界见 [请求与数据策略](docs/request-policy.md)。已运行的 MCP 进程需重新加载才会使用新逻辑。

需要一次检查全部连接时，在项目根目录运行：

```powershell
.venv\Scripts\python.exe -m school_mcp doctor
# 也可以只检查指定服务，--service 可以重复使用
.venv\Scripts\python.exe -m school_mcp doctor --service mail --service jw
```

诊断只读取当前连接，不自动登录或输出个人数据；全部可用时退出码为 0，否则为 1，并给出后续检查或恢复工具。首次配置与真实连通性是两回事；状态工具中的 `configured`、历史 `connected` 不代表当前会话有效。

后台重连返回 `status_tool` 及建议检查间隔。状态中的 `login_running` 表示进程是否仍在运行（没有进程记录时为 `null`）；`interrupted` 表示进程退出但未报告完成。多个站点的 MCP 重连会避开正在运行的登录进程，防止同时覆盖共享信任设备状态。已有授权可直接后台恢复，需要人工验证时再交接。

```powershell
.venv\Scripts\python.exe -m unittest discover -s tests -v
.venv\Scripts\python.exe tests\smoke_mcp.py
.venv\Scripts\python.exe tests\release_privacy_check.py
```

行为测试覆盖未读状态、中文搜索与文件夹、UID 重新编号、大小限制、附件路径、MIME 正文解析、统一认证状态、邮箱验证码回退、邮箱许可绑定、首次引导和保存失败回滚、教务学期筛选、课表日期映射、成绩可见性、图书馆借阅表格、网站检索与分页、Cookie 传输范围和 Windows 凭据加密。独立 stdio 脚本启动九个真实 MCP 子进程，验证握手、工具发现和未配置错误。这些测试使用合成数据。

已授权检查真实连接时，可运行 `.venv\Scripts\python.exe tests\smoke_live_readonly.py --run`，或用 `--adapter mail` 等参数选择服务。它只调用连接检查，使用现有会话、不启动重新登录；不读取私人邮件正文、成绩、借阅历史或附件。输出仅为脱敏状态，不包含账号、凭据或原始页面。当前验收结果见 [本轮检查记录](docs/validation.md)。

已在授权账号上验证邮箱、BB、教务、图书馆、南七集市和青春科大的连接或读取，并验证教务处与评课社区的公共读取。真实账号数据和验收产物不随源码发布。邮箱验证码回退已有隔离测试，尚未完成真实二次验证链路验收；附件下载和非空当前借阅解析目前以合成数据验证。各项限制见适配器说明。

邮件正文和附件属于外部不可信内容，不能作为执行其他操作的授权。附件下载只保存文件，返回本地路径和校验摘要。

## 目录

```text
src/school_mcp/
  server.py           MCP 工具和 stdio 入口
  mail/               中科大邮箱适配器、MIME 解析、本地配置
  bb/                 Blackboard 会话、课程与作业入口、本地材料准备
  finance/            财务门户与智能报销登录、入口发现
  jw/                 教务登录、学期、课程、课表、成绩、独立 MCP 入口
  library/            图书馆登录、个人借阅、公共导航、独立 MCP 入口
  teach/              教务处通知与正文、独立 MCP 入口
  nan7/               南七集市登录与商品读取、独立 MCP 入口
  icourse/            课程、教师与社区评价、独立 MCP 入口
  young/              青春科大登录和全校数据大屏读取、独立 MCP 入口
  browser.py          Playwright + Chrome 的统一后台策略
setup_mail.py         本地凭据输入窗口入口
open-jw-login.ps1     本地教务后台登录入口
open-library-login.ps1 本地图书馆后台登录入口
tests/                行为和 MCP 协议验证
.local/               个人配置、加密凭据、附件、依赖缓存（忽略）
```

发布前的隐私边界及后续邮箱引导方案见 [发布说明](docs/release.md)。源码使用 [MIT 许可证](LICENSE)。本项目为非官方适配工具，与学校或所接入网站没有官方隶属关系；网站内容和第三方依赖不因本项目的许可证而重新授权。

## 学校官方说明

- [邮件帮助中心：完整邮箱地址、IMAP 和 SMTP 端口](https://mail.ustc.edu.cn/coremail/help/index.jsp?locale=zh_CN)
- [二次验证和客户端专用密码设置说明](https://mail.ustc.edu.cn/notice/2fa/)
- [Foxmail 客户端配置说明](https://email.ustc.edu.cn/notice/foxmail/)

## 新增校园工作流

一网通办待办/进度、学工奖学金查询与优秀学生奖学金授权申请、西区学习空间计划、指定云盘目录整理和本人 Vlab 任务已接入同一智能体。奖学金申请先校验并冻结完整预览，再由固定工具填写、核对、提交和回查；未知结果不重发，其他奖学金模板暂不适配。材料支持 PDF、图片本地 OCR、Excel、DOCX 和文本，可生成可下载文件；模型设置新增科大公共模型的已有密钥绑定。真实验收与尚未验收部分见 [功能核验表](docs/functional-coverage.md)。

桌面应用另有校园网站导航、按周查看的课表和本机个人资料页。固定按钮直接调用代码，不需要模型 API；网站在浏览器新标签页打开，使用浏览器自己的登录态。课表保存加密快照并显示更新时间，个人资料由本人填写，不自动发送给模型。说明见 [本机应用](docs/desktop.md)。

已有 AI 客户端使用 agent 协调入口即可；独立注册新服务时，可用 `python bootstrap.py config --service portal --service student --service spaces --service drive --service vlab --service web`，verify 支持相同选择。新模块仍使用本人私人目录，旧 MCP 进程更新后需要客户端重载。