OpenEclass Interface Gateway (MCP Server)

A dedicated MCP gateway for seamless interaction with Open eClass environments, featuring specialized support for UoA's CAS authentication infrastructure.

This gateway empowers AI reasoning engines to establish credentials on eClass, fetch granular course details, and execute predefined administrative actions within the system.

Core Capabilities

• Secure Access: Establishes authenticated sessions utilizing the UoA CAS federated identity service.
• Curriculum Retrieval: Access and list all courses associated with the authenticated user profile.
• State Maintenance: Persists the necessary session tokens across successive tool invocations.
• Connectivity Check: Provides a utility to validate the current operational login state.

Source Code Organization

This application employs a layered architectural design promoting clarity and ease of maintenance:

interface-gateway/ ├── launch_server.py # Primary script to initiate the service listener ├── standalone_eclass_util.py # Non-MCP client for direct platform testing ├── project.toml # Dependency management and package metadata ├── .secrets # Local configuration file (securely store sensitive data) ├── documentation/ ├── overview.md # General documentation guide ├── mechanics.md # Deep dive into execution logic ├── mcp-integration.md # Guide for protocol SDK interfacing └── tool_reference.md # Catalog of exposed functionalities ├── src/ └── gateway_core/ ├── init.py ├── listener.py # Main server socket handling and routing ├── auth_handler.py # Logic dedicated to credential validation and session establishment ├── syllabus_accessor.py # Functions for querying course lists and data ├── markup_processor.py # Utilities for cleaning and interpreting HTML payloads └── tests/ ├── init.py ├── verify_login.py ├── check_curriculum.py └── run_all_suites.py

Deployment Instructions

Deploy the gateway using the UV dependency manager (recommended approach):

bash

Obtain the repository source code

git clone https://github.com/yourusername/eClass-MCP-server.git cd interface-gateway

Install required packages and development dependencies

uv sync --dev --all-extras

Alternatively, use standard pip installation:

bash pip install -e .

Configuration Parameters

Populate the .secrets file in the root directory based on the provided example.secrets template:

PLATFORM_BASE_URI=https://eclass.uoa.gr USER_ID=your_credentials_id SECRET_KEY=your_secret_password

The server strictly mandates that all required access parameters reside within this local .secrets file; no tool calls or command-line arguments are accepted for sensitive data.

Operation

Command Line Invocation

Execute the bootstrap script:

bash python launch_server.py

Or initiate execution as a module entry point:

bash python -m src.gateway_core.listener

IDE Configuration (e.g., Cursor)

( Applicable from version 0.48 ) Navigate to Settings -> MCP Configuration. Select the option to 'Register a new global MCP endpoint':

This action modifies the global mcp.json configuration file:

{ "mcpServers": { "eclass-endpoint": { "command": "python", "args": ["/full/absolute/path/to/interface-gateway/launch_server.py"] } } }

Ensure the path specified in args points directly to launch_server.py.

Desktop Client Integration (e.g., Claude Desktop)

1. Open the Desktop Client application.
2. Access the Server Management panel (Settings > Server).
3. Add a novel endpoint:
4. Label: EClass Gateway
5. Execution String: Path pointing to your launch_server.py script.
6. Finalize the addition.
7. Select this newly configured endpoint during interactive sessions.

Exposed Tools

This gateway exposes the following functionalities via the MCP layer:

login

Initiates the connection sequence using the SSO mechanism.

{ "dummy_payload": "Any placeholder value required by the calling agent" }

get_courses

Retrieves the current user's roster of registered courses (requires prior successful authentication).

{ "dummy_payload": "Any placeholder value required by the calling agent" }

logout

Terminates the active eClass session.

{ "dummy_payload": "Any placeholder value required by the calling agent" }

authstatus

Reports the present validation status of the established session.

{ "dummy_payload": "Any placeholder value required by the calling agent" }

Standalone Client Utility (standalone_eclass_util.py)

The repository contains standalone_eclass_util.py, providing direct, non-MCP interaction capabilities:

Client Utility Capabilities

• Pure Python logic, independent of the MCP framework.
• Implements the full credential exchange sequence with UoA’s federated login.
• Fetches course metadata directly from the eClass endpoint.
• Offers a clean session termination method.

This file serves two main purposes: 1. As a reference implementation demonstrating the raw platform communication sequence. 2. As a simpler utility for projects not necessitating the overhead of MCP integration.

Execute the utility directly for testing:

bash python standalone_eclass_util.py

Verification Procedures

Use the integrated test suites for functional verification:

bash

Execute the entire test suite collection

python -m src.gateway_core.tests.run_all_suites

Execute targeted authentication tests

python -m src.gateway_core.tests.verify_login

Documentation Index

Detailed technical documentation is cataloged within the documentation/ subdirectory:

• General Guide
• Operational Mechanics
• Protocol Integration Details
• Exposed Functions Reference

Example MCP Invocation Sequence

python from mcp import SessionManager, StdIoConfig from mcp.client.transport import stdio_transport import asyncio

async def execute_eclass_workflow(): # Configuration pointing to the locally running server config = StdIoConfig( execution_command="python /full/path/to/interface-gateway/launch_server.py", )

async with stdio_transport(config) as (reader, writer):
    async with SessionManager(reader, writer) as agent_session:
        # Step 1: Establish connection
        await agent_session.establish_protocol_link()

        # Step 2: Authenticate
        auth_response = await agent_session.invoke_tool("login", {
            "dummy_payload": "initiate"
        })
        print(f"Login Status: {auth_response}")

        # Step 3: Obtain course list
        course_data = await agent_session.invoke_tool("get_courses", {
            "dummy_payload": "fetch_roster"
        })
        print(f"Retrieved Courses: {course_data}")

        # Step 4: Clean up
        await agent_session.invoke_tool("logout", {
            "dummy_payload": "terminate"
        })

