eClass MCP 服务器

功能

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

项目结构

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

eclass-mcp-server/
├── run_server.py               # Entry point script for running the server
├── pyproject.toml              # Project configuration and dependencies
├── .env                        # Environment variables (create from example.env)
├── src/
    └── eclass_mcp_server/      # Main package
        ├── __init__.py         # Package initialization
        ├── server.py           # Core server implementation and tool handlers
        ├── authentication.py   # Authentication functionality 
        ├── course_management.py # Course-related functionality
        ├── html_parsing.py     # HTML parsing utilities
        └── test/               # Test scripts for functionality verification
            ├── __init__.py
            ├── test_login.py
            ├── test_courses.py
            └── run_all_tests.py

安装

推荐使用 UV 安装服务器：

# Clone the repository
git clone https://github.com/yourusername/eClass-MCP-server.git
cd eClass-MCP-server

# Install dependencies
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

前往设置 -> MCP。点击“添加新的 MCP 服务器”：

• 选择一个独特但合适的名称，以便代理知道服务器的用途（例如，“eClass 服务器”）
• 在“类型”上选择 command 选项
• 在命令输入框中添加此内容：python /path/to/eclass-mcp-server/run_server.py

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

Claude 桌面版

要与 Claude 桌面版一起使用：

1. 打开 Claude 桌面版
2. 前往设置 > 服务器
3. 添加一个新的服务器，详细信息如下：
   • 名称：eClass MCP
   • 命令：指向你的 run_server.py 脚本的路径
4. 点击添加服务器
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"
}

测试

项目包括测试脚本来验证功能：

# Run all tests
python -m src.eclass_mcp_server.test.run_all_tests

# Run specific tests
python -m src.eclass_mcp_server.test.test_login
python -m src.eclass_mcp_server.test.test_courses

示例 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:
            # Initialize the session
            await session.initialize()
            
            # Login to eClass
            login_result = await session.call_tool("login", {
                "random_string": "dummy"
            })
            print(login_result)
            
            # Get courses
            courses_result = await session.call_tool("get_courses", {
                "random_string": "dummy"
            })
            print(courses_result)
            
            # Logout
            logout_result = await session.call_tool("logout", {
                "random_string": "dummy"
            })
            print(logout_result)

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

与 AI 代理集成

此 MCP 服务器设计用于支持 Model Context Protocol 的 AI 代理。这使得 AI 系统可以直接与 eClass 交互，从而实现诸如以下功能：

• 检索课程信息
• 查看课程公告
• 访问课程资料
• 提交作业（未来功能）

安全注意事项

• 服务器处理敏感的身份验证凭据
• 凭据仅用于身份验证，不会持久存储
• 会话 cookie 在服务器生命周期内保存在内存中
• 服务器在执行操作前验证会话状态
• 包含凭据的 .env 文件永远不应提交到版本控制中（它已被包含在 .gitignore 中）

许可证

MIT 许可证

贡献

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