MCP Commerce

🚀 MCP Dynamics 365 Commerce Server

このModel Context Protocol (MCP) サーバーは、Dynamics 365 Commerce Retail ServerのCustomer Consumer APIとやり取りするためのツールを提供します。このサーバーにより、AIアシスタントはコントローラーで整理された包括的なツールセットを通じて、コマース操作を実行できます。

✨ 主な機能

このMCPサーバーは、19以上のコントローラーに整理された125以上のツールを提供し、Dynamics 365 Commerce APIの主要なエンドポイントを網羅しています。

🛍️ 顧客コントローラー (10個のツール)

• customer_get_order_shipments_history - 顧客の注文出荷履歴を取得する
• customer_create_entity - 新しい顧客エンティティを作成する
• customer_update_entity - 既存の顧客エンティティを更新する
• customer_get_order_history - 顧客の注文履歴を取得する
• customer_search - さまざまな条件で顧客を検索する
• customer_get_purchase_history - 顧客の購入履歴を取得する
• customer_get_by_account_numbers - アカウント番号から顧客リストを取得する
• customer_get_customer_search_fields - 店舗の顧客検索フィールドを取得する
• customer_search_by_fields - 指定されたフィールドで顧客を検索する
• customer_post_nontransactional_activity_loyalty_points - 非トランザクションのロイヤルティポイントを投稿する

📦 販売注文コントローラー (24個のツール)

• salesorder_get_receipts - 印刷用のフォームタイプに基づいて、販売注文のレシートを取得する
• salesorder_get_gift_receipts - 特定の販売明細行番号のギフトレシートを取得する
• salesorder_get_by_receipt_id - レシート識別子で販売注文を取得する
• salesorder_search_sales_transactions_by_receipt_id - レシートIDで販売トランザクションを検索する
• salesorder_search - 与えられた検索条件に一致する注文を検索する
• salesorder_search_orders - 注文検索条件に一致する注文を検索する
• salesorder_get_invoices_by_sales_id - 販売識別子で販売請求書を取得する
• salesorder_get_order_invoices - 顧客アカウントで未決済の注文請求書を取得する
• salesorder_get_invoices - 検索条件で未決済の請求書を取得する
• salesorder_get_invoiced_sales_lines_by_sales_ids - 販売注文IDで請求済みの販売明細行を取得する
• salesorder_create_picking_list - 販売注文のピッキングリストを作成する（非推奨）
• salesorder_create_picking_list_for_items - 選択された販売注文明細行のピッキングリストを作成する
• salesorder_get_picking_lists - 本部からの注文のピッキングリストを取得する
• salesorder_create_packing_slip - 荷積書を作成する
• salesorder_get_sales_order_details_by_transaction_id - トランザクションIDで販売注文の詳細を取得する
• salesorder_get_sales_order_details_by_sales_id - 販売IDで販売注文の詳細を取得する
• salesorder_get_sales_order_details_by_quotation_id - 見積もりIDで販売注文の詳細を取得する
• salesorder_get_entity_by_key - トランザクション識別子で販売注文を取得する
• salesorder_create_entity - 入金明細行を含む予約済みの販売注文をアップロードする
• salesorder_checkin_for_order_pickup - 注文受け取りのチェックインを行う
• salesorder_get_invoice_details - 検索条件で請求書の詳細を取得する
• salesorder_send_receipt - トランザクションレシートを電子メールアドレスに送信する
• salesorder_get_order_by_channel_reference_lookup_criteria - チャネル参照IDで販売注文を取得する
• salesorder_search_sales_transactions_by_receipt_id_paged - ページング付きでレシートIDで販売トランザクションを検索する

🛒 カートコントローラー (55個のツール)

