moodle-webservice MCP

Moodle MCP Web服务插件

一个实现以下功能的Moodle web服务插件 模型上下文协议（MCP） 与人工智能助手和外部系统无缝集成。此插件使用JSON-RPC 2.0将Moodle的外部函数作为MCP工具公开，使其可被MCP兼容客户端发现和调用。

特性

• MCP协议实现：使用JSON-RPC 2.0完全支持模型上下文协议
• 动态工具发现：自动将Moodle外部函数作为MCP工具公开
• JSON模式生成：将Moodle参数描述转换为JSON模式，以获得更好的工具文档
• 基于令牌的身份验证：使用Moodle的外部服务令牌进行安全访问
• 服务意识：仅向经过身份验证的服务公开可用的函数
• 经过充分测试：全面的PHPUnit测试覆盖率
• 易于集成：内置客户端类，可快速与其他系统集成

什么是MCP？

这 模型上下文协议（MCP） 是一个开放协议，规范了应用程序如何向人工智能助手和大型语言模型（LLM）提供上下文。它允许AI助手：

• 发现可用的工具及其功能
• 使用适当的参数调用工具
• 接收结构化响应

此插件将Moodle的web服务与MCP协议连接起来，使AI助手能够以标准化的方式与您的Moodle实例进行交互。

需求

• 魔灯：4.2或更高
• PHP：8.0或更高
• Moodle Web服务：必须启用

安装

方法1：通过Moodle插件目录（推荐）

1. 访问 网站管理→ 插件→ 安装插件
2. 搜索“MCP Web服务”
3. 点击 安装 并按照屏幕上的说明进行操作

方法2：手动安装

1. 从存储库下载插件或克隆：

   cd /path/to/moodle/webservice
   git clone https://github.com/onbirdev/moodle-webservice_mcp.git mcp

1. 访问 网站管理→ 通知 完成安装

1. 该插件将按以下方式安装 webservice_mcp

配置

1.启用Web服务

1. 首选 网站管理→ 高级功能
2. 启用 启用web服务
3. 保存更改

2.启用MCP协议

1. 首选 网站管理→ 插件→ Web服务→ 管理协议
2. 启用 模型上下文协议（MCP）

3.创建外部服务

1. 首选 网站管理→ 服务器→ Web服务→ 外部服务
2. 点击 添加 创建新服务
3. 配置服务：

- 名字：例如，“MCP服务” - 短名称：例如，“mcp_sement” - 启用：是的 - 仅限授权用户：是（推荐）

1. 添加服务应公开的外部函数

4.创建令牌

1. 首选 网站管理→ 服务器→ Web服务→ 管理代币
2. 点击 添加 创建新令牌
3. 选择：

- 用户：此令牌将验证为的用户 - 服务：您在上面创建的服务

1. 保存并复制生成的令牌

5.分配能力

确保用户拥有 webservice/mcp:use 访问MCP web服务的能力。

用法

端点URL

MCP服务器端点可以通过两种方式访问。

1.使用查询参数（wstoken）：

https://your-moodle-site.com/webservice/mcp/server.php?wstoken=YOUR_TOKEN

2.使用授权标头（承载令牌）：

https://your-moodle-site.com/webservice/mcp/server.php

将令牌添加到请求标头中：

Authorization: Bearer YOUR_TOKEN

替换：

• your-moodle-site.com 使用您的Moodle域名
• YOUR_TOKEN 使用您生成的令牌

监控

通过以下方式监控MCP web服务的使用情况：

• 标准Moodle日志位于 网站管理→ 报告→ Logs

客户示例

1.初始化会话

请求：

{
   "jsonrpc": "2.0",
   "method": "initialize",
   "params": {},
   "id": 1
}

答复：

{
   "jsonrpc": "2.0",
   "result": {
      "protocolVersion": "1.0",
      "serverInfo": {
         "name": "Moodle MCP Server",
         "version": "0.1.0"
      },
      "capabilities": {
         "tools": {}
      }
   },
   "id": 1
}

2.列出可用工具

请求：

{
   "jsonrpc": "2.0",
   "method": "tools/list",
   "params": {},
   "id": 2
}

答复：

{
   "jsonrpc": "2.0",
   "result": {
      "tools": [
         {
            "name": "core_user_get_users",
            "description": "Search for users matching the criteria",
            "inputSchema": {
               "type": "object",
               "properties": {
                  "criteria": {
                     "type": "array",
                     "items": {
                        "type": "object",
                        "properties": {
                           "key": {
                              "type": "string"
                           },
                           "value": {
                              "type": "string"
                           }
                        }
                     }
                  }
               }
            },
            "outputSchema": {
               "type": "object",
               "properties": {
                  "result": {
                     "type": "object"
                  }
               }
            }
         }
      ]
   },
   "id": 2
}

