Moqui MCP

🚀 Moqui MCP 组件

Moqui MCP 组件是用于 AI 与 Moqui 集成的模型上下文协议（MCP）服务器组件，它通过标准化的协议接口，为 AI 系统与 Moqui 企业框架之间提供无缝连接，使两者能够安全地交互。

🚀 快速开始

Moqui MCP 组件实现了模型上下文协议（MCP）服务器，使 AI 系统能够通过标准化的协议接口与 Moqui 实体、服务和业务逻辑进行安全交互。

✨ 主要特性

核心 MCP 功能

• MCP 协议服务器：全面实现了模型上下文协议规范。
• 实体访问工具：对 Moqui 实体进行安全的 CRUD 操作，并进行权限验证。
• 服务执行工具：调用 Moqui 服务时进行参数验证和安全检查。
• 搜索与发现：具备跨实体和服务的高级搜索功能。
• 会话管理：通过身份验证和授权进行安全的会话处理。

安全与管理

• 多层安全机制：提供实体级、服务级和 API 级的安全控制。
• 审计日志：对所有 MCP 操作进行全面的审计跟踪。
• 速率限制：可配置速率限制，防止滥用。
• 会话管理：可配置会话超时和清理。
• 用户组：预配置了 MCP_ADMIN 和 MCP_USER 角色。

集成特性

• Web 仪表盘：提供用于监控和配置的管理界面。
• REST API：提供用于 MCP 服务器管理的 RESTful 端点。
• 配置管理：基于属性的灵活配置。
• 数据库集成：与 Moqui 的事务数据库完全集成。

📦 安装指南

前提条件

• Moqui 框架 3.0 及以上版本。
• Java 17 及以上版本。
• 数据库（MySQL、PostgreSQL 或 Moqui 支持的其他数据库）。

安装步骤

1. 组件部署

   # 将组件复制到 Moqui 运行时目录
   cp -r moqui-mcp /path/to/moqui/runtime/component/
   

2. 数据库初始化
   • 组件实体在启动时会自动创建。
   • 种子数据包含默认配置和用户组。
3. 配置
   • 编辑 MoquiConf.xml 以进行屏幕集成。
   • 根据需要在 component.xml 中配置属性。
4. 重启 Moqui

   ./gradlew run
   

📚 详细文档

服务器配置

<property-list name="mcp.server">
    <property name="enabled" value="true"/>
    <property name="port" value="8081"/>
    <property name="session.timeout.minutes" value="60"/>
    <property name="rate.limit.requests.per.minute" value="100"/>
    <property name="audit.enabled" value="true"/>
    <property name="max.session.duration.minutes" value="480"/>
</property-list>

LLM 提供商配置

<property-list name="mcp.llm">
    <property name="provider.url" value="${mcp_llm_provider_url}"/>
    <property name="provider.api_key" value="${mcp_llm_provider_api_key}"/>
    <property name="provider.model" value="${mcp_llm_provider_model:gpt-4}"/>
    <property name="timeout.seconds" value="30"/>
    <property name="max.tokens" value="4096"/>
    <property name="temperature" value="0.7"/>
</property-list>

安全配置

<property-list name="mcp.security">
    <property name="require.https" value="false"/>
    <property name="allowed.origins" value="*"/>
    <property name="max.request.size.mb" value="10"/>
    <property name="enable.cors" value="true"/>
</property-list>

💻 使用示例

基础用法

访问 MCP 仪表盘

1. 以管理员身份登录 Moqui。
2. 导航到“应用程序”→“MCP 服务器”。
3. 在 /apps/mcp/ 访问仪表盘。

可用的 MCP 工具

实体工具

• entity_find：使用过滤器和分页查询实体。
• entity_find_one：检索单个实体记录。
• entity_create：创建新的实体记录。
• entity_update：修改现有实体记录。
• entity_delete：删除实体记录。

服务工具

• service_call：使用参数调用 Moqui 服务。
• service_list：发现可用的服务。
• service_help：获取服务文档。

搜索工具

• search_entities：跨实体进行全文搜索。
• search_services：搜索服务定义。
• search_help：高级搜索功能。

示例 MCP 会话

