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 中正常使用（或生成配置文件以便手動設置）！