MCP Commerce

🚀 MCP Dynamics 365 商務服務器

這是一個模型上下文協議（MCP）服務器，它提供了與 Dynamics 365 商務零售服務器客戶消費 API 進行交互的工具。藉助該服務器，AI 助手能夠通過一套按控制器組織的全面工具來執行商務操作。

🚀 快速開始

本 MCP 服務器提供了與 Dynamics 365 商務零售服務器客戶消費 API 交互的工具，AI 助手可藉助它執行商務操作。配置完成後，即可在 AI 對話中使用這些工具。

✨ 主要特性

此 MCP 服務器提供了125 多種工具，這些工具被組織到19 多個控制器中，涵蓋了 Dynamics 365 商務 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 - 獲取支持的語言集合

📦 安裝指南

克隆倉庫

git clone <repository-url>
cd mcp-commerce

安裝依賴

pip install -r requirements.txt

或者使用 pip 和 pyproject.toml 進行安裝：

pip install -e .

📚 詳細文檔

配置

Claude 桌面版

將服務器添加到你的 Claude 桌面版配置文件中：

• 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"
      }
    }
  }
}

帶有 MCP 擴展的 VS Code

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 對話中使用這些工具：

示例客戶操作

"Search for customers with email containing 'john@example.com'"
"Get order history for customer CUST001"
"Create a new customer with name 'Jane Smith' and email 'jane.smith@example.com'"

示例產品操作

"Search for wireless headphones under $100"
"Get detailed information for product PROD001"
"Check availability of product PROD001 in Seattle area"

示例購物車操作

"Add product PROD001 with quantity 2 to cart CART001"
"Checkout cart CART001 with credit card payment"
"Suspend cart CART001 with reason 'customer will return later'"

示例商店操作

"Find stores in Seattle area with pickup service"
"Get inventory for store STORE001"
"What are the hours for store STORE001?"

模擬數據

本服務器為所有 API 端點提供了全面的模擬數據，包括：

• 真實的商務數據：產品、客戶、訂單、交易
• 完整的響應結構：遵循 Dynamics 365 商務 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

API 參考

每個工具都接受一個 baseUrl 參數，用於指定你的 Dynamics 365 商務網站 URL。如果未提供，默認值為 https://your-commerce-site.com。

身份驗證

本服務器提供了模擬實現。在生產環境中，你需要：

1. 實現適當的身份驗證（OAuth 2.0、API 密鑰）
2. 添加 SSL/TLS 證書處理
3. 為 API 失敗實現適當的錯誤處理
4. 添加速率限制和請求節流

實際 API 集成

要與實際的 Dynamics 365 商務 API 集成：

1. 用實際的 HTTP 請求替換模擬實現
2. 添加身份驗證頭和令牌
3. 處理實際的 API 響應格式
4. 為網絡問題實現適當的錯誤處理
5. 添加數據驗證和清理

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

貢獻說明

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 為新功能添加測試
5. 提交拉取請求

支持說明

• MCP 服務器：在本倉庫中創建問題
• Dynamics 365 商務：查閱微軟的官方文檔
• Claude 桌面版：查看 Anthropic 的文檔

⚠️ 重要提示

這是一個用於開發和測試目的的模擬實現。要在實際的 Dynamics 365 商務系統中進行生產使用，需要額外實現身份驗證、安全和錯誤處理。