• cart_checkout - 支払い処理を伴うカートの決済を行う
• cart_add_cart_lines - カートにカート明細行（商品）を追加する
• cart_void_cart_lines - カート内のカート明細行を無効にする
• cart_update_cart_lines - カート内の既存のカート明細行を更新する
• cart_refill_gift_card - ギフトカードに残高を追加する
• cart_issue_gift_card - 新しいギフトカードを発行する
• cart_cashout_gift_card - ギフトカードを現金化する
• cart_add_tender_line - カートの入金明細行を追加する
• cart_add_preprocessed_tender_line - 事前処理された入金明細行を追加する
• cart_validate_tender_line_for_add - 追加前に入金明細行を検証する
• cart_update_tender_line_signature - カートの入金明細行の署名を更新する
• cart_void_tender_line - カートの入金明細行を無効にする
• cart_suspend_with_journal - カートを一時停止し、仕訳帳を作成する
• cart_resume - 一時停止されたカートを再開する
• cart_resume_from_receipt_id - レシートIDからカートを再開する
• cart_recall_order - 顧客の注文を呼び戻す
• cart_add_invoiced_sales_lines_to_cart - 請求済みの販売明細行をカートに追加する
• cart_recall_quote - 見積もりを呼び戻す
• cart_recall_sales_invoice - 販売請求書を呼び戻す
• cart_add_order_invoice - 注文請求書をカートに追加する
• cart_add_invoices - 請求書をカートに追加する
• cart_recalculate_order - 顧客の注文を再計算する
• cart_update_commission_sales_group - 手数料販売グループを更新する
• cart_delivery_preferences - カートの配送設定を取得する
• cart_get_line_delivery_options - 明細行の配送オプションを取得する
• cart_get_line_delivery_options_by_channel_id - チャネルで明細行の配送オプションを取得する
• cart_get_payments_history - 支払い履歴を取得する
• cart_get_delivery_options - 配送オプションを取得する
• cart_update_line_delivery_specifications - 明細行の配送仕様を更新する
• cart_add_charge - カートに手数料を追加する
• cart_override_charge - 手数料金額を上書きする
• cart_add_cart_line_charge - カート明細行に手数料を追加する
• cart_override_cart_line_charge - カート明細行の手数料を上書きする
• cart_update_delivery_specification - 配送仕様を更新する
• cart_override_cart_line_price - カート明細行の価格を上書きする
• cart_get_promotions - カートのプロモーションを取得する
• cart_add_discount_code - 割引コードを追加する
• cart_remove_discount_codes - 割引コードを削除する
• cart_remove_cart_lines - カート明細行を削除する
• cart_search - 条件でカートを検索する
• cart_get_card_payment_accept_point - カード支払いの受け付けポイントを取得する
• cart_retrieve_card_payment_accept_result - カード支払いの受け付け結果を取得する
• cart_add_coupons - クーポンをカートに追加する
• cart_remove_coupons - クーポンをカートから削除する
• cart_get_charge_codes - 手数料コードを取得する
• cart_get_max_loyalty_points_to_redeem_for_transaction_balance - トランザクション残高で引き換える最大ロイヤルティポイントを取得する
• cart_get_declined_or_voided_card_receipts - 拒否または無効にされたカードレシートを取得する
• cart_reset_all_charges - すべての手数料をリセットする
• cart_get_entity_by_key - キーでカートエンティティを取得する
• cart_create_entity - カートエンティティを作成する
• cart_update_entity - カートエンティティを更新する
• cart_delete_entity - カートエンティティを削除する
• cart_get_cart_by_id - IDでカートを取得する
• cart_merge_carts - 複数のカートを統合する
• cart_validate_cart - 決済前にカートを検証する

🏷️ 商品コントローラー (4個のツール)

• products_search - さまざまな条件で商品を検索する
• products_get_by_id - 特定の商品の詳細情報を取得する
• products_get_recommended_products - 特定の商品に基づいておすすめ商品を取得する
• products_get_product_availability - さまざまな場所での商品の在庫状況を取得する

🏪 組織単位コントローラー (3個のツール)

• orgunits_get_locations_by_area - 特定のエリア内の店舗の場所を取得する
• orgunits_get_available_inventory - 店舗/倉庫の利用可能な在庫を取得する
• orgunits_get_store_hours - 特定の店舗の営業時間を取得する

💳 ロイヤルティカードコントローラー (3個のツール)

• loyaltycard_issue_loyalty_card - 顧客に新しいロイヤルティカードを発行する
• loyaltycard_get_loyalty_card - ロイヤルティカードの情報とステータスを取得する
• loyaltycard_get_loyalty_card_transactions - ロイヤルティカードの取引履歴を取得する

👨‍💼 シフトコントローラー (4個のツール)

• shifts_get_shift - 特定のシフトの情報を取得する
• shifts_open - 従業員の新しいシフトを開始する
• shifts_close - 既存のシフトを終了する
• shifts_resume - 以前に一時停止されたシフトを再開する

