Sfcc Dev MCP

🚀 SFCC開發MCP服務器

SFCC開發MCP服務器是一個基於Model Context Protocol（MCP）的服務器，它為Salesforce B2C Commerce Cloud開發功能提供全面訪問。藉助該服務器，AI代理能夠協助處理SFCC開發任務，包括日誌分析、調試、監控以及SFCC文檔查詢等。

🚀 快速開始

若要將此MCP服務器與Claude Desktop或其他MCP客戶端配合使用，請在MCP設置文件中添加以下內容：

僅文檔模式（無需SFCC憑證）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"]
    }
  }
}

完整模式（使用SFCC憑證進行日誌分析和系統對象工具操作）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
    }
  }
}

完整模式下的 dw.json 文件創建

在完整模式下，你需要創建一個包含SFCC憑證的 dw.json 文件：

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "your-client-id",
  "client-secret": "your-client-secret"
}

各模式下可用工具

立即開始使用：該服務器無需任何憑證即可運行，只需使用 npx sfcc-dev-mcp 命令，你就能訪問所有文檔和最佳實踐工具！

✨ 主要特性

SFCC最佳實踐指南

• 獲取可用指南：列出所有可用的SFCC最佳實踐指南，涵蓋插件創建、ISML模板、OCAPI鉤子、SCAPI鉤子、SFRA控制器和自定義SCAPI端點等內容。
• 獲取完整指南：獲取特定SFCC開發領域的全面最佳實踐指南，包括新的ISML模板指南，其中包含安全、性能和可維護性準則。
• 搜索最佳實踐：在所有最佳實踐指南中搜索特定術語、概念或模式，包括ISML特定主題，如編碼、XSS預防和模板架構。
• 獲取鉤子參考：訪問OCAPI和SCAPI鉤子的詳細參考表。

SFCC文檔查詢

• 獲取類信息：檢索任何SFCC類的詳細信息，包括屬性、方法和描述。
• 搜索類：通過部分匹配類名查找SFCC類。
• 獲取類方法：列出特定SFCC類的所有方法及其簽名。
• 獲取類屬性：列出特定SFCC類的所有屬性及其類型和修飾符。
• 搜索方法：在所有SFCC類中搜索特定名稱的方法。
• 列出所有類：獲取所有可用SFCC類的完整列表。
• 獲取原始文檔：訪問任何類的完整Markdown文檔。

SFRA文檔訪問

• 獲取可用SFRA文檔：列出所有可用的SFRA（Storefront Reference Architecture）文檔，包括服務器、請求、響應、查詢字符串和渲染模塊。
• 獲取SFRA文檔：檢索完整的SFRA類或模塊文檔，包含屬性、方法和使用示例的詳細信息。
• 搜索SFRA文檔：在所有SFRA文檔中搜索特定術語、概念或功能，如路由、中間件、請求處理或響應管理。
• 獲取SFRA類方法：獲取特定SFRA類（服務器、請求、響應、查詢字符串）的所有方法，包括詳細的簽名、參數和描述。
• 獲取SFRA類屬性：獲取特定SFRA類的所有屬性及其類型和描述，以幫助理解請求/響應對象和控制器中的SFRA類屬性。

SFCC系統對象定義

• 獲取所有系統對象：檢索所有系統對象定義的完整列表及其元數據，包括屬性計數。
• 獲取系統對象定義：獲取特定系統對象（產品、客戶、訂單等）的詳細信息，包括所有屬性。
• 搜索系統對象屬性定義：使用複雜查詢在系統對象類型中搜索特定屬性定義。支持按ID、顯示名稱、描述進行文本搜索，按屬性（如必需、可搜索、系統）進行過濾和排序。這對於查找自定義屬性或具有特定特徵的屬性至關重要。若要獲取對象的所有屬性，請使用 match_all_query。
• 搜索站點首選項：在指定的首選項組和實例中搜索站點首選項。這對於發現自定義站點首選項、理解首選項配置或處理特定於站點的設置非常重要。支持複雜查詢，包括文本搜索、過濾和排序。
• 搜索系統對象屬性組：搜索特定系統對象類型的屬性組。這對於發現站點首選項組（使用 "SitePreferences" 作為對象類型）非常重要，這些組是站點首選項搜索API所必需的。支持複雜查詢，包括文本搜索、過濾和排序。
• 搜索自定義對象屬性定義：使用複雜查詢在自定義對象類型中搜索特定屬性定義。此功能用於自定義對象（用戶定義的數據結構），而不是系統對象。支持按ID、顯示名稱、描述進行文本搜索，按屬性（如必需、可搜索、系統）進行過濾和排序。這對於在自定義對象定義中查找自定義屬性或具有特定特徵的屬性至關重要。

