内容
# GDMU MCP Server
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](https://playwright.dev/)
[](https://pypi.org/project/gdmu-mcp/)
AI 助手（Codex / Claude Desktop / Cursor 等）与正方 V-9.0 教务系统的 MCP 桥梁——15 个工具覆盖教务全场景。
> 🎯 专为 **正方 V-9.0 + CAS 单点登录 + MFA 多因子认证** 设计。
---
## 目录
- [快速开始](#快速开始)
- [工具列表（15 个）](#工具列表15-个)
- [配置说明](#配置说明)
- [AI 客户端集成](#ai-客户端集成)
- [部署](#部署)
- [开发指南](#开发指南)
- [项目结构](#项目结构)
- [许可证](#许可证)
---
## 快速开始
```text
浏览器登录（CAS+MFA）→ 保存 jw_session.json → MCP Server 启动 → AI 客户端连接
↓
15 个工具可用
6 查询 + 4 分析 + 4 信息 + 1 登录
适配正方 V-9.0 接口
```
**一句话流程**：先用浏览器完成 CAS 统一认证（含短信/微信等二次验证），把 Session Cookie 持久化到本地，MCP Server 启动后自动加载 Cookie 调用教务 API，AI 客户端通过 MCP 协议与工具交互。
### 前置条件
- Python 3.10+
- 能访问学校内网 / VPN / aTrust
- 拥有教务系统账号 + 可用浏览器
- [Playwright](https://playwright.dev/) + Chromium 浏览器引擎
### 1. 安装
```bash
# 从 PyPI 安装（推荐）
pip install gdmu-mcp
# 或从源码安装
git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e .
```
### 2. 浏览器登录
```bash
# 自动打开 Chrome，完成 CAS 认证（含 MFA）
# 登录成功后自动保存 Cookie 到 jw_session.json
python browser_login.py
```
过程中浏览器会打开 CAS 登录页，输入账号密码后如遇短信验证码 / 微信扫码等二次认证，正常完成即可。脚本会自动检测登录成功并提取 Cookie。
### 3. 启动 MCP Server
```bash
# 标准启动
python server.py
# 指定调试模式
GDMU_DEBUG=1 python server.py
```
### 4. 配置 AI 客户端
#### Codex CLI / Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"gdmu-mcp": {
"command": "python",
"args": ["path/to/gdmu_mcp/server.py"],
"env": {
"GDMU_JW_BASE": "https://jw.gdmu.edu.cn",
"GDMU_AUTH_BASE": "https://authserver.gdmu.edu.cn"
}
}
}
}
```
#### Cursor
在 Cursor 的 MCP 配置中添加 stdio 服务端。
---
## 工具列表（15 个）
### 核心查询（6 个）
| 工具名 | API 端点 | 功能 | 参数 |
|--------|----------|------|------|
| cj_tool | /cjcx/ 成绩查询 | 按学期查成绩 | xnm, xqm（可选） |
| kb_tool | /kbcx/ 课表查询 | 按学期查课表 | xnm, xqm |
| ks_tool | /kwgl/ 考试查询 | 考试安排/时间/地点 | xnm, xqm |
| grxx_tool | /xsxxxggl/ 学籍查询 | 完整学籍 34 字段 | 无 |
| xsxyqk_tool | /xsxy/ 学业进展 | 已修/在修/毕业资格 | 无 |
| course_select_tool | /xsxk/ 选课提交 | 一键提交选课预约表 | confirmed, xkkz_id, ... |
### 分析工具（4 个）
| 工具名 | 数据源 | 功能 | 参数 |
|--------|--------|------|------|
| gpa_tool | cj_tool | GPA 趋势分析 + 学期明细 | 无 |
| conflict_tool | kb_tool | 课程表时间冲突检测 | xnm, xqm |
| countdown_tool | ks_tool | 考试倒计时 + 3 天临考标记 | 无 |
| warning_tool | xsxyqk+cj | 学业预警 & 挂科记录 | 无 |
### 信息查询（4 个）
| 工具名 | API 端点 | 功能 | 参数 |
|--------|----------|------|------|
| cdjy_tool | /cdjy/ 空闲教室 | 按条件查空闲教室 | xqh_id, jxl_id, xqj, jcd, zc |
| cxbm_tool | /cxbm/ 重修报名 | 重修课程报名状态 | xnm, xqm |
| kjgl_tool | /kjgl/ 考级管理 | 四六级/计算机/普通话 | 无 |
| xsjc_tool | /xsjcgl/ 奖惩查询 | 奖励/处分记录 | 无 |
### 登录工具（1 个）
| 工具名 | 功能 | 参数 |
|--------|------|------|
| login_tool | CAS 统一认证登录 | mode (direct/vpn/atrust) |
---
## 配置说明
通过环境变量或 `.env` 文件配置：
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| GDMU_JW_BASE | https://jw.gdmu.edu.cn | 教务系统地址 |
| GDMU_AUTH_BASE | https://authserver.gdmu.edu.cn | CAS 认证地址 |
| GDMU_CAS_SERVICE | {JW_BASE}/sso/jziotlogin | CAS service 参数 |
| GDMU_COOKIE_PATH | ./jw_session.json | Cookie 持久化路径 |
| GDMU_DEBUG | 0 | 调试模式开关（1=开启） |
### 适配其他学校
本工具基于**正方 V-9.0** 教务系统开发。如果你的学校也使用正方 V-9.0 + CAS 认证，只需修改 `GDMU_JW_BASE` 和 `GDMU_AUTH_BASE` 即可。
> ⚠️ **合规提示**：本项目仅供学习与个人自助使用，请遵守所在学校的《信息系统使用规定》。不要将 Cookie 文件提交到公共仓库或分享给他人。
---
## 部署
### 方式一：PyPI 安装（推荐）
```bash
pip install gdmu-mcp
python -m gdmu_mcp
```
### 方式二：Docker
```bash
docker build -t gdmu-mcp .
docker run -v ./jw_session.json:/app/jw_session.json gdmu-mcp
```
### 方式三：源码运行
```bash
git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e .
python server.py
```
---
## 开发指南
详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
### 快速开发
```bash
# 克隆 + 安装开发依赖
git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e ".[dev]"
playwright install chromium
# 运行测试
pytest
# 代码检查
ruff check .
mypy server.py browser_login.py
```
---
## 项目结构
```text
gdmu_mcp/
├── server.py # MCP Server 入口
├── browser_login.py # 浏览器辅助登录（CAS + MFA）
├── Dockerfile # 容器化部署
├── config.example.env # 环境变量模板
├── requirements.txt # 依赖清单
├── pyproject.toml # 包配置（支持 pip install gdmu-mcp）
├── CHANGELOG.md # 更新日志
├── CONTRIBUTING.md # 贡献指南
├── LICENSE # MIT 许可证
├── README.md # 本文件
├── tests/ # 测试目录
│ ├── __init__.py
│ ├── conftest.py
│ └── test_smoke.py # 18 个测试用例（3 基础 + 15 mcp/gdmu_agent 跳过）
├── gdmu_mcp/ # 包目录（python -m gdmu_mcp 入口）
│ ├── __init__.py
│ ├── __main__.py
│ └── server.py # 转发到根目录 server.py
└── .github/
└── workflows/
├── pytest.yml # CI — 测试
└── publish.yml # PyPI 自动发布
```
---
## 许可证
本项目基于 [MIT 许可证](LICENSE) 开源。逆向研究仅用于教育目的，请遵守所在学校的网络使用规定。
---
*用技术守护每一个求知者的校园时光。*
