sfcc-dev-mcp

SFCC Development MCP Server

一款由 AI 驱动的 Model Context Protocol (MCP) 服务，可全面访问 Salesforce B2C Commerce Cloud 开发工具、文档和运行时诊断功能。

✨ 主要功能

• 🔍 完整的 SFCC 文档访问 - 搜索和浏览所有 SFCC API 类及方法
• 🏗️ SFRA 文档 - 更便捷地访问 Storefront Reference Architecture 文档
• 🧱 ISML 模板参考 - 提供完整的 ISML 元素文档、示例和使用指南
• 📊 日志分析工具 - 对 SFCC 实例进行实时错误监控、调试和作业日志分析
• ⚙️ 系统对象定义 - 浏览自定义属性和站点偏好设置
• 🧪 脚本调试器 - 在凭据模式下执行并检查 script-debugger 端点，包括为非默认店面路由指定自定义触发 URL/路径
• 🚀 Cartridge 生成 - 自动创建 cartridge 结构，并确保路径安全且限定在工作区内（写入操作仅限工作区根目录内；若根目录不可用，则回退到当前工作目录；禁止回退到主目录）
• 🧩 Agent 技能初始化 - 将 AGENTS.md 和捆绑技能安装或合并到当前项目或临时目录，供 AI 助手使用
• ✅ 工具参数验证 - 运行时架构验证会在处理程序执行前检查必填字段、类型、枚举约束、整数/数值边界，以及对象架构（顶层和嵌套）的未知键
• ⏱️ MCP 进度 + 取消 - 工具调用会遵循请求取消信号；当客户端提供 progressToken 时，还会发送带外 notifications/progress 更新

🚀 快速开始

选项 1：仅文档模式（无需 SFCC 凭据）

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

选项 2：完整模式（需 SFCC 凭据以分析日志和作业）

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

创建一个包含 SFCC 凭据的 dw.json 文件。可选择以下任一身份验证模式，也可以同时使用两者：

• 基本身份验证：username + password
• OAuth：client-id + client-secret
• 可选的店面身份验证（用于在采用基本身份验证的店面上触发脚本调试器）：storefrontUsername + storefrontPassword

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

设置了 hostname 时，至少需要一组完整的凭据。 如果提供了凭据，也必须设置 hostname。

选项 3：自动发现（推荐 VS Code 用户使用）

只需打开包含 dw.json 文件的 VS Code 工作区，服务便会自动发现并使用该文件：

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

🔧 配置发现优先级

服务按以下顺序发现 SFCC 凭据（优先级由高到低）：

优先级	来源	说明
1	--dw-json CLI 参数	指定 dw.json 文件的显式路径
2	环境变量	SFCC_HOSTNAME、SFCC_USERNAME、SFCC_PASSWORD、SFCC_CLIENT_ID、SFCC_CLIENT_SECRET
3	MCP 工作区根目录	自动在 VS Code 工作区文件夹中发现 dw.json，并在客户端发送 notifications/roots/list_changed 时刷新

注意：服务不再默认搜索当前工作目录，因为 MCP 服务通常以用户主目录作为 cwd 启动。MCP 工作区根目录机制可提供可靠的项目上下文。

🎯 运行模式

模式	可用工具	是否需要 SFCC 凭据
仅文档模式	18 个工具	❌ 否
完整模式	40 个工具	✅ 是

仅文档模式

非常适合学习和开发，无需 SFCC 实例：

• 完整的 SFCC API 文档（5 个工具）
• SFRA 文档（5 个工具）
• ISML 模板文档（5 个工具）
• Cartridge 生成（1 个工具，仅在工作区根目录或当前工作目录中写入）
• Agent 指令初始化（2 个工具），用于复制/合并 AGENTS.md 和技能，或禁用后续提示

完整模式

通过实时访问 SFCC 实例，获得完整的开发体验：

• 仅文档模式的所有功能（18 个工具）
• 实时日志分析和作业日志（13 个工具）
• 系统对象定义（6 个工具）
• 代码版本管理（2 个工具）
• 脚本调试器操作（1 个工具）

🏗️ 架构概览

此服务采用由能力门控的模块化处理器架构，将工具路由与领域逻辑清晰分离：

核心层