日誌分析與監控

• 獲取最新錯誤：從SFCC日誌中檢索最新的錯誤消息。
• 獲取最新警告：獲取最近的警告消息。
• 獲取最新信息：訪問最近的信息級日誌條目。
• 總結日誌：獲取日誌活動的概述，包括錯誤計數和關鍵問題。
• 搜索日誌：在日誌文件中搜索特定模式。
• 列出日誌文件：查看可用的日誌文件及其元數據。

🤖 AI助手集成

為了在處理SFCC項目時獲得最佳的AI輔助，請將 文件複製到你的SFCC項目目錄，並將其重命名為 copilot-instructions.md、claude.md 或類似名稱。該文件為AI助手提供了以下方面的全面指導：

• 何時使用MCP工具 與依賴通用AI知識的對比
• 針對常見SFCC開發任務的特定工具推薦
• 調試、實施和最佳實踐的工作流模式
• 通過鼓勵使用當前經過驗證的SFCC信息來減少錯誤

這將顯著提高AI在處理SFCC開發任務時的輔助準確性，並減少幻覺現象。

📦 安裝指南

1. 克隆此倉庫：

git clone [倉庫地址]

2. 安裝依賴項：

npm install

3. 構建TypeScript代碼：

npm run build

💻 使用示例

啟動參數和命令行選項

服務器支持多個命令行參數來定製其行為：

--dw-json <路徑>

指定自定義的 dw.json 配置文件路徑：

# 使用npm並指定自定義dw.json路徑
npm start -- --dw-json /path/to/your/dw.json

# 使用npm並指定相對路徑
npm start -- --dw-json ./config/dw.json

# 直接使用node
node dist/main.js --dw-json /path/to/your/dw.json

--debug <true|false>

控制調試日誌輸出，以定製服務器日誌的詳細程度：

# 啟用調試日誌（顯示詳細的調試消息、方法進入/退出、計時信息）
npm start -- --debug true
npm start -- --debug  # 簡寫為true

# 禁用調試日誌（僅顯示基本信息、警告和錯誤）
npm start -- --debug false

# 與其他選項結合使用
npm start -- --dw-json ./config/dw.json --debug false

啟動服務器

# 基本啟動（使用./dw.json或環境變量）
npm start

# 使用自定義dw.json文件啟動
npm start -- --dw-json /path/to/custom/dw.json

# 或者直接使用node啟動
node dist/main.js

# 或者使用自定義配置啟動
node dist/main.js --dw-json ./config/production.json

使用npx運行

你也可以直接使用npx運行服務器，而無需在本地安裝：

# 使用npx運行（使用./dw.json或環境變量）
npx sfcc-dev-mcp

# 使用npx並指定自定義dw.json文件運行
npx sfcc-dev-mcp --dw-json /path/to/custom/dw.json

# 使用npx並指定相對路徑運行
npx sfcc-dev-mcp --dw-json ./config/dw.json

MCP客戶端配置

將此服務器添加到你的MCP客戶端配置中。例如，在Claude Desktop的配置中：

使用本地安裝

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "node",
      "args": ["/path/to/sfcc-dev-mcp/dist/main.js"]
    }
  }
}

使用npx（推薦）

{
  "mcpServers": {
    "sfcc-dev": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "sfcc-dev-mcp",
        "--dw-json",
        "/path/to/your/dw.json"
      ]
    }
  }
}

可用工具示例

SFCC文檔工具

• get_sfcc_class_info - 獲取SFCC類的綜合信息

{
  "className": "Catalog"
}

• search_sfcc_classes - 按名稱搜索類

{
  "query": "product"
}

SFCC最佳實踐工具

• get_available_best_practice_guides - 列出所有可用的最佳實踐指南

{}

• get_best_practice_guide - 獲取完整的最佳實踐指南

{
  "guideName": "sfra_controllers"
}

SFCC SFRA文檔工具

• get_available_sfra_documents - 列出所有可用的SFRA文檔