🏠 住所コントローラー (1個のツール)

• address_get_address_purposes - ページングとソートをサポートした住所の目的を取得する

🏷️ バーコードコントローラー (1個のツール)

• barcode_get_barcode_by_id - 識別子でバーコードを取得する

💰 現金申告コントローラー (1個のツール)

• cash_declaration_get_cash_declarations - ページングをサポートした現金申告を取得する

🏙️ 都市コントローラー (1個のツール)

• cities_get_cities - 国/地域、州/都道府県、郡でフィルタリングされたすべての都市を取得する

🏞️ 郡コントローラー (1個のツール)

• counties_get_counties - 国/地域と州/都道府県でフィルタリングされたすべての郡を取得する

🌍 国/地域コントローラー (3個のツール)

• country_region_get_country_regions_for_shipping - 配送モードが設定された国/地域を取得する
• country_region_get_country_regions_by_language_id - 言語IDでフィルタリングされた国/地域を取得する
• country_region_get_country_regions - すべての国/地域を取得する

📄 クレジットメモコントローラー (1個のツール)

• credit_memo_get_credit_memo_by_id - 識別子でクレジットメモを取得する

🛒 一時停止カートコントローラー (1個のツール)

• suspended_cart_get_all_suspended_carts - すべての一時停止されたカートを取得する

💳 入金種別コントローラー (2個のツール)

• tender_types_get_tender_types - 入金種別を取得する
• tender_types_round_amount_by_tender_type - 入金種別で金額を丸める

❓ 理由コードコントローラー (3個のツール)

• reason_codes_get_reason_codes - 理由コードを取得する
• reason_codes_get_return_order_reason_codes - 返品注文の理由コードを取得する
• reason_codes_get_reason_codes_by_id - グループまたは単一の識別子で理由コードを取得する

💲 価格設定コントローラー (1個のツール)

• pricing_calculate_sales_document - 与えられた数量で商品の価格と割引を計算する

🚚 配送オプションコントローラー (1個のツール)

• delivery_options_get_delivery_options - チャネルの配送オプションを取得する

👥 顧客グループコントローラー (1個のツール)

• customer_group_get_customer_groups - 顧客グループのコレクションを取得する

💱 通貨コントローラー (2個のツール)

• currency_get_currencies_amount - 通貨の金額を取得する
• currency_calculate_total_currency_amount - 通貨の合計金額を計算する

⚖️ 顧客残高コントローラー (1個のツール)

• customer_balance_get_customer_balance - 顧客の残高を取得する

📱 デバイス設定コントローラー (1個のツール)

• device_configuration_get_device_configuration - 単一のデバイス設定を取得する

🌐 言語コントローラー (1個のツール)

• language_get_languages - サポートされている言語のコレクションを取得する

📦 インストール

1. リポジトリをクローンする：

   git clone <repository-url>
   cd mcp-commerce
   

2. 依存関係をインストールする：

   pip install -r requirements.txt
   

   または、pyproject.tomlを使用してpipでインストールする：

   pip install -e .
   

📚 ドキュメント

Claude Desktop

サーバーをClaude Desktopの設定ファイルに追加します：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dynamics365-commerce": {
      "command": "python",
      "args": ["/path/to/mcp-commerce/mcp_dynamics365_commerce_server/server.py"],
      "env": {
        "DYNAMICS365_BASE_URL": "https://your-commerce-site.com"
      }
    }
  }
}

VS CodeとMCP拡張機能

1. VS Code用のMCP拡張機能をインストールします。
2. サーバーの設定を追加します：

{
  "name": "dynamics365-commerce",
  "command": "python",
  "args": ["/path/to/mcp-commerce/mcp_dynamics365_commerce_server/server.py"],
  "env": {
    "DYNAMICS365_BASE_URL": "https://your-commerce-site.com"
  }
}

💻 使用例

設定が完了したら、AI会話でツールを使用できます。

顧客操作の例

"メールアドレスに 'john@example.com' を含む顧客を検索する"
"顧客CUST001の注文履歴を取得する"
"名前が 'Jane Smith' でメールアドレスが 'jane.smith@example.com' の新しい顧客を作成する"

商品操作の例

"100ドル未満のワイヤレスヘッドフォンを検索する"
"商品PROD001の詳細情報を取得する"
"シアトルエリアで商品PROD001の在庫状況を確認する"

