🛍️ MCP - MCP for Commerce Platforms - Universal E-commerce Customer Support Assistant

---

title: Enneagora - 电商 MCP 服务 emoji: 🛍️ colorFrom: blue colorTo: purple sdk: gradio sdk_version: 5.33.0 app_file: main.py pinned: true license: mit tags:

• mcp-server-track
• cuustomer support
• commerce
• e-commerce

---

Enneagora - 电商 MCP 服务

Enneagora 是一个通用电商客户支持助手，使用模型上下文协议（MCP），为不同电商平台提供平台无关的客户支持解决方案。这个全面的 MCP 服务可与 Claude Desktop 或任何兼容 MCP 的客户端集成，处理客户咨询的方方面面。

🚀 功能

• 符合 MCP 规范：双 MCP 服务实现，同时使用 Gradio 和 FastMCP，并支持 SSE 和 STDIO 传输
• 14 个全面的客户支持工具：
  • 订单管理：get_order_status、cancel_order、process_return、track_package
  • 支持信息：get_support_info、get_return_policy、get_shipping_info、get_contact_information
  • 产品指南：get_size_guide、get_warranty_information、get_product_care_info
  • 账户与支付：get_payment_information、get_account_help、get_loyalty_program_info
• 平台无关：采用策略模式，方便与任何电商平台集成
• 动态模拟数据：智能测试数据系统，基于模式的订单行为
• 双实现支持：用于 Web 部署的 Gradio MCP 服务，以及用于 Claude Desktop STDIO 集成的 FastMCP
• 可用于生产环境：CI/CD 流水线，可自动部署到 Hugging Face Spaces

📋 前置条件

• Python 3.10 或更高版本
• pip 包管理器
• （可选）用于部署的 Hugging Face 账户

🛠️ 安装

1. 克隆仓库：

git clone https://github.com/slavpilus/mcp.git
cd mcp

2. 创建并激活虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. 安装依赖：

pip install -r requirements.txt

🚀 使用选项

选项 1：Gradio MCP 服务（推荐用于 Hugging Face Spaces）

使用托管在 Hugging Face Spaces 上的 Gradio MCP 服务：

Gradio MCP 端点： https://huggingface.co/spaces/SlavPilus/mpc-for-commerce-platforms

优势：

• 原生 Gradio MCP 服务实现，使用 mcp_server=True
• 无需本地设置
• 始终提供最新功能
• 非常适合兼容 MCP 的客户端和集成
• 与 Hugging Face Spaces 无缝部署

Gradio MCP 服务（本地开发）

python main.py

Gradio MCP 服务将在 http://localhost:7860 上启动，MCP SSE 端点为 http://localhost:7860/gradio_api/mcp/sse。

FastMCP Claude Desktop 集成（STDIO）

步骤 1：配置 Claude Desktop

**macOS：**编辑 ~/Library/Application Support/Claude/claude_desktop_config.json **Windows：**编辑 %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "enneagora": {
      "command": "python",
      "args": ["/full/absolute/path/to/mcp/main_stdio.py"],
      "env": {}
    }
  }
}

⚠️ 重要：

• 使用 main_stdio.py 的完整绝对路径
• 确保 Python 环境已安装所有依赖
• 更改配置后重启 Claude Desktop

步骤 2：测试配置

你可以手动测试 STDIO 版本：

python main_stdio.py

🔧 所有可用工具

订单管理工具

1. get_order_status - 获取详细的订单状态和跟踪信息
2. cancel_order - 通过验证检查取消订单
3. process_return - 使用预付运单处理退货请求
4. track_package - 实时跟踪包裹配送状态

信息与支持工具

5. get_support_info - 一般支持信息和指南
6. get_return_policy - 按产品类别提供详细退货政策
7. get_shipping_info - 运费、配送时效和国际配送选项
8. get_contact_information - 按问题类型和紧急程度提供联系方式

产品与服务工具

9. get_size_guide - 服装、鞋履和配饰尺码表
10. get_warranty_information - 保修范围和索赔处理
11. get_product_care_info - 产品护理说明和维护指南

账户与支付工具

12. get_payment_information - 支付方式、账单帮助和故障排查
13. get_account_help - 账户故障排查和登录协助
14. get_loyalty_program_info - 奖励计划详情和会员权益

🧪 使用动态模拟数据进行测试

Enneagora 采用智能模拟数据系统，根据订单 ID 模式确定订单行为：

订单状态模式

• ORD-XXXX-D - 已送达的订单（例如，ORD-1001-D）
• ORD-XXXX-S - 已发货且含跟踪信息的订单（例如，ORD-1002-S）
• ORD-XXXX-T - 运输中的订单，含位置更新（例如，ORD-1003-T）
• ORD-XXXX-P - 处理中订单（例如，ORD-1004-P）
• ORD-XXXX-R - 可供取货的订单（例如，ORD-1005-R）
• ORD-XXXX-C - 已取消的订单（例如，ORD-1006-C）
• ORD-XXXX-F - 失败/有问题的订单（例如，ORD-1007-F）
• ORD-XXXX-E - 错误/未找到（例如，ORD-1008-E）
• ORD-XXXX - 待处理订单（无后缀，例如，ORD-1009）

示例查询

连接到 Claude Desktop 或 MCP 客户端后，你可以使用自然语言：

订单管理：

• “查询订单 ORD-1001-S 的状态”
• “取消订单 ORD-1004-P，因为我找到了更优惠的价格”
• “我想退回订单 ORD-1002-D，尺码不太合适”

