下链连接-MCP助手

Name: 下链连接-MCP助手
Author: mathofdynamic

作者：mathofdynamic2 星标更新：2025-08-21

安装使用来源：spider==github.com

项目介绍

Droplinked MCP（模型上下文协议）服务器

基于FastAPI的智能助手，与Droplinked电子商务平台集成，通过OpenAI的Assistant API提供先进的AI图像生成能力，实现AI驱动的产品管理功能。

🚀 特性

AI驱动的产品管理：通过自然语言对话创建、列出和管理Droplinked产品
🎨 AI设计图生成：
- 使用OpenAI的GPT-Image-1模型生成专业增强的产品设计图
- 自动服装检测——在不同姿势/设置下展示模特身上的衣物
- 成本效益生成（~$0.033用于3个专业设计图）
- 智能提示区分时尚产品和一般产品
📦 完整的产品管理：
- 获取产品详情：查看包括定价、媒体和设置在内的全面产品信息
- 更新产品：修改产品字段如标题、描述、价格、集合、标签等
- 删除产品：带有安全确认的产品删除
- 产品发现：列出并搜索您的产品目录
增强的图片上传流程：
- 多产品图片上传的直观工作流
- 在产品创建过程中逐步添加图片
- 首次上传图片后提供AI设计图选项
- 清晰的选择继续或添加更多图片的选项
- 单张图片上传后不会提前创建产品
简化的工作流：单一功能方法，具有清晰的操作步骤
集合管理：浏览和组织产品到集合中
安全认证：基于JWT的认证与Droplinked API
交互式Web界面：现代聊天界面，支持拖放图片上传
OpenAI助手集成：利用OpenAI的Assistant API进行智能响应
最终确认过程：在创建产品前始终需要明确的用户确认
实时通信：通过FastAPI端点实现类似WebSocket的体验
🔧 坚固的错误处理：增强的错误处理，自动重试和全面的日志记录
📊 改进的API响应处理：更好地处理各种Droplinked API响应格式

📋 先决条件

Python 3.8+
OpenAI API账户及API密钥
Droplinked账户及API访问权限
现代网络浏览器

🛠️ 安装

克隆仓库

git clone <repository-url>
cd droplinked_mcp

创建并激活虚拟环境

python -m venv venv

# 在Windows上
venv\Scripts\activate

# 在macOS/Linux上
source venv/bin/activate

安装依赖项
```
pip install -r requirements.txt
```

⚙️ 配置

创建环境文件 在项目根目录创建一个.env文件，包含以下变量：

# OpenAI配置
OPENAI_API_KEY=your_openai_api_key_here
ASSISTANT_ID=your_openai_assistant_id_here

# Droplinked配置（可选 - 测试用户解决办法）
STATIC_DROPLINKED_JWT=your_static_jwt_for_testing

OpenAI助手设置
- 在OpenAI仪表板中创建一个OpenAI助手
- 使用以下工具配置助手：
  - list_my_droplinked_products：列出用户的产品
  - create_new_droplinked_product：创建新产品（支持图片）
  - get_droplinked_shop_collections：获取产品集合
  - handle_image_upload_response：处理上传的图片
- 将助手ID复制到您的.env文件中
Droplinked API配置
- 应用使用Droplinked API基础URL：https://apiv3.droplinked.com
- 图片上传使用Droplinked上传服务：https://tools.droplinked.com/upload
- 认证通过/auth/login/basic端点处理
- 可用测试用户解决办法：mathofdynamic@gmail.com
AI设计图配置
- 使用OpenAI的GPT-Image-1模型生成专业设计图
- 使用GPT-4V自动检测服装
- 成本结构：
  - 低质量：每张图片$0.011
  - 中质量：每张图片$0.042
  - 高质量：每张图片$0.167
- 默认设置：为了成本效益，选择低质量（~$0.033用于3个设计图）
- 智能提示区分服装和一般产品

🚀 运行应用程序

启动服务器

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

访问应用程序
- 打开浏览器并导航至http://localhost:8000
- 您将看到Droplinked MCP助手的聊天界面
认证
- 访问http://localhost:8000/login以您的Droplinked凭证进行认证
- JWT令牌将用于后续的API调用

📁 项目结构