{
  "session_id": "mcp_session_12345",
  "user_id": "admin",
  "created_time": "2024-01-15T10:30:00Z",
  "tools_available": [
    "entity_find",
    "entity_create", 
    "service_call",
    "search_entities"
  ],
  "permissions": ["MCP_ADMIN"]
}

🔧 技术细节

安全模型

权限级别

MCP_ADMIN

• 完全访问所有 MCP 工具和实体。
• 具备用户和会话管理能力。
• 进行系统配置和监控。
• 访问审计日志。

MCP_USER

• 根据 Moqui 权限进行有限的实体访问。
• 受限的服务执行。
• 基本的搜索功能。
• 仅管理自己的会话。

实体安全

• 遵循 Moqui 内置的实体权限。
• 额外的 MCP 特定访问控制。
• 对敏感数据进行字段级安全保护。

服务安全

• 服务级权限验证。
• 参数清理和验证。
• 执行超时控制。

API 参考

REST 端点

会话管理

• POST /mcp/api/sessions - 创建新会话。
• GET /mcp/api/sessions/{id} - 获取会话详情。
• DELETE /mcp/api/sessions/{id} - 终止会话。

工具执行

• POST /mcp/api/tools/{tool_name} - 执行 MCP 工具。
• GET /mcp/api/tools - 列出可用工具。

管理

• GET /mcp/api/status - 获取服务器状态和统计信息。
• GET /mcp/api/audit - 访问审计日志。
• GET /mcp/api/config - 获取配置详情。

MCP 协议消息

初始化请求

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "clientInfo": {
      "name": "ai-client",
      "version": "1.0.0"
    }
  }
}

工具调用请求

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "entity_find",
    "arguments": {
      "entity": "Product",
      "filter": {"productId": "PROD-001"},
      "limit": 10
    }
  }
}

监控与故障排除

仪表盘指标

• 活动会话计数。
• 请求速率和响应时间。
• 错误率和类型。
• 资源利用率。

审计日志

所有 MCP 操作都会记录以下信息：

• 时间戳和会话 ID。
• 用户标识。
• 调用的工具和参数。
• 执行结果和错误。

常见问题

会话超时

• 检查 session.timeout.minutes 配置。
• 验证用户活动和会话清理。

权限被拒

• 验证用户组分配。
• 检查实体和服务权限。
• 审查 MCP 安全配置。

性能问题

• 监控数据库查询性能。
• 检查速率限制设置。
• 审查审计日志量。

开发

组件结构

moqui-mcp/
├── component.xml          # 组件定义
├── MoquiConf.xml          # 屏幕外观配置
├── entity/                # 实体定义
│   └── McpServerEntities.xml
├── service/               # 服务实现
│   ├── org/moqui/mcp/
│   └── mcp-tools/
├── screen/                # 屏幕定义
│   ├── McpRoot.xml
│   └── McpServerScreens.xml
├── data/                  # 种子数据
│   └── McpServerData.xml
└── webapp/               #  Web 应用程序资源

添加新工具

1. 在 service/mcp-tools/ 中定义服务。
2. 在 MCP 工具服务中添加工具注册。
3. 在组件配置中更新权限。
4. 在本 README 中添加文档。

测试

# 运行组件测试
./gradlew test --tests "*Mcp*"

# 测试 MCP 协议
curl -X POST http://localhost:8081/mcp/api \
  -H "Content-Type: application/json" \
  -d @test_mcp_request.json

📄 许可证

本组件根据 CC0 1.0 通用许可证和专利许可协议发布，属于公共领域。

支持

文档

• Moqui 框架文档
• MCP 协议规范
• 组件 AGENTS.md 提供详细的实现指南。

社区

• Moqui 社区论坛
• GitHub 问题

版本历史

v1.0.0（当前版本）

• 初始 MCP 服务器实现。
• 实体和服务工具。
• 安全和审计框架。
• Web 仪表盘界面。
• REST API 端点。

⚠️ 重要提示

此组件在生产环境使用前需要进行适当的安全配置。请先在开发环境中审查和测试安全设置。

贡献

开发指南

• 遵循 Moqui 组件约定。
• 实施适当的安全控制。
• 添加全面的审计日志。
• 包含单元和集成测试。
• 更新文档。

拉取请求流程

1. 分叉仓库。
2. 创建功能分支。
3. 实现带测试的更改。
4. 更新文档。
5. 提交带有描述的拉取请求。