产品信息：

• “电子产品的退货政策是什么？”
• “$45 的订单寄到加拿大，运费是多少？”
• “男士衬衫的尺码指南是什么？”
• “我的笔记本电脑还在保修期内吗？我在 2023-06-15 买的”

账户与支付：

• “我的信用卡被拒付了，我该怎么办？”
• “我忘记了密码，如何重置？”
• “你们的忠诚度计划是如何运作的？”

产品护理：

• “丝绸连衣裙该如何护理？”
• “清洁皮鞋的最佳方法是什么？”

🏗️ 架构

┌─────────────────────────────────────┐
│         MCP Clients                 │
│  (Claude Desktop, Web Clients)      │
└──────────────┬──────────────────────┘
               │ MCP Protocol Transport
┌──────────────▼──────────────────────┐
│      Dual MCP Implementation        │
│  • main.py (Gradio MCP Server)      │
│  • main_stdio.py (FastMCP STDIO)    │
├─────────────────────────────────────┤
│  14 MCP Tools:                      │
│  • Order Management (4 tools)       │
│  • Information & Support (4 tools)  │
│  • Product & Service (3 tools)      │
│  • Account & Payment (3 tools)      │
├─────────────────────────────────────┤
│   E-commerce Strategy Layer         │
│  • Mock Strategy (Demo/Testing)     │
│  • Shopify Strategy (Future)        │
│  • Magento Strategy (Future)        │
│  • WooCommerce Strategy (Future)    │
└─────────────────────────────────────┘

🚢 部署

托管于 Hugging Face Spaces

服务已部署，可通过以下地址访问：

• Web UI： https://huggingface.co/spaces/SlavPilus/mpc-for-commerce-platforms
• SSE 端点： https://huggingface.co/spaces/SlavPilus/mpc-for-commerce-platforms/sse

手动部署

# Build Docker image
docker build -t enneagora .

# Run container
docker run -p 7860:7860 enneagora

部署你自己的实例

1. Fork 此仓库
2. 设置 GitHub secrets：
   • HF_TOKEN：你的 Hugging Face 令牌
   • HF_USERNAME：你的 Hugging Face 用户名
   • HF_SPACE_NAME：你的 Space 名称
3. 推送到 main 分支以触发部署

🧪 开发

运行测试

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests with coverage
pytest --cov=mcp_server --cov=main

# Run linting and formatting
pre-commit run --all-files

项目结构

mcp/
├── main.py                 # Gradio MCP server (mcp_server=True)
├── app.py                  # MCP tools for Gradio registration
├── main_stdio.py          # FastMCP server (STDIO transport for Claude Desktop)
├── mcp_server/            # Core server implementation
│   ├── server.py          # Main server logic
│   ├── mcp_tools.py       # All 14 MCP tool definitions
│   └── strategies/        # E-commerce platform strategies
│       ├── base.py        # Base strategy interface
│       └── mock_strategy.py # Mock data strategy
├── tests/                 # Comprehensive test suite
│   ├── unit/              # Unit tests (96%+ coverage)
│   └── integration/       # Integration tests
├── static/                # Web UI assets
│   └── index.html         # Server info and documentation page
├── requirements.txt       # Python dependencies
├── requirements-dev.txt   # Development dependencies
└── pyproject.toml         # Project configuration

🔧 配置

环境变量

目前使用模拟数据进行演示。在生产环境中，请配置：

• ECOMMERCE_PLATFORM：要使用的平台（例如，“shopify”、“magento”）
• 平台专属凭据（API 密钥、端点等）

添加新的电商平台

1. 在 mcp_server/strategies/ 中创建一个新策略：

from .base import EcommerceStrategy

class ShopifyStrategy(EcommerceStrategy):
    async def get_order(self, order_id: str):
        # Implement Shopify API integration
        pass

2. 在配置中注册该策略
3. 配置凭据和端点

📝 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

🐛 故障排查

常见问题

1. Claude Desktop 中看不到工具

   • 检查配置文件的路径和语法
   • 确保使用 main_stdio.py 的完整绝对路径
   • 检查 Python 环境是否包含所有依赖项
   • 更改配置后重启 Claude Desktop

2. 服务连接问题

   • 确保服务在正确的端口上运行
   • 检查本地开发的防火墙设置
   • 确认 SSE 端点可访问

3. 导入错误或缺少依赖项

   • 激活虚拟环境
   • 运行 pip install -r requirements.txt
   • 确保已安装 Python 3.10+

测试配置

测试本地设置：

# Test STDIO version
python main_stdio.py

# Test SSE version
python main.py
# Then visit http://localhost:7860

📚 资源

• 项目代码库： https://github.com/slavpilus/mcp
• MCP 文档： Model Context Protocol
• FastMCP 文档： FastMCP GitHub
• Hugging Face Spaces： HF Spaces 文档

🏆 致谢

Enneagora 是作为 Hugging Face MCP 黑客马拉松的一部分构建的，旨在展示 Model Context Protocol 在创建全面的 AI 驱动客户支持系统方面的强大能力。它展示了 MCP 如何弥合 AI 助手与真实电商运营之间的差距。

展示的主要功能：

• 全面的工具生态系统（14 个相互关联的工具）
• 具备智能行为模式的动态模拟数据
• 多传输方式支持（SSE + STDIO）
• 可用于生产环境的部署与 CI/CD
• 类型安全的实现，测试覆盖率达 96% 以上