moodle-ai-mcp

一个面向 Moodle 的 AI 原生 MCP 控制平面。

MCP 客户端（Claude Code、ChatGPT、Cursor 或任何其他支持模型上下文协议的工具）连接到该服务器，并获得关于真实 Moodle 站点的结构化、准确答案：它是什么、连接以谁的身份认证、它被允许做什么、它可以访问 Moodle 的哪些外部函数，以及——使其不仅仅是 REST 封装的部分——站点安装了哪些 H5P 库以及它们的内容模式是什么。

这不是对 Moodle REST 的简单封装。长期目标是一个 AI 客户端可以用来安全设计和构建整个课程的控制平面。本仓库目前包含该目标的第一块基石。

当前成熟度：基础里程碑，只读

当前可用：

• 基于官方 MCP TypeScript SDK 构建的 stdio MCP 服务器，提供七个精选工具

• 一个 Moodle 5.2 本地插件（local_aimcp），包含七个只读外部函数、真实的能力强制和 PHPUnit 测试覆盖

• 一个能力感知的课程读取模型：章节、活动、完成和成绩配置，反映认证身份实际可以看到的内容，而不是所有带有 hidden 标志的内容

• 动态发现认证服务可以访问的外部函数，并具有无损签名内省

• 动态发现已安装的 H5P 库及其真实安装语义，转换为 JSON Schema，并对 JSON Schema 无法表达的所有内容提供明确说明

有意未构建：任何写操作、课程/活动/H5P 创建、课程蓝图引擎、浏览器自动化、文件传输和托管基础设施。请参阅下面的“限制”。

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-docker 的 Moodle 5.2 栈

• 一个 Moodle Web 服务令牌，用于在已启用的外部服务上获得授权的用户

本地开发

完整说明：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* 被 gitignore；请参阅 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

集成套件不是模拟：它将构建的服务器作为子进程启动，使用官方 SDK 客户端与其进行 MCP 通信，并针对实时站点进行断言——包括身份是预期的 Moodle 用户，并且任何输出中都不出现令牌。

限制

• 通过 MCP 只读。 没有创建、更新、删除、注册、评分、上传或下载。仓库中唯一写入 Moodle 的是开发夹具 CLI，它无法从任何 MCP 客户端或 Web 服务访问（请参阅 docs/SECURITY.md）。

• 没有任意函数执行。 仅搜索和描述。

• 仅 stdio。 HTTP 传输是未来的补充；领域层已经与传输无关。

• 没有课程蓝图，没有差异/应用引擎，没有内容生成。

• 没有浏览器自动化、截图或可访问性审计。

• 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 — 秘密处理、授权、表面约束