Dam Butler MCP

🚀 🤖 DAM Butler MCP

DAM Butler MCP 是一款革命性的模型，它藉助自然語言和人工智能，改變了團隊查找品牌資產的方式，為 Breville 的 Vault DAM 系統提供基於意圖的數字資產發現功能。

🌐 在線部署地址： https://dam-butler-mcp.vercel.app/

🚀 快速開始

團隊成員快速上手

1. 訪問自定義 GPT

1. 打開 ChatGPT Enterprise。
2. 在自定義 GPT 中找到 “Breville Vault Assistant”。
3. 開始使用自然語言進行搜索！

2. 查詢示例

💬 "查找用於我演示文稿的帶有透明背景的 Oracle Jet 產品照片"
💬 "獲取面向英國市場的 Sage BES985 產品照片"
💬 "給我展示用於社交媒體的 Oracle 雙鍋爐生活方式照片"
💬 "我需要澳大利亞買家指南資產"
💬 "查找用於電子郵件營銷活動的 PNG 格式的 Breville 標誌"
💬 "我需要澳大利亞版的 BES881 手冊"

3. 專業提示

• 明確使用場景：例如 “用於演示文稿”、“用於網頁”、“用於印刷”。
• 提及相關地區：例如 “面向英國市場”、“澳大利亞版”。
• 指定格式需求：例如 “透明背景”、“高分辨率”。

✨ 主要特性

🧠 三層 AI 智能（第三階段）

• 🤖 OpenAI 增強：定製的 Breville 提示，置信度達 95% 以上。
• 👁️ GPT - 4 視覺：視覺相似性搜索和圖像分析。
• 🏢 Vault 智能：基於 14 個部分和 80 多個可交付成果進行訓練。
• 🔄 三重回退機制：OpenAI → 增強模式 → 基本模式（100% 可靠性）。

🌍 區域領域智能

• 亞太/美國市場領域：Breville 品牌（BES 型號）。
• 歐洲、中東和非洲市場領域：Sage 品牌（SES 型號）。
• 自動檢測：區域上下文和品牌切換。
• 📊 使用分析：特定領域的性能跟蹤。

📁 資產類型掌控

• 標誌：品牌標識、產品標誌、矢量格式。
• 產品攝影：特寫照片、技術照片、360° 視圖。
• 生活方式攝影：使用中的圖像、情境照片。
• 營銷材料：營銷活動資產、社交媒體內容、橫幅。
• 文檔：買家指南、手冊、規格表。

🎨 使用場景優化

• 演示文稿：高分辨率 PNG/SVG 格式，支持透明背景。
• 網頁：優化格式，響應式尺寸。
• 印刷：CMYK 模式、矢量格式、高 DPI。
• 社交媒體：特定平臺尺寸，注重互動性。
• 電子郵件：適合電子郵件的格式，輕量級文件。

📦 安裝指南

此部分原文檔未提供安裝步驟，暫不展示安裝指南相關內容。

💻 使用示例

基礎用法

// 輸入
{
  "request": "Oracle Jet logo for my presentation",
  "context": {
    "user_region": "AU",
    "campaign_type": "product_launch", 
    "urgency": "high"
  }
}

// MCP 輸出（ChatGPT Enterprise）
{
  "content": [
    {
      "type": "text", 
      "text": "🎯 Found 1 asset for \"Oracle Jet logo for my presentation\"\n\n📋 **Detected**: Oracle Jet | logo | presentation\n\n**1. Oracle Jet Logo - Primary**\n📁 Format: PNG | Size: 2048x1024\n🔗 Download: https://vault.breville.com/download/...\n💡 Oracle Jet Logo in PNG format with transparency. Perfect for presentation use.\n   ✅ PNG format ideal for presentations\n   ✅ High resolution, suitable for print\n   ✅ Transparent background supported\n\n💡 **Suggestions**:\n• For web use, consider WebP format for faster loading\n• SVG version available for infinite scalability"
    }
  ]
}

