eClass MCP 服务器

<p align="center"> <strong>一个用于与 Open eClass 平台实例交互的 MCP 服务器，特别支持 UoA 的 SSO 身份验证系统。</strong> </p>

<p align="center"> <a href="https://github.com/modelcontextprotocol/python-sdk"><img src="https://img.shields.io/badge/MCP-Protocol-blue" alt="MCP Protocol"></a> <a href="https://www.gnu.org/licenses/gpl-3.0"><img src="https://img.shields.io/badge/License-GPLv3-blue.svg" alt="License: GPL v3"></a> <img src="https://img.shields.io/badge/Python-3.9%2B-blue" alt="Python: 3.9+"> <img src="https://img.shields.io/badge/Status-Development-orange" alt="Status: Development"> <a href="https://github.com/gunet/openeclass"><img src="https://img.shields.io/badge/Open-eClass-yellow" alt="Open eClass"></a> </p>

<p align="center"> <a href="https://glama.ai/mcp/servers/@sdi2200262/eclass-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@sdi2200262/eclass-mcp-server/badge" alt="eClass Server MCP server" /> </a> </p>

<p align="center"> <img src="assets/example.png" alt="Example Usecase"> </p>

<p align="center"> <strong>此服务器使 AI 代理能够通过 eClass 进行身份验证，检索课程信息，并在平台上执行基本操作。</strong> </p>

功能特性

• 身份验证: 通过 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 版本开始 ) 转到 Settings -> MCP。单击 Add new global MCP server：

这将打开全局 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 中的主服务器入口点连接。

<p align="center"> <img src="assets/cursor-server.png" alt="Cursor Server Card"> </p>

Claude Desktop

要与 Claude Desktop 一起使用：

1. 打开 Claude Desktop
2. 转到 Settings > Server
3. 添加一个新服务器，其中包含以下详细信息：
   • Name: eClass MCP
   • Command: 指向您的 run_server.py 脚本的路径
4. 单击 Add Server
5. 在与 Claude 聊天时，从下拉列表中选择服务器

工具

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

login

使用 SSO 身份验证登录 eClass。

{
  "random_string": "any_value"
}

get_courses

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

{
  "random_string": "any_value"
}

logout

从 eClass 注销。

{
  "random_string": "any_value"
}

authstatus

检查当前的身份验证状态。

{
  "random_string": "any_value"
}

eClass 客户端（非 MCP）

该存储库包括 eclass_client.py，这是一个用于与 eClass 平台交互的独立客户端。这是最初的实现，激发了 MCP 服务器的创建。

eClass 客户端的功能

• 没有 MCP 集成的纯 Python 实现
• 处理与 UoA 的 SSO 系统的完整身份验证流程
• 从 eClass 检索课程信息
• 提供干净的注销功能

此客户端既充当：

1. 用于理解 eClass 身份验证流程的参考实现
2. 对于不需要 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 SDK 集成
• 工具参考

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 或其他 LLM）永远不会收到您的凭据
  • 这可以防止凭据：
    • 存储在 AI 提供商日志中
    • 包含在模型训练数据中
    • 在远程服务器上处理

会话管理

• 内存中会话：会话 cookie 和状态仅在内存中维护
• 无持久性：会话数据不会在运行之间存储
• 直接身份验证：MCP 服务器直接与 eClass 通信，除了您大学的 CAS 机制外，没有中间人。

推荐做法

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

许可证

GNU 通用公共许可证 v3.0

本项目根据 GNU 通用公共许可证 v3.0 获得许可 - 有关详细信息，请参阅 LICENSE 文件。

这对您意味着什么

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

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

我们为什么选择 GPL-3.0

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

1. 保护用户安全：确保任何处理凭据的修改都必须是开源的，从而允许用户验证安全实现
2. 促进分享：鼓励向社区贡献
3. 防止滥用：使恶意行为者更难以创建可能损害安全性的闭源衍生产品
4. 匹配生态系统价值：与 Open eClass 平台（也是开源的）的价值保持一致

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

致谢

• GUnet (希腊大学网络) 开发和维护 Open eClass 平台，这是一个希腊各地学术机构使用的开源学习管理系统。
• Open eClass 平台根据 GNU GPL v2.0 作为免费开源软件分发，这使得像这样的 MCP 集成项目成为可能。
• 特别感谢 GUnet 的异步电子学习团队，感谢他们不断开发和改进 eClass 平台。
• 本项目是 Open eClass 系统的独立接口，不隶属于 GUnet，也不受其认可。它尊重 eClass 平台的服务条款并使用适当的身份验证机制。

贡献

欢迎贡献！请随时提交 Pull Request。