# STU MCP

这个项目的前身，是我在「养」Hermes agent 时，从零搭起来的一个自用信息聚合器。学校通知、课程、作业，散在不同地方的信息，我都想慢慢接进去。自己用的版本里，甚至还接入了微信聊天记录。

我折腾它的原因，是希望 agent 在帮我做事时，能拿到足够的个人上下文：我最近在忙什么、有什么通知要看、哪些事情还没做完。和我有关的信息，如果它能在需要时自己查到，我就能少重复一些背景，也不用总在几个网站和聊天窗口之间来回复制粘贴。

后来，我把里面和汕大有关的部分整理成了 STU MCP，想让其他同学也能接到自己常用的 agent 上。它负责找信息、读信息，怎么理解和整理，交给你自己的 agent。

微信聊天记录接入留在自用版本里，公开版不包含。用这里的功能也不需要先装 Hermes，或者另外配一份模型 API key。

## 想试试的话

找一个能在你电脑上执行命令的 agent，把这两行发给它：

```text
帮我安装 STU MCP：https://github.com/0error0warning/stu-mcp
按 docs/install.md 接入当前客户端，保留已有配置并验证公开查询。按安装版本说明登录；认证信息由我本人输入，不发给 agent。
```

[单独复制这段 prompt](install-prompt.txt) · [安装细节](docs/install.md)

装好以后，可以直接问它：

- “最近有什么适合我报名的竞赛？把截止时间和原文找出来。”
- “整理一下 MySTU 接下来两周的作业，按截止时间排一排。”
- “树洞里有人聊过这门选修课吗？搜一下大家怎么说。”

## 现在能查些什么

| 功能分类 | 来源与系统 | 当前接入范围 | 登录方式 |
| --- | --- | --- | --- |
| 通知与活动 | 学校官网、学生处、OA 公告 | 新闻、通知、活动、正文、附件列表及 PDF / 文本附件内容 | OA 原站可达且内容公开时免登录；WebVPN 访问通道按需，见[读取范围与条件](docs/verification/2026-10-22-oa-entry-boundaries.md) |
| 课程与教务 | 教务、MySTU / Moodle、雨课堂、对分易 | 成绩、考试、本人理论课表、课程、作业、资料、个人日程；对分易课程监听、启停及签到结果，新课堂提交仍待实测 | 教务与 MySTU 使用学校 SSO；雨课堂手机确认二维码；对分易原微信回调，各自保存会话 |
| 校园办事 | 宿舍报修、综合报修、一网通办等 | 桑浦山宿舍 `repair` 支持填表、完整预览、本人确认后单次提交及回执核对；综合报修 `r`、一网通办目前提供入口导航 | 宿舍报修使用学校 SSO，单独保存会话；其他入口按原站要求 |
| 一卡通本人查询 | 学校一卡通系统 | 卡余额和状态、指定日期及类型的历史流水；不挂失、充值或改密 | 独立查询密码和本人填写的图片验证码；官方入口为明文 HTTP |
| 网络访问与排障 | 登记的学校入口及认证依赖 | 单服务连接诊断、学校入口批量检测：检查 DNS、匿名直连，按需对照代理或公共 DNS | 免登录；不改变网络设置，不代表业务已可用 |
| 第三方校园生活与社区 | 充电平台、STU 外卖（开发中）、狐友 | 设备与插座状态、外卖目录 / 配送批次 / 选餐、树洞公开帖子及评论；外卖不下单或支付 | 充电和公开讨论免登录；外卖需单独配置 |
| 软件与本地管理 | stu-mcp 宿主及本地数据 | 安装接入、登录配置、更新检查与升级、本地待办和个人偏好 | 按需配置 |

