moodle-ai-mcp
moodle-ai-mcp
Eine KI-native MCP-Steuerungsebene für Moodle.
Ein MCP-Client (Claude Code, ChatGPT, Cursor oder alles andere, das das Model Context Protocol spricht) verbindet sich mit diesem Server und erhält strukturierte, präzise Antworten über eine echte Moodle-Website: was sie ist, als wer die Verbindung authentifiziert ist, was sie tun darf, welche von Moodles externen Funktionen sie erreichen kann, und – der Teil, der sie mehr als einen REST-Wrapper macht – genau welche H5P-Bibliotheken die Website installiert hat und wie deren Inhaltsschemata aussehen.
Dies ist kein dünner Wrapper um Moodle REST. Das langfristige Ziel ist eine Steuerungsebene, die ein KI-Client nutzen kann, um ganze Kurse sicher zu entwerfen und zu erstellen. Dieses Repository enthält derzeit das erste Fundament dafür.
Aktueller Reifegrad: Grundstein-Meilenstein, schreibgeschützt
Heute funktionsfähig:
MCP-Server auf stdio mit sieben kuratierten Tools, basierend auf dem offiziellen MCP TypeScript SDK
Ein Moodle-5.2-Local-Plugin (
local_aimcp) mit sieben schreibgeschützten externen Funktionen, echter Capability-Durchsetzung und PHPUnit-AbdeckungEin capability-bewusstes Kurs-Lesemodell: Abschnitte, Aktivitäten, Abschluss- und Bewertungskonfiguration, das widerspiegelt, was die authentifizierte Identität tatsächlich sehen darf, statt alles mit einem
hidden-Flag.Dynamische Erkennung der externen Funktionen, die der authentifizierte Dienst erreichen kann, mit verlustfreier Signatur-Introspektion
Dynamische Erkennung installierter H5P-Bibliotheken und ihrer tatsächlich installierten Semantik, konvertiert in JSON Schema mit expliziten Hinweisen für alles, was JSON Schema nicht ausdrücken kann.
Absichtlich nicht gebaut: jegliche Schreiboperationen, Kurs-/Aktivitäts-/H5P-Erstellung, die Course-Blueprint-Engine, Browser-Automatisierung, Dateiübertragung und Hosting-Infrastruktur. Siehe „Einschränkungen“ unten.
Related MCP server: Drupal Bridge MCP
Architektur
AI client --MCP/stdio--> apps/mcp-server (TypeScript, MIT)
|
| authenticated Moodle web service call
v
moodle/local/aimcp (Moodle plugin, GPL-3.0-or-later)
|
v
Moodle 5.2 core + H5P coreDer Server besitzt das Protokoll, die Tool-Oberfläche, die Orchestrierung und die Schema-Konvertierung. Das Plugin besitzt alles, was nur Moodle beantworten kann: Identität, Kontext, Capabilities, das Register der externen Funktionen und die H5P-Engine. Moodle-Logik wird nie in TypeScript neu implementiert, und Orchestrierung leckt nie in PHP.
Details, einschließlich warum die Tool-Oberfläche sechs Tools statt mehrerer hundert umfasst, finden Sie in docs/ARCHITECTURE.md.
Voraussetzungen
Node.js 24
Docker, mit einem Moodle-5.2-Stack von moodle-docker
Ein Moodle-Webservice-Token für einen Benutzer, der auf einem aktivierten externen Dienst autorisiert ist
Lokale Entwicklung
Vollständige Anleitung: docs/LOCAL-DEV.md. Die Kurzversion:
cd ~/DEV/moodle-ai/moodle-ai-mcp
# 1. Start the Moodle stack (installs the persistence override, mounts the plugin)
./scripts/stack.sh start
# 2. Register the plugin with Moodle
docker exec -u www-data -w /var/www/html moodle-ai-webserver-1 \
php admin/cli/upgrade.php --non-interactive
# 3. Attach the plugin's functions to your external service (idempotent)
docker exec -u www-data -w /var/www/html moodle-ai-webserver-1 \
php public/local/aimcp/cli/provision_service.php --service=moodle_ai_mcp_dev
# 4. Build and run the server
npm install
npm run build
./scripts/run-server.shDie Datenbank, moodledata und installierte H5P-Bibliotheken befinden sich in benannten Docker-Volumes, daher ist ./scripts/stack.sh recreate sicher. Nur ./scripts/stack.sh reset zerstört Daten, und es fragt vorher. Sichern Sie jederzeit mit ./scripts/backup.sh.
Anmeldedaten stammen aus .env.local, einem Symlink zu einer Datei außerhalb dieses Repositorys. .env* ist gitignored; siehe docs/SECURITY.md.
Verbinden eines MCP-Clients
claude mcp add moodle-ai --scope local -- \
/absolute/path/to/moodle-ai-mcp/scripts/run-server.shOder mit dem Inspector:
npx @modelcontextprotocol/inspector ./scripts/run-server.shTools
Tool | Was es beantwortet |
| Welches Moodle ist das, als wer bin ich verbunden, was kann diese Identität tun, welche Plugins und H5P sind verfügbar. |
| Welche Kurse existieren und für diese Identität sichtbar sind, optional durchsucht. |
| Die Struktur eines Kurses: Abschnitte in Reihenfolge, Aktivitäten in Kursseiten-Reihenfolge, Abschlusskonfiguration und Bewertungselement-Konfiguration. Lässt aus, was der Aufrufer nicht sehen darf, schützt kursverwaltungsbezogene Felder (rohe Verfügbarkeitsregeln, Modul-ID-Nummern) hinter Moodles eigenen Editor-Capabilities und gibt an, wie viel es zurückgehalten hat. |
| Welche von Moodles externen Funktionen kann diese Verbindung erreichen, nach Relevanz sortiert. Live entdeckt, nie aus einer eingebauten Liste. |
| Die vollständige Signatur einer Funktion: Moodles eigener Parameter- und Rückgabebaum, plus generiertes JSON Schema und Konvertierungshinweise. |
| Welche H5P-Bibliotheken installiert sind, in welchen exakten Versionen, welche ausführbare Inhaltstypen sind, welche nur Abhängigkeiten sind, und welche Moodle derzeit zum Erstellen anbietet. |
| Die installierte Semantik für eine H5P-Bibliotheksversion, plus generiertes JSON Schema und Hinweise für alles, was H5P ausdrückt, das JSON Schema nicht kann. |
Jedes Tool ist mit readOnlyHint: true, destructiveHint: false annotiert und gibt sowohl structuredContent als auch einen JSON-Text-Fallback zurück.
Es gibt bewusst kein generisches Tool „beliebige Moodle-Funktion aufrufen“. Suche und Beschreibung machen den Long Tail auffindbar; die Ausführung beliebiger Funktionen benötigt eine Sicherheitsklassifizierung, die es noch nicht gibt.
Tests
npm --prefix apps/mcp-server run typecheck # TypeScript, strict
npm --prefix apps/mcp-server run test:unit # pure logic, no Moodle needed
npm --prefix apps/mcp-server run build
npm --prefix apps/mcp-server run test:integration # real Moodle + real MCP session
./scripts/lint-plugin.sh # php -l over the plugin
./scripts/check-plugin.sh # Moodle coding standard (moodle-cs)
./scripts/test-plugin.sh # PHPUnit inside the Moodle containerDie Integrationssuite ist kein Mock: Sie startet den gebauten Server als Kindprozess, spricht MCP mit dem offiziellen SDK-Client und prüft gegen die Live-Site – einschließlich, dass die Identität der erwartete Moodle-Benutzer ist und dass kein Token in irgendeiner Ausgabe erscheint.
Einschränkungen
Schreibgeschützt über MCP. Kein Erstellen, Aktualisieren, Löschen, Einschreiben, Bewerten, Hoch- oder Herunterladen. Das Einzige im Repository, das in Moodle schreibt, ist die Entwicklungs-Fixture-CLI, die von keinem MCP-Client oder Webdienst erreichbar ist (siehe docs/SECURITY.md).
Keine beliebige Funktionsausführung. Nur Suche und Beschreibung.
Nur stdio. HTTP-Transport ist eine zukünftige Ergänzung; die Domänenschicht ist bereits transportfrei.
Kein Course Blueprint, keine Diff/Apply-Engine, keine Inhaltsgenerierung.
Keine Browser-Automatisierung, keine Screenshots oder Barrierefreiheitsprüfung.
moodle_course_inspectgibt Kursstruktur zurück, nicht Lernleistung: keine Noten und kein benutzerspezifischer Abschlussstatus.Moodles Startseite ist eine Kurszeile, aber kein Lehrkurs, daher lehnt
moodle_course_inspectsie ab.moodle_course_listmeldet sie weiterhin, gekennzeichnet alsisSiteCourse.H5P-Schemagenerierung ist eine Ebene tief: Ein verschachteltes
library-Feld legt die Wrapper-Form und die erlaubten Bibliotheksversionen fest, aber seineparamsfolgen der eigenen Semantik dieser Bibliothek – rufen Sie sie mit einem zweitenmoodle_h5p_schema-Aufruf ab.Einige H5P- und Moodle-Konstrukte können nicht in JSON Schema ausgedrückt werden (
showWhen-Bedingungen, HTML-Tag-Whitelists, PCRE-Muster, PARAM-Bereinigungsregeln). Sie werden alsx-h5p-*/x-moodle-*-Annotationen bewahrt und als Konvertierungshinweise gemeldet, statt verworfen zu werden.Moodle REST kann kein leeres Array oder ein echtes
nullausdrücken; der Client meldet beides als explizite Warnungen.Das Plugin ist per Bind-Mount aus diesem Repository in den Container eingebunden; die rsync-Kopie wird nur als Fallback aufbewahrt. Ein Host-Symlink funktioniert nicht, aus Gründen, die in docs/LOCAL-DEV.md erläutert werden.
Lizenzierung
apps/mcp-server/— MITmoodle/local/aimcp/— GPL-3.0-or-later (erforderlich: Es ist ein Moodle-Plugin)
Es wird kein GPL-Implementierungscode in den MIT-Server kopiert. Referenzprojekte wurden als Architektur-Referenzen untersucht und im Clean-Room-Verfahren neu implementiert; die Begründung pro Projekt finden Sie in docs/REFERENCE-ARCHITECTURE.md.
Dokumentation
docs/ARCHITECTURE.md — Design und Grenzen
docs/REFERENCE-ARCHITECTURE.md — Wiederverwendungsmatrix und Lizenzierung
docs/LOCAL-DEV.md — reproduzierbare lokale Einrichtung
docs/SECURITY.md — Umgang mit Geheimnissen, Autorisierung, Oberflächenbeschränkungen
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Read-only discovery of ChatGXT's integration catalog and public MCP capabilities.
Public AI web-readiness scanner and machine-facing observability discovery service.
Read-only discovery of Framekeep capabilities, security boundaries, and public resources.
Find governed AI capabilities and verify signed receipts. Read-only, no account.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Moodle via web services, allowing tasks like listing courses, assignments, events, and downloading files.1032 PyPI4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Drupal sites through MCP tools, with automatic discovery, OAuth-based authentication, and scope validation.30 npm5MIT
- AlicenseNot gradedqualityDmaintenanceConnects Moodle LMS with AI assistants through the Model Context Protocol, enabling users to interact with Moodle data via a conversational chatbot interface.10 npmMIT
- AlicenseAqualityNot gradedmaintenanceProvides read-only access to Gemini 3 Online's knowledge surface (models, pricing, links, FAQ) for MCP-compatible AI clients, requiring no API keys.3MIT