# chaoxing-mcp — 让 AI 连接你的学习通

**再也不用自己一遍遍刷学习通查作业了。**

把这个 MCP 装进你的 AI 助手（Claude Desktop / ZCode / Codex 等都行），然后你只需要说人话：

> "我还有啥作业没交？"
> —— 0.3 秒后：实验2（第3周）简单优化模型，未交，剩 138 小时；实验1 已交待批阅。

以前你得：打开浏览器 → 登录 → 点课程 → 点作业 → 一门一门翻。现在一句话的事。

## 它到底能干嘛？

给学生的话术版：

- 📋 **查作业**："还有什么没交"、"数模课作业截止时间"、"这周要交啥" —— AI 直接回答，不用你登录翻页面
- ⏰ **防漏交**：让 AI 每天扫一遍全部课程，快到期的作业主动提醒你
- 📖 **读要求**：作业详情页的题目要求、提交格式，AI 直接拉原文给你讲
- ✍️ **写作业**（配合配套 skill）：AI 读题目 → 写代码/答案 → 生成报告 → 传附件 → 暂存草稿，**你只负责最后检查一遍、点一下提交**

一句话总结：**查作业、盯截止这种体力活全自动；写作业 AI 打草稿你把关；提交按钮永远在你手里。**

## 为什么选这个，而不是自己写脚本或用别的工具？

| | 浏览器自动化脚本 | 网上的签到/查分类工具 | **chaoxing-mcp** |
|---|---|---|---|
| 查一次作业 | 1~2 分钟 | 看工具 | **0.3 秒（实测）** |
| 要开浏览器 | 要，还抢你电脑前台 | 部分要 | **完全不用** |
| 登录掉线 | 经常，得重新扫码登录 | 看工具 | **cookie 落盘，重启都不掉** |
| 登录加密参数 | 自己抓包逆向 | 自己折腾 | **已经逆向好了，开箱即用** |
| 接入 AI 助手 | 要自己粘代码 | 基本没有 | **标准 MCP 协议，装上就能对话** |
| 代码量 | 上千行 | 未知 | **单文件 ~400 行纯 Python，零框架** |

几个实在的卖点：

1. **快到离谱**。不走浏览器、不发截图、不渲染页面，直接跟学习通服务器说 HTTP。实测 36 门课列表 0.3 秒、作业列表 0.35 秒（浏览器方案 1~2 分钟起步）。
2. **登录这关已经替你趟平了**。学习通网页登录的手机号和密码都要过一层 AES 加密，参数藏在它们的 JS 里——这里已经逆向完成并封装好，你装完就能用，不用碰一行密码学。
3. **掉线焦虑没了**。登录态持久化在本地文件里，AI 助手重启、电脑重启，回来还是登录状态，掉了也会自动重登。
4. **就一个文件**。没有 SDK 依赖、没有构建步骤，`server.py` 拖进任何 MCP 客户端配置就能跑。想改？400 行读一遍就会了。
5. **账号只在你电脑上**。没有任何中间服务器，账号密码从你本机读、请求从你本机发。
6. **不是孤军奋战**。配套的 [xuexitong-skill](https://github.com/Han-maker-wp/xuexitong-skill) 提供完整的浏览器端能力（AI 作答、课件下载、附件上传），两者组合就是学习通全自动流水线。

## 🤖 最省事的安装：让 AI 自己给自己装

**你不需要看下面的安装教程。** 把这句话复制给你的 AI 助手（ZCode / Claude / Codex 都行）：

> 帮我接入 chaoxing-mcp：https://raw.githubusercontent.com/Han-maker-wp/chaoxing-mcp/main/AGENTS.md

AI 会读取这份[专门写给它的安装指南](AGENTS.md)，自动完成下载代码、装依赖、写配置、验证连通的全过程——你只需要提供账号密码，然后重启一次客户端。

之后你对它说"我还有啥作业没交"就行了。装坏了也是 AI 自己修，不劳烦你。

## 安装（手动版，给喜欢自己动手的人）

Python 3.10+，装两个依赖：

```bash
pip install requests pycryptodome
```

在 MCP 客户端配置里注册：

```json
{
  "mcpServers": {
    "xt": {
      "command": "python",
      "args": ["-u", "/path/to/chaoxing-mcp/server.py"],
      "env": { "XT_PHONE": "13800000000", "XT_PASSWORD": "yourpassword" }
    }
  }
}
```

账号也可以不写 env，改放一个 markdown 文件（详见 AGENTS.md 的"步骤 4"）。

## 工具一览

| 工具 | 干什么 | 风险 |
|------|--------|------|
| `xt_homework(course)` | 一门课的作业：标题、状态、剩余时间、详情链接 | 🟢 只读 |
| `xt_homework_all` | 扫全部课程，汇总未交作业 | 🟢 只读 |
| `xt_courses` | 列出全部在读课程 | 🟢 只读 |
| `xt_page_text(url)` | 读任意学习通页面的正文（带登录态） | 🟢 只读 |
| `xt_seed_enc` / `xt_login` | 一次性配置工具（见下） | 🟢 |

## enc 参数：装完只差这一步

作业列表接口需要每门课一对 `stuenc/enc` 参数（学习通的防爬设计）。它们不出现在任何页面源码里，但实测**按课程+学生是固定值**，所以只需配置一次、永久有效：

1. 浏览器登录学习通，进某门课 → 作业标签
2. 从作业列表页 URL 里抄下 `stuenc=...` 和 `enc=...`
3. 对 AI 说："帮我把这门课的 enc 配置一下"（调 `xt_seed_enc`）

之后这门课就永久可查了。`xt_courses` 会标出哪些课已配置。

## 它是怎么工作的

```
你: "还有啥作业没交？"
  ↓
AI 助手 ──调用 xt_homework──▶ chaoxing-mcp（本地进程）
                                  │ ① 读本地 cookie（掉了就自动 AES 加密重登）
                                  │ ② 带cookie直连 mooc1.chaoxing.com
                                  ▼
                            学习通服务器
                                  │ ③ 返回数据，解析成纯文本
你 ◀──"实验2 未交，剩 138 小时"────┘
```

登录加密细节（逆向自学习通自己的 login.js）：手机号和密码都用 **AES-CBC** 加密（key = iv = `u2oh6Vu^HWe4_AES`，PKCS7，Base64）后 POST 到 `/fanyalogin`。全程本地完成。

## 老实说的部分

- 目前**只有查询类工具**：上传附件、暂存草稿、课件下载走配套 skill 的浏览器方案，后续版本会搬进来
- 学习通如果触发验证码/双因子，需要人工过一次
- 学习通改版接口时需要更新解析（单文件，改起来快）
- 请保持正常使用频率；本工具只做单发低频请求

**设计哲学：AI 只做辅助，提交权永远在人。** 本工具刻意不提供"提交作业"能力。

## License

MIT