{}

• get_sfra_document - 獲取完整的SFRA類或模塊文檔

{
  "documentName": "server"
}

SFCC系統對象定義工具

• get_system_object_definitions - 獲取所有系統對象定義

{
  "count": 50,
  "select": "(**)"
}

• get_system_object_definition - 獲取特定系統對象定義

{
  "objectType": "Product"
}

日誌分析工具

• get_latest_errors - 獲取最近的錯誤消息
• get_latest_warnings - 獲取最近的警告消息
• get_latest_info - 獲取最近的信息消息
• summarize_logs - 獲取日誌摘要及計數
• search_logs - 在日誌中搜索模式
• list_log_files - 列出可用的日誌文件

📚 詳細文檔

配置

覆蓋工作目錄

服務器使用當前工作目錄（cwd）來定位文檔文件。默認情況下，它期望在服務器啟動的目錄中找到一個 docs/ 文件夾。如果你需要使用不同位置的文檔，可以採用以下幾種方法：

方法一：從正確的目錄啟動服務器

cd /path/to/sfcc-dev-mcp
npx sfcc-dev-mcp

方法二：使用 --cwd 標誌（如果你的MCP客戶端支持）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"],
      "cwd": "/path/to/sfcc-dev-mcp"
    }
  }
}

方法三：創建符號鏈接

# 在你期望的位置創建指向docs文件夾的符號鏈接
ln -s /path/to/sfcc-dev-mcp/docs /your/desired/location/docs
cd /your/desired/location
npx sfcc-dev-mcp

期望的目錄結構 服務器期望的目錄結構如下：

./docs/
├── best-practices/
│   ├── cartridge_creation.md
│   ├── ocapi_hooks.md
│   ├── scapi_hooks.md
│   └── ...
├── sfra/
│   ├── server.md
│   ├── request.md
│   ├── response.md
│   ├── querystring.md
│   └── render.md
├── dw_catalog/
├── dw_order/
└── ... (其他SFCC類文檔文件夾)

使用 dw.json（推薦）

服務器支持Commerce Cloud開發工具使用的標準SFCC dw.json 配置格式。在項目根目錄下創建一個 dw.json 文件：

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "your-client-id",
  "client-secret": "your-client-secret",
  "code-version": "version1"
}

必填字段：

• hostname：你的SFCC實例主機名
• username：你的SFCC用戶名
• password：你的SFCC密碼

可選字段：

• client-id：OAuth客戶端ID（用於API訪問）
• client-secret：OAuth客戶端密鑰（用於API訪問）
• code-version：要使用的代碼版本

使用環境變量

你也可以使用環境變量來配置服務器：

export SFCC_HOSTNAME="your-instance.sandbox.us01.dx.commercecloud.salesforce.com"
export SFCC_USERNAME="your-username"
export SFCC_PASSWORD="your-password"
export SFCC_CLIENT_ID="your-client-id"
export SFCC_CLIENT_SECRET="your-client-secret"
export SFCC_SITE_ID="RefArch"

數據API配置

系統對象定義工具的Business Manager設置

若要使用系統對象定義工具（get_system_object_definitions、get_system_object_definition、search_system_object_attribute_definitions、search_site_preferences、search_system_object_attribute_groups、search_custom_object_attribute_definitions），你需要在Business Manager中配置數據API訪問：

步驟一：在賬戶管理器中創建API客戶端

1. 登錄到 賬戶管理器（不是Business Manager）。
2. 導航到 API客戶端 部分。
3. 點擊 添加API客戶端。
4. 配置API客戶端：
   • 名稱：SFCC Dev MCP Server（或任何描述性名稱）
   • 密碼：生成一個安全的密碼
   • 範圍：選擇 SFCC 範圍
   • 角色：為你的組織分配適當的角色

步驟二：在Business Manager中配置數據API訪問

1. 登錄到你的實例的 Business Manager。
2. 導航到 管理 > 站點開發 > 開放商務API設置。
3. 點擊 數據API 選項卡。
4. 配置以下設置：

客戶端配置：