• 工具架构（src/core/tool-schemas/）：按类别划分的模块化工具定义（文档、SFRA、ISML、日志、作业日志、系统对象、cartridge、代码版本、Agent 指令、脚本调试器）。通过 tool-definitions.ts 重新导出。
• 服务编排模块（src/core/server-tool-catalog.ts、src/core/server-tool-call-lifecycle.ts、src/core/server-workspace-discovery.ts）：通过提取具备能力感知功能的工具目录逻辑、tools/call 生命周期（进度/取消/预检）以及工作区根目录重新配置流程，让 server.ts 保持精简。
• 工具参数验证器（src/core/tool-argument-validator.ts）：在工具分派前，于 MCP 边界对所有工具强制执行运行时参数结构验证（必填字段、基本类型/对象/数组类型、枚举检查、整数/数值范围、字符串模式/长度，以及针对顶层和嵌套对象架构的严格未知键检查）。
• OCAPI 查询覆盖范围（src/core/tool-schemas/shared-schemas.ts）：共享搜索架构包含 text_query、term_query、bool_query、filtered_query 和 match_all_query，使 MCP 边界验证与支持的 OCAPI 查询模式一致。
• 处理器（src/core/handlers/）：每个类别都有一个处理器，继承公共基类以支持计时、结构化日志记录和错误规范化，并通过 ConfiguredClientHandler 进行配置驱动的连接，减少重复样板代码（例如 log-handler、docs-handler、isml-handler、system-object-handler）。
• 客户端（src/clients/）：封装领域操作（OCAPI、SFRA 文档、ISML 文档、模块化日志分析、脚本调试器、cartridge 生成、Agent 指令同步）。处理器将操作委托给这些客户端，从而将编排与计算分离。
• 服务（src/services/）：通过依赖注入提供文件系统和路径操作抽象，提升可测试性并隔离副作用。
• 模块化日志系统（src/clients/logs/）：包含读取器（范围/尾部优化）、发现器、处理器（行 → 结构化条目）、分析器（模式与健康状态）和格式化器（人类可读输出），便于持续演进和维护。
• 配置工厂（src/config/configuration-factory.ts）：根据提供的凭据确定能力（canAccessLogs、canAccessOCAPI），并据此筛选已公开的工具（遵循最小权限原则）。
• 共享凭据验证（src/config/credential-validation.ts）：集中处理 dw.json 加载和运行时配置创建所需的身份验证凭据对完整性及主机名格式验证。
• 调用时能力防护（src/core/server.ts）：拒绝执行当前模式下不可用的工具，因此无法通过直接发送 tools/call 请求来调用隐藏工具。
• 调用生命周期信号（src/core/server.ts）：tools/call 处理支持通过请求中止信号取消操作；当调用方提供 _meta.progressToken 时，还会尽力发送进度通知。
• 工具错误清理（src/core/tool-error-response.ts）：在返回 MCP 工具响应前清理上游执行错误，减少意外泄露后端载荷详细信息的风险。
• 运行时 WebDAV 验证（src/core/server.ts）：对于仅使用 OAuth 的配置（有 client-id/client-secret，但没有 username/password），通过一次性 WebDAV 能力探测来控制日志/作业日志/脚本调试器工具的公开，避免工具可用性误报。
• CLI 选项辅助工具（src/config/cli-options.ts）：集中处理命令行解析和环境凭据检测，确保启动行为可预测。
• 共享路径安全策略（src/config/path-security-policy.ts）：在工作区根目录发现和安全加载 dw.json 时复用允许/阻止路径规则。
• 共享中止工具（src/utils/abort-utils.ts）：集中组合超时和中止信号，供 HTTP 和调试器客户端使用，以确保取消语义一致并清理计时器。

为什么这很重要

• 可扩展性：添加新工具通常只需添加一个架构和少量处理逻辑（如果属于新领域，则需添加新的处理器）。
• 安全性：当功能标志为 false 时，需要凭据的工具绝不会被暴露。
• 可测试性：单元测试针对客户端和模块；集成/MCP 测试用于验证处理器路由和响应结构。
• 性能：读取日志尾部内容并进行轻量级缓存（cache.ts、log-cache.ts），可减少不必要的 I/O。

添加新工具（高级步骤）

1. 在 src/core/tool-schemas/ 中的相应文件里添加架构（如果是新类别，则创建新文件）。
2. 如果添加了新文件，则从 src/core/tool-schemas/index.ts 导出新架构。
3. 在客户端/服务中实现领域逻辑（避免让处理器变得臃肿）。
4. 扩展现有处理器；如果属于新类别，则创建新的处理器。
5. （仅适用于新类别）在 server.ts 的 registerHandlers() 中注册新的处理器。
6. 编写测试前，先使用 npx aegis query 了解实际响应结构。
7. 添加 Jest 单元测试和 YAML MCP 测试（如果需要凭据，则测试文档模式和完整模式）。
8. 更新文档（如果内容有变更，则更新 AGENTS.md 和 README 中的数量）。

如需深入了解内部实现，请参阅文档网站中的 Development Guide。

🤖 AI 接口设置

选择你偏好的 AI 助手：

接口	适用场景	设置指南
Claude Desktop	多轮对话、调试	📖 设置指南
GitHub Copilot	VS Code 集成、内联建议	📖 设置指南
Cursor	现代 AI 驱动的编辑器	📖 设置指南

📦 安装

使用 npx（推荐）

提示：添加 -y（或 --yes），即可跳过 npx 下载软件包前显示的交互式提示。这可以避免 AI 客户端（Claude Desktop、Copilot、Cursor）因等待确认而卡住。

# Test the server
npx -y sfcc-dev-mcp

# Use with your configuration
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json

全局安装

