iflow-mcp_sdi2200262-eclass-mcp-server 0.1.0__py3-none-any.whl

eclass_mcp_server/__init__.py

@@ -0,0 +1,12 @@
+"""eClass MCP Server - MCP integration for Open eClass platform."""
+
+import asyncio
+
+from . import server
+
+__all__ = ['main', 'server']
+
+
+def main() -> None:
+    """Main entry point for the package."""
+    asyncio.run(server.main())

eclass_mcp_server/authentication.py

@@ -0,0 +1,197 @@
+"""
+Authentication module for eClass MCP Server.
+
+Handles authentication with eClass through UoA's SSO (CAS) system.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Optional, Tuple
+from urllib.parse import urlparse
+
+import mcp.types as types
+import requests
+
+from . import html_parsing
+
+if TYPE_CHECKING:
+    from .server import SessionState
+
+logger = logging.getLogger('eclass_mcp_server.authentication')
+
+
+def attempt_login(
+    session_state: SessionState, username: str, password: str
+) -> Tuple[bool, Optional[str]]:
+    """
+    Attempt to log in to eClass using the SSO authentication flow.
+    
+    Returns:
+        Tuple of (success, error_message). On success, error_message is None.
+    """
+    try:
+        # Step 1: Visit the eClass login form page
+        response = session_state.session.get(session_state.login_form_url)
+        response.raise_for_status()
+        
+        # Step 2: Find and follow the SSO login link
+        sso_link = html_parsing.extract_sso_link(response.text, session_state.base_url)
+        if not sso_link:
+            return False, "Could not find SSO login link on the login page"
+        
+        response = session_state.session.get(sso_link)
+        response.raise_for_status()
+        
+        # Step 3: Validate SSO redirect and extract CAS form data
+        if not _is_valid_sso_redirect(response.url, session_state):
+            return False, f"Unexpected redirect to {response.url}"
+        
+        execution, action, error_text = html_parsing.extract_cas_form_data(
+            response.text, response.url, session_state.sso_base_url
+        )
+        
+        if error_text and ('authenticate' in error_text.lower() or 'credentials' in error_text.lower()):
+            return False, f"Authentication error: {error_text}"
+        if not execution:
+            return False, "Could not find execution parameter on SSO page"
+        if not action:
+            return False, "Could not find login form on SSO page"
+        
+        # Step 4: Submit credentials to CAS
+        login_data = {
+            'username': username,
+            'password': password,
+            'execution': execution,
+            '_eventId': 'submit',
+            'geolocation': ''
+        }
+        
+        response = session_state.session.post(action, data=login_data)
+        response.raise_for_status()
+        
+        # Check for authentication errors in response
+        if 'Πόροι Πληροφορικής ΕΚΠΑ' in response.text or \
+           'The credentials you provided cannot be determined to be authentic' in response.text:
+            _, _, error_text = html_parsing.extract_cas_form_data(response.text, response.url)
+            if error_text:
+                return False, f"Authentication error: {error_text}"
+            return False, "Authentication failed: Invalid credentials"
+        
+        logger.info("Successfully authenticated with SSO")
+        
+        # Step 5: Verify login by accessing portfolio page
+        if session_state.eclass_domain not in response.url:
+            return False, f"Unexpected redirect after login: {response.url}"
+        
+        response = session_state.session.get(session_state.portfolio_url)
+        response.raise_for_status()
+        
+        if not html_parsing.verify_login_success(response.text):
+            return False, "Could not access portfolio page after login"
+        
+        session_state.logged_in = True
+        session_state.username = username
+        logger.info("Login successful, redirected to eClass portfolio")
+        return True, None
+    
+    except requests.RequestException as e:
+        logger.error(f"Request error during login: {e}")
+        return False, f"Network error during login process: {e}"
+    except Exception as e:
+        logger.error(f"Login error: {e}")
+        return False, f"Error during login process: {e}"
+
+
+def _is_valid_sso_redirect(response_url: str, session_state: SessionState) -> bool:
+    """Check if the redirect is to a valid SSO domain."""
+    response_url_domain = urlparse(response_url).netloc
+    sso_domain_netloc = urlparse(session_state.sso_base_url).netloc
+    
+    # Valid if: SSO domain in URL, exact domain match, or same domain for local testing
+    return (
+        session_state.sso_domain in response_url or
+        response_url_domain == sso_domain_netloc or
+        (session_state.eclass_domain == session_state.sso_domain and
+         session_state.eclass_domain in response_url)
+    )
+
+
+def perform_logout(session_state: SessionState) -> Tuple[bool, Optional[str]]:
+    """
+    Log out from eClass.
+    
+    Returns:
+        Tuple of (success, username_or_error).
+        On success with prior login: (True, username)
+        On success without prior login: (True, None)
+        On failure: (False, error_message)
+    """
+    if not session_state.logged_in:
+        return True, None
+    
+    try:
+        response = session_state.session.get(session_state.logout_url)
+        response.raise_for_status()
+        
+        username = session_state.username
+        session_state.reset()
+        return True, username
+    except Exception as e:
+        logger.error(f"Logout error: {e}")
+        return False, f"Error during logout: {e}"
+
+
+def format_login_response(
+    success: bool, message: Optional[str], username: Optional[str] = None
+) -> types.TextContent:
+    """Format login response for MCP."""
+    if success:
+        return types.TextContent(
+            type="text",
+            text=f"Login successful! You are now logged in as {username}.",
+        )
+    return types.TextContent(
+        type="text",
+        text=f"Error: {message}",
+    )
+
+
+def format_logout_response(
+    success: bool, username_or_error: Optional[str]
+) -> types.TextContent:
+    """Format logout response for MCP."""
+    if success:
+        if username_or_error:
+            return types.TextContent(
+                type="text",
+                text=f"Successfully logged out user {username_or_error}.",
+            )
+        return types.TextContent(
+            type="text",
+            text="Not logged in, nothing to do.",
+        )
+    return types.TextContent(
+        type="text",
+        text=f"Error during logout: {username_or_error}",
+    )
+
+
+def format_authstatus_response(session_state: SessionState) -> types.TextContent:
+    """Format authentication status response for MCP."""
+    if not session_state.logged_in:
+        return types.TextContent(
+            type="text",
+            text="Status: Not logged in",
+        )
+    
+    if session_state.is_session_valid():
+        return types.TextContent(
+            type="text",
+            text=f"Status: Logged in as {session_state.username}\nCourses: {len(session_state.courses)} enrolled",
+        )
+    
+    return types.TextContent(
+        type="text",
+        text="Status: Session expired. Please log in again.",
+    )

eclass_mcp_server/course_management.py

@@ -0,0 +1,82 @@
+"""
+Course management module for eClass MCP Server.
+
+Handles retrieval and formatting of course information from eClass.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+
+import mcp.types as types
+import requests
+
+from . import html_parsing
+
+if TYPE_CHECKING:
+    from .server import SessionState
+
+logger = logging.getLogger('eclass_mcp_server.course_management')
+
+
+def get_courses(
+    session_state: SessionState
+) -> Tuple[bool, Optional[str], Optional[List[Dict[str, str]]]]:
+    """
+    Retrieve a list of enrolled courses from eClass.
+    
+    Returns:
+        Tuple of (success, message, courses).
+        On success: (True, None, courses_list)
+        On empty result: (True, message, [])
+        On failure: (False, error_message, None)
+    """
+    if not session_state.logged_in:
+        return False, "Not logged in. Please log in first using the login tool.", None
+    
+    if not session_state.is_session_valid():
+        return False, "Session expired. Please log in again.", None
+    
+    try:
+        response = session_state.session.get(session_state.portfolio_url)
+        response.raise_for_status()
+        
+        courses = html_parsing.extract_courses(response.text, session_state.base_url)
+        session_state.courses = courses
+        
+        if not courses:
+            return True, "No courses found. You may not be enrolled in any courses.", []
+        
+        logger.info(f"Successfully retrieved {len(courses)} courses")
+        return True, None, courses
+    
+    except requests.RequestException as e:
+        logger.error(f"Network error getting courses: {e}")
+        return False, f"Network error retrieving courses: {e}", None
+    except Exception as e:
+        logger.error(f"Error getting courses: {e}")
+        return False, f"Error retrieving courses: {e}", None
+
+
+def format_courses_response(
+    success: bool, message: Optional[str], courses: Optional[List[Dict[str, str]]]
+) -> types.TextContent:
+    """Format course list response for MCP."""
+    if not success:
+        return types.TextContent(
+            type="text",
+            text=f"Error: {message}",
+        )
+    
+    if message:  # No courses found message
+        return types.TextContent(
+            type="text",
+            text=message,
+        )
+    
+    course_list = html_parsing.format_course_list(courses)
+    return types.TextContent(
+        type="text",
+        text=f"Found {len(courses)} courses:\n\n{course_list}",
+    )