// 原始 API 輸出
{
  "success": true,
  "intent": {
    "products": [{"name": "Oracle Jet", "model": "BES985", "confidence": 0.95}],
    "assetTypes": ["logo"],
    "useCase": "presentation", 
    "formats": ["PNG", "SVG"],
    "region": "global",
    "confidence": 0.95,
    "source": "openai",
    "reasoning": "User wants Oracle Jet logo for presentation, suggesting PNG/SVG for transparency"
  },
  "results": [...],
  "suggestions": [...]
}

📚 詳細文檔

🎯 什麼是 DAM Butler？

DAM Butler 是一個 革命性的 MCP（模型上下文協議）服務器，它將 ChatGPT Enterprise 與 Breville 的 Vault DAM 系統連接起來。它無需用戶進行復雜的搜索和篩選，而是理解自然語言請求，並準確提供他們所需的內容。

🔥 神奇之處

❌ 舊方法：“搜索資產” → “按 Oracle Jet 過濾” → “按標誌過濾” → “查看 47 個結果”
✅ DAM Butler：“我演示文稿需要的 Oracle Jet 標誌” → 30 秒內找到 3 個完美匹配項

真實用戶反饋：“這感覺就像魔法！我只需要說出我需要的東西，它就能找到。”

🏗️ 架構：基於意圖與 API 包裝器

🚫 為什麼大多數 DAM 集成會失敗

大多數公司構建簡單的 API 包裝器，存在以下問題：

• 迫使 AI 為簡單請求進行 4 次以上的 API 調用。
• 返回如 “404 Not Found” 這樣的隱晦錯誤。
• 提供無關數據，浪費令牌。
• 給用戶帶來糟糕的體驗。

✅ 我們基於意圖的方法

用戶請求 → 意圖解析器 → 智能編排器 → 完美結果
     ↓              ↓               ↓                    ↓
"Oracle Jet   產品=BES985   增強搜索    3 個完美匹配項
照片用於      格式=PNG       + 上下文      + 使用說明
演示文稿" 用例=演示文稿  + 品牌映射    + 下載鏈接

關鍵創新：單個 MCP 調用通過內置智能處理完整工作流程。

🔧 API 參考

增強型 MCP 端點

🌐 MCP URL：https://dam-butler-mcp.vercel.app/api/mcp
🏥 健康檢查：https://dam-butler-mcp.vercel.app/api/health  
📋 架構：https://dam-butler-mcp.vercel.app/api/schema

快速狀態檢查

# 檢查系統健康和配置
curl https://dam-butler-mcp.vercel.app/api/health

# 獲取 ChatGPT Enterprise 的 MCP 功能
curl https://dam-butler-mcp.vercel.app/api/mcp

主要搜索工具：find_brand_assets

此部分代碼示例已在使用示例中展示。

📊 當前狀態：第三階段企業平臺

🌐 在線部署

https://dam-butler-mcp.vercel.app/

✅ 第三階段企業平臺 - 完全運行

• [x] 🎛️ 即時分析儀表板 - 企業級監控，30 秒刷新一次。
• [x] 🔗 生產環境 Brandfolder 集成 - OAuth 準備好立即激活。
• [x] 🧠 帶有 GPT - 4 視覺的高級 AI - 視覺相似性搜索和預測性推薦。
• [x] 📊 企業可觀測性 - 性能指標、使用分析、區域洞察。
• [x] 🔄 三重回退架構 - OpenAI → 增強模式 → 基本模式（100% 可靠性）。
• [x] 👁️ 視覺智能 - “查找與此圖像相似的資產” 功能。
• [x] 🎯 預測性推薦 - 基於 AI 的批量操作和優化。
• [x] 🌍 區域領域智能 - 亞太/美國市場（Breville）與歐洲、中東和非洲市場（Sage）識別。
• [x] 📈 使用分析 - 產品受歡迎程度、解析方法有效性、響應時間。
• [x] 🛡️ 企業級錯誤處理 - 優雅降級，詳細監控。