3.调用工具

请求：

{
   "jsonrpc": "2.0",
   "method": "tools/call",
   "params": {
      "name": "core_user_get_users",
      "arguments": {
         "criteria": [
            {
               "key": "email",
               "value": "student@example.com"
            }
         ]
      }
   },
   "id": 3
}

答复：

{
   "jsonrpc": "2.0",
   "result": {
      "content": [
         {
            "type": "text",
            "text": "{\"result\":{\"users\":[{\"id\":2,\"username\":\"student\",\"firstname\":\"Student\",\"lastname\":\"User\",\"email\":\"student@example.com\"}]}}"
         }
      ],
      "structuredContent": {
         "result": {
            "users": [
               {
                  "id": 2,
                  "username": "student",
                  "firstname": "Student",
                  "lastname": "User",
                  "email": "student@example.com"
               }
            ]
         }
      }
   },
   "id": 3
}

使用cURL

curl -X POST "https://your-moodle-site.com/webservice/mcp/server.php?wstoken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

curl -X POST "https://your-moodle-site.com/webservice/mcp/server.php" \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

API 参考

支持的MCP方法

错误响应

JSON-RPC 2.0格式错误：

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32600,
        "message": "Invalid Request",
        "data": "Missing method"
    },
    "id": null
}

常见错误代码：

• -32700：解析错误（JSON无效）
• -32600：无效请求（缺少必填字段）
• -32601：未找到方法
• -32602：无效参数
• -32603：内部错误

建筑

组件

webservice_mcp/
├── classes/
│   ├── local/
│   │   ├── server.php          # MCP server implementation
│   │   ├── request.php         # Request parser and validator
│   │   └── tool_provider.php   # Tool discovery and schema generation
│   └── privacy/
│       └── provider.php        # Privacy API implementation
├── db/
│   └── access.php              # Capability definitions
├── lang/
│   └── en/
│       └── webservice_mcp.php  # Language strings
├── tests/
│   ├── server_test.php         # Server tests
│   ├── client_test.php         # Client tests
│   ├── request_test.php        # Request parser tests
│   └── tool_provider_test.php  # Tool provider tests
├── lib.php                     # Client class
├── locallib.php                # Local library functions
├── server.php                  # Server endpoint
└── version.php                 # Plugin metadata

数据流

1. 客户端请求 → JSON-RPC 2.0 POST到 server.php
2. 认证 → 通过Moodle的网络服务API进行代币验证
3. 请求解析 → request 类验证JSON-RPC格式
4. 方法路由 → server 类路由到适当的处理程序
5. 工具发现 → tool_provider 查询可用的外部函数
6. 模式生成 → 将Moodle描述转换为JSON模式
7. 工具执行 → 调用Moodle的外部函数API
8. 响应 → JSON-RPC 2.0格式的响应

关键类

• server：主服务器实现扩展 webservice_base_server
• request：分析和验证JSON-RPC 2.0请求
• tool_provider：发现可用工具并生成JSON模式
• webservice_mcp_client：客户提出MCP请求

测试

运行测试

# Run all plugin tests
vendor/bin/phpunit --testsuite webservice_mcp_testsuite

测试覆盖率

该插件包括对以下内容的全面测试：

• ✅ JSON-RPC 2.0请求解析和验证
• ✅ MCP协议方法（初始化、工具/列表、工具/调用）
• ✅ 工具发现和模式生成
• ✅ 客户端类功能
• ✅ 错误处理和边缘情况

故障排除

常见问题

1.“未启用Web服务”

解决方案：在中启用web服务 网站管理→ 高级功能

2.“无效令牌”

解决方案:

• 验证令牌是否正确
• 检查令牌是否未过期
• 确保服务已启用
• 确认用户具有适当的能力

3.“未找到方法”

解决方案：检查方法名称是否正确：

• initialize
• tools/list
• tools/call

4.“缺少工具名称”

解决方案：使用时 tools/call，确保您提供 name 参数：

{
    "method": "tools/call",
    "params": {
        "name": "core_user_get_users",
        "arguments": {}
    }
}

5.空工具清单

解决方案:

• 检查您的服务是否添加了功能
• 验证令牌是否与正确的服务相关联
• 确保功能不被弃用

日志记录

MCP请求记录在Moodle的标准web服务日志中：

• 网站管理→ 报告→ Logs
• 按“Web服务”组件筛选

💖 支持此插件的开发

保持更新，对所有人免费！

☕ 给我买杯咖啡（Ko-fi） | 💸 通过PayPal提供支持