npm install -g sfcc-dev-mcp
sfcc-dev-mcp --dw-json /path/to/your/dw.json

🐛 调试模式与日志记录

启用调试日志

# Enable debug mode for detailed logging
npx -y sfcc-dev-mcp --debug

# Or with configuration file
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json --debug

--debug 接受 true/false、1/0 或 yes/no。无效值会立即触发错误，并显示明确的错误消息。

日志文件位置

服务会将日志写入系统临时目录：

• macOS：/var/folders/{user-id}/T/sfcc-mcp-logs/
• Linux：/tmp/sfcc-mcp-logs/
• Windows：%TEMP%\sfcc-mcp-logs\

创建的日志文件：

• sfcc-mcp-info.log - 常规应用日志和启动消息
• sfcc-mcp-debug.log - 详细调试信息（仅在启用 --debug 时）
• sfcc-mcp-error.log - 错误消息和堆栈跟踪
• sfcc-mcp-warn.log - 警告消息

查找日志目录

// The exact path varies by system - to find yours:
node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"

🧪 发布流程（维护者）

此仓库现使用 Changesets 发布 npm 软件包。

当某项变更需要随新版本的 sfcc-dev-mcp 一同发布时，请从仓库根目录添加 changeset：

npm run changeset

合并前，请检查相对于 main 的待发布状态：

npm run release:status

main 上的发布工作流会根据待处理的 changeset 创建或更新发布拉取请求。合并该发布拉取请求后，工作流会通过 npm 可信发布（GitHub Actions OIDC）发布 npm 软件包，等待 npm 完成传播，针对已发布的 NPX 构件重新运行 MCP 测试，然后将同一版本发布到 MCP Registry。

npm run version-packages 还会将 server.json 与软件包版本同步，确保 validate:server-json 在发布拉取请求中继续通过。

软件包发布现使用 GitHub Actions OIDC 可信发布，因此无需单独的 npm 发布密钥。

你可以在本地运行相同的验证：

# Ensure docs-site tool catalog stays in sync with runtime tool definitions
npm run validate:tools-sync

# Ensure docs-site skills catalog stays in sync with bundled skills
npm run validate:skills-sync

# Ensure MCP registry metadata stays in sync with package.json
npm run validate:server-json

# In a separate terminal, start the mock server first for full-mode MCP tests
npm run test:mock-server:start

# Uses latest published version by default
npm run test:mcp:published-npx

# Or pin a specific published version
bash ./scripts/test-published-npx.sh 1.0.21

在 GitHub Actions 中，发布工作流会自动管理模拟服务器的生命周期。

📖 文档

📚 完整文档 - 全面的指南和参考资料

文档源文件位于 docs-site-v2/（VitePress）。旧版 React 站点仍位于 docs-site/。

快速链接：

• 入门指南 - 安装和首次运行设置
• AI 界面设置 - 配置 Claude Desktop、GitHub Copilot 或 Cursor
• 配置指南 - SFCC 凭据和 Data API 设置
• 可用工具 - 完整的工具参考
• 示例 - 实际使用模式
• 故障排除 - 常见问题和解决方案

🛠️ AI 交互示例

🧑‍💻 "Create a new SFCC controller for product search"
🤖 Generates complete controller with proper imports, route handling, and SFRA patterns

🧑‍💻 "What's wrong with my checkout flow? Check the logs"  
🤖 Analyzes recent error logs, identifies issues, and suggests fixes

🧑‍💻 "Show me how to implement OCAPI hooks for order validation"
🤖 Retrieves related SFCC classes and methods, then proposes a concrete hook implementation pattern

🔒 安全说明

• 专注于本地开发：面向开发者在本地计算机上单独使用而设计
• 凭据保护：切勿将 dw.json 文件提交到版本控制系统
• 网络安全：所有 API 调用均使用 HTTPS 并进行适当身份验证
• 不存储数据：服务不会在本地持久保存任何 SFCC 数据

🔮 未来计划

我们将持续改进 SFCC Development MCP Server，并计划推出令人期待的新功能：

🎯 即将推出的改进

• 🧠 更智能的日志获取 - 增强日志分析功能，提供智能筛选、模式识别和上下文错误关联
• 🚀 部署工具 - 集成 SFCC 部署流程和代码版本管理

🤝 欢迎贡献！

对新功能或改进有想法？我们很乐意听取你的建议！

• 💡 功能请求：提交 issue，讨论你的想法
• 🐛 错误报告：报告你遇到的问题，帮助我们改进
• 🔧 拉取请求：贡献代码、文档或示例
• 📚 文档：帮助扩充我们的指南和最佳实践

查看我们的贡献指南以开始参与，或浏览未解决的问题，看看你可以提供哪些帮助。

你的专业知识和反馈将帮助这款工具更好地服务整个 SFCC 社区！

🤝 贡献

欢迎贡献！详情请参阅我们的贡献指南。

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

---

🚀 准备用 AI 为 SFCC 开发提速了吗？

📖 阅读完整文档，开始使用