HDU Academic System MCP Server

HDU教务处MCP服务器

一个用于杭州电子科技大学教务处系统的MCP (Model Context Protocol) 服务器，支持自动登录和课程表获取功能。

项目概述

本项目实现了一个MCP服务器，允许AI助手通过用户提供的学号和密码登录杭电教务处系统，并获取相关的学术信息，如课程表等。

主要功能

• ✅ 教务处登录: 支持通过学号和密码登录杭电SSO系统
• 🚧 课程表获取: 获取当前学期或指定学期的课程表信息
• 🔒 会话管理: 自动处理登录状态和Cookie管理
• 📊 结构化数据: 返回JSON格式的结构化课程信息

技术架构

核心技术栈

• TypeScript: 主要开发语言
• @modelcontextprotocol/sdk: MCP协议实现
• axios: HTTP客户端，用于网络请求
• cheerio: HTML解析，用于提取页面信息
• tough-cookie: Cookie管理
• axios-cookiejar-support: Axios的Cookie支持

项目结构

构建过程

环境要求

• Node.js >= 18.0.0
• npm >= 8.0.0

安装依赖

编译项目

运行服务器

功能详解

1. 登录功能 (hdu_login)

功能描述: 使用学号和密码登录杭电教务处系统

输入参数:

• username (string): 学号
• password (string): 密码

返回结果:

实现原理:

1. 访问SSO登录页面 (https://sso.hdu.edu.cn/login)
2. 解析页面获取必要的隐藏字段 (lt, execution, _eventId)
3. 构造登录表单数据并提交
4. 处理重定向和登录状态验证
5. 提取用户信息

2. 课程表获取功能 (get_course_schedule)

功能描述: 获取指定学期的课程表信息（需要先登录）

输入参数:

• semester (string, 可选): 学期标识，默认为当前学期

返回结果:

当前状态: 🚧 开发中 - 需要进一步分析教务处课表页面结构

使用方式

作为MCP服务器使用

1. 启动服务器:
   npm start
2. 在支持MCP的AI客户端中配置:
   { "mcpServers": { "hdu-jwc": { "command": "node", "args": ["/path/to/hdu-jwc-mcp/dist/index.js"] } } }
3. 使用工具:
   • 调用 hdu_login 工具进行登录
   • 调用 get_course_schedule 工具获取课程表

独立测试使用

1. 修改测试脚本: 编辑 src/test-login.ts，填入真实的学号和密码：
   const username = 'your_student_id'; const password = 'your_password';
2. 运行测试:
   npm run build node dist/test-login.js

开发迭代过程

第一阶段：项目初始化 ✅

• 创建基本项目结构
• 配置TypeScript和构建环境
• 设置MCP服务器框架
• 添加必要的依赖包

第二阶段：登录功能实现 ✅

• 分析杭电SSO登录流程
• 实现HTTP客户端和Cookie管理
• 处理登录表单提交和重定向
• 添加错误处理和状态验证
• 创建测试脚本验证功能

第三阶段：课程表功能 🚧

• 分析教务处课程表页面结构
• 实现课程表数据解析
• 支持不同学期的课程表获取
• 优化数据格式和错误处理

第四阶段：功能完善 📋

• 添加更多教务处功能（成绩查询、考试安排等）
• 优化错误处理和用户体验
• 添加配置文件支持
• 完善文档和使用示例

注意事项

安全性

• 🔐 用户凭据仅在内存中临时存储，不会持久化
• 🛡️ 使用HTTPS确保数据传输安全
• ⚠️ 请妥善保管学号和密码，避免在公共环境中使用

使用限制

• 📚 仅支持杭州电子科技大学教务处系统
• 🕒 依赖于教务处网站结构，如有变更可能需要更新
• 🔄 建议适度使用，避免对教务处服务器造成过大负载

故障排除

登录失败常见原因:

1. 用户名或密码错误
2. 教务处系统维护或不可用
3. 网络连接问题
4. 验证码或其他安全措施

调试方法:

1. 检查控制台错误输出
2. 验证网络连接
3. 确认教务处网站是否正常访问
4. 使用测试脚本进行独立测试

贡献指南

欢迎提交Issue和Pull Request来改进这个项目！

开发环境设置

1. Fork本仓库
2. 克隆到本地：git clone <your-fork-url>
3. 安装依赖：npm install
4. 开始开发：npm run dev

提交规范

• 使用清晰的提交信息
• 遵循现有的代码风格
• 添加必要的测试和文档

许可证

MIT License - 详见 LICENSE 文件

更新日志

v1.0.0 (当前版本)

• ✅ 实现基本的MCP服务器框架
• ✅ 完成杭电SSO登录功能
• 🚧 课程表获取功能开发中
• 📝 完善项目文档

免责声明: 本项目仅供学习和研究使用，请遵守学校相关规定，合理使用教务处系统资源。