GDMU MCP Server

AI 助手（Codex / Claude Desktop / Cursor 等）与正方 V-9.0 教务系统的 MCP 桥梁——15 个工具覆盖教务全场景。

🎯 专为 正方 V-9.0 + CAS 单点登录 + MFA 多因子认证 设计。

---

目录

• 快速开始
• 工具列表（15 个）
• 配置说明
• AI 客户端集成
• 部署
• 开发指南
• 项目结构
• 许可证

---

快速开始

浏览器登录（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 + Chromium 浏览器引擎

1. 安装

# 从 PyPI 安装（推荐）
pip install gdmu-mcp

# 或从源码安装
git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e .

2. 浏览器登录

# 自动打开 Chrome，完成 CAS 认证（含 MFA）
# 登录成功后自动保存 Cookie 到 jw_session.json
python browser_login.py

过程中浏览器会打开 CAS 登录页，输入账号密码后如遇短信验证码 / 微信扫码等二次认证，正常完成即可。脚本会自动检测登录成功并提取 Cookie。

3. 启动 MCP Server

# 标准启动
python server.py

# 指定调试模式
GDMU_DEBUG=1 python server.py

4. 配置 AI 客户端

Codex CLI / Claude Desktop

在 claude_desktop_config.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 安装（推荐）

pip install gdmu-mcp
python -m gdmu_mcp

方式二：Docker

docker build -t gdmu-mcp .
docker run -v ./jw_session.json:/app/jw_session.json gdmu-mcp

方式三：源码运行

git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e .
python server.py

---

开发指南

详见 CONTRIBUTING.md。

快速开发

# 克隆 + 安装开发依赖
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

---

项目结构

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 许可证 开源。逆向研究仅用于教育目的，请遵守所在学校的网络使用规定。

---

用技术守护每一个求知者的校园时光。