eClass MCP 服务器

一个用于与Open eClass平台实例交互的MCP服务器，特别支持UoA的SSO认证系统。

示例用例

该服务器允许AI代理认证eClass，检索课程信息，并在平台上执行基本操作。

特性

身份验证: 通过UoA的CAS SSO认证系统登录eClass
课程管理: 获取已注册课程列表
会话管理: 在工具调用之间维护已认证的会话
状态检查: 验证认证状态

项目结构

本项目采用模块化架构，以提高可维护性：

eclass-mcp-server/
├── run_server.py               # 运行服务器的入口脚本
├── eclass_client.py            # eClass (非MCP)的独立客户端
├── pyproject.toml              # 项目配置和依赖项
├── .env                        # 环境变量 (从 example.env 创建)
├── docs/                       # 文档
│   ├── README.md               # 文档概述
│   ├── how-it-works.md         # 核心实现说明
│   ├── mcp-sdk-integration.md  # MCP SDK 使用详情
│   └── tools-reference.md      # 可用工具参考
├── src/
    └── eclass_mcp_server/      # 主包
        ├── __init__.py         # 包初始化
        ├── server.py           # 核心服务器实现和工具处理器
        ├── authentication.py   # 身份验证功能
        ├── course_management.py # 课程相关功能
        ├── html_parsing.py     # HTML 解析工具
        └── test/               # 功能验证测试脚本
            ├── __init__.py
            ├── test_login.py
            ├── test_courses.py
            └── run_all_tests.py

安装

推荐使用 UV 安装服务器：

# 克隆仓库
git clone https://github.com/yourusername/eClass-MCP-server.git
cd eClass-MCP-server

# 安装依赖项
uv sync --dev --all-extras

或者，使用pip安装：

pip install -e .

配置

在根目录下创建一个.env文件，包含以下配置（或者复制并重命名提供的example.env文件）：

ECLASS_URL=https://eclass.uoa.gr
ECLASS_USERNAME=your_username
ECLASS_PASSWORD=your_password

所有凭据必须在.env文件中提供。服务器不接受参数形式的凭据。

使用方法

终端

使用入口脚本运行服务器：

python run_server.py

或者作为模块运行：

python -m src.eclass_mcp_server.server

Cursor

(0.48版本及以上) 前往设置 -> MCP。点击 添加新的全局MCP服务器：

这将打开全局的mcp.json文件：

{
    "mcpServers": {
      "server-name": {
        "command": "python",
        "args": ["absolute\\path\\to\\eclass-mcp-server\\run_server.py"]
      }
    }
}

或者在args字段中尝试这种路径格式：

absolute/path/to/eclass-mcp-server/run_server.py

此命令运行run_server.py脚本，该脚本将MCP客户端连接到server.py中的主服务器入口点。

Cursor Server Card

Claude Desktop

在Claude Desktop中使用：

打开Claude Desktop
前往设置 > 服务器
使用以下详细信息添加新服务器：
- 名称：eClass MCP
- 命令：run_server.py脚本的路径
点击添加服务器
与Claude聊天时，从下拉菜单中选择服务器

工具

服务器提供以下工具供 MCP 客户端使用：

获取课程

检索已注册课程的列表（需要先登录）。

{
  "random_string": "any_value"
}

登出

从 eClass 注销。

{
  "random_string": "any_value"
}

认证状态

检查当前的认证状态。

{
  "random_string": "any_value"
}

eClass 客户端（非 MCP）

该仓库包含 eclass_client.py，这是一个用于与 eClass 平台交互的独立客户端。这是最初的实现，也是创建 MCP 服务器的灵感来源。

eClass 客户端的功能

纯 Python 实现，无需 MCP 集成
处理与奥克兰大学 SSO 系统的完整身份验证流程
从 eClass 检索课程信息
提供干净的注销功能

该客户端兼具以下两种用途：

用于理解 eClass 身份验证流程的参考实现
对于不需要 MCP 集成的项目来说，是一个更简单的替代方案

您可以直接运行客户端：

python eclass_client.py

测试

该项目包含用于验证功能的测试脚本：

# 运行所有测试
python -m src.eclass_mcp_server.test.run_all_tests