droplinked_mcp/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI应用程序入口点
│   ├── core/
│   │   └── config.py          # 配置设置
│   ├── models/                # Pydantic模型（当前为空）
│   ├── routers/
│   │   └── chatbot_router.py  # 聊天API端点
│   └── services/
│       ├── auth_service.py    # 认证逻辑
│       ├── droplinked_api_service.py  # Droplinked API集成
│       ├── ai_mockup_service.py       # AI图像生成服务
│       └── nlu_service.py     # 自然语言理解
├── openai_config/             # OpenAI助手配置
│   ├── assistant_system_instructions.md
│   ├── updated_function_definition.json
│   └── simplified_instructions.md
├── static/
│   ├── script.js             # 前端JavaScript
│   └── style.css             # 前端样式
├── templates/
│   ├── index.html            # 主聊天界面
│   └── login.html            # 登录页面
├── tests/                    # 测试文件
├── requirements.txt          # Python依赖项
├── .gitignore               # Git忽略规则
└── README.md                # 此文件

🔧 API端点

认证

GET /login - 登录页面
POST /auth/mcp/login - 用户认证并获取JWT令牌

聊天界面

GET / - 主聊天界面
POST /chatbot/message - 向AI助手发送消息

图片上传

POST /upload/image - 上传产品图片（需认证）

健康检查

GET /health - 应用健康状态

🤖 可用AI工具

OpenAI助手采用精简的单功能方法：

manage_droplinked_product（主要功能）

一个综合功能，通过操作参数处理所有产品创建步骤：

操作：create_product - 数据收集阶段
- 收集所需信息：标题、描述、集合、价格、数量、重量
- 引导用户逐步收集数据
操作：upload_images - 图像处理阶段
- 处理上传的产品图片
- 支持每个产品的多张图片上传
- 提供AI设计图生成选项
操作：generate_ai_mockups - AI增强阶段
- 使用GPT-Image-1生成3个专业AI增强的设计图
- 自动检测服装项目并在模特身上展示
- 创建工作室、生活方式和高级时尚照片
- 成本：~$0.033用于3个高质量设计图
操作：show_summary - 确认阶段
- 显示创建前完整的商品摘要
- 展示所有收集的数据，包括图片
- 需要明确的用户确认
操作：confirm_creation - 最终创建阶段
- 实际在Droplinked上创建商品
- 只有在用户查看并确认摘要后才执行

辅助功能

list_my_droplinked_products - 列出用户的现有产品（分页）
get_droplinked_shop_collections - 获取可用的产品集合

产品管理功能

manage_product_operations - 统一功能，用于获取、更新或删除产品（推荐）
- 操作：get_product - 通过ID检索详细的产品信息
- 操作：update_product - 修改产品字段（标题、描述、价格、集合、标签等）
- 操作：delete_product - 删除产品（带有安全确认）
get_product_by_id - 获取特定产品的详细信息
update_product - 更新特定产品的字段，具有细粒度控制
delete_product - 删除产品（需要明确确认）

💬 使用示例

创建带有AI设计图生成的产品

用户："我想创建一个新的产品"
助手："我将帮助您创建一个新的产品。这个产品的标题（名称）是什么？"
用户："复古牛仔夹克"
助手："这个产品的描述是什么？"
用户："经典复古风格的牛仔夹克，带有破损细节"
...（继续引导设置，包括集合选择）
助手："您想上传产品图片吗？请使用聊天界面中的图片上传功能，或者键入“跳过”以继续不带图片。"
用户：[使用相机按钮上传第一张图片]
助手："很好！我已经上传了您的第一张图片。您现在有1张产品图片。

🎨 **AI设计图选项**：我可以从您的图片生成3个专业的AI增强设计图（成本：~$0.033）。对于服装项目，我会在不同的设置下展示它们！

您想：
1. **生成AI设计图**（推荐以提高销售）
2. 手动上传更多图片
3. 仅继续使用原始图片

键入“生成设计图”，“上传更多”，或“继续”以继续。"
用户："生成设计图"
助手："🎉 成功生成了3个AI设计图！您现在总共有4张图片（1张原始 + 3张AI增强）。AI已经创建了展示您的产品在不同风格和设置下的专业版本。"
用户："创建它"
助手："这是您的产品的摘要：

- 标题：复古牛仔夹克
- 描述：经典复古风格的牛仔夹克，带有破损细节
- 集合：时尚
- 价格：$89.99
- 数量：25
- 重量：1.2
- 图片：已上传4张图片
  1. original_jacket.jpg
  2. ai_studio_model.png（AI生成）
  3. ai_lifestyle_photo.png（AI生成）
  4. ai_premium_fashion.png（AI生成）

您想：
1. 按原样创建产品
2. 添加更多图片
3. 更改详细信息

请键入“创建”，“添加图片”，或告诉我您想更改什么。"
用户："创建"
助手："产品'复古牛仔夹克'成功创建，带有4张专业图片！"

列出产品

用户："显示我的产品"
助手：[列出所有产品及其详细信息]

用户："显示前5个产品"
助手：[列出前5个产品]

管理集合

