mcp-usc

Lokaler und HTTP-first MCP-Server für das Moodle-Campus-Virtual der Universidade de Santiago de Compostela. Ermöglicht das Abfragen von Kursen, Kalender, Nachrichten, Foren, Materialien, Aufgaben und Tests sowie die Suche nach Prüfungsterminen auf offiziellen USC-Seiten und PDFs.

Version 0.3.0 erweitert die Abdeckung des Schülers auf 301 untersuchte Moodle-Fähigkeiten: 192 erlaubte Lesevorgänge und 109 identifizierte Aktionen. Nur zwölf private Änderungen mit eindeutigem Umfang können über die generische Schnittstelle ausgeführt werden; Veröffentlichungen, bewertbare Aktivitäten, Abgaben, Tests und Löschungen verwenden kontextbezogene Werkzeuge. Jede Operation mit Wirkung erfordert eine Vorschau, ein Einmal-Token und die Genehmigung des MCP-Clients.

Designprinzipien

• Der MCP-Server verwendet STDIO; „HTTP-first“ beschreibt die Verbindung zwischen diesem Prozess und Moodle/USC.

• Normale Abfragen und Schreibvorgänge automatisieren keinen Browser.

• Die offizielle Moodle-REST-API wird bevorzugt, wenn ein legitimes Token vorhanden ist.

• Mit einem MoodleSession-Cookie verwenden Lesevorgänge AJAX same-origin und direkte Downloads /pluginfile.php. HTML-Formulare sind für bereits bestätigte Testoperationen reserviert.

• Playwright öffnet nur einen sichtbaren Browser, um Microsoft Entra/MFA abzuschließen und das anfängliche Cookie zu erhalten. Es wird nach dem Login geschlossen.

• Jeder entfernte Text – Namen, Nachrichten, Fragen, Hinweise und Dokumente – wird als nicht vertrauenswürdiger Inhalt markiert und niemals als Anweisungen interpretiert.

• Der Connector handelt ausschließlich mit den Berechtigungen des authentifizierten Kontos: Er erhöht keine Privilegien und gibt sich nicht als Lehrpersonal oder Verwaltung aus.

• Er muss mit einem Schülerkonto und einem Token mit minimalen Rechten konfiguriert werden. Die gemeinsamen Moodle-APIs respektieren immer die effektiven Berechtigungen, und ein Konto mit zusätzlichen Rollen könnte mehr Daten sehen als ein normaler Schüler.

Es fragt weder E-Mail noch Teams ab. Eine interne Moodle-Nachricht kann je nach Empfängerkonfiguration externe Benachrichtigungen erzeugen; die Vorschau weist vor dem Senden darauf hin.

Related MCP server: MCP UJI Academic Server

Anforderungen

• Windows, Linux oder macOS;

• Python 3.11 oder höher;

• uv empfohlen;

• ein aktives USC-Konto für private Daten;

• optional ein Token für Moodle-Webdienste, das die erforderlichen Funktionen bereitstellt.

Installation

git clone https://github.com/PabloPC05/mcp-usc.git
cd mcp-usc
uv sync --extra dev

Dies genügt, um den Server mit einem REST-Token oder einer bereits gespeicherten Sitzung auszuführen. Installiere Playwright nur, wenn du die Sitzung über den Login-Assistenten erstellen oder erneuern musst:

uv sync --extra dev --extra browser-auth
uv run playwright install chromium

Der Assistent kann Chromium oder ein installiertes Chrome/Edge verwenden:

$env:USC_BROWSER_CHANNEL = "chrome" # también "msedge" o "chromium"

Authentifizierung und HTTP-Transporte

Der Connector wählt automatisch den privaten Transport in dieser Reihenfolge:

1. Offizielles REST, wenn USC_MOODLE_TOKEN oder USC_MOODLE_TOKEN_FILE ein Token bereitstellt.

2. HTTP mit dem von keyring gespeicherten MoodleSession-Cookie.

REST-Token

Verwende ausschließlich ein legitimes Token, das Moodle für dein Konto und deinen Dienst ausgestellt hat:

$env:USC_MOODLE_TOKEN = "..."
uv run mcp-usc status

Es kann auch aus einer geschützten lokalen Datei gelesen werden:

$env:USC_MOODLE_TOKEN_FILE = "C:\ruta\privada\moodle-token.txt"

Verwende dein USC-Passwort nicht mit login/token.php und speichere es nicht in .env. Dass eine Funktion in Moodle existiert, bedeutet nicht, dass sie im mit dem Token verbundenen Dienst aktiviert ist.

Sitzung per Cookie