# 运行特定测试
python -m src.eclass_mcp_server.test.test_login
python -m src.eclass_mcp_server.test.test_courses

文档

完整的文档位于 docs/ 目录下：

MCP客户端使用示例

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio

async def run_agent():
    server_params = StdioServerParameters(
        command="python /path/to/eclass-mcp-server/run_server.py",
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 初始化会话
            await session.initialize()
            
            # 登录eClass
            login_result = await session.call_tool("login", {
                "random_string": "dummy"
            })
            print(login_result)
            
            # 获取课程
            courses_result = await session.call_tool("get_courses", {
                "random_string": "dummy"
            })
            print(courses_result)
            
            # 退出登录
            logout_result = await session.call_tool("logout", {
                "random_string": "dummy"
            })
            print(logout_result)

if __name__ == "__main__":
    asyncio.run(run_agent())

与AI智能体的集成

该MCP服务器旨在与支持模型上下文协议的AI智能体一起使用。这使AI系统能够直接与eClass交互，从而实现以下功能：

获取课程信息
查看课程公告
访问课程资料
提交作业 (未来功能)

安全性

eClass MCP 服务器的设计将安全性作为首要任务，尤其是在凭据处理方面：

本地执行

无云服务: MCP 服务器完全在您的本地机器上运行，没有任何云组件
无远程存储: 凭据和会话数据永远不会离开您的本地环境
用户控制: 您完全控制您的身份验证数据

凭据保护

仅环境变量: 凭据仅存储在本地 .env 文件中
绝不作为参数传递: 所有工具都设计为使用虚拟参数（例如，random_string）
AI 客户端隔离: AI 客户端（如 Claude 或其他大型语言模型）永远不会接收您的凭据
- 这可以防止凭据：
  - 存储在 AI 提供商日志中
  - 包含在模型训练数据中
  - 在远程服务器上进行处理

会话管理

内存会话: 会话 Cookie 和状态仅保存在内存中
无持久化: 会话数据在运行之间不会存储
直接身份验证: MCP 服务器直接与 eClass 通信，除了您大学的 CAS 机制外，没有任何中间机构。

建议的做法

安全地存储您的 .env 文件，切勿将其提交到版本控制系统
仅在受信任的机器上运行服务器
不要通过任何提示将参数传递给 MCP 客户端，服务器不会使用它们，而 AI 代理提供商将访问它们

许可证

GNU 通用公共许可证 v3.0

本项目根据 GNU 通用公共许可证 v3.0 许可——详情请参见 LICENSE 文件。

对您的意义

GPL-3.0 许可证是一个强大的复制左许可证，要求任何分发此代码或衍生作品的人都必须以相同条款提供源代码。要点：

使用自由: 您可以将此软件用于任何目的
学习自由: 您可以检查源代码以了解其工作原理
分享自由: 您可以重新分发软件
修改自由: 您可以根据您的需求调整软件

我们选择 GPL-3.0 的原因

我们选择 GPL-3.0 许可证是为了：

保护用户安全: 确保处理凭据的任何修改都必须是开源的，允许用户验证安全实现
促进共享: 鼓励回馈社区
防止滥用: 使恶意行为者更难创建可能危及安全的闭源衍生作品
匹配生态系统价值观: 与同样是开源的 Open eClass 平台的价值观相符

此许可证对于此软件尤其重要，因为它处理身份验证和敏感凭据。GPL-3.0 确保此代码的任何修改都保持透明，允许用户验证其凭据的处理方式。

致谢

感谢 GUnet (希腊大学网络) 开发和维护 Open eClass 平台，这是一个由希腊各学术机构使用的开源学习管理系统。
Open eClass 平台作为免费的开源软件在 GNU GPL v2.0 许可下分发，使得像这样的 MCP 集成项目成为可能。
特别感谢 GUnet 的异步在线学习团队不断开发和改进 eClass 平台。
本项目是 Open eClass 系统的独立接口，与 GUnet 无关联，也未获得其认可。它遵守 eClass 平台的服务条款，并使用适当的身份验证机制。

欢迎贡献！请随意提交拉取请求。