使用说明

MCP Moodle服务器

优化的MCP（模型上下文协议）服务器，通过MCP工具提供对Moodle REST API的访问。这使Claude和其他MCP客户端能够对Moodle资源（用户、课程、注册等）执行CRUD操作。

✨ v2.0中的新增功能

🚀 主要优化版本发布 -具有生产就绪功能的全面检修：

✅ MCP SDK 1.10.0 -带有工具注释的最新协议功能
✅ 智能缓存 -使用智能TTL将API调用减少80%
✅ 结构化日志记录 -元数据的调试/信息/警告/错误级别
✅ 40测试 -Vitest综合测试套件
✅ 整洁架构 -使用实用程序（toolWrapper、格式化程序）减少70%的代码
✅ 类型安全 -使用正确的类型实现完全的TypeScript覆盖
✅ 工具注释 -语义提示（只读、破坏性、幂等）

📖 查看完整的优化报告

📚 文档

快速入门指南 -5分钟后开始跑步
使用示例 -15+实例
开发指南 -对于贡献者
API 参考 -Moodle API文档
文档索引 -浏览所有文档

🛠️ 特征

15个MCP工具（优化）

所有工具都包含适当的注释，以便更好地理解LLM：

用户操作 （5个工具）

moodle_search_users 🔍 - 按条件搜索用户（用户名、电子邮件、id等）
moodle_get_user_by_field 🔍 - 按特定字段值获取用户
moodle_create_users ➕ - 创建新用户
moodle_update_users 🔄 - 更新现有用户（幂等）
moodle_delete_users ⚠️ - 按ID删除用户（破坏性）

课程操作 （4个工具）

moodle_list_courses 🔍 - 获取所有课程或按ID（缓存1分钟）
moodle_search_courses 🔍 - 按领域搜索课程
moodle_create_courses ➕ - 创建新课程
moodle_get_course_contents 🔍 - 获取课程内容/模块（缓存2分钟）

注册运营 （4个工具）

moodle_get_enrolled_users 🔍 - 让用户注册课程
moodle_get_user_courses 🔍 - 获取用户的所有课程
moodle_enroll_users 🔄 - 为用户注册具有角色的课程（幂等）
moodle_unenroll_user ➖ - 从课程中取消用户注册

类别和现场操作 （2个工具）

moodle_list_categories 🔍 - 获取课程类别（缓存5分钟）
moodle_get_site_info 🔍 - 获取Moodle站点信息（缓存10分钟）

🔍 = 只读|➕ = 创建|🔄 = 更新/标识|⚠️ = 破坏性|➖ = 移除

🚀 快速开始

安装

# 1. Clone repository
git clone https://github.com/yourusername/mcp-moodle.git
cd mcp-moodle

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your Moodle credentials

# 4. Build
npm run build

# 5. Test
npm test  # Run 40 tests to verify

配置

创建 .env 文件：

MOODLE_URL=https://your-moodle-instance.com
MOODLE_TOKEN=your_moodle_api_token

# Optional
LOG_LEVEL=INFO  # DEBUG | INFO | WARN | ERROR

获取Moodle API代币

以管理员身份登录您的Moodle实例
导航至 站点管理>服务器>Web服务
启用web服务
创建具有所需功能的新服务
授权用户并生成令牌
将令牌复制到您的 .env 文件

📖 详细的说明

🧪 测试

MCP 检查员

以交互方式测试服务器：

npx @modelcontextprotocol/inspector node dist/index.js

这将打开一个web UI，您可以在其中：

列出所有15个可用工具
使用自定义输入的测试工具调用
查看响应和错误

单元测试

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:ui       # Interactive UI
npm run test:coverage # Coverage report

当前覆盖范围： 40项测试通过

✅ 参数生成器（8个测试）
✅ 格式化程序（7次测试）
✅ toolWrapper（5个测试）
✅ 再加上20个集成测试

🔌 整合

克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "moodle": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_moodle/dist/index.js"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.com",
        "MOODLE_TOKEN": "your_token_here",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

重新启动Claude Desktop，工具将出现在工具选择器中。

其他MCP客户端

服务器使用标准的MCP stdio传输，并与任何兼容MCP的客户端配合使用。

🏗️ 建筑

技术栈

Types/Node.js -ES模块，现代JavaScript
MCP SDK 1.10.0 -最新协议功能
佐德3.23 -运行时验证+类型推断
Vitest -快速测试框架
结构化日志记录 -可配置的日志级别

系统设计