uv run mcp-usc login
uv run mcp-usc status

Schließe Microsoft Entra und MFA persönlich im sichtbaren Fenster ab. Das Programm extrahiert nur MoodleSession, prüft die Sitzung per HTTP und speichert das Cookie mit dem Schlüssel moodle-session im sicheren Systemspeicher – unter Windows im Credential Manager. Das Passwort läuft nicht über den MCP.

Nach dem Login verwenden alle Operationen httpx:

• /user/preferences.php liefert die Identität und den ephemeren sesskey, ohne das Dashboard zu öffnen;

• /lib/ajax/service.php führt als AJAX markierte Funktionen aus;

• Lesevorgänge schlagen geschlossen fehl, wenn Moodle sie nicht per AJAX bereitstellt;

• authentifizierte Downloads behalten das Cookie, akzeptieren nur direkte /pluginfile.php-Pfade und wenden lokale Grenzen an;

• nur bestimmte Testoperationen können nach expliziter Bestätigung HTML-Formulare verwenden.

Der sesskey wird weder gespeichert noch zurückgegeben. Aufgrund der AJAX-Protokollanforderungen kann er in der URL erscheinen, die die Moodle-Infrastruktur sieht. Das Cookie entspricht einer Anmeldeinformation, solange es gültig ist: Kopiere, protokolliere, veröffentliche oder synchronisiere es nicht. Wenn es abläuft, wiederhole mcp-usc login.

Kompatibilitätsmatrix

Der filemanager-Manager von Moodle erstellt Entwürfe über JavaScript und entspricht keinem Standard-Multipart-Feld. Wenn eine Abgabe nur diesen Manager anbietet, erfordert das Ersetzen oder Löschen seiner Dateien ein autorisiertes REST-Token; die öffentlichen Dateiwerkzeuge im Sitzungsmodus stoppen, ohne etwas zu ändern. Playwright wird nicht verwendet, um den Dateimanager zu emulieren.

Autorisierte lokale Dateien

Die Upload-Werkzeuge sind deaktiviert, bis ein Allowlist-Ordner konfiguriert ist:

$env:USC_UPLOAD_ROOT = "C:\Users\TU_USUARIO\Documents\mcp-usc-uploads"
$env:USC_MAX_UPLOAD_BYTES = "52428800"

USC_UPLOAD_ROOT muss existieren. Es werden nur reguläre Dateien akzeptiert, die innerhalb dieses Ordners aufgelöst werden; Pfade, die aus ihm herausführen, werden nicht verfolgt, und dieselbe Datei wird nicht zweimal zugelassen. Die Vorschau zeigt relativen Pfad, Name, Größe und SHA-256, bevor ein Token ausgegeben wird.

Lokale Upload-Grenzen:

• maximal 20 Dateien pro Operation;

• USC_MAX_UPLOAD_BYTES gilt sowohl für jede Datei als auch für die Gesamtmenge;

• Standardwert: 50 MiB (52428800 Bytes);

• konfigurierbarer Bereich: von 1 Byte bis 100 MiB;

• Online-Text hat ein zusätzliches Limit von 1 MiB.

replace_submission_files ersetzt den vollständigen Satz von Abgabedateien; es fügt nicht stillschweigend eine zu den vorhandenen hinzu. Vor der Bestätigung prüft es, ob der Dienst Uploads erlaubt und ob die Abgabe nur das Plugin file aktiv hat. Ebenso wird das Speichern von REST-Text nur aktiviert, wenn onlinetext das einzige aktive Plugin ist. Moodle verarbeitet alle Plugins in mod_assign_save_submission, daher wird eine unbekannte Kombination abgelehnt, bevor ein Entwurf erstellt oder die Abgabe geändert wird.

Öffentliche Prüfungsquellen

Jedes USC-Zentrum veröffentlicht seine eigenen Kalender. Konfiguriere kanonische Seiten oder PDFs, getrennt durch Semikolons:

$env:USC_EXAM_SOURCES = "https://www.usc.gal/gl/centro/MI_CENTRO/horarios/cursos;https://assets.usc.gal/ruta/calendario.pdf"

Die Suche verwendet direktes HTTP, akzeptiert nur HTTPS unter usc.gal/usc.es, folgt maximal fünf Weiterleitungen und lädt maximal 15 MB pro Dokument herunter. Sie führt kein Massen-Crawling durch: Sie fragt die angegebenen Quellen und deren direkte Prüfungs-/PDF-Links ab. Jeder Beleg speichert URL, PDF-Seite, falls zutreffend, und Abfragezeit; abweichende Quellen werden als Konflikt angezeigt.

