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 Framework 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. 「Apps」→「MCP Server」に移動します。
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

コントリビュート

開発ガイドライン

• Moquiコンポーネントの規約に従います。
• 適切なセキュリティコントロールを実装します。
• 包括的な監査ログを追加します。
• 単体テストと統合テストを含めます。
• ドキュメントを更新します。

プルリクエストのプロセス

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. テストを含めて変更を実装します。
4. ドキュメントを更新します。
5. 説明付きでプルリクエストを送信します。

📄 ライセンス

このコンポーネントはCC0 1.0ユニバーサルと特許ライセンスの付与の下で公開されており、パブリックドメインに置かれています。

サポート

ドキュメント

• Moqui Framework Documentation
• MCP Protocol Specification
• 詳細な実装ガイドについては、コンポーネントの AGENTS.md を参照してください。

コミュニティ

• Moqui Community Forum
• GitHub Issues

バージョン履歴

v1.0.0 (現在)

• 初期のMCPサーバー実装
• エンティティとサービスツール
• セキュリティと監査フレームワーク
• Webダッシュボードインターフェース
• REST APIエンドポイント

⚠️ 重要提示

このコンポーネントは本番環境で使用する前に適切なセキュリティ設定が必要です。必ず開発環境でセキュリティ設定を確認し、テストしてください。