⏳ 等待事項

• [ ] Brandfolder OAuth 憑證（應用程序審批中）→ 即時資產下載。
• [ ] 在此之前：具有複雜 Vault 智能的 智能演示模式。

🆕 第三階段新增主要功能

• 📊 企業分析平臺（241 行） - 即時監控儀表板。
• 🔗 生產環境 OAuth 集成（350 行） - 準備好立即激活 Brandfolder。
• 🧠 高級 AI 功能（459 行） - GPT - 4 視覺 + 預測性推薦。
• 🎛️ 即時儀表板（521 行） - 基於 React 的監控界面。
• 🧪 全面測試套件（436 行） - 完成第三階段驗證。
• 🗂️ 專業版本控制 - 舊版本組織和部署策略。

📈 平臺演進

• 第一階段：基本模式匹配工具。
• 第二階段：集成 OpenAI 智能。
• 第三階段：完整的企業級 DAM 智能平臺。

🏢 代碼庫總量

2000 多行企業級功能代碼。

📋 路線圖 - 更新

• [x] 視覺相似性搜索 → ✅ 在第三階段 C 完成（GPT - 4 視覺集成）。
• [x] 智能資產推薦 → ✅ 在第三階段 C 完成（預測性 AI）。
• [x] 使用 AI 視覺自動標記 → ✅ 在第三階段 C 完成（高級智能）。
• [ ] Brandfolder OAuth 激活 → 等待憑證。
• [ ] 高級分析導出 → 為企業團隊提供 CSV/PDF 報告。
• [ ] 多語言支持 → 拓展國際市場。
• [ ] 批量操作支持 → 一次下載多個資產。
• [ ] 高級訪問控制 → 基於團隊的權限設置。
• [ ] 資產版本控制 → 跟蹤更新和更改。

🚨 故障排除

常見問題

❌ “需要身份驗證”（Brandfolder）

• 原因：Brandfolder OAuth 憑證待審批。
• 當前狀態：系統在智能演示模式下工作，提供模擬結果。
• 解決方案：等待 Brandfolder 批准 OAuth 應用程序。

✅ “OpenAI 集成正常工作”

• 狀態：✅ 已配置，置信度達 95%。
• 功能：高級意圖解析、上下文感知、智能推薦。
• 回退機制：當 OpenAI 不可用時，採用智能模式匹配。

❌ “未找到資產”

• 原因：搜索詞過於具體或產品名稱有變體。
• 解決方案：嘗試使用型號代碼（如 BES985）、更寬泛的術語（如 “Oracle Jet”）或檢查拼寫。
• 專業提示：當搜索不匹配時，系統會提供智能建議。

獲取幫助

1. 檢查健康端點：https://dam-butler-mcp.vercel.app/health。
2. 在 Vercel 儀表板中 查看日誌。
3. 使用基本查詢進行 測試，如 “Oracle Jet 標誌”。
4. 如有資產訪問問題，聯繫 DAM 團隊。

🏢 企業功能

訪問控制

• 繼承 Brandfolder 權限：用戶只能看到他們有權限訪問的資產。
• 基於區域的限制：買家指南按市場限制訪問。
• 團隊使用跟蹤：按部門和營銷活動進行分析。

性能與可靠性

• 全球 CDN：全球快速響應時間。
• 99.9% 正常運行時間：Vercel 企業級託管。
• 智能緩存：減少 API 調用，加快響應速度。
• 優雅降級：回退系統確保始終正常工作。

監控與分析

• 即時健康檢查：即時通知問題。
• 使用分析：跟蹤熱門搜索和資產。
• 性能指標：響應時間和成功率。
• 錯誤日誌記錄：詳細的調試信息。

🤝 貢獻指南

開發工作流程

