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. 提交帶有描述的拉取請求。