eclass_mcp_server/html_parsing.py

@@ -0,0 +1,163 @@
+"""
+HTML parsing utilities for eClass MCP Server.
+
+Uses BeautifulSoup to extract data from eClass and CAS SSO HTML responses.
+"""
+
+import logging
+from typing import Dict, List, Optional, Tuple
+
+from bs4 import BeautifulSoup
+
+logger = logging.getLogger('eclass_mcp_server.html_parsing')
+
+
+def extract_sso_link(html_content: str, base_url: str) -> Optional[str]:
+    """
+    Extract the SSO login link from the eClass login page.
+    
+    Returns:
+        Absolute SSO login URL, or None if not found.
+    """
+    soup = BeautifulSoup(html_content, 'html.parser')
+    sso_link = None
+    
+    # Look for UoA login button
+    for link in soup.find_all('a'):
+        if 'Είσοδος με λογαριασμό ΕΚΠΑ' in link.text or 'ΕΚΠΑ' in link.text:
+            sso_link = link.get('href')
+            break
+    
+    # Fallback: look for CAS form action
+    if not sso_link:
+        for form in soup.find_all('form'):
+            if form.get('action') and 'cas.php' in form.get('action'):
+                sso_link = form.get('action')
+                break
+    
+    if not sso_link:
+        logger.warning("Could not find SSO login link on the login page")
+        return None
+    
+    # Ensure URL is absolute
+    if not sso_link.startswith(('http://', 'https://')):
+        sso_link = f"{base_url}/{sso_link.lstrip('/')}"
+    
+    logger.debug(f"Extracted SSO link: {sso_link}")
+    return sso_link
+
+
+def extract_cas_form_data(
+    html_content: str,
+    current_url: str,
+    sso_base_url: str = "https://sso.uoa.gr"
+) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+    """
+    Extract execution parameter and form action from CAS login page.
+    
+    Returns:
+        Tuple of (execution_value, form_action, error_message).
+        On parsing failure, appropriate values will be None.
+    """
+    soup = BeautifulSoup(html_content, 'html.parser')
+    
+    # Check for error message
+    error_msg = soup.find('div', {'id': 'msg'})
+    error_text = error_msg.text.strip() if error_msg else None
+    
+    # Find execution token
+    execution_input = soup.find('input', {'name': 'execution'})
+    if not execution_input:
+        logger.warning("Could not find execution parameter on SSO page")
+        return None, None, error_text or "Could not find execution parameter on SSO page"
+    
+    execution = execution_input.get('value')
+    
+    # Find login form
+    form = soup.find('form', {'id': 'fm1'}) or soup.find('form')
+    if not form:
+        logger.warning("Could not find login form on SSO page")
+        return execution, None, error_text or "Could not find login form on SSO page"
+    
+    action = form.get('action')
+    if not action:
+        action = current_url
+    elif not action.startswith(('http://', 'https://')):
+        action = f"{sso_base_url}/{action.lstrip('/')}"
+    
+    return execution, action, error_text
+
+
+def verify_login_success(html_content: str) -> bool:
+    """
+    Verify if login was successful by checking for portfolio page content.
+    """
+    return ('Μαθήματα' in html_content or
+            'portfolio' in html_content.lower() or
+            'course' in html_content.lower())
+
+
+def extract_courses(html_content: str, base_url: str) -> List[Dict[str, str]]:
+    """
+    Extract course information from the portfolio page.
+    
+    Returns:
+        List of dicts with 'name' and 'url' keys.
+    """
+    courses = []
+    soup = BeautifulSoup(html_content, 'html.parser')
+    
+    # Try specific course selectors
+    course_elements = (
+        soup.select('.course-title') or
+        soup.select('.lesson-title') or
+        soup.select('.course-box .title') or
+        soup.select('.course-info h4')
+    )
+    
+    if course_elements:
+        for course_elem in course_elements:
+            course_link = course_elem.find('a') or course_elem
+            if course_link and course_link.get('href'):
+                course_name = course_link.text.strip()
+                course_url = course_link.get('href')
+                if course_name:
+                    courses.append({
+                        'name': course_name,
+                        'url': _make_absolute_url(course_url, base_url)
+                    })
+    else:
+        # Fallback: find course links by URL pattern
+        for link in soup.find_all('a'):
+            href = link.get('href', '')
+            if 'courses' in href or 'course.php' in href:
+                course_name = link.text.strip()
+                if course_name:
+                    courses.append({
+                        'name': course_name,
+                        'url': _make_absolute_url(href, base_url)
+                    })
+    
+    logger.debug(f"Extracted {len(courses)} courses")
+    return courses
+
+
+def _make_absolute_url(url: str, base_url: str) -> str:
+    """Convert relative URL to absolute URL."""
+    if url.startswith(('http://', 'https://')):
+        return url
+    return f"{base_url}/{url.lstrip('/')}"
+
+
+def format_course_list(courses: List[Dict[str, str]]) -> str:
+    """
+    Format course list for display.
+    
+    Returns:
+        Formatted string with numbered courses and URLs.
+    """
+    lines = []
+    for i, course in enumerate(courses, 1):
+        lines.append(f"{i}. {course['name']}")
+        lines.append(f"   URL: {course['url']}")
+    return "\n".join(lines)