1. 分叉倉庫。
2. 創建功能分支：git checkout -b feature/amazing-feature。
3. 進行更改 並在本地測試：npm run dev。
4. 測試更改：node test-mcp.js。
5. 提交更改：git commit -m 'Add amazing feature'。
6. 推送到分支：git push origin feature/amazing-feature。
7. 打開拉取請求。

代碼標準

• ESLint：使用提供的配置。
• 註釋：記錄複雜的意圖解析邏輯。
• 測試：所有新功能必須包含測試。
• 環境：切勿提交 .env 文件或機密信息。

部署

• 自動部署：推送到 main 分支會自動部署到生產環境。
• 環境變量：在 Vercel 儀表板中設置，而不是在代碼中。
• 測試：合併前始終在開發環境中測試。

🔧 技術細節

本地開發設置

# 克隆倉庫
git clone https://github.com/vivid-brg/dam-butler-mcp.git
cd dam-butler-mcp

# 安裝依賴
npm install

# 創建環境文件 (.env)
# 添加你的 OpenAI API 密鑰和 Brandfolder 憑證
cat > .env << EOF
OPENAI_API_KEY=your_openai_api_key_here
BRANDFOLDER_CLIENT_ID=your_brandfolder_client_id_here
BRANDFOLDER_CLIENT_SECRET=your_brandfolder_client_secret_here
VAULT_BASE_URL=https://thevault.work/breville
VAULT_API_BASE=https://api.brandfolder.com/v4
BRANDFOLDER_REDIRECT_URI=https://dam-butler-mcp.vercel.app/auth/callback
NODE_ENV=development
EOF

# 測試增強型 MCP 功能
npm test

# 啟動本地開發服務器
npm run dev

# 部署到生產環境
npm run deploy

環境變量

# 增強型 AI 意圖解析所需
OPENAI_API_KEY=your_openai_key_here              # ✅ 正常工作 - 95% 置信度解析

# 即時 Brandfolder 集成所需
BRANDFOLDER_CLIENT_ID=your_client_id_here        # ⏳ 等待審批
BRANDFOLDER_CLIENT_SECRET=your_client_secret_here # ⏳ 等待審批

# 生產環境自動配置
VAULT_BASE_URL=https://thevault.work/breville
VAULT_API_BASE=https://api.brandfolder.com/v4
BRANDFOLDER_REDIRECT_URI=https://dam-butler-mcp.vercel.app/auth/callback
NODE_ENV=production

項目結構

dam-butler-mcp/
├── api/
│   ├── mcp.js              # ✨ 增強型 MCP 端點，支持完整資產搜索
│   ├── find-brand-assets.js # 智能資產發現邏輯
│   ├── health.js           # 健康監測與診斷
│   ├── authenticate.js     # OAuth 認證流程
│   └── schema.js           # ChatGPT Enterprise 的 OpenAPI 架構
├── src/
│   └── server.js           # 🧠 集成 OpenAI 的 AI 意圖解析器
├── config/
│   └── breville-config.json # 📦 500 多種產品目錄和品牌映射
├── test-mcp.js             # 🧪 全面測試套件
├── package.json            # 📦 專業開發工作流程
└── vercel.json             # ☁️ 生產環境部署配置

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

企業使用說明：本軟件是為 Breville 內部使用而開發的，並與專有 DAM 系統集成。

🙋‍♂️ 支持與聯繫

終端用戶

• 文檔：本 README 和自定義 GPT 中的內聯幫助。
• 資產訪問問題：聯繫您團隊的 DAM 管理員。
• 功能請求：在 GitHub 上創建帶有 “enhancement” 標籤的問題。

開發者

• 技術問題：在 GitHub 上創建包含完整錯誤詳細信息的問題。
• 架構問題：查看代碼註釋和架構文檔。
• 部署問題：檢查 Vercel 日誌和健康端點。

企業用戶

• 戰略問題：聯繫 Breville DAM 團隊。
• 訪問控制：與 IT 和 DAM 管理員合作。
• 定製需求：可提供企業支持。