moodle-mcp

Сервер протокола контекста модели (MCP) для Moodle. Позволяет ИИ-агентам публиковать педагогический контент — уроки, ресурсы, задания — в Moodle и управлять им через веб-сервисы с гарантированной идемпотентностью.

Статус: v0.1 MVP.

Что это такое

moodle-mcp — это MCP-сервер на базе stdio, который предоставляет небольшой набор высокоуровневых фасадов и один низкоуровневый примитив ws_raw для публикации канонической педагогической «Ficha» (markdown-файл с YAML-заголовком) в курсе Moodle в виде реальных разделов, страниц, ресурсов и заданий. Каждая запись выполняется методом upsert по idnumber, поэтому повторная публикация одной и той же Ficha никогда не создает дубликатов.

Основной потребитель: Claude Desktop, управляющий рабочим процессом обучения языку Italicia. Однако это универсальный адаптер с открытым исходным кодом — его может использовать любой агент с поддержкой MCP и любой экземпляр Moodle 4.x/5.x с включенными веб-сервисами.

Инструменты, доступные в v0.1

Не включено в v0.1 (запланировано на v0.2+): publicar_ficha_examen, sync_alumnos_csv, транспорт HTTP/SSE, конструктор GIFT, загрузка составных ресурсов, автоматическое создание модулей.

Установка

# Via npx (recommended for Claude Desktop)
npx -y @marcosnahuel/moodle-mcp

# Or install globally
npm install -g @marcosnahuel/moodle-mcp

Требуется Node.js 20 или выше.

Конфигурация (переменные окружения)

Конфигурация Claude Desktop

Добавьте в claude_desktop_config.json (см. examples/setup-claude-desktop.md для точного пути в зависимости от ОС):

{
  "mcpServers": {
    "moodle": {
      "command": "npx",
      "args": ["-y", "moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle.example.com",
        "MOODLE_WS_TOKEN": "your-ws-token"
      }
    }
  }
}

Перезапустите Claude Desktop. Пять инструментов, указанных выше, теперь должны быть доступны агенту.

Примеры

1. Снимок курса перед выполнением действий

// tool call
{
  "name": "obtener_contexto_curso",
  "arguments": { "course_id": 42, "incluir_ultimas_clases": 5 }
}

Ответ (сокращенно):

{
  "course": { "id": 42, "fullname": "Italiano A1", "shortname": "ITA-A1", "format": "topics", "startdate": 1700000000 },
  "secciones": [{ "id": 100, "name": "Unidad 3", "section": 3, "visible": true, "modules_count": 6 }],
  "ultimas_clases": [{ "seccion_id": 100, "seccion_name": "Unidad 3", "ficha_idnumber": "mcp:a9993e364706816aba3e2571" }],
  "matriculados": { "total": 18, "docentes": 1, "alumnos": 17 }
}

2. Публикация FichaClase (сначала предварительный просмотр)

{
  "name": "publicar_preview",
  "arguments": {
    "ficha_path": "/home/alicia/fichas/italiano/a1-2026/u3/c5.md",
    "course_id": 42
  }
}

Ответ включает preview_url, который Alicia может открыть для проверки. После одобрения:

{
  "name": "confirmar_preview",
  "arguments": { "seccion_id": 100, "recursos_ids": [501, 502, 503] }
}

3. «Аварийный выход» — вызов функции WS напрямую

{
  "name": "ws_raw",
  "arguments": {
    "function_name": "core_webservice_get_site_info",
    "params": {}
  }
}

Ответ:

{ "data": { "sitename": "Aula Italicia", "release": "5.0.2+", ... } }

Идемпотентность

Каждый ресурс, созданный этим MCP, имеет стабильный idnumber вида:

mcp:<first 24 chars of sha1(ficha.id + "|" + component_id)>

Повторная публикация той же Ficha находит существующий ресурс по idnumber и обновляет его на месте. Ничего не дублируется. Безопасно для повтора в любое время и в любом месте.

Особенности v0.1

v0.1 честно заявляет о границах своих возможностей. Он надежно:

• Ищет курс, его разделы и модули.

• Находит «собственные» ресурсы по префиксу mcp: в idnumber.

• Обновляет видимость уже существующих модулей (рабочий процесс предварительный просмотр → подтверждение).

• Выводит структурированные ошибки Moodle со стабильными полями code.

• Никогда не записывает токены в лог, никогда не передает трассировки стека.

v0.1 пока не умеет:

• Загружать файлы ресурсов через multipart в область черновиков Moodle. Вызовы, запланированные для загрузки ресурсов, сообщаются в advertencias — добавьте их вручную в первый раз.

• Создавать совершенно новые разделы или модули через веб-сервисы. Там, где модуль еще не существует, инструмент возвращает статус "missing" плюс advertencia. Установка local_wsmanagesections (или аналога) и подключение этих конечных точек — задача для v0.2.

Оба пробела выявляются набором интеграционных тестов в tests/integration/ при запуске на реальном Docker-контейнере Moodle.

Разработка

git clone https://github.com/marcosnahuel/moodle-mcp
cd moodle-mcp
npm install

npm run typecheck         # tsc --noEmit
npm test                  # vitest unit suite
npm run test:coverage     # with v8 coverage (≥80% enforced)
npm run build             # tsup → dist/

# Integration — requires docker
docker compose -f tests/integration/docker-compose.test.yml up -d
export MOODLE_TEST_URL=http://localhost:8081
export MOODLE_TEST_TOKEN=<generate in Moodle admin>
export MOODLE_TEST_COURSE=<course id>
npm run test:integration
docker compose -f tests/integration/docker-compose.test.yml down -v

Безопасность

• Токен никогда не записывается в лог. Токены, появляющиеся в любом поле любой записи лога, заменяются на ***.

• URL-адреса в сообщениях об ошибках также маскируются.

• HTTPS обязателен, если не установлен MOODLE_ALLOW_INSECURE=true (только для разработки).

• MCP взаимодействует с Moodle только через REST веб-сервисов. Никакой cookie-авторизации, никакого веб-скрейпинга, никакого прямого доступа к БД.

Участие в проекте

См. CONTRIBUTING.md для ознакомления с правилами оформления проблем, PR и коммитов.

Участвуя в этом проекте, вы соглашаетесь соблюдать CODE_OF_CONDUCT.md.

Лицензия

MIT © 2026 Italicia — см. LICENSE.