选择登录配置时，可先看[配置哪些登录，当前能用哪些功能](docs/campus-services.md#配置哪些登录当前能用哪些功能)：学校统一账号对应已适配的教务、MySTU 和宿舍报修；雨课堂、对分易、WebVPN 及第三方配置各有自己的功能范围，公开内容按条件免登录。同目录另列学校服务的入口和未接入项，不将“学校有这个系统”算成“MCP 已能使用”。

设置页、`stu-mcp status` 和 MCP `get_capabilities` 使用同一份功能目录，告诉你配置后能做什么、哪些服务还没接入。学校统一账号输入一次，分别连接已接入的教务、MySTU 和宿舍报修；各业务仍独立保存会话，某项未完成会单独说明。

也可以记一下本地待办，或者告诉 agent 你的学院、专业和兴趣。它们都不是必填项，本地勾选“完成”也不会替你向学校提交作业。

查到的信息会带来源和缓存时间。想看最新消息时，让 agent 先刷新；没查到也可能只是这次没取全。狐友里是同学们的讨论，学校的正式要求还是要看 OA 或学校原文。[狐友怎么查](docs/huyou.md)

本版包含充电查询，由本机 MCP 直接请求充电平台，按设备缓存，没有网站或自建服务器依赖。现有清单包含 14 台已核验设备，不代表全校完整清单；离线和旧数据会单独标记。[充电查询用法](docs/charging.md)

校园连接按服务处理：r和一网通办先查自身入口，宿舍报修需要时核实校园接入，SSO和ITS各协议独立判断。同属网络排障的两个工具保留各自范围：单服务诊断定位一个入口及其依赖，批量检测比较固定目录；校园入口普查并不会自动扩充运行时探测清单。普通读取复用连接，同批次暂时跳过连接失败的主机，继续读取其他来源，不自动改代理或接入远程隧道。[单服务诊断](docs/network.md) · [批量检测](docs/network-audit.md)

## 自己动手安装

先装好 [uv](https://docs.astral.sh/uv/getting-started/installation/)，然后运行。这里以 Codex 为例：

```sh
uv tool install --python 3.12 https://github.com/0error0warning/stu-mcp/releases/download/v0.7.1/stu_mcp-0.7.1-py3-none-any.whl
stu-mcp connect codex --apply
```

第二行换成你用的客户端，比如 `claude-code` 或 `cursor`。其他客户端、豆包工作和 Skill 的接法放在[这里](docs/clients.md)。v0.6.1 起，运行 `stu-mcp update` 即可检查并升级；只想看有无新版用 `stu-mcp update --check`，也可以让 agent 调用对应更新工具。升级后，本机 stdio 重新加载 MCP；私有 HTTP 须重启宿主 MCP 服务。旧版首次升级见[安装说明](docs/install.md#从旧版升级)，支持范围见[更新说明](docs/updates.md)。

MCP 接入和技能安装分别处理。随包的[课表导出技能](docs/timetable.md)组织校历核对和文件转换。v0.7.1 加入教务本人理论课表读取，继续复用该技能和同一转换器；实验课、校历及作息另行核对。技能 ZIP 是可选资源包，生成后仍需按客户端支持的方式安装，不会自动让当前 agent 加载技能。

需要登录时，让 agent 打开设置页，或自己运行 `stu-mcp setup`。在自己的浏览器里配置学校统一账号、雨课堂、对分易、WebVPN 或一卡通，认证信息不经过 agent。WebVPN 可填写已有令牌密钥，由程序生成动态码并自动登录；不配置密钥也能手动输入当前动态码。喜欢终端可用 `stu-mcp login school` 等命令，完整用法见[认证说明](docs/authentication.md)。

本机 stdio 与个人服务器私有 Streamable HTTP 共用一套工具。CLI 与设置页共用 HTTP 认证核心，默认安装和 Docker 模板不需要桌面或 Chromium；无桌面服务器可以完整使用 CLI。会话及个人缓存加密保存，普通学校密码只用于本次认证。客户端到 MCP 和 MCP 到学校是两段网络，连上服务器不代表服务器能访问校园网。[服务器说明](docs/server.md) · [存储与隐私](SECURITY.md)

本版包含对分易后台和轻量本地网页：选课、启停监听、查询签到结果，微信回调可在宿主终端或本地网页完成。MCP 退出后后台继续运行，状态明确区分未启动、未登录、已暂停、监听中和查询异常。支持持续监听；电脑需保持运行和联网。新的课堂自动提交仍待实测。[安装与用法](docs/checkin.md)

宿舍报修使用独立 HTTP 会话填表，完整展示实际表单，等你明确确认后只提交一次。随后核对新增单据及详情，返回单号、处理状态和核对时间；结果未知时只读查单。草稿留在进程内存，登录会话独立加密保存。当前适配桑浦山学生社区；新版真实登录和填表预览已核验，正式提交仍由合成与回环测试覆盖，没有为验收额外建单。校园网报修是另一套入口。[使用与验证范围](docs/repair.md)

喜欢用终端的话，也可以直接查：

```sh
stu-mcp refresh oa --limit 20
stu-mcp query notice --source oa --search 竞赛
stu-mcp huyou search 选课
```

## 还在慢慢补

本轮准备 **[v0.7.1 学生预览版](docs/releases/v0.7.1.md)**，发布状态以 GitHub 发行页为准。本版加入本人理论课表与一卡通只读查询，共 50 项 MCP 工具；已有接口保持兼容，继续以 GitHub prerelease 发布。[发行说明](docs/releases/v0.7.1.md) · [最近更新](CHANGELOG.md)

正式 HTTP 适配器已实测教务、MySTU 的身份与课程、ELC/Campus 的部分业务、雨课堂课程活动，以及报修登录和完整预览。WebVPN 的密码、动态口令和资源目录通过；受保护 OA 正文及自然过期续登尚未通过本轮验收。发行 CI 包含跨平台测试和默认镜像离线检查，容器内学校业务、跨机接入、更多账号和真实新报修提交仍分别待验，详见[验证记录](docs/verification.md)。

如果你用起来了，或者发现某个入口读不动了，欢迎开 issue 聊聊。告诉我用的版本、卡在哪一步就很有帮助，别把真实成绩、密码或登录凭据贴进去。

想自己改也可以：

```sh
uv sync --extra dev
uv run --extra dev pytest -q
uv run --extra dev ruff check .
uv run stu-mcp setup
uv run stu-checkin
uv build
```

[文档目录](docs/README.md) · [更新记录](CHANGELOG.md) · [代码结构](docs/architecture.md) · [代码来源](docs/provenance.json)

MIT 许可。个人折腾的小项目，和学校官方没有关系。