Yangotech MCP

🚀 洋戈科技MCP服务器 - 一键安装

本项目提供了与领先的电商自动化平台 洋戈科技 的集成方案。

洋戈科技隶属于洋戈集团，这是一家全球性的科技公司，致力于改变全球人们的日常业务模式：

• 📊 自2018年以来，已完成超过1.5亿次出行服务。
• 💰 总商品交易额（GMV）超过25亿美元。
• ✅ 订单交付准确率高达99.99%，无漏发情况。
• 📦 日订单处理量超过130万单。

洋戈科技 提供了全面的解决方案，涵盖以下领域：

• 🌐 APP与网站应用
• 🏪 订单管理与物流配送
• 📦 实时库存管理
• 🛍️ 产品目录管理，提供详细的产品信息
• 🚚 配送与订单履行
• 📊 数据分析与销售报告
• 🔄 API集成，支持B2B自动化业务

通过这个MCP服务器，你可以直接从 Claude桌面版 或 Cursor IDE 轻松与洋戈科技的API进行交互，获取订单、产品、库存水平等平台信息。

🚀 快速开始

✨ 简单安装

下载本项目并运行以下命令：

python3 install.py

🎉 完成！一切将自动配置完成。

🔧 安装程序功能

1. ✅ 自动检测操作系统（支持Mac、Windows、Linux）
2. ✅ 查找Python环境 并创建虚拟环境
3. ✅ 自动安装所有依赖项（包括FastMCP 2.5+）
4. ✅ 检测已安装的IDE（Claude桌面版 和 Cursor IDE）
5. ✅ 提供测试API密钥 或使用你自己的密钥
6. ✅ 自动创建IDE配置（如果已安装IDE）
7. ✅ 在项目根目录生成配置文件，方便手动设置
8. ✅ 使用真实API测试功能
9. ✅ 显示下一步操作说明

💡 即使未安装IDE也能正常工作，配置文件将始终生成！

✨ 主要特性

🤖 强大的IDE集成

🖥️ Claude桌面版

具备洋戈科技强大功能的专业AI助手：

• 💬 自然语言查询：通过自然语言与洋戈科技API进行交互。
• 🔍 智能产品搜索：支持使用易读的产品名称进行搜索。
• 📋 订单管理：通过对话方式管理订单。
• 📊 实时库存检查：实时获取库存信息。

📸 查看 Claude桌面版 实际操作效果：

• 🛍️ 产品目录分析：
• 🎬 实时产品搜索演示：
• 📦 库存管理：
• 📋 订单详情查询：
• 🔍 订单状态跟踪：

⚡ Cursor IDE

具备业务数据访问能力的AI代码编辑器：

• 🛠️ 查询数据时编写代码：在编写代码的同时查询 洋戈科技 的数据。
• 🔄 API集成：直接在工作流程中集成API。
• 📝 文档生成：根据真实数据生成文档。
• 🚀 快速原型开发：借助实时业务洞察进行快速原型开发。

🎨 集成带来的变革

无需在多个工具之间频繁切换，你可以：

• ✨ 向Claude提问："显示订单240920 - 728268的详细信息"
• ✨ 向 Cursor 提问："店铺L001中哪些产品库存不足？"
• ✨ 获得即时答案，并显示易读的产品名称
• ✨ 使用自然语言工作，无需复杂的API调用，提高工作效率

🔗 一切均由 洋戈科技 提供支持，它是你的电商自动化平台！

💻 使用示例

安装后操作

1. 重启 Claude桌面版 和/或 Cursor IDE（如果已安装）
2. 你将获得6个具备产品名称丰富功能的洋戈科技工具：
   • get_order_details：获取包含产品名称的订单详情
   • get_order_status：获取订单状态
   • get_all_products：获取包含显示名称的所有产品信息
   • get_products_batch：分页获取包含产品名称的产品信息
   • get_all_stocks：获取包含产品名称的所有库存信息
   • get_stocks_batch：分页获取包含产品名称的库存信息

🎯 关键特性：所有工具均显示用户友好的产品名称，而非晦涩的产品ID！

测试命令

