使用说明

🎓 Moodle MCP服务器

Moodle LMS的模型上下文协议集成

特性 • 安装 • 用法 • 文档 • 贡献

📖 概述

一个强大的模型上下文协议（MCP）服务器，将AI助手与Moodle学习管理系统无缝集成。使您的AI助手能够访问课程、检索教育内容、下载资源和搜索您的学习材料。

🔌 兼容：Claude Desktop和任何兼容MCP的AI助手

✨ 特性

🔐 安全认证 -使用Moodle Web Services的基于令牌的身份验证
📚 课程管理 -列出并访问所有已注册的课程
📄 内容检索 -从课程中获取章节、模块和资源
💾 文档访问 -下载具有适当身份验证的文件和文档
🔍 智能搜索 -按名称查找所有已注册课程中的资源
🛡️ 错误处理 -通过自动令牌刷新进行全面的错误处理
🚀 TypeScript -完全打字，提供更好的开发人员体验

🎯 用例

学习顾问：让人工智能帮助您浏览课程材料
内容组织：搜索和组织学习资源
课程概述：获取课程结构的快速摘要
资源发现：查找跨多个课程的特定文档
学习分析：分析课程内容和结构

📋 先决条件

Node.js 18岁或以上
Moodle实例 启用Web服务
有效凭据 使用API访问您的Moodle实例

🚀 安装

快速开始

# Clone the repository
git clone <repository-url>
cd moodle-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

创建环境文件

cp .env.example .env

配置您的凭据

MOODLE_URL=https://your-moodle-instance.com
MOODLE_USERNAME=your_username
MOODLE_PASSWORD=your_password
MOODLE_SERVICE=moodle_mobile_app  # Optional

Moodle Web服务设置

您的Moodle实例必须启用Web服务。如果您是Moodle管理员：

导航至 站点管理→ 服务器→ Web服务→ 概述
按照安装向导启用web服务
创建或使用内置 moodle_mobile_app 服务
确保这些功能已启用：
- core_webservice_get_site_info
- core_enrol_get_users_courses
- core_course_get_courses
- core_course_get_contents

🎮 用法

运行服务器

# Production
node dist/index.js

# Development with auto-reload
npm run dev

与Claude Desktop集成

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "moodle": {
      "command": "node",
      "args": ["/absolute/path/to/moodle-mcp/dist/index.js"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.com",
        "MOODLE_USERNAME": "your_username",
        "MOODLE_PASSWORD": "your_password"
      }
    }
  }
}

可用工具

工具	说明
`list_courses`	列出所有已注册的课程及其详细信息
`get_course_contents`	检索包含章节和模块的完整课程结构
`get_course_documents`	通过直接URL从课程中获取所有可下载文件
`search_resources`	按名称搜索所有课程中的资源

📚 详细文件：参见用法.md 用于全面的工具文档

🧪 测试

快速测试

# Run the complete test suite
npm test

测试选项

方法	说明
自动化测试	`npm test` -完整的测试套件
MCP检查员	基于网络的交互式工具测试
独立脚本	无MCP的API直接测试
手动cURL	直接测试Moodle API端点

📘 完整的测试指南：参见测试.md

🏗️ 发展

项目结构

moodle-mcp/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── moodle-client.ts  # Moodle API client
│   ├── types.ts          # TypeScript type definitions
│   └── test.ts           # Standalone test script
├── dist/                 # Compiled JavaScript
├── .env.example          # Environment template
├── README.md             # This file
├── USAGE.md              # Tool usage guide
└── TESTING.md            # Testing guide

命令

# Build the project
npm run build

# Watch mode (auto-rebuild)
npm run watch

# Run tests
npm test

# Development mode
npm run dev

🔧 API体系结构

认证流程

1. Token Generation → POST /login/token.php
2. API Calls        → GET/POST /webservice/rest/server.php?wstoken={token}
3. File Downloads   → GET /pluginfile.php/...?token={token}

Moodle Web服务

core_webservice_get_site_info -用户和站点信息
core_enrol_get_users_courses -已注册课程列表
core_course_get_courses -所有可用课程
core_course_get_contents -课程结构和资源

📚 文档

用法.md -所有可用工具的全面指南
测试.md -测试说明和方法
MCP文件 -了解有关MCP的更多信息

🐛 故障排除

Authentication Errors

✅ 验证凭据是否正确 .env
✅ 确保在Moodle中启用Web服务
✅ 检查服务名称是否与Moodle配置匹配
✅ 验证用户是否具有适当的API访问权限

Permission Errors

✅ 验证用户在Moodle中具有适当的角色权限
✅ 某些资源可能会根据注册情况受到限制
✅ 检查课程可见性设置

Connection Errors

✅ 验证Moodle URL是否正确且可访问
✅ 检查网络连接和防火墙设置
✅ 确保Moodle实例接受API请求
✅ 尝试直接在浏览器中访问Moodle URL

🔒 安全

🔐 使用环境变量安全地存储凭据
🌐 在生产环境中使用HTTPS进行Moodle连接
🔄 定期轮换密码和令牌
📋 遵循组织的安全策略
⚠️ 永不承诺 .env 文件到版本控制

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

🍴 分叉存储库
🔨 创建要素分支(git checkout -b feature/amazing-feature)
💾 提交您的更改(git commit -m 'Add amazing feature')
📤 推到分支(git push origin feature/amazing-feature)
🎉 打开拉取请求

请确保您的PR：

✅ 包括对新功能的测试
✅ 根据需要更新文档
✅ 遵循现有代码样式
✅ 通过所有测试

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

内置模型上下文协议SDK
由...驱动 Moodle LMS
TypeScript和Node.js生态系统

📞 支持

📖 文档
🐛 问题追踪器
💬 讨论

由以下材料制成❤️ 对于Moodle和AI社区

⭐ 如果你觉得这个repo有用，请将其标记为星号！