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-Abdeckung

• Ein 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 core

Der 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.sh

Die 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.sh

Oder mit dem Inspector:

npx @modelcontextprotocol/inspector ./scripts/run-server.sh

Tools

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 container

Die 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_inspect gibt Kursstruktur zurück, nicht Lernleistung: keine Noten und kein benutzerspezifischer Abschlussstatus.

• Moodles Startseite ist eine Kurszeile, aber kein Lehrkurs, daher lehnt moodle_course_inspect sie ab. moodle_course_list meldet sie weiterhin, gekennzeichnet als isSiteCourse.

• H5P-Schemagenerierung ist eine Ebene tief: Ein verschachteltes library-Feld legt die Wrapper-Form und die erlaubten Bibliotheksversionen fest, aber seine params folgen der eigenen Semantik dieser Bibliothek – rufen Sie sie mit einem zweiten moodle_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 als x-h5p-* / x-moodle-*-Annotationen bewahrt und als Konvertierungshinweise gemeldet, statt verworfen zu werden.

• Moodle REST kann kein leeres Array oder ein echtes null ausdrü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/ — MIT

• moodle/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