• "从洋戈科技目录中显示5种产品"（包含产品名称）
• "显示店铺中的产品库存"（包含产品名称）
• "显示订单240920 - 728268的详细信息"（包含丰富的购物车商品信息）
• "获取订单240920 - 728268的状态"

📚 详细文档

📁 生成的配置文件

安装程序会在项目根目录始终生成以下文件：

• claude_desktop_config.json：可直接使用的 Claude桌面版 配置文件
• cursor_settings.json：可直接使用的 Cursor IDE 配置文件

这些文件可用于：

• 手动设置IDE
• 备份配置
• 将设置复制到其他机器
• 故障排除

⚙️ 系统要求

• Python 3.8+（自动检测和验证）
• 网络连接：用于下载依赖项
• Claude桌面版 和/或 Cursor IDE（可选，无论是否安装都会生成配置文件）

🐍 未安装Python怎么办？

没问题！如果缺少Python或版本过旧，安装程序将显示详细的安装指南：

• macOS：可使用官方安装程序、Homebrew或pyenv进行安装
• Windows：可使用官方安装程序（⚠️ 请勾选“添加到PATH”）、Microsoft Store或Chocolatey进行安装
• Linux：可使用包管理器（如apt、dnf、pacman）或从源代码进行安装

为什么需要Python 3.8+？ 这是FastMCP框架兼容性的要求。

快速检查：运行 python3 --version 或 python --version

📖 详细指南：请参阅 PYTHON_SETUP.md 获取详细的安装步骤

🧹 完全环境重置

如果需要完全清理并重新安装，请运行以下命令：

python3 cleanup.py
python3 install.py

清理脚本将删除以下内容：

• 虚拟环境
• 两个IDE的配置文件
• 生成的配置文件
• 环境文件
• 缓存文件

🌍 API端点

• 测试环境：https://api.tst.eu.cloudretail.tech
• 生产环境：https://api.retailtech.yango.com

🔧 技术细节

项目架构

yangotech_mcp/
├── install.py               # 🎯 通用安装程序
├── cleanup.py               # 🧹 完全清理脚本
├── server.py                # FastMCP服务器
├── client.py                # 洋戈科技API的HTTP客户端
├── models.py                # Pydantic数据模型
├── claude_desktop_config.json  # 生成的Claude配置文件
├── cursor_settings.json        # 生成的Cursor配置文件
└── README.md                # 本项目文档

开发安装

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# 或
.venv\Scripts\activate     # Windows

# 安装依赖项（现在包含FastMCP 2.5+）
pip install -e .

# 测试API
export YANGO_TECH_API_KEY="your_api_key"
python test_api_connection.py

# 运行MCP服务器
python server.py

技术栈

• FastMCP 2.5+：现代MCP服务器框架
• Python 3.8+：核心编程语言
• HTTPx：异步HTTP客户端
• Pydantic：数据验证工具
• python-dotenv：环境管理工具

API端点

服务器与真实的洋戈科技API进行交互：

• 测试URL：https://api.tst.eu.cloudretail.tech/b2b/v1
• 生产URL：https://api.retailtech.yango.com/b2b/v1
• 授权方式：使用OAuth令牌进行头部授权
• 请求方法：大多数请求使用POST方法
• 分页方式：对于大数据量，采用基于游标（Cursor）的分页方式

IDE支持

• Claude桌面版：使用 mcpServers 配置
• Cursor IDE：使用 mcp.servers 配置
• 自动检测：安装程序会自动检测已安装的IDE
• 通用性：即使未安装IDE也能正常工作，配置文件将始终生成

📄 许可证

文档未提供相关许可证信息。

📞 技术支持

如果遇到问题，请按以下步骤进行排查：

1. 检查Python版本：运行 python3 --version（应不低于3.8）
2. 完全重置环境：运行 python3 cleanup.py && python3 install.py
3. 手动设置：使用生成的配置文件（claude_desktop_config.json、cursor_settings.json）
4. 手动设置指南：请参阅 MANUAL_SETUP.md 获取详细的手动设置步骤
5. 检查IDE日志（Claude桌面版 或 Cursor IDE）
6. 确保IDE已重启：安装完成后，请重启IDE

🎯 目标：一键安装，即可在 Claude桌面版 和 Cursor IDE 中正常使用（或生成配置文件以便手动设置）！