Mit Codex verbinden

Von PowerShell auf diesem Rechner:

codex mcp add usc-campus -- uv --directory C:\Users\pablo\mcp-usc run mcp-usc serve
codex mcp list

Um öffentliche Quellen aus der MCP-Konfiguration einzubeziehen:

codex mcp remove usc-campus
codex mcp add usc-campus --env USC_EXAM_SOURCES="https://www.usc.gal/gl/centro/MI_CENTRO/horarios/cursos" -- uv --directory C:\Users\pablo\mcp-usc run mcp-usc serve

Starte den Client neu oder öffne eine neue Sitzung, um den Server zu laden. Laut der offiziellen OpenAI-Dokumentation wird die MCP-Konfiguration zwischen der ChatGPT-App, der Codex-CLI und der IDE-Erweiterung desselben Hosts geteilt.

Aktiviere außerdem die Host-Genehmigung für alle Schreibvorgänge in %USERPROFILE%\.codex\config.toml:

[mcp_servers.usc-campus]
command = "uv"
args = ["--directory", 'C:\Users\pablo\mcp-usc', "run", "mcp-usc", "serve"]
default_tools_approval_mode = "writes"

Die MCP-Anmerkungen, die Vorschau, das Token und die Host-Genehmigung sind komplementäre Ebenen; keine ersetzt eine menschliche Entscheidung über die genauen Parameter.

MCP-Werkzeuge

Version 0.3.0 stellt 75 Werkzeuge bereit: 39 Lesevorgänge, 18 Vorschauen und 18 Operationen mit Wirkung. Die vollständige Fähigkeitsstudie erläutert das Inventar, die Sicherheitsgrenzen und die Unterschiede zwischen Moodle 4.5 und 5.2.

call_student_read akzeptiert nur die 192 Funktionen, die ausdrücklich in der Whitelist enthalten sind; es ist kein beliebiger Moodle-Proxy. Mit REST-Token kann list_student_capabilities(available_only=true) anzeigen, welche der konfigurierte Dienst ankündigt. Mit AJAX-Sitzung ist die vollständige Verfügbarkeit nicht immer ermittelbar, und jeder Aufruf schlägt geschlossen fehl, wenn Moodle die Funktion nicht bereitstellt.

Die zwölf generischen Aktionen beschränken sich auf eigene Präferenzen, private Favoriten, Stummschalten oder Markieren von Konversationen/Benachrichtigungen, das Aufbewahren eines ungesendeten Entwurfs und das Markieren einer Frage. Die neuen kontextuellen Aktionen lösen über proprietäres HTTP, Kurs, Forum, Gruppe, Zielgruppe, Phase und Optionen auf, bevor sie eine Bestätigung ausgeben:

• persönliche Kalenderereignisse erstellen oder löschen;

• eine Diskussion starten oder öffentlich in einem Forum antworten, ohne Anhänge und ohne private Antwort;

• eigene Antworten einer Choice-Aktivität senden oder zurückziehen.

Diese sechs kontextuellen Aktionen setzen voraus, dass ein legitimes REST-Token sie ankündigt. Moodle 4.5–5.2 kennzeichnet seine Funktionen normalerweise nicht als AJAX; der Cookie-Modus stoppt vor der Vorschau und versucht nicht, sie mit dem Browser zu emulieren.

Der Katalog identifiziert außerdem studentische Aktionen, für die es noch keinen sicheren Ausführer gibt. Sie werden als generic_execution_supported=false veröffentlicht: Das Erscheinen im Inventar erlaubt weder ihre Ausführung noch bedeutet es, dass die USC das entsprechende Modul oder Plugin aktiviert hat.

Nachrichten, Foren und Materialien

• list_messages liest empfangene oder gesendete Nachrichten, ohne sie zu markieren. list_conversations bleibt nur aus Kompatibilitätsgründen erhalten und schlägt geschlossen fehl: Bestimmte Moodle-Versionen können beim Ausführen dieser vermeintlichen Leseoperation eine Konversation mit sich selbst erstellen und als Favorit markieren.

• Die Foren umfassen alle sichtbaren, nicht nur Neuigkeiten. Moodle kann Beiträge beim Ausführen von mod_forum_get_discussion_posts als gelesen markieren; deshalb schlägt list_discussion_posts geschlossen fehl und das Paar preview_inspect_discussion_posts / inspect_discussion_posts verlangt vor dem Durchgehen von Beiträgen und Anhangsmetadaten eine Bestätigung.

• search_message_contacts erstellt eine temporäre Referenz auf den Empfänger. preview_message verlangt eine kürzliche Suche, zeigt Name, ID und Text an und sendet niemals.

