moodle-ai-mcp

Un plano de control MCP nativo de IA para Moodle.

Un cliente MCP (Claude Code, ChatGPT, Cursor, o cualquier otra cosa que hable el Model Context Protocol) se conecta a este servidor y obtiene respuestas estructuradas y precisas sobre un sitio Moodle real: qué es, quién es la identidad autenticada de la conexión, qué se le permite hacer, qué funciones externas de Moodle puede alcanzar, y — la parte que lo hace más que un envoltorio REST — exactamente qué bibliotecas H5P tiene instaladas el sitio y cuáles son sus esquemas de contenido.

Esto no es un envoltorio fino alrededor de Moodle REST. El objetivo a largo plazo es un plano de control que un cliente de IA pueda usar para diseñar y construir cursos completos de forma segura. Este repositorio contiene actualmente la primera base de eso.

Madurez actual: hito fundacional, solo lectura

Funcionando hoy:

• Servidor MCP en stdio con siete herramientas seleccionadas, construido sobre el SDK oficial de MCP TypeScript

• Un plugin local de Moodle 5.2 (local_aimcp) con siete funciones externas de solo lectura, aplicación real de capacidades y cobertura PHPUnit

• Un modelo de lectura de curso consciente de capacidades: secciones, actividades, configuración de finalización y calificaciones, que refleja lo que la identidad autenticada puede ver realmente en lugar de todo lo que tiene un indicador hidden adjunto

• Descubrimiento dinámico de las funciones externas que el servicio autenticado puede alcanzar, con introspección de firmas sin pérdida

• Descubrimiento dinámico de las bibliotecas H5P instaladas y sus semánticas reales instaladas, convertidas a JSON Schema con notas explícitas para todo lo que JSON Schema no puede expresar

No construido, a propósito: cualquier operación de escritura, creación de cursos/actividades/H5P, el motor de Course Blueprint, automatización de navegador, transferencia de archivos e infraestructura de alojamiento. Ver "Limitaciones" más abajo.

Related MCP server: Drupal Bridge MCP

Arquitectura

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

El servidor posee el protocolo, la superficie de herramientas, la orquestación y la conversión de esquemas. El plugin posee todo lo que solo Moodle puede responder: identidad, contexto, capacidades, el registro de funciones externas y el motor H5P. La lógica de Moodle nunca se reimplementa en TypeScript, y la orquestación nunca se filtra a PHP.

Los detalles, incluido por qué la superficie de herramientas son seis herramientas en lugar de varios cientos, están en docs/ARCHITECTURE.md.

Requisitos previos

• Node.js 24

• Docker, con una pila de Moodle 5.2 de moodle-docker

• Un token de servicio web de Moodle para un usuario autorizado en un servicio externo habilitado

Desarrollo local

Instrucciones completas: docs/LOCAL-DEV.md. La versión corta:

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

La base de datos, moodledata y las bibliotecas H5P instaladas viven en volúmenes Docker con nombre, por lo que ./scripts/stack.sh recreate es seguro. Solo ./scripts/stack.sh reset destruye datos, y pregunta primero. Haz una copia de seguridad en cualquier momento con ./scripts/backup.sh.

Las credenciales provienen de .env.local, que es un enlace simbólico a un archivo fuera de este repositorio. .env* está en gitignore; ver docs/SECURITY.md.

Conexión de un cliente MCP

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

O con el Inspector:

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

Herramientas

Cada herramienta está anotada con readOnlyHint: true, destructiveHint: false, y devuelve tanto structuredContent como un respaldo de texto JSON.

Deliberadamente no hay una herramienta genérica de "llamar a cualquier función de Moodle". Buscar y describir hacen que la larga cola sea descubrible; la ejecución de funciones arbitrarias necesita una clasificación de seguridad que aún no existe.

Pruebas

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

La suite de integración no es un simulacro: lanza el servidor compilado como un proceso hijo, le habla MCP con el cliente oficial del SDK, y verifica contra el sitio en vivo — incluyendo que la identidad es el usuario Moodle esperado y que no aparece ningún token en ninguna salida.

Limitaciones

• Solo lectura sobre MCP. Sin crear, actualizar, eliminar, inscribir, calificar, subir o descargar. Lo único en el repositorio que escribe en Moodle es la CLI de datos de desarrollo, que no es accesible desde ningún cliente MCP o servicio web (ver docs/SECURITY.md).

• Sin ejecución arbitraria de funciones. Solo buscar y describir.

• Solo stdio. El transporte HTTP es una adición futura; la capa de dominio ya está libre de transporte.

• Sin Course Blueprint, sin motor de diff/aplicación, sin generación de contenido.

• Sin automatización de navegador, capturas de pantalla o auditoría de accesibilidad.

• moodle_course_inspect devuelve la estructura del curso, no el rendimiento del alumno: sin calificaciones y sin estado de finalización por usuario.

• La portada de Moodle es una fila de curso pero no un curso de enseñanza, por lo que moodle_course_inspect la rechaza. moodle_course_list aún la informa, marcada como isSiteCourse.

• La generación de esquemas H5P es de un nivel de profundidad: un campo library anidado fija la forma del envoltorio y las versiones de biblioteca permitidas, pero sus params siguen la semántica propia de esa biblioteca — recupéralos con una segunda llamada a moodle_h5p_schema.

• Algunas construcciones de H5P y Moodle no se pueden expresar en JSON Schema (condiciones showWhen, listas blancas de etiquetas HTML, patrones PCRE, reglas de limpieza PARAM). Se conservan como anotaciones x-h5p-* / x-moodle-* y se informan como notas de conversión en lugar de descartarse.

• Moodle REST no puede expresar un array vacío o un null verdadero; el cliente informa ambos como advertencias explícitas.

• El plugin se monta en el contenedor desde este repositorio; la copia rsync se mantiene solo como respaldo. Un enlace simbólico del host no funciona, por razones explicadas en docs/LOCAL-DEV.md.

Licencia

• apps/mcp-server/ — MIT

• moodle/local/aimcp/ — GPL-3.0-or-later (requerido: es un plugin de Moodle)

No se copia código de implementación GPL en el servidor MIT. Los proyectos de referencia se estudiaron como referencias de arquitectura y se reimplementaron en sala limpia; el razonamiento, por proyecto, está en docs/REFERENCE-ARCHITECTURE.md.

Documentación

• docs/ARCHITECTURE.md — diseño y límites

• docs/REFERENCE-ARCHITECTURE.md — matriz de reutilización y licencia

• docs/LOCAL-DEV.md — configuración local reproducible

• docs/SECURITY.md — manejo de secretos, autorización, restricciones de superficie