用户："我有哪些集合？"
助手：[列出可用集合]

上传产品图片

用户："我想创建一个新的产品"
助手：[引导完成产品创建过程]
助手："您想为这个产品上传图片吗？"
用户：[点击聊天界面中的相机按钮（📷）]
用户：[选择多个图片文件或拖放它们]
助手："我收到了3张产品图片。正在处理..."
助手："图片上传成功！继续创建产品..."

AI设计图生成

用户："我想创建一个名为'Summer Dress'的产品"
助手：[引导完成产品创建]
用户：[上传连衣裙图片]
助手："🎨 可用AI设计图选项！生成3个专业设计图？"
用户："是的"
助手："✅ 已生成3个AI设计图，展示了在工作室、生活方式和高级设置下的连衣裙！"

获取产品信息

用户："显示ID为64f1a2b3c4d5e6f7g8h9i0j1的产品详情"
助手："📦 **产品：复古牛仔夹克**
- **ID**：64f1a2b3c4d5e6f7g8h9i0j1
- **描述**：经典复古风格的牛仔夹克，带有破损细节
- **价格范围**：$79.99 - $89.99
- **集合**：时尚
- **类型**：NORMAL
- **图片**：已上传4张
- **状态**：已发布
- **联盟营销**：是（15%佣金）"

用户："我有哪些产品？"
助手：[列出产品标题和ID，然后询问要查看哪个详细信息]

更新产品

用户："我想将我的牛仔夹克的价格更新为$95"
助手："我将帮助您更新产品。首先，让我获取当前的详细信息..."
助手：[显示当前产品信息]
助手："我可以看到您的复古牛仔夹克目前的价格是$89.99。您想将其更新为$95.00吗？"
用户："是的，更新它"
助手："✅ **产品更新成功**
- **产品**：复古牛仔夹克（64f1a2b3c4d5e6f7g8h9i0j1）
- **更新字段**：价格
- **应用变更**：价格从$89.99更新为$95.00"

用户："将产品64f1a2b3c4d5e6f7g8h9i0j1的描述更改为'高端复古牛仔夹克，带有真实的破损效果'"
助手：[获取当前产品，显示当前描述，然后更新它]
助手："✅ 描述更新成功！"

删除产品

用户："删除产品64f1a2b3c4d5e6f7g8h9i0j1"
助手："⚠️ **删除确认所需**

我找到了要删除的产品：
📦 **产品：复古牛仔夹克**
- **ID**：64f1a2b3c4d5e6f7g8h9i0j1
- **价格**：$95.00
- **图片**：已上传4张
- **状态**：已发布

**此操作不可逆。** 您确定要永久删除此产品吗？
用户："是的，删除它"
助手："✅ 产品'复古牛仔夹克'（64f1a2b3c4d5e6f7g8h9i0j1）已被永久从您的商店中删除。"

产品发现和管理

用户："显示我在时尚集合中的所有产品"
助手：[按集合过滤列出产品]

用户："我的哪些产品可以进行联盟营销？"
助手：[显示启用联盟营销设置的产品]

用户："将我的所有产品更新为允许联盟营销，并设置20%佣金"
助手：[引导完成批量更新过程，并进行确认]

图片上传功能：

支持多种图片格式（JPEG、PNG、GIF、WebP）
拖放界面
实时上传进度指示器
图片预览功能
最大文件大小：每张图片10MB
如果不需要，可以选择跳过图片上传

AI设计图功能：

使用GPT-4V自动检测服装
使用GPT-Image-1生成专业设计图
在不同姿势/设置下展示时尚项目
成本效益：~$0.033用于3个专业图片
智能提示区分不同类型的产品
无缝集成到产品创建工作流中

🔒 安全特性

JWT认证：与Droplinked的安全令牌认证
会话管理：内存会话存储（适合开发）
错误处理：全面的错误处理和详细的日志记录
输入验证：使用Pydantic模型进行请求验证

🧪 开发

运行测试

# 运行所有测试
python -m pytest tests/

# 运行并带有覆盖率
python -m pytest tests/ --cov=app

开发模式

# 带有自动重载运行
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

调试

通过检查控制台输出启用调试日志
所有API调用和响应都被记录下来以供故障排除
OpenAI助手交互被跟踪并带有详细的日志

🚨 生产考虑

在部署到生产之前，请考虑：

会话存储：替换内存会话存储为Redis或数据库
环境变量：使用适当的秘密管理
HTTPS：启用SSL/TLS加密
速率限制：实施API速率限制
监控：添加应用程序监控和日志
数据库：考虑持久化存储会话和用户数据

🐛 故障排除

常见问题

OpenAI客户端未初始化
- 确保.env中设置了`OPEN