{
  "_v": "23.2",
  "clients": [
    {
      "client_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "resources": [
        {
          "resource_id": "/system_object_definitions",
          "methods": [
            "get"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definitions/*",
          "methods": [
            "get"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definition_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definitions/*/attribute_definition_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definitions/*/attribute_group_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "，"write_attributes": "(**)"
        },
        {
          "resource_id": "/custom_object_definitions/*/attribute_definition_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/site_preferences/preference_groups/*/*/preference_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}

必填設置：

• 客戶端ID：你的API客戶端ID（例如 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa）
• 資源ID：/system_object_definitions/*（允許訪問所有系統對象定義端點）
• 資源ID：/site_preferences/preference_groups/*/*/preference_search（允許訪問站點首選項搜索）
• 方法：get 和 post（檢索和搜索系統對象及首選項所需）
• 讀取屬性：(**)（允許讀取所有屬性）
• 寫入屬性：(**)（某些操作可能需要）

步驟三：更新你的配置

將客戶端憑證添加到你的 dw.json 文件中：

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "client-secret": "your-api-client-password",
  "code-version": "version1"
}

數據API訪問故障排除

常見問題：

• 403禁止訪問：檢查你的API客戶端是否具有正確的範圍和角色。
• 401未授權：驗證你的客戶端憑證是否正確。
• 資源未找到：確保資源ID模式與 /system_object_definitions/* 和 /site_preferences/preference_groups/*/*/preference_search 匹配。

測試你的配置： 你可以使用MCP工具測試你的數據API訪問：

{
  "tool": "get_system_object_definitions",
  "parameters": {
    "count": 5,
    "select": "(**)"
  }
}

測試站點首選項工作流：

{
  "tool": "search_system_object_attribute_groups",
  "parameters": {
    "objectType": "SitePreferences",
    "searchRequest": {
      "query": {
        "match_all_query": {}
      },
      "select": "(**)"
    }
  }
}

🔧 技術細節

配置加載優先級

服務器按以下優先級加載配置：

1. 命令行 --dw-json 參數（最高優先級）：允許你指定自定義的 dw.json 文件路徑，適用於不同環境或項目配置。
2. 當前目錄下的 ./dw.json 文件：如果工作目錄中存在該文件，則會自動檢測並使用，這是標準的SFCC開發工作流程。
3. 環境變量（最低優先級）：如果未找到 dw.json 文件，則會回退到使用環境變量。

調試模式

啟用調試模式可獲取詳細的故障排除信息：

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/dw.json", "--debug", "true"]
    }
  }
}

調試模式提供以下信息：

• 方法進入和退出跟蹤
• 性能計時信息
• 完整的請求/響應詳細信息
• 配置加載詳細信息
• 客戶端初始化狀態

日誌清理

日誌文件會隨著時間積累，你可以安全地刪除舊的日誌文件：

macOS/Linux：

