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"
}

各模式下可用工具

工具类别	仅文档模式	完整模式
SFCC文档 (7个工具)	✅ 可用	✅ 可用
最佳实践指南 (4个工具)	✅ 可用	✅ 可用
SFRA文档 (5个工具)	✅ 可用	✅ 可用
日志分析 (6个工具)	❌ 需要凭证	✅ 可用
系统对象定义 (6个工具)	❌ 需要OAuth	✅ 支持OAuth

立即开始使用：该服务器无需任何凭证即可运行，只需使用 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 文件以获取详细信息。