カート操作の例

"商品PROD001を数量2でカートCART001に追加する"
"カートCART001をクレジットカードで決済する"
"カートCART001を理由 '顧客が後で戻ってくる' で一時停止する"

店舗操作の例

"シアトルエリアでピックアップサービスを提供する店舗を検索する"
"店舗STORE001の在庫を取得する"
"店舗STORE001の営業時間はいつですか？"

📋 モックデータ

このサーバーは、すべてのAPIエンドポイントに対して包括的なモックデータを提供します。これには以下が含まれます：

• 現実的なコマースデータ：商品、顧客、注文、トランザクション
• 完全なレスポンス構造：Dynamics 365 Commerce APIのパターンに従う
• 豊富なメタデータ：タイムスタンプ、ID、ステータス情報、ネストされたオブジェクト
• エラーハンドリング：無効なリクエストに対する適切なエラーレスポンス

すべてのモックレスポンスには以下が含まれます：

• APIエンドポイント情報
• 現実的なサンプルデータ
• 適切なデータ関係
• タイムスタンプ情報
• ステータスとメタデータフィールド

🔧 技術詳細

サーバーは、各APIエリアに対して個別のコントローラーで構成されています：

mcp_dynamics365_commerce_server/
├── server.py                    # メインのMCPサーバーエントリポイント
├── controllers/
│   ├── customer.py             # 顧客操作
│   ├── sales_order.py          # 販売注文操作  
│   ├── cart.py                 # カート操作
│   ├── products.py             # 商品操作
│   ├── org_units.py            # 店舗/倉庫操作
│   ├── loyalty_card.py         # ロイヤルティプログラム操作
│   ├── shifts.py               # 従業員シフト操作
│   ├── address.py              # 住所操作
│   ├── barcode.py              # バーコード操作
│   ├── cash_declaration.py     # 現金申告操作
│   ├── cities.py               # 都市操作
│   ├── counties.py             # 郡操作
│   ├── country_region.py       # 国/地域操作
│   ├── credit_memo.py          # クレジットメモ操作
│   ├── suspended_cart.py       # 一時停止カート操作
│   ├── tender_types.py         # 入金種別操作
│   ├── reason_codes.py         # 理由コード操作
│   └── pricing.py              # 価格設定操作

新しいツールの追加

1. 適切なコントローラーを選択するか、新しいコントローラーを作成する。
2. コントローラーの get_tools() メソッドにツール定義を追加する。
3. コントローラーの handle_tool() メソッドにハンドラーロジックを実装する。
4. メインサーバーを更新して、新しいコントローラーをインポートして登録する。

テスト

サーバーを直接実行してテストします：

python mcp_dynamics365_commerce_server/server.py

📚 ドキュメント

各ツールは、Dynamics 365 CommerceサイトのURLを指定するための baseUrl パラメーターを受け付けます。指定されない場合、デフォルトは https://your-commerce-site.com です。

認証

このサーバーはモック実装を提供します。本番環境では、以下が必要になります：

1. 適切な認証（OAuth 2.0、APIキー）を実装する。
2. SSL/TLS証明書の処理を追加する。
3. APIの失敗に対する適切なエラーハンドリングを実装する。
4. レート制限とリクエストのスロットリングを追加する。

実際のAPIとの統合

実際のDynamics 365 Commerce APIと統合するには：

1. モック実装を実際のHTTPリクエストに置き換える。
2. 認証ヘッダーとトークンを追加する。
3. 実際のAPIレスポンス形式を処理する。
4. ネットワーク問題に対する適切なエラーハンドリングを実装する。
5. データの検証とサニタイズを追加する。

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

🤝 コントリビューション

1. リポジトリをフォークする。
2. 機能ブランチを作成する。
3. 変更を加える。
4. 新しい機能に対するテストを追加する。
5. プルリクエストを送信する。

🆘 サポート

以下に関連する問題について：

• MCPサーバー：このリポジトリにイシューを作成してください。
• Dynamics 365 Commerce：Microsoftの公式ドキュメントを参照してください。
• Claude Desktop：Anthropicのドキュメントを確認してください。

⚠️ 重要提示

これは開発とテスト目的のモック実装です。実際のDynamics 365 Commerceシステムでの本番使用には、追加の認証、セキュリティ、およびエラーハンドリングの実装が必要です。