# 刪除所有日誌文件
rm /tmp/sfcc-mcp-logs/*.log

# 刪除7天以上的日誌
find /tmp/sfcc-mcp-logs -name "*.log" -mtime +7 -delete

Windows：

# 刪除所有日誌文件
Remove-Item "$env:TEMP\sfcc-mcp-logs\*.log"

# 刪除7天以上的日誌
Get-ChildItem "$env:TEMP\sfcc-mcp-logs" -Filter "*.log" | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } | Remove-Item

文檔生成

SFCC文檔是使用包含的抓取腳本從官方SFCC文檔自動轉換而來的。

注意：文檔轉換腳本需要額外的依賴項，這些依賴項未包含在主包中，以保持MCP服務器的輕量級：

# 安裝文檔轉換所需的依賴項
npm install axios cheerio

# 轉換SFCC文檔（帶速率限制）
node scripts/convert-docs.js

# 測試模式（有限轉換）
node scripts/convert-docs.js --test

# 保守的速率限制
node scripts/convert-docs.js --slow

axios 和 cheerio 依賴項僅在從SFCC文檔網站重新生成文檔時需要，正常的MCP服務器操作不需要這些依賴項。

最佳實踐覆蓋範圍

服務器包含了所有主要SFCC開發領域的全面最佳實踐指南：

• OCAPI鉤子：傳統API擴展模式和實施指南
• SCAPI鉤子：現代API鉤子，考慮事務完整性和性能
• SFRA控制器：店面控制器模式、中間件鏈和擴展策略
• 自定義SCAPI端點：構建新API端點的三支柱架構

文檔覆蓋範圍

服務器包含了所有SFCC包的全面文檔：

• dw.campaign - 活動和促銷管理
• dw.catalog - 產品和目錄管理
• dw.content - 內容管理
• dw.customer - 客戶管理
• dw.order - 訂單處理
• dw.system - 系統實用程序
• dw.web - 網絡框架
• 還有更多...

安全注意事項

• 安全存儲你的 dw.json 文件，切勿將其提交到版本控制系統。
• 將 dw.json 添加到你的 .gitignore 文件中。
• 在生產環境中使用環境變量。
• 確保你的SFCC憑證具有適當的權限。

開發

從源代碼構建

npm run build

運行測試

npm test

故障排除和調試

MCP服務器日誌

服務器會自動將所有日誌寫入文件，以避免干擾JSON-RPC協議，並確保一致的調試能力。這可以防止JSON解析錯誤，併為故障排除提供可靠的日誌訪問。

不同操作系統的日誌文件位置

macOS：

/tmp/sfcc-mcp-logs/
├── sfcc-mcp-info.log      # 一般信息和啟動消息
├── sfcc-mcp-warn.log      # 警告消息和棄用通知
├── sfcc-mcp-error.log     # 錯誤消息和堆棧跟蹤
└── sfcc-mcp-debug.log     # 詳細的調試信息（啟用調試模式時）

Windows：

%TEMP%\sfcc-mcp-logs\
├── sfcc-mcp-info.log      # 一般信息和啟動消息
├── sfcc-mcp-warn.log      # 警告消息和棄用通知
├── sfcc-mcp-error.log     # 錯誤消息和堆棧跟蹤
└── sfcc-mcp-debug.log     # 詳細的調試信息（啟用調試模式時）

Linux：

/tmp/sfcc-mcp-logs/
├── sfcc-mcp-info.log      # 一般信息和啟動消息
├── sfcc-mcp-warn.log      # 警告消息和棄用通知
├── sfcc-mcp-error.log     # 錯誤消息和堆棧跟蹤
└── sfcc-mcp-debug.log     # 詳細的調試信息（啟用調試模式時）

即時查看日誌

macOS/Linux：

# 即時查看所有日誌
tail -f /tmp/sfcc-mcp-logs/*.log

# 查看特定日誌級別
tail -f /tmp/sfcc-mcp-logs/sfcc-mcp-error.log    # 僅查看錯誤日誌
tail -f /tmp/sfcc-mcp-logs/sfcc-mcp-debug.log    # 查看調試信息（如果啟用）

Windows (PowerShell)：

# 即時查看錯誤日誌
Get-Content "$env:TEMP\sfcc-mcp-logs\sfcc-mcp-error.log" -Wait

# 查看所有日誌
Get-ChildItem "$env:TEMP\sfcc-mcp-logs" | ForEach-Object { Get-Content $_.FullName -Wait }

常見問題及解決方案

• JSON解析錯誤：
  • 問題：Expected ',' or ']' after array element in JSON at position X
  • 原因：以前的版本將日誌輸出到控制檯，干擾了MCP協議。
  • 解決方案：更新到最新版本 - 現在日誌會自動寫入文件。
• 日誌文件未創建：
  • 問題：預期目錄中沒有日誌文件。
  • 原因：服務器運行時存在權限問題。
  • 解決方案：檢查你是否通過MCP客戶端運行（而不是直接使用 node），或者驗證臨時目錄的寫入權限。
• 缺少調試信息：
  • 問題：調試日誌文件為空或缺少詳細信息。
  • 原因：調試模式未啟用。
  • 解決方案：在你的MCP客戶端配置中添加 --debug true：

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/dw.json", "--debug", "true"]
    }
  }
}

• 連接問題：
  • 問題：服務器似乎已啟動，但工具無法正常工作。
  • 原因：各種配置或網絡問題。
  • 解決方案：檢查錯誤日誌以獲取特定的錯誤消息，並驗證SFCC憑證。

貢獻

我們歡迎貢獻！請參閱我們的 貢獻指南 以瞭解以下詳細信息：

• 設置開發環境
• 代碼風格和約定
• 測試要求
• 拉取請求流程
• 我們期望的貢獻類型

無論你是修復錯誤、添加功能、改進文檔還是增強最佳實踐指南，你的貢獻都有助於讓每個人更輕鬆地進行SFCC開發。

📄 許可證

本項目採用ISC許可證，請參閱 LICENSE 文件以獲取詳細信息。