moodle-ai-mcp

Управляющая плоскость MCP для Moodle, ориентированная на ИИ.

MCP-клиент (Claude Code, ChatGPT, Cursor или что-либо ещё, говорящее на Model Context Protocol) подключается к этому серверу и получает структурированные, точные ответы о реальном сайте Moodle: что это за сайт, под кем аутентифицировано подключение, что ему разрешено делать, к каким внешним функциям Moodle он может обращаться, и — та часть, которая делает его чем-то большим, чем обёртка над REST, — какие именно библиотеки H5P установлены на сайте и каковы их схемы контента.

Это не тонкая обёртка вокруг Moodle REST. Долгосрочная цель — управляющая плоскость, которую ИИ-клиент может использовать для безопасного проектирования и создания целых курсов. В этом репозитории сейчас находится первый фундамент для этого.

Текущая зрелость: базовый этап, только чтение

Работает сегодня:

• MCP-сервер на stdio с семью курируемыми инструментами, построенный на официальном MCP TypeScript SDK

• Локальный плагин Moodle 5.2 (local_aimcp) с семью внешними функциями только для чтения, реальным контролем возможностей и покрытием PHPUnit

• Модель чтения курса с учётом возможностей: разделы, действия, настройки завершения и оценок, отражающая то, что аутентифицированная учётная запись действительно может видеть, а не всё с прикреплённым флагом hidden

• Динамическое обнаружение внешних функций, доступных аутентифицированному сервису, с без потерь интроспекцией сигнатур

• Динамическое обнаружение установленных библиотек H5P и их реальной установленной семантики, преобразованной в JSON Schema с явными примечаниями для всего, что JSON Schema не может выразить

Намеренно не построено: любые операции записи, создание курсов/действий/H5P, движок Course Blueprint, автоматизация браузера, передача файлов и инфраструктура хостинга. См. «Ограничения» ниже.

Related MCP server: Drupal Bridge MCP

Архитектура

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

Сервер владеет протоколом, поверхностью инструментов, оркестрацией и преобразованием схем. Плагин владеет всем, на что может ответить только Moodle: идентичность, контекст, возможности, реестр внешних функций и движок H5P. Логика Moodle никогда не переписывается на TypeScript, а оркестрация никогда не просачивается в PHP.

Подробности, включая то, почему поверхность инструментов состоит из шести инструментов, а не из нескольких сотен, — в docs/ARCHITECTURE.md.

Предварительные требования

• Node.js 24

• Docker со стеком Moodle 5.2 из moodle-docker

• Токен веб-сервиса Moodle для пользователя, авторизованного на включённом внешнем сервисе

Локальная разработка

Полные инструкции: docs/LOCAL-DEV.md. Краткая версия:

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

База данных, moodledata и установленные библиотеки H5P находятся в именованных Docker-томах, поэтому ./scripts/stack.sh recreate безопасен. Только ./scripts/stack.sh reset уничтожает данные, и он сначала спрашивает. Создавайте резервные копии в любое время с помощью ./scripts/backup.sh.

Учётные данные берутся из .env.local, который является симлинком на файл вне этого репозитория. .env* игнорируется git; см. docs/SECURITY.md.

Подключение MCP-клиента

claude mcp add moodle-ai --scope local -- \
  /absolute/path/to/moodle-ai-mcp/scripts/run-server.sh

Или с помощью Inspector:

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

Инструменты

Каждый инструмент аннотирован readOnlyHint: true, destructiveHint: false и возвращает как structuredContent, так и JSON-текстовый запасной вариант.

Намеренно нет универсального инструмента «вызвать любую функцию Moodle». Поиск и описание делают длинный хвост обнаруживаемым; выполнение произвольных функций требует классификации безопасности, которой пока не существует.

Тесты

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

Интеграционный набор — не макет: он запускает собранный сервер как дочерний процесс, общается с ним по MCP с помощью официального SDK-клиента и проверяет утверждения на живом сайте — включая то, что идентичность является ожидаемым пользователем Moodle и что ни один токен не появляется в каком-либо выводе.

Ограничения

• Только чтение через MCP. Нет создания, обновления, удаления, зачисления, оценок, загрузки или скачивания. Единственное, что в репозитории пишет в Moodle, — это CLI для фикстур разработки, который недоступен ни одному MCP-клиенту или веб-сервису (см. docs/SECURITY.md).

• Нет произвольного выполнения функций. Только поиск и описание.

• Только stdio. HTTP-транспорт — будущее дополнение; доменный слой уже не зависит от транспорта.

• Нет Course Blueprint, нет движка diff/apply, нет генерации контента.

• Нет автоматизации браузера, скриншотов или аудита доступности.

• moodle_course_inspect возвращает структуру курса, а не успеваемость: нет оценок и нет состояния завершения для каждого пользователя.

• Главная страница Moodle — это строка курса, но не учебный курс, поэтому moodle_course_inspect отклоняет её. moodle_course_list всё равно сообщает о ней с флагом isSiteCourse.

• Генерация схемы H5P — на один уровень вглубь: вложенное поле library определяет форму обёртки и допустимые версии библиотеки, но его params следуют собственной семантике этой библиотеки — получите их вторым вызовом moodle_h5p_schema.

• Некоторые конструкции H5P и Moodle нельзя выразить в JSON Schema (условия showWhen, белые списки HTML-тегов, шаблоны PCRE, правила очистки PARAM). Они сохраняются как аннотации x-h5p-* / x-moodle-* и сообщаются как примечания по преобразованию, а не отбрасываются.

• Moodle REST не может выразить пустой массив или настоящий null; клиент сообщает об обоих как о явных предупреждениях.

• Плагин монтируется в контейнер из этого репозитория; копия rsync сохраняется только как запасной вариант. Симлинк на хосте не работает по причинам, объяснённым в docs/LOCAL-DEV.md.

Лицензирование

• apps/mcp-server/ — MIT

• moodle/local/aimcp/ — GPL-3.0-or-later (обязательно: это плагин Moodle)

Никакой код реализации GPL не копируется в MIT-сервер. Справочные проекты изучались как архитектурные ссылки и переписывались в чистой комнате; обоснование по каждому проекту — в docs/REFERENCE-ARCHITECTURE.md.

Документация

• docs/ARCHITECTURE.md — дизайн и границы

• docs/REFERENCE-ARCHITECTURE.md — матрица повторного использования и лицензирование

• docs/LOCAL-DEV.md — воспроизводимая локальная настройка

• docs/SECURITY.md — обработка секретов, авторизация, ограничения поверхности