• list_course_contents listet Abschnitte, Aktivitäten, Seiten, Links und Dateien auf.

• list_course_resources gibt undurchsichtige Referenzen mit zehn Minuten Gültigkeit zurück. Nur eine kürzliche Referenz kann mit read_course_resource verwendet werden.

• read_course_resource unterstützt PDF, Text/HTML und OOXML (.docx, .pptx, .xlsx). Standardmäßig begrenzt es den Download auf 25 MiB, den Text auf 100.000 Zeichen und PDFs auf 100 Seiten; die pro Aufruf akzeptierten Maxima sind 50 MiB, 500.000 Zeichen und 300 Seiten.

• Im Sitzungsmodus erfordern Inhalte und Ankündigungen eine reine AJAX-Funktion, und Ressourcen müssen direkt auf /pluginfile.php zeigen; das Öffnen von course/view.php, mod/*/view.php oder Forumsseiten wird abgelehnt, weil es Besuche registrieren, Lesestatus markieren oder die Abschlussbearbeitung ändern kann.

Aufgaben und Abgaben

• Mit einem REST-Token, das die erforderlichen Funktionen ankündigt, können Aufgaben aufgelistet und Entwurf, Dateien, Online-Text, Feedback und Berechtigungen abgefragt werden.

• Die HTML-Seiten von Aufgaben registrieren Aufrufe und können die Abschlussbearbeitung ändern; deshalb schlagen alle Lese-, Vorschau- und Schreiboperationen für Aufgaben fehl, bevor sie im Sitzungsmodus geöffnet werden.

• Text speichern, Dateien ersetzen/löschen, zur Bewertung einreichen oder die gesamte Abgabe entfernen sind unterschiedliche Schreiboperationen, jede mit ihrer eigenen Vorschau.

• submit_assignment kann die Bearbeitung des Entwurfs schließen und muss die von Moodle angezeigte Abgabeerklärung respektieren.

• remove_submission verwendet mod_assign_remove_submission, verfügbar in Moodle 4.5 oder neuer. Es ist destruktiv und entspricht nicht „wieder öffnen“.

• check_submission_reopen ändert niemals den Status. Wenn die Abgabe bereits bearbeitbar ist, meldet es dies; wenn sie geschlossen ist, behält die Standard-API die Wiedereröffnung dem Lehrpersonal vor. Der Connector versucht nicht, diese Einschränkung zu umgehen: Die Wiedereröffnung muss über die normalen Kanäle beim Lehrenden beantragt werden.

Tests

• Eigene Tests und Versuche können aufgelistet und die erlaubte Überprüfung eines bereits abgeschlossenen Versuchs gelesen werden.

• Das Öffnen der Daten oder der Zusammenfassung eines aktiven Versuchs kann dazu führen, dass Moodle einen Ablauf verarbeitet und dessen Status ändert. Deshalb schlagen get_quiz_attempt_page und get_quiz_attempt_summary geschlossen fehl; preview_inspect_quiz_attempt zeigt das Risiko an, und inspect_quiz_attempt verlangt eine Bestätigung.

• Im Sitzungsmodus erfordern die reinen Listen AJAX. Die Formulare werden nur im zweiten bestätigten Aufruf geöffnet, um einen potenziell zustandsbehafteten Versuch zu prüfen, zu starten, zu speichern oder abzuschließen; die Vorschau öffnet mod/quiz/view.php nicht.

• start_quiz kann sofort einen Timer aktivieren.

• save_quiz_answers ändert einen offenen Versuch, schließt ihn aber nicht ab.

• finish_quiz ist normalerweise irreversibel.

• Die Fragen und Feldnamen stammen von Moodle, werden als nicht vertrauenswürdige Daten behandelt, und der Connector leitet niemals ab, ob eine Antwort richtig ist.

• Jede Schreiboperation erfordert eine eigene Vorschau; eine frühere Genehmigung autorisiert nicht den nächsten Schritt des Versuchs.

Bestätigungen und Schreiboperationen

Jede Schreiboperation folgt zwei Aufrufen:

1. preview_* validiert den Zustand und gibt die sichtbaren Parameter plus ein confirmation_token zurück.

2. Das Schreibwerkzeug verbraucht dieses Token nur, wenn Aktion und Parameter exakt übereinstimmen.

Die Tokens leben nur im Speicher, laufen nach fünf Minuten ab und sind nur einmal verwendbar. Das Ändern von Text, Empfänger, Dateien, Antworten, Versuch oder einer anderen Eingabe macht die Bestätigung ungültig. Die writes-Genehmigung des Hosts muss weiterhin aktiv sein, damit der zweite Aufruf menschliches Eingreifen erfordert.

Jede Kontaktreferenz und jedes Bestätigungstoken ist außerdem an die user_id von Moodle gebunden, die es erstellt hat. Wenn sich Konto oder Sitzung zwischen Vorschau und Schreiboperation ändern, wird die Operation abgelehnt. Eine gültige Antwort auf ein HTML-Formular bestätigt nur, dass die Anfrage gesendet wurde: Es wird outcome="unknown" zurückgegeben, wenn Moodle keine eindeutige Nachbedingung bietet, und es wird niemals über einen zweiten Transport bei einer mehrdeutigen Antwort erneut versucht.

Ein Timeout oder eine Verbindungsunterbrechung während einer Schreiboperation ist mehrdeutig: Moodle kann die Operation angewendet haben, auch wenn der Client keine Antwort erhalten hat. Wiederhole nicht automatisch eine Nachricht, Abgabe, Speicherung oder Abschluss. Lies die Konversation, den Abgabestatus oder den Versuch erneut und entscheide anhand dieser Evidenz; bei einem zeitgesteuerten Test prüfe die Uhr auch direkt in Moodle.

Tests

uv run pytest
uv run ruff check .

Die Suite ersetzt HTTP, Keyring, Formulare, Uploads und Downloads durch Test-Doubles. Sie enthält keine Tokens, Cookies oder echten Daten und führt keine Schreiboperation gegen die USC aus. Der echte Zugriff wird nur manuell und lokal validiert.

Offizielle Quellen

Der Vertrag wurde mit offizieller Dokumentation und offiziellem Code abgeglichen:

• Externe Dienste von Moodle und seine Sicherheitsempfehlungen.

• Definitionen von Moodle 4.5 für Messaging, Foren, Inhalte, Aufgaben und Quizze aus dem offiziellen GPL-3.0-Repository.

• moodlehq/moodleapp (Apache-2.0), offizielle Referenz für die Nutzung von Diensten, Inhalten und Ressourcen von einem Client aus.

Überprüfte Vorarbeiten

Es wurden lizenzierte Projekte untersucht, um bereits gelöste Muster nicht zu wiederholen. Es wurden Architekturideen und öffentliche Verträge wiederverwendet, keine Anmeldedaten oder inkompatibler Code:

• haolamnm/moodle-mcp-srv (Apache-2.0): Architektur, Diagnose und REST-Client.

• Snaw80/moodle-mcp (MIT): SSO-Login und mobiler Ablauf. Der öffentliche mobile Endpunkt der USC gibt 404 zurück, daher wird ein lokal erhaltenes Cookie verwendet.

• GhaithAlHallak8/moodler-mcp (MIT): Moodle-Sitzung und AJAX same-origin.

• 1alexandrer/moodle-mcp (MIT): auf Studierende ausgerichtete Werkzeuge und umsetzbare Ereignisse.

• mrcinv/moodle_api.py (MIT): generischer Client und core_course_get_contents.

• lmscloud-io/moodle-mcp-server (GPL-3.0): MCP-Exposition von Moodle-Funktionen mit minimalen Rechten.

loyaniu/moodle-mcp wurde nur zum Vergleich des Umfangs verwendet, da das Repository keine Lizenz angibt; es wurde kein Code kopiert.

Bekannte Grenzen

• Die Verfügbarkeit jedes Web Service hängt von der Version, Konfiguration und den Berechtigungen ab, die die USC dem Token oder der Sitzung zuweist.

• Die OIDC-Sitzung und MoodleSession laufen ab; mcp-usc login muss erneut ausgeführt werden.

• AJAX und die Quizformulare können sich zwischen Versionen ändern. Der Connector schlägt fehl (fail-closed), wenn er eine Operation nicht sicher erkennt.

• Aufgaben erfordern REST: Ihre Seiten registrieren Ansichten und der JavaScript-filemanager entspricht keinem nativen Multipart-Feld.

• Das Löschen einer vollständigen Abgabe erfordert Moodle 4.5+ und gültige Berechtigungen. Das Wiederöffnen einer geschlossenen Abgabe obliegt dem Lehrpersonal.

• Nicht alle Lehrkräfte nutzen den Campus Virtual; E-Mail oder Teams können Informationen enthalten, die dieser Server nicht abruft.

• Ein Moodle-Datum kann eine kontinuierliche Bewertung sein und ein öffentliches Datum eine offizielle Prüfung. Sie werden als getrennte Quellen beibehalten.