if name == "main": asyncio.run(execute_eclass_workflow())

AI Agent Interoperability Rationale

This MCP gateway is specifically engineered for integration with AI agents supporting the Model Context Protocol, enabling automated tasks such as:

• Accessing real-time syllabus updates.
• Checking assignment deadlines.
• Retrieving course resources.
• Future integration: Submission handling (planned feature).

Security Posture

Security, especially concerning sensitive credentials, dictates the server's design:

Localized Execution Paradigm

• No Remote Telemetry: The server operates exclusively within the local execution host; no external cloud dependencies exist.
• Data Residency: Authentication tokens and secrets remain strictly confined to the local filesystem/memory.
• Operator Sovereignty: Full authority over execution and data access rests with the user.

Credential Handling Protocol

• Environment Isolation: Credentials are sourced solely from the .secrets file.
• Tool Parameter Neutrality: All exposed tools accept non-sensitive placeholder arguments (e.g., dummy_payload).
• LLM Isolation: LLMs interfacing via MCP are prevented from accessing secrets:
  • Credentials are not logged by AI service providers.
  • They are excluded from model fine-tuning datasets.
  • Sensitive data processing never leaves the local environment.

Session State Management

• Volatile Storage: Session context and cookies are held transiently in memory.
• Run-Bound Lifespan: State is discarded upon server termination.
• Direct Channel Communication: Communication flows directly to eClass, bypassing external proxies, save for the necessary interaction with the university's CAS gateway.

Recommended Practices

• Secure the .secrets file; never commit this file to public repositories.
• Execute the service only on trusted, secure computation environments.
• Do not attempt to pass actual secrets to the AI agent via the tool call arguments, as these will be ignored by the server and may be exposed to the LLM provider.

Licensing Agreement

GNU General Public License v3.0

This software is distributed under the terms of the GNU General Public License version 3—refer to the accompanying [LICENSE] file for specifics.

Implications for Users

Under GPL-3.0, redistribution (whether modified or not) mandates that the source code be offered under the same license. Key provisions include:

• Permitted Use: Use for any objective is allowed.
• Transparency: Source inspection is guaranteed.
• Distribution Rights: Sharing the software is permitted.
• Modification Rights: Customization and adaptation are allowed.

Rationale for GPL-3.0 Selection

We adopted GPL-3.0 to enforce specific community standards:

1. Security Verification: Mandates that any modifications affecting credential handling remain open for public audit.
2. Community Contribution: Encourages improvements to be returned to the public domain.
3. Malicious Fork Prevention: Discourages proprietary derivatives that might undermine security assurances.
4. Alignment: Matches the licensing philosophy of the underlying Open eClass project (GPL v2.0).

This licensing choice is critical given the software's role in managing secure access credentials, ensuring continuous transparency in its operation.

Acknowledgements

• Gratitude to GUnet (Greek Universities Network) for engineering and maintaining the foundational Open eClass platform, utilized widely by Hellenic academic institutions.
• The Open eClass core system is licensed under GNU GPL v2.0, enabling complementary open-source integrations like this one.
• Special commendation to the Asynchronous eLearning Group at GUnet for their ongoing platform enhancements.
• This project operates independently of GUnet; it respects all published Terms of Service for the eClass platform by employing official authentication pathways.

Collaboration

We welcome contributions! Please submit any proposed enhancements via a Pull Request.

WIKIPEDIA: XMLHttpRequest (XHR) is a programming interface, realized as a JavaScript object, used to execute HTTP requests between a user agent (like a web browser) and a remote server. Its methods permit client-side applications to asynchronously dispatch requests post-page load and process incoming data. XHR is a foundational element of the Ajax programming paradigm. Before Ajax, server interaction relied predominantly on traditional page reloads triggered by form submissions or hyperlink navigation.

== Historical Context == The conceptual basis for XMLHttpRequest originated in 2000 among developers at Microsoft Outlook. This concept was first realized within Internet Explorer 5 (released in 1999). The initial implementation did not utilize the standardized XMLHttpRequest string; instead, developers relied on object instantiations such as ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal browser support for the explicit XMLHttpRequest identifier was achieved. This standardized identifier has since become the established convention across all major browser rendering engines, including Mozilla's Gecko (since 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Specification Progression === The World Wide Web Consortium (W3C) published the first Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft for Level 2 arrived on February 25, 2008, introducing capabilities for monitoring transfer progress, enabling cross-origin communication, and handling binary data streams. By late 2011, the Level 2 features were integrated back into the primary specification. Development ownership was transferred to the WHATWG group towards the close of 2012, which now maintains the document using Web IDL definitions.

== Standardized Procedure == Implementing a data exchange using XMLHttpRequest typically involves a fixed sequence of programming steps:

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor.
2. Configuration (open): Invoke the open method to define the request method (GET/POST, etc.), specify the target URI, and set the operation mode (synchronous or asynchronous).
3. Event Listener Setup: For asynchronous operations, define a callback function to handle state transitions upon response receipt.
4. Transmission (send): Initiate the actual network request by calling the send method, optionally including data payload.
5. Response Processing: Monitor the object's state; upon reaching state 4 (the 'done' state), the server response is accessible, typically via the responseText property.

Beyond these fundamentals, XHR offers extensive control: custom request headers can inject metadata for server instructions, and data can be uploaded within the send call. Responses can be natively parsed from JSON into JavaScript objects or streamed incrementally. Furthermore, operations can be terminated prematurely or configured with timeouts.

== Cross-Origin Restrictions ==

Historically, limitations in the early architecture of the World Wide Web restricted requests originating from one domain to access resources on a different domain, a concept that XHR initially inherited.