JinDaGe - moqui-mcp MCP Details

article

README

🚀 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 支持的其他数据库）。

安装步骤

组件部署

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

数据库初始化
- 组件实体在启动时会自动创建。
- 种子数据包含默认配置和用户组。
配置
- 编辑 MoquiConf.xml 以进行屏幕集成。
- 根据需要在 component.xml 中配置属性。
重启 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 仪表盘

以管理员身份登录 Moqui。
导航到“应用程序”→“MCP 服务器”。
在 /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 应用程序资源

添加新工具

在 service/mcp-tools/ 中定义服务。
在 MCP 工具服务中添加工具注册。
在组件配置中更新权限。
在本 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 提供详细的实现指南。

社区

版本历史

v1.0.0（当前版本）

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

⚠️ 重要提示

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

贡献

开发指南

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

拉取请求流程

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