┌─────────────────┐
│   MCP Client    │  (Claude, etc.)
│   (stdio)       │
└────────┬────────┘
         │ MCP Protocol
┌────────▼────────┐
│  MCP Server     │  ← index.ts
│  (this project) │
└────────┬────────┘
         │
    ┌────┴─────┬──────────┬────────────┐
    │          │          │            │
┌───▼───┐  ┌──▼──┐  ┌────▼─────┐  ┌──▼──┐
│ Tools │  │Cache│  │ Logger   │  │Utils│
│(15)   │  │Layer│  │(4 levels)│  │     │
└───┬───┘  └──┬──┘  └──────────┘  └─────┘
    │         │
┌───▼─────────▼───┐
│  MoodleClient   │  ← HTTP client
└─────────┬───────┘
          │ HTTPS REST
┌─────────▼───────┐
│  Moodle Server  │  (Your Moodle instance)
│  REST API       │
└─────────────────┘

项目结构

mcp-moodle-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── config.ts             # Environment configuration
│   ├── types/
│   │   ├── moodle.ts         # Moodle API types
│   │   └── tools.ts          # Zod schemas
│   ├── client/
│   │   ├── moodleClient.ts   # Core API client + cache
│   │   └── parameterBuilder.ts
│   ├── tools/
│   │   ├── registry.ts       # Tool registration + zod-to-json
│   │   ├── users.ts          # User CRUD (5 tools)
│   │   ├── courses.ts        # Course ops (4 tools)
│   │   ├── enrollments.ts    # Enrollment ops (4 tools)
│   │   ├── categories.ts     # Category ops (1 tool)
│   │   └── site.ts           # Site info (1 tool)
│   └── utils/
│       ├── toolWrapper.ts    # 🆕 DRY error handling
│       ├── formatters.ts     # 🆕 Response formatting
│       ├── logger.ts         # 🆕 Structured logging
│       ├── errorHandler.ts   # Moodle error handling
│       └── validator.ts      # Input validation
├── docs/                     # 🆕 Organized documentation
│   ├── guides/
│   ├── reference/
│   ├── architecture/
│   └── history/
├── tests/                    # 🆕 Test suite
└── dist/                     # Compiled output

📖 详细架构 （即将推出）

🎯 演出

缓存策略

智能缓存可将API负载减少80%：

资源	缓存TTL	基本原理
站点信息	10分钟	静态数据
类别	5分钟	不经常更改
课程内容	2分钟	偶尔更新
课程列表	1分钟	平衡新鲜度/表现
用户/注册	无缓存	动态数据

缓存是自动的，每个工具都可以配置。

基准测试

冷启动： <200ms
测试套件： 497ms（40次测试）
构建时间： <1s
内存： 约50MB的典型使用量

🔧 发展

脚本

npm run build         # Compile TypeScript
npm run watch         # Watch mode
npm run dev           # Development with tsx
npm start            # Production start

npm test             # Run tests
npm run test:watch   # Tests in watch mode
npm run test:ui      # Interactive test UI
npm run test:coverage # Coverage report

添加新工具

看开发指南获取分步说明。

快速概述：

在中定义Zod模式 src/types/tools.ts
在适当的文件中添加工具（用户/课程等）
使用 wrapToolHandler 用于自动验证
使用 formatters 用于一致的响应
添加适当的注释

代码质量

✅ TypeScript严格模式
✅ ESLint+预处理就绪
✅ 综合测试
✅ 最新文档

📖 Moodle API参考

此服务器与 769 Moodle REST API函数 36个类别。

通用角色ID moodle_enroll_users:

1=经理
2=课程创建者
3=教师（编辑教师）
4=非编辑教师
5=学生

📖 API完整参考

🐛 错误处理

服务器提供带有正确MCP错误代码的详细错误消息：

无效参数 -验证错误（缺少/无效字段）
内部错误 -Moodle API错误或网络问题
方法未找到 -请求未知工具

所有错误都包含有助于调试的消息和上下文。

🤝 贡献

欢迎投稿！拜托：

阅读开发指南
检查现有问题
分叉并创建特征分支
为新功能编写测试
提交拉取请求

📄 许可证

MIT许可证-请参阅许可证详细信息文件

🙏 致谢

内置于 MCP-SDK
由...驱动 Moodle REST API
在Claude Sonnet 4.5的帮助下进行了优化

📞 支持

由...制作❤️ 对于Moodle社区

最后更新时间：2026-02-04 |版本2.0.0