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 商务系统中进行生产使用，需要额外实现身份验证、安全和错误处理。