eclass_mcp_server/server.py

@@ -0,0 +1,237 @@
+"""
+eClass MCP Server - MCP Integration for Open eClass Platform
+
+Provides an MCP server for interacting with eClass through UoA's SSO authentication.
+"""
+
+import asyncio
+import logging
+import os
+from typing import Any, Dict, List
+from urllib.parse import urlparse
+
+import requests
+from dotenv import load_dotenv
+from mcp.server.lowlevel import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+import mcp.server.stdio
+import mcp.types as types
+
+from . import authentication
+from . import course_management
+from . import html_parsing
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger('eclass_mcp_server')
+
+server = Server("eclass-mcp")
+
+
+class SessionState:
+    """Maintains authentication state between MCP tool calls."""
+    
+    def __init__(self) -> None:
+        # Load .env from project root
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        project_root = os.path.dirname(os.path.dirname(script_dir))
+        env_path = os.path.join(project_root, '.env')
+        load_dotenv(env_path, override=False)
+        
+        self.session = requests.Session()
+        self.logged_in = False
+        
+        # Base URL configuration
+        self.base_url = os.getenv('ECLASS_URL', 'https://eclass.uoa.gr').rstrip('/')
+        self.eclass_domain = urlparse(self.base_url).netloc
+        
+        # SSO configuration
+        self.sso_domain = os.getenv('ECLASS_SSO_DOMAIN', 'sso.uoa.gr')
+        sso_protocol = os.getenv('ECLASS_SSO_PROTOCOL', 'https')
+        self.sso_base_url = f"{sso_protocol}://{self.sso_domain}"
+        
+        # eClass endpoint URLs
+        self.login_form_url = f"{self.base_url}/main/login_form.php"
+        self.portfolio_url = f"{self.base_url}/main/portfolio.php"
+        self.logout_url = f"{self.base_url}/index.php?logout=yes"
+        
+        self.username: str | None = None
+        self.courses: List[Dict[str, str]] = []
+        
+        logger.info(f"Initialized eClass session for {self.base_url} (SSO: {self.sso_domain})")
+    
+    def is_session_valid(self) -> bool:
+        """Check if the current session is still valid."""
+        if not self.logged_in:
+            return False
+        
+        try:
+            response = self.session.get(self.portfolio_url, allow_redirects=False)
+            if response.status_code == 302 and 'login' in response.headers.get('Location', ''):
+                self.logged_in = False
+                return False
+            if response.status_code == 200 and html_parsing.verify_login_success(response.text):
+                return True
+            self.logged_in = False
+            return False
+        except Exception:
+            self.logged_in = False
+            return False
+    
+    def reset(self) -> None:
+        """Reset the session state."""
+        self.session = requests.Session()
+        self.logged_in = False
+        self.username = None
+        self.courses = []
+
+
+session_state = SessionState()
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    """List available eClass tools."""
+    return [
+        types.Tool(
+            name="login",
+            description="Log in to eClass using username/password from your .env file through UoA's SSO. Configure ECLASS_USERNAME and ECLASS_PASSWORD in your .env file.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "random_string": {
+                        "type": "string",
+                        "description": "Dummy parameter for no-parameter tools"
+                    },
+                },
+                "required": ["random_string"],
+            },
+        ),
+        types.Tool(
+            name="get_courses",
+            description="Get list of enrolled courses from eClass",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "random_string": {
+                        "type": "string",
+                        "description": "Dummy parameter for no-parameter tools"
+                    },
+                },
+                "required": ["random_string"],
+            },
+        ),
+        types.Tool(
+            name="logout",
+            description="Log out from eClass",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "random_string": {
+                        "type": "string",
+                        "description": "Dummy parameter for no-parameter tools"
+                    },
+                },
+                "required": ["random_string"],
+            },
+        ),
+        types.Tool(
+            name="authstatus",
+            description="Check authentication status with eClass",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "random_string": {
+                        "type": "string",
+                        "description": "Dummy parameter for no-parameter tools"
+                    },
+                },
+                "required": ["random_string"],
+            },
+        ),
+    ]
+
+@server.call_tool()
+async def handle_call_tool(
+    name: str, arguments: Dict[str, Any] | None
+) -> List[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+    """Handle eClass tool execution requests."""
+    if name == "login":
+        return await handle_login()
+    elif name == "get_courses":
+        return await handle_get_courses()
+    elif name == "logout":
+        return await handle_logout()
+    elif name == "authstatus":
+        return await handle_authstatus()
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+
+async def handle_login() -> List[types.TextContent]:
+    """Handle login to eClass."""
+    if session_state.logged_in and session_state.is_session_valid():
+        return [
+            types.TextContent(
+                type="text",
+                text=f"Already logged in as {session_state.username}",
+            )
+        ]
+    
+    if session_state.logged_in and not session_state.is_session_valid():
+        session_state.reset()
+    
+    username = os.getenv('ECLASS_USERNAME')
+    password = os.getenv('ECLASS_PASSWORD')
+    
+    if not username or not password:
+        return [
+            types.TextContent(
+                type="text",
+                text="Error: Username and password must be provided in the .env file. Please set ECLASS_USERNAME and ECLASS_PASSWORD in your .env file.",
+            )
+        ]
+    
+    logger.info(f"Attempting to log in as {username}")
+    success, message = authentication.attempt_login(session_state, username, password)
+    return [authentication.format_login_response(success, message, username if success else None)]
+
+
+async def handle_get_courses() -> List[types.TextContent]:
+    """Handle getting the list of enrolled courses."""
+    success, message, courses = course_management.get_courses(session_state)
+    return [course_management.format_courses_response(success, message, courses)]
+
+
+async def handle_logout() -> List[types.TextContent]:
+    """Handle logout from eClass."""
+    success, username_or_error = authentication.perform_logout(session_state)
+    return [authentication.format_logout_response(success, username_or_error)]
+
+
+async def handle_authstatus() -> List[types.TextContent]:
+    """Handle checking authentication status."""
+    return [authentication.format_authstatus_response(session_state)]
+
+
+async def main() -> None:
+    """Run the MCP server."""
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="eclass-mcp",
+                server_version="0.1.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

eclass_mcp_server/test/__init__.py

@@ -0,0 +1 @@
